MegaPOV Documentation

MegaPOV 1.1 is an update to POV-Ray™ 3.6. Development of POV-Ray™ 3.6 took longer than expected so MegaPOV 1.1 was delayed as well. We regret this but on the other hand MegaPOV 1.1 now also comes with some useful new features:

Some of the patches from MegaPOV 1.0 are now included in the POV-Ray™ 3.6 update, and some have become obsolete because of changes in POV-Ray™ 3.6. The parts concerning these changes have been removed from this manual, because they are no longer considered as "patches". Here is an overview:

For an overview of the previous versions, (see Section 6.3, “MegaPOV before POV-Ray 3.6”)

Packages with compiled binaries are available for the most common platforms. They can be obtained at the MegaPOV site where you can also find the source code.

The Mac version with its special user interface is maintained separately on Smellenbergh's site.

An online version of the MegaPOV documentation as well as downloadable archives in various formats are located at the MegaPOV site - documentation section.

A preview of the samples coming with MegaPOV can be found in our demo section. The thumbnails there have a link to a larger image (640*480) and an mpeg file in case of animations and some description is available there as well.

	Note
	None of the MegaPOV packages includes the official POV-Ray™ documentation, samples and include files although these are essential for using MegaPOV. If you do not already have installed POV-Ray™ you should get the official version from the POV-Ray™ website.

We don't maintain our own forum for discussions. MegaPOV is an unofficial patch to POV-Ray™ and the MegaPOV-Team is just part of the POV-Ray™ Community. That's why you can use the povray.unofficial.patches group for discussions related to MegaPOV. You can also use povray.binaries.* and povray.text.* groups to upload files related to MegaPOV. All mentioned groups are located on news.povray.org.

The Frame_Step=n (+STPn) option introduces breaks in the order of rendered steps. It splits the order of rendered frames into a 'virtual' and a 'real' order.

'Virtual' order is the same as the traditional (used in POV-Ray™ 3.5) order described with Initial_Frame, Final_Frame, Initial_Clock, Final_Clock, Subset_Start_Frame, Subset_End_Frame. This order is what the scripts reads from initial_frame, clock_delta and other animation related build-in tokens in SDL.

'Real' order is a subset of 'virtual' order. It is every n-th frame where n is the value of Frame_Step. Selected frames are reordered (with ascending or descending order) according to the sign of Frame_Step option.

Frame_Step is supposed to use parallel rendering over one source with one location shared between instances of renderer.

megapov +Iscene.pov Initial_Frame=1 Final_Frame=5 +FN

scene1.png
scene2.png
scene3.png
scene4.png
scene5.png

megapov +Iscene.pov Initial_Frame=1 Final_Frame=5 +FN Frame_Step=-2

scene5.png
scene3.png
scene1.png

	Important
	Frame_Step different than 1 works fine for those animations where variables are not passed between frames when using external files and where the next frame does not use values derived from a previous (in the meaning of virtual order) frame by other ways.

Apart from reading HDR images as image maps (see Section 2.6.6, “HDR (High Dynamic Range) image type”) MegaPOV also supports this file format for image output. Further information on this file format can be found in Section 2.6.6, “HDR (High Dynamic Range) image type” as well.

The file format identification character is H. Writing this file format is activated by the command line option

+FH

or the ini option

Output_File_Type=H

MegaPOV delivers new pre-defined functions. These new internal functions can be accessed through the mp_functions.inc include file, so it should be included in your scene to make use of them.

2.2.4.1. f_triangle

Włodzimierz ABX Skiba

f_triangle function has 10 parameters:

FLOAT f_triangle(FLOAT V1x, FLOAT V1y, FLOAT V1z, FLOAT V2x, FLOAT V2y, FLOAT V2z, FLOAT V3x, FLOAT V3y, FLOAT V3z, FLOAT Thickness);

The parameters V1x, V1y, V1z describe the coordinates of the first vertex in the triangle.

The parameters V2x, V2y, V2z describe the coordinates of the second vertex in the triangle.

The parameters V3x, V3y, V3z describe the coordinates of the third vertex in the triangle.

The parameter Thickness describes how thick the triangle is.

	Note
	In order to achieve the fastest calculation, try to pass the parameters so that the side V1-V2 represents the longest side and V1-V3 represents the shortest side.

The polynomial solver is accessible from scripts via the float functions n_roots and nth_root with the following syntax:

n_roots returns the number of roots derived from the polynomial given by the parameters a_n, ..., a₀ and calculated under the conditions specified by the parameters sturm_flag and epsilon.

nth_root returns the value of the nth root of a given polynomial.

The sturm flag turns on a different algorithm of calculation. Its usage influences the number of returned roots. Epsilon (positive) value means that the roots below Epsilon value are ignored. Epsilon=0 means that none of the roots are ignored.

	Important
	You don't have to call n_roots before nth_root, but if you do call nth_root with the wrong root number then it causes an error and breaks parsing. It is better to call n_roots first to verify the number of available roots.

#declare N=n_roots(1, 6, -1, -6, off, 0);

#declare R0=nth_root(0, 1, 6, -1, -6, off, 0);
#declare R1=nth_root(1, 1, 6, -1, -6, off, 0);
#declare R2=nth_root(2, 1, 6, -1, -6, off, 0);

Instead of patching POV-Ray™ with new camera types MegaPOV provides a tool to define any projection type directly inside the scene scripts. This tool is named user_defined camera type. It allows starting camera rays from any point in any direction. Both the location and direction of rays is specified as a set of three functions or as one pigment.

Syntax is:

camera {
  user_defined
  location { FUNCTION_VECTOR }
  direction { FUNCTION_VECTOR }
}

FUNCTION_VECTOR:
  PIGMENT | 3_USER_DEFINED_FUNCTIONS ...

3_USER_DEFINED_FUNCTIONS:
  USER_DEFINED_FUNCTION
  USER_DEFINED_FUNCTION
  USER_DEFINED_FUNCTION

In the case of 3 functions used to define location or direction, please remember that those functions operate on screen coordinates (u and v) in the area <0,0>-<1,1> so that they are independent of the image resolution. If you want to convert the value from the range 0-1 to the range 0-image_width or 0-image_height you can use the function adj_range from the math.inc include file.

In the case of a pigment used to define location or direction, please remember that the values of the pigment are taken from the area <0,0,0>-<1,1,0>.

camera{
  orthographic
  location <.5,.5,0>
  direction z
  up y
  right x
}

camera{
  user_defined
  location{
    function{u}
    function{v}
    function{0}
  }
  direction{
    function{0}
    function{0}
    function{1}
  }
}

camera{
  user_defined
  location{
    pigment{
      gradient x
      pigment_map{
        [0 gradient y color_map{[0 rgb 0][1 rgb x]}]
        [1 gradient y color_map{[0 rgb y][1 rgb x+y]}]
      }
    }
  }
  direction{
    pigment{rgb z}
  }
}

camera{
  user_defined
  location{
    function{u}
    function{v}
    function{0}
  }
  direction{
    pigment{rgb z}
  }
}

simcloth allows to simulate cloth in MegaPOV. The cloth patch is rectangular, and interacts with its environment (gravity, some obstructing objects, wind, ...).

Syntax is:

  simcloth {
    [ environment OBJECT-IDENTIFIER ]
    [ friction FLOAT ]
    [ gravity VECTOR ]
    [ wind { PIGMENT } ]
    [ viscosity FLOAT ]
    [ neighbors 0 | 1 ]
    [ internal_collision on | off ]
    [ damping FLOAT ]
    [ intervals FLOAT ]
    [ iterations INTEGER ]
    input STRING
    [ output STRING ]
    [ mesh_output STRING ]
    [ smooth_mesh on | off ]
    [ uv_mesh on | off ]
  }

environment is followed by an object identifier. The object should be declared before simcloth {}. This object defines the environment that will interact with the cloth. Although any object can be used, it is recommended to use objects which have well-defined interiors.

friction is a coefficient specifying energy loss when the cloth touches the environment. A low value (<= 0) means a lot of friction and strongly slows the movement of the cloth. A high value (>= 1) will allow the cloth to slide over the objects (but not to bounce off ...). Default value is 1.0

gravity Specifies the direction and the strength of gravity. The default value is <0, 0, 0>.

wind A pigment is used to define the direction and strength of the wind in every space location. At a given point, the wind is defined by the red, green and blue components of the pigment at this point. You can explicitly declare the pigment, or use an already declared identifier. Don't forget that the color components can take any value you want (negative ones, greater than one, ...)

viscosity Specifies the influence of the wind and air friction on the cloth. The default value is 0 (no influence).

neighbors Specifies the number of neighbors that are joined by springs at each point. neighbors 0 is for 8 neighbors (faster but rougher calculation), and neighbors 1 (default value) is for 24 neighbors (slower calculation, but better results).

internal_collision Activates or deactivates internal collision management (cloth against itself). This problem is handled by added springs between points that are too close together. System instability probability is increased, and you must, most often, decrease the intervals parameter (see below). Deactivated by default (warning: much longer parsing when activated).

damping General energy loss parameter, it limits the accumulation of the model approximations and errors. A value lower than 0.95 (default value) is strongly recommended.

intervals specifies the time interval between each iteration. Keep it low. Default value is 0.05.

iterations It's the number of iterations to calculate.

input Filename of the starting *.cth file. The only required parameter, since you need a cloth to start with. For a complete description of the *.cth file format, see below.

output Filename of the ending *.cth file. If this parameter is specified, the result of the simulation is saved. Useful for animations, or for a multi-stage calculation.

mesh_output Allow the program to output a file (with specified name), containing tons of triangles, corresponding to the cloth points after the simulation. It allows you to save the result of a simulation, in a format usable by other POV-Ray™ versions (official or unofficial).

smooth_mesh Activate or deactivate the creation of smooth_triangle's if the mesh_output option is activated. Deactivated by default.

uv_mesh Activates or deactivates uv coordinates within the triangle (or smooth_triangle) if the mesh_output option is activated. UV coordinates go from <0, 0> to <1, 1>. Deactivated by default.

n1, n2, nlng, ks,
Points[0][0], Velocity[0][0],
Points[0][1], Velocity[0][1],
...
Points[0][n2-1], Velocity[0][n2-1],
Points[1][0], Velocity[1][0],
Points[1][1], Velocity[1][1],
...
Points[1][n2-1], Velocity[1][n2-1],
Points[2][0], Velocity[2][0],
...
...
Points[n1-1][n2-1], Velocity[n1-1][n2-1],
Index1, coef1[x], coef1[y], coef1[z],
Index2, coef2[x], coef2[y], coef2[z],
Index3, coef3[x], coef3[y], coef3[z],

This atmospheric glow effect makes a fast-rendering glow effect. It is based on the light source glow effect from POV-AFX, written by Marcos Fajardo, but has been heavily modified.

Syntax is:

glow {
  type 0 | 1 | 2 | 3
  location VECTOR
  size FLOAT
  radius FLOAT
  fade_power FLOAT
  color COLOR
  TRANSFORMATIONS
}

You can specify glows individually, or attached to a light_source. If created in a light source, they will be automatically initialized with the light's position and color (though transforming the light source will not give the expected result).

Choose a glow type from 0, 1, 2 or 3. Type 2 and 3 glows are not completely implemented yet, but 2 will be based on the exp() function and 3 will simulate a sphere with constant density.

The size keyword adjusts the scale of the glow effect. It is not an absolute size, just a scaling amount (because some glows are infinite). It does not quite work properly yet, it causes strange effects with changing distances of objects behind the glow.

The radius keyword specifies a clipping radius confining the glow to a circular area perpendicular to the ray. If the glow is still visible at this radius, it will make a sudden transition.

The fade_power keyword allows you to provide an exponent to adjust the falloff with.

	Note
	A glow is not an object, it is an atmospheric effect. Therefore glows cannot be used in CSG operations. Transformations on a glow only affect the location vector. So will scale not change the size or shape of a glow, but scale the location coordinates.

A motion_blur object is created by averaging many transformed copies of that object. Because only part of the image has to go through some extra calculations, this internal motion blur is usually faster than averaging whole images with an external program.

This patch only does per-object motion blur. The camera cannot be blurred using this method.

Also lights can be blurred using this method: the performance is comparable to the performance of area lights.

To initialize motion blur, add the following to your global_settings block:

  global_settings {
    motion_blur SAMPLES, SHUTTER-TIME
  }

SAMPLES is the number of time-frames that will be sampled. More samples will give smoother results, but will take longer to render.

SHUTTER-TIME is the amount of time the shutter is open in POV-clock units. Depending on the specified type, this time interval will be centered around, or added to the clock value for the current frame.

	Note
	Especially in animations it will give more natural results when this value is kept close to the clock_delta value. You could #declare Shutter_time = clock_delta*Small_factor;

To create a Motion Blur object, use the following syntax:

  motion_blur {
    type 0 | 1
    OBJECT | LIGHT-SOURCE
    OBJECT-MODIFIERS
  }

Type 0 will oscillate the motion blur around the current clock value. Half of the SHUTTER-TIME value is subtracted from, the other half added to that clock value. Type 0 is the default.

Type 1 will add the full SHUTTER-TIME value to the current clock value.

Motion blur is triggered by the keyword clock. Any modifier in the motion_blur block that contains the clock keyword will show a blurring effect on that modifier.

Example:

  motion_blur {
    sphere { 0, 1  material { My_material rotate x*clock}}
    translate x*clock
  }

Here the clock keyword within the material will trigger a rotational blurring of this material and the clock keyword within the motion_blur block will trigger a motion blur in the translation of the sphere.

	Note
	A motion_blur object contains many copies of the blurred object (one copy for each time sample). For this reason, adding this kind of motion blur can use a lot of memory. Be careful of this. (Remember that multiple copies of mesh objects do not use much memory, though.)

	Important
	The blurring is achieved by parsing the contents of the motion_blur object (everything between the curly braces) many times (once for each time sample). Anything outside of the motion_blur block is only parsed once. This means that only one copy gets created of any item declared outside the blur object. And this static copy is applied to each copy of the motion-blurred object.

The fur patch extends media to generate faked three dimensional fur. This is done by "filling" a media container with a new scattering type 6. The light is scattered inside the container approximately like a lot of hairs would scatter them. Furthermore, the density is varied between dense regions ("Here is a hair.") and sparse regions ("Space between the hairs").

The syntax is:

scattering { 6, COLOUR
	[ structure { OBJECT_TYPE } ]
	[ ratio FLOAT ]
	[ falloff FLOAT ]
	[ frequency FLOAT ]
	[ diffuse FLOAT ]
	[ reflection FLOAT ]
	[ reflection_exponent FLOAT ]
	[ force VECTOR ]
	[ waves FLOAT ]
	[ pigment PIGMENT ]
}

OBJECT_TYPE:
  sphere { VECTOR, FLOAT } |
  torus { FLOAT, FLOAT } |
  box { VECTOR, VECTOR } |
  cylinder { VECTOR, VECTOR, FLOAT } |
  cone { VECTOR, VECTOR, FLOAT } |
  plane { VECTOR, FLOAT } |
  smooth_triangle { VECTOR, VECTOR, VECTOR, VECTOR, VECTOR, VECTOR }

In order to simulate fur, we need a structure to which we attach the hairs. The structure provides the positions and directions in which the hairs grow. The possible object types sphere, torus, box, cylinder, cone, plane, and smooth_triangle and their respective parameters are known from POV-Ray™. Remark however, that the provided structure is not necessarily tied to the type of container you use. You are free to fill a (complicated) container with a different (approximating) structure. The default structure is a sphere at the origin with radius 1.

With the next three parameters you can influence the way hairs are grown. The ratio is the ratio between hairs and empty space (default: 0.3). The falloff value describes how fast the density changes from dense (hair) to sparse (space). It you change the default value 0.9, you can create sharper hairs or more fluffy fur. The frequency (default 200.0) determines the scale of the fur (lots of thin hairs vs. fewer thicker hairs).

The next three parameters describe how light is reflected in the media. The diffuse component is similar to the diffuse reflection in usual textures. The default value however is 5.0. The reflection component creates highlights on the hairs. The default reflection is 1.0. The appearance of the reflection can be modified by the reflection_exponent varying from bright spots to soft areas. The default exponent is 1.0.

With the parameter force you can simulate a force pulling the hairs in one direction. Applications include gravity and wind. The vector that you provide determines the direction and the strength of the force.

Curly fur can be created by setting the parameter waves. The larger this parameter is, the bigger the turbulence of the hairs.

Last but not least the fur patch provides a convenient way of setting a pigment of the fur. If you're modelling a tiger or a cow, you can realize the colors by using pigment. The default value is the usual colour of the media. Using a pigment overrides this colour.

The value returned by this pattern is proportional to the angle between a certain ray and the (perturbed) normal at the surface of the object. The range of returned values goes from 0 to 1.

Syntax is:

pigment { aoi [ POINT ] }

When no POINT is given, the incident ray of rendering is used. This is not necessarily the ray coming from the camera, it can also be a secondary ray from reflection or refraction effects.

	Note
	With this option and without reflection and refraction, the range of return values on the visible surfaces goes from 0 to 0.5 since the angle between ray and normal can only be less than 90 degrees

When a POINT is specified, the reference ray for measuring the angle will be the ray between this specified point and the intersection point on the object.

	Important
	This pattern can only be used in situations where the intersection information of the rendering process is available. This applies for usage in pigments, textures and normals but not in media densities or functions.

Syntax is:

pigment {
  listed FLOAT
  color_map { color_map stuff } } |
  pigment_map { pigment_map stuff } }
}

normal {
  listed FLOAT
  normal_map { normal_map stuff } }
}

This "pattern" is simply a solid pattern, the value of FLOAT is used as the return value of the pattern. This means that the pattern listed at the specified FLOAT value is used as the pattern for the whole object.

This is very useful in having a progression of objects blending from one texture to another, and can also be useful in animating textures.

In this pattern the pattern value is determined by shooting a ray in a certain direction. When this ray hits a specified object it returns 1, if not it returns 0. There are a few options to specify the direction of this ray.

Syntax is: