====== POV-Ray Plugin ======

POV-Ray is a free ray-tracer. The POV-Ray plugin defines an export of a 3D scene to POV-Ray's file format, this can be used to obtain high-quality images of scenes modelled with GroIMP.

===== Installation of POV-Ray =====

POV-Ray is available for download at [[http://www.povray.org]]. For GroIMP's POV-Ray plugin, you need POV-Ray version 3.5 or higher. Please follow the instructions given at POV-Ray's web page in order to install POV-Ray properly.

** Note: Most Linux distributions contain POV-Ray. Just select it in the setup tool of your distribution, POV-Ray will then be installed automatically. **

===== Configuration =====

If the POV-Ray executable file is named //povray// and
is contained in one of the directories specified in the PATH-variable  of your
system, no further configuration of GroIMP is necessary. This is the case for
most UNIX-like systems, but normally not for Windows systems.

{{:pov:preferences.png}}

** Figure 1: Configuration of the POV-Ray plugin **



The configuration of the POV-Ray plugin is done in the
Preferences panel, see Figure 1. In
the field "Programme", enter the path to POV-Ray's executable file. For Windows
systems, this is typically
"C:\Path to POV-Ray Installation\bin\pvengine.exe". The field
"Command line" allows you to specify
some options for POV-Ray, which may, e.g., influence rendering quality; please
consult POV-Ray's documentation. Finally, the option "Use standard output"
controls how the rendered image is transferred from POV-Ray to GroIMP: If
POV-Ray's standard output is used, the image is transferred continuously, so
that a progressive display within GroIMP is possible. Without standard output,
POV-Ray writes its output to a temporary file, which is displayed at once after
completion of the ray-tracing process. Generally, the method using standard
output is preferable; however, there is a bug in (some versions of) POV-Ray for
Windows, which corrupts image data in the output. If you see unexpected colors
in the rendered image, deactivate this option. 

** Note: POV-Ray for
Windows is equipped with a graphical user interface for editing POV-Ray scenes
etc. Unfortunately, this graphical user interface is always shown, even when
POV-Ray is only used in batch mode, as is the case for GroIMP. Depending on
POV-Ray's configuration, POV-Ray may even keep running after the rendering has
completed. If this is the case, add the option // /exit// in the
field "Command line". The option // /nr // keeps POV-Ray from
restoring previous edit sessions, which may reduce startup
time. **

===== Using the Plugin ===== 

GroIMP's POV-Ray plugin is used in two ways: At first, it
defines an export to POV-Ray's file format. This is available via
// View/Export// in the 3D view. You have to specify a
file name for the output, the POV-Ray scene will then be written to this
file. Some scenes contain additional image files, they will be written into a
subdirectory called ''scene.pov-files'' (where
<filename>scene.pov</filename> is the file name you have
chosen).

Secondly, this export is used to obtain a POV-Ray-rendered
image of the current scene directly in GroIMP's 3D view. Just use the menu
//Render View/POV-Ray// in the 3D
view.

===== Limitations =====

3D geometry and 3D materials are complex objects.
Therefore, a 1:1 translation of one
representation of 3D scenes to another is almost always impossible. All of
GroIMP's geometry can be exported to POV-Ray, however, some objects like NURBS
surfaces have to be exported as triangle meshes because POV-Ray does not
support them directly. This leads to quite big POV-Ray file
sizes.

The export of GroIMP's materials to POV-Ray is even more
restricted. For some material definitions, it is not possible to export all of
their parts to POV-Ray, so POV-Ray's output may look different from what you
would expect. Manual postprocessing of exported POV-Ray-scenes may be
necessary.