POV-Ray Export

What Files are Saved?

  • output.pov: The master file. It #includes all the other files and has the camera, lighting, and other directives to drive the rendering process.
  • output.0000.inc, etc.: The data files. There is typically one per plot/domain/isolevel, and each contains the coordinates and fields for that chunk.
  • colortables.inc: All the current colortables in the VisIt session.
  • atomicproperties.inc: Atomic radius and other molecular-type properties.

What Data Types are Supported?

Most things are supported. It will render 0D points using a glyph, 1D lines using cylinders, 2D polygons, and a even volume render 3D volumetric data. For geometry with no scalar fields, you can specify a fixed color. For ones with scalar fields, you can specify a value-to-color mapping function with a VisIt color table. For vector fields, you can render those using a glyph as well.

How Do I Render This Using POV-Ray?

Typically, you will simply run povray on your .pov file. For example, you can render a 640x480 image with:

povray +W640 +H480 output.pov

This will generate a view with the camera looking down the Z axis, with a light source located slightly off to the side of the camera.

Why Doesn't the Result Look Exactly Like My VisIt Window?

Because POV-Ray is a raytracing renderer, it supports a lot of things you can't do with a normal polygonal renderer. In fact, it's generally not possible to get an exact match -- for example, while mesh lines are single pixels in a polygonal renderer, in POV-Ray you would have to set a width in terms of spatial units, and so its width in pixels will vary based on the camera location.

One downside of the current implementation is that you will probably want to change the camera, maybe the light sources, and you may want or need to change some scalar to color mapping, or glyphing options, before you get a picture you're happy with. The upside, though, is that we can generate files that are organized and commented, so that it's easy to tweak and change settings to take advantage of all those raytracing-specific features, and get a result which is more than just a raytraced version of what you saw in your VisIt window.

Look at the following sections to learn what to change if you're trying to match the picture VisIt generated.

How Do I Get The Picture I Want?

An Example .pov Master File

This is an example .pov file generated when saving a window to the POV-Ray format.

#include "colortables.inc"
#include "atomicproperties.inc"
#include "math.inc"
#include "transforms.inc"

// Keep it fast for now
global_settings {
    max_trace_level 8
    adc_bailout 1/128.
}

// Sizes for glyph objects
#declare VertFixedSize = 0.3; // absolute scale
#declare VertScaleSize = 0.0; // scale by value
#declare LineWidth     = 0.1; // absolute scale only
#declare VecFixedSize  = 1.0; // absolute scale
#declare VecScaleSize  = 0.0; // scale by value

// Default scale function for vertex glyph objects with a scalar value
#macro VertScaleFunction(value)
  VertFixedSize + value*VertScaleSize
#end

// Default scale function for vector glyph objects
#macro VecScaleFunction(vec)
  VecFixedSize + vlength(vec)*VecScaleSize
#end

// Glyph objects (normalized to unit-1 size)
#declare VertGlyph = object { sphere {<0,0,0>,1} };
#declare VecGlyph = object { union { object { cylinder {<0,0,0>,<0,.5,0>,.1} } object { cone {<0,.5,0>,.3,<0,1,0>,0} } } };

// Default pigments for geometries without scalar values
#declare VertPigment = pigment { rgb<.6,0,0> };
#declare LinePigment = pigment { rgb<.6,.6,.6> };
#declare PolyPigment = pigment { rgb<0,.4,.8> };
#declare VecPigment  = pigment { rgb<.4,.3,.8> };

// To force single pigment for the geometries, set these to 1
#declare ConstantVertColor = 0;
#declare ConstantLineColor = 0;
#declare ConstantPolyColor = 0;
#declare ConstantVecColor  = 0;

// Finishes for each type of geometry
#declare VertFinish = finish {ambient .3 reflection .0 diffuse .8 specular 0.2 roughness 0.1};
#declare LineFinish = finish {ambient .3 reflection .0 diffuse .8 specular 0.2 roughness 0.1};
#declare PolyFinish = finish {ambient .3 reflection .0 diffuse .8 specular 0.2 roughness 0.1};
#declare VecFinish  = finish {ambient .3 reflection .0 diffuse .8 specular 0.2 roughness 0.1};

// Clamp values for scalar quantities, and a default linear map to [0,1]
#macro ScalarNormalize(value)
  (clip(value,min_scalar_value,max_scalar_value)-min_scalar_value)/(max_scalar_value-min_scalar_value)
#end
#declare min_scalar_value = 1.53137;
#declare max_scalar_value = 5.45382;
//note: min/max = 1/108 for elements and 0/108 for residues

// Extents and sizes of spatial geometries
#declare xmin = -10;
#declare xmax = 10;
#declare ymin = -10;
#declare ymax = 10;
#declare zmin = -10;
#declare zmax = 10;
#declare xsize = (xmax - xmin);
#declare ysize = (ymax - ymin);
#declare zsize = (zmax - zmin);
#declare xcenter = (xmin + xmax) / 2.;
#declare ycenter = (ymin + ymax) / 2.;
#declare zcenter = (zmin + zmax) / 2.;
#declare ds_size = sqrt(xsize*xsize + ysize*ysize + zsize*zsize);

// Set up the color table default
#declare colortable = ct_levels;

// Set up the color table and opacity for volume renderings
#declare volren_colortable = ct_hot;
#declare volren_opacity = color_map {
   [0.00  color  0.0]
   [1.00  color  1.0]
};

// The emission for volume plots typically needs to scale with data set size
#declare volren_attenuation = 2.0 / ds_size;

// Set some variables to make camera/light source positioning easier
#declare aspect       = 4/3;
#declare scene_origin = <xcenter,ycenter,zcenter>;
#declare camera_at    = scene_origin;
#declare camera_pos   = scene_origin + z*ds_size*2.5;
#declare camera_up    = y;
#declare viewangle    = 40;

// Set the camera/aspect from the given parameters
camera {
    location camera_pos
    right    -x*aspect
    look_at  camera_at
    sky      camera_up
    angle    viewangle
}

// Set the light source near the camera
light_source {
    camera_pos color 1
}

// Include the declarations for all chunk geometries

//
// NOTE: To change the colortable, scalar clamps, pigments,
//       finishes, etc. for different chunks, just redeclare
//       them in between the appropriate include files here.
//

#include "output.0000.inc"
#include "output.0001.inc"

// Instantiate all chunk geometries
#if (nverts0000 > 0) object { vertex_geometry0000 }  #end
#if (nvecs0000  > 0) object { vector_geometry0000 }  #end
#if (nlines0000 > 0) object { line_geometry0000   }  #end
#if (ntris0000  > 0) object { poly_geometry0000   }  #end
#if (nvols0000  > 0) object { volume_geometry0000 }  #end

#if (nverts0001 > 0) object { vertex_geometry0001 }  #end
#if (nvecs0001  > 0) object { vector_geometry0001 }  #end
#if (nlines0001 > 0) object { line_geometry0001   }  #end
#if (ntris0001  > 0) object { poly_geometry0001   }  #end
#if (nvols0001  > 0) object { volume_geometry0001 }  #end

The Master .pov File Structure

The sections of the .pov file are, in order, as follows:

  • General include directives. The included files are both VisIt generated ones (like color tables) and POV-Ray built-in files (like trigonometric functions).
  • Tracing directives. These set some reasonable default cutoffs to keep runtime in check without affecting picture quality noticeably.
  • Geometry scales. The default glyphing functions scale the glyph sizes (sphere radius, cylinder widths) linearly with the scalar quantity at that point using these constants.
  • Geometry scaling functions. These define a default 1st order polynomial for glyph scaling which use the above constants.
  • Glyph objects. These include the object definitions for the default point and vector glyphs.
  • Geometry pigments. These are the colors to use for any geometry which doesn't have any scalar values for a scalar-to-color mapping.
  • Constant color flags. If you wish to override scalar-to-color mapping for any geometry type even when it has scalars, set these to 1.
  • Geometry finishes. These are the surface properties apart from color, and apply to single-color or color-mapped geometry alike.
  • Scalar mapping parameters. By default this is a linear ramp, from the min to max value to [0..1]. Note that any mapping function must not result in a value outsize [0,1].
  • Geometric extents. These are useful for setting camera and light source positions, or creating new geometry to lie in the scene.
  • Volume rendering parameters. These are the color map and opacity map, as well as the attenuation for emissive cells.
  • Camera and light source settings. The defaults set here are appropriate to the scene size.
  • Geometry include directives. These contain the arrays and macros to define the geometry of the scene and apply material properties. These are typically one per plot/domain/isolevel, so if you need to change some values like colormaps or glyph parameters between plots, add them between these include directives.
  • Geometry instantiation. Some plots may have geometry which you which to not instantiate. One example is a Mesh Plot which contains both lines and surfaces, and VisIt will typically hide those surfaces if it is redundant with other geometry. If you need to remove some geometry from your scene, comment out the relevant lines in this section.

Editing the .pov File

While it helps to know POV-Ray syntax, many simple changes should be self-evident and be done even by those unfamiliar with POV-Ray syntax.

Setting the Camera

Due to a limitation of the current implementation, your camera will not be in the same place as the one inside VisIt when you saved the window. Still, you can transfer your settings from the "3D view" tab of VisIt's View window to the camera settings. Most of these are identical between the two, except for the names (e.g. "focus" is the same as "look_at"). The one exception is the camera location: in VisIt, this is determined by a view direction and a parallel scale. The exact mapping is this:

 location = focus + view_normal*(parallel_scale/tan(radians(view_angle)/2))

Setting the Geometry

The default glyph scaling values may be wrong for your scene. For example, line widths (cylinders here) are fixed in terms of world units, and you can simply change the width. Points are typically rendered as spheres, and you have the capability to change both the glyph shape and scale its size by point value instead of leaving it at a fixed size. For example if VertFixedSize is 1.0 and VertScaleSize is 0.0, then all your spheres will be of radius 1. If VertFixedSize is 0.0 and VertScaleSize is 3.0, then the sphere at any point will have radius 3 times the scalar value at that point. If you'd like something more than a simple linear scaling, you can change the VertScaleFunction. And if you'd like to change the glyph shape, you can define a new object for VertGlyph.

Setting the Colors

For objects with no scalars, you can set the appropriate pigment for its geometry type. If the object has scalars and you still wish to render it with a single pigment color, you will need to set the appropriate ConstantColor flag, e.g. setting ConstantVertColor to 1 will force vertices to be rendered with a single color even if it has a scalar field associated with it.

For objects with scalars, the default color ramp is linear, from the min to the max value in the scene. You can change the scaling function as necessary, even to get a nonlinear ramp, but note that POV-Ray is sensitive to any values outside the [0,1] ramp range used for these colortables. As the default min/max values are obtained across all plots in the scene, you may need to ensure these values are appropriate for all plots, potentially setting them per-plot.

Per-Plot Settings

Note that you may need different values for different plots in your scene, such as changing color tables, min/max values for color ramps, or geometry glyph parameters; simply re-declare these values as appropriate between the geometry include directives in the lower section of the file.. Note that you should not re-declare them between the instantiation directives below those include directives. At that point it is too late; the only modification which makes sense for the instantiation directives is to comment one out in case one of your plots has geometry you need to remove from the scene, such as removing the hidden-surface-removal polygons in a Mesh plot while keeping the mesh lines.

Advanced Features

For much beyond these settings, you are likely to be diving into POV-Ray language territory. Still, some things, like changing the reflection coefficient to get shiny/reflective objects, should be easy to add by modifying the finish properties. Others, like making an area light or adding a ground plane, are simple modifications that you can copy+paste from other examples.

Where Can I Find More Information?