MegaPOV Documentation

The #set keyword modifies the most recently created version of a variable. So, if a variable has been created previously with either #declare or #local, its value can be changed with the #set directive.

#declare MyCounter = 0:
#set MyCounter = MyCounter + 1;

Another advantage is that if you try to change a variable that doesn't yet exist, it produces an error. This could happen if you make a typing mistake, like this:

#declare MyCounter = 0;
#while (MyCounter < 10)
  #declare MyCountr = MyCounter+1;
#end

This would normally cause an infinite loop, and may take a while to track down, especially in complex scenes and with typos that "look right" at a glance. If #set was used, it would cause an error ("#set cannot assign to uninitialized identifier MyCountr.") at that line, pointing you directly at the problem.

POV-Ray™ 3.5 in its official release does not accept all built-in constants and variables to be used in functions. Following tokens are recognized additionally in VM since MegaPOV 1.0: clock_delta, clock_on, false, final_clock, final_frame, frame_number, initial_clock, initial_frame, image_height, image_width, no, off, on, true, version, yes . All mentioned tokens return the same values as in the whole SDL parser.

As other animation options, also Frame_Step has its own equivalent in SDL. You can use the frame_step key-word to get the value which was passed to Frame_Step (see Section 2.1.1, “Frame_Step”). Default value is 1.

With the keyword date, time and/or a date can be used in your images. This might be useful in a macro to place a time stamp in your images, along with your name. The keyword date works like other string functions, except that you have to supply a format string.

#declare TheString=date("%a %B")

The most flexible implementation was chosen (which is probably not the easiest ...) because not all countries write dates in the same way. Just think of the difference between the USA and most parts of Europe. These are the possible specifiers for the format string: Please note that these should be equal for all platforms but if you don't get the expected result, contact the person who compiled your version to find out if there are differences.

	Note:
	To use the '%' character in the result, use it twice: date("%%")

Refer to date.pov for an example scene. Please note that you might have to write the result in a file if you want to abort the rendering and continue later on. Otherwise you could get a different result because time goes on :-)

The keyword start_chrono sets an internal variable and returns the current internal clock counter of your computer. The return value is not important. However, you must assign this return value from start_chrono otherwise you get an error. Use it like this:

#declare Stopwatch = start_chrono;

or use it like this:

#if (start_chrono)

but not:

start_chrono //parsing stops with a fatal error

The keyword current_chrono returns the time in full seconds (no fractions of seconds) between start_chrono and current_chrono. The start value is not changed. A second current_chrono will still return the seconds between start_chrono and the second current_chrono.

If you don't call start_chrono somewhere before you call current_chrono, you will get the seconds elapsed since the beginning of the current render (parsing).

//reset the chrono and return the internal clock counter
#declare ParseStart = start_chrono; 

... syntax to be parsed

//read the seconds elapsed since chrono_start
#declare ParseEnd = current_chrono;
#debug concat("\nParsing took ",str((ParseEnd, 1, 0)," seconds\n")

Refer to chrono.pov for a demo scene.

Some animators want to use filenames of previous, already rendered frames to average them to mimic motion_blur in one turn. But the concatenation of filename with frame number is not a trivial thing and can be platform dependant. MegaPOV allows you to get n-th filename of current animation. For stills it always returns filename without numbers.

Syntax is:

#declare File_Name=output_filename(Frame_Number)

#if(mod(frame_number,10)=9)
  #declare Averaged_Frames=pigment{
    average
    #local Counter=1;
    #while(Counter<10)
      [1 image_map{output_filename(frame_number-Counter)}]
      #set Counter=Counter+1;
    #end
  }
  // placing of pigment in output area
#else
  // conventional scene
#end

You probably already know that the image_width and image_height keywords return the sizes of a rendered image. But there are cases when you would like to change the content of a scene depending on the sizes of the images used for maps. For this purpose the image_width and image_height keywords are extended with an optional parameter which is the identifier of an item using an image.

Syntax is:

#declare Identifier=image_width [ (ITEM_WITH_IMAGE) ];
#declare Identifier=image_height [ (ITEM_WITH_IMAGE) ];

ITEM_WITH_IMAGE: PIGMENT_ID | NORMAL_ID | TEXTURE_ID

The usage of the dimension_size is extended since MegaPOV 1.1 with a measurement of floats, vectors and colors. If you want to write a universal script which works differently depending on the number of components in an identifier, you can use the dimension_size to get 1,2,3,4 or 5 as number of the components in the given identifier.

Syntax is:

#declare Identifier=dimension_size ( FLOAT | VECTOR | COLOR );

MegaPOV 1.1 allows the verification of the type (and in some cases subtypes) of identifiers. It is possible thanks to the is function which tests the internal type of an identifier.

Syntax is:

#declare Identifier=is ( IDENTIFIER , TYPE | SUBTYPE );

TYPE: array | camera | color | 
      color_map | density | density_map | 
      finish | float | fog | 
      function | interior | light_source | 
      material | media | normal | 
      normal_map | object | pigment | 
      pigment_map | rainbow | sky_sphere | 
      slope_map | spline | string | 
      texture | texture_map | transform | 
      vector

SUBTYPE: SPLINE_TYPE | OBJECT_TYPE | CAMERA_TYPE

SPLINE_TYPE: akima_spline | basic_x_spline | 
             cubic_spline | extended_x_spline | 
             general_x_spline | linear_spline | 
             natural_spline | quadratic_spline | 
             sor_spline | tcb_spline 

OBJECT_TYPE: bicubic_patch | blob | box | 
             cone | cubic | cylinder | 
             disc | height_field | intersection | 
             isosurface | julia_fractal | lathe | 
             merge | mesh | parametric | 
             plane | poly | polygon | 
             prism | quadric | quartic | 
             smooth_triangle | sor | sphere | 
             sphere_sweep | superellipsoid | text | 
             torus | triangle | union

CAMERA_TYPE: cylinder | fisheye | omnimax | 
             orthographic | panoramic | perspective | 
             spherical | ultra_wide_angle | user_defined

	Important
	Internally mesh2 is stored as mesh. Similar difference is stored as intersection.

An example using the is keyword can be found in the mp_types.inc include file (see Section 3.3, “The 'mp_types.inc' include file”).

f_triangle function has 10 parameters:

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.

Splines in POV-Ray™ can be used to create objects through rotation, translation or by being a border of a surface. Usually it is hard to match those surfaces with calculations developed in SDL because they are mostly hard-coded within the source core code of POV-Ray™. The spline feature introduced in POV-Ray™ 3.5 makes such operations much easier but some spline types are still missing. sor_spline is introduced to access the surface of the sor object in SDL.

To use the data from the sor object in a sor_spline, the order of coordinates has to be changed. The old y coordinate is now the clock value in the spline. The advantage is that one sor_spline can hold data from five old sor-s. That's because every spline can operate up to five dimensions along the clock value.

spline{
   sor_spline
  -1.000000,0.000000*x
   0.000000,0.118143*x
   0.540084,0.620253*x
   0.827004,0.210970*x
   0.962025,0.194093*x
   1.000000,0.286920*x
   1.033755,0.468354*x
}

sor{
  7
  <0.000000, -1.000000>
  <0.118143,  0.000000>
  <0.620253,  0.540084>
  <0.210970,  0.827004>
  <0.194093,  0.962025>
  <0.286920,  1.000000>
  <0.468354,  1.033755>
}

An akima_spline is a spline that goes smoothly (pleasingly for some) through all points. ACM Press abstracts original work of Hiroshi Akima:

Syntax is:

spline {
  akima_spline
  time_Val_1, <Vector_1> [,]
  time_Val_2, <Vector_2> [,]
    ...
  time_Val_n, <Vector_n>
}

This spline is also known as Kochanek-Bartels spline.

Syntax is:

spline {
  tcb_spline [TCB_PARAMETERS]
  time_Val_1 [TCB_PARAMETERS], <Vector_1> [TCB_PARAMETERS][,]
  time_Val_2 [TCB_PARAMETERS], <Vector_2> [TCB_PARAMETERS][,]
    ...
  time_Val_n [TCB_PARAMETERS], <Vector_n> [TCB_PARAMETERS]
}

TCB_PARAMETERS:
  [tension FLOAT] [continuity FLOAT] [bias FLOAT]

The tension, continuity and bias are fully optional. Depending on the place where they appear, they control the spline in different ways:

What is controlled by these parameters?

	Note
	A tcb_spline needs additional control points before and after the spline. This is required to control the first and last segment of the spline.

A very nice property of x splines is that they can go through a control point as well as just approximate it.

2.2.6.4.1. basic x spline

Włodzimierz ABX Skiba

Syntax is:

spline {
  basic_x_spline [freedom_degree FLOAT]
  time_Val_1, <Vector_1> [,]
  time_Val_2, <Vector_2> [,]
  ...
  time_Val_n, <Vector_n>
}

	Note
	A basic_x_spline needs additional control points before and after the spline. This is required to control the first and last segment of the spline.

spline {
  extended_x_spline [freedom_degree FLOAT]
  time_Val_1, <Vector_1> [freedom_degree FLOAT ][,]
  time_Val_2, <Vector_2> [freedom_degree FLOAT ][,]
  ...
  time_Val_n, <Vector_n> [freedom_degree FLOAT ]
}

spline {
  general_x_spline [freedom_degree FLOAT]
  time_Val_1, <Vector_1> [freedom_degree FLOAT ][,]
  time_Val_2, <Vector_2> [freedom_degree FLOAT ][,]
  ...
  time_Val_n, <Vector_n> [freedom_degree FLOAT ]
}

Since MegaPOV 1.0 it is possible to read values stored in a spline with a notation similar to an array. Previously once the spline was declared, it was only possible to evaluate it for a specified argument. Now two new usages are possible: you can get the number of entries and read the exact values placed in splines.

SPLINE_USAGE:
  SPLINE_EVALUATION | SPLINE_MEASUREMENT | SPLINE_ENTRY

SPLINE_EVALUATION:
  #declare Spline_Value = MySpline(Val);
  #declare Spline_Value = MySpline(Val, SPLINE_TYPE);

SPLINE_MEASUREMENT:
  #declare Number_Of_Entries = dimension_size( MySpline );

SPLINE_ENTRY:
  #declare Float_Time_Parameter = MySpline[ Counter ][ 0 ];
  #declare Vector_Value_Of_Entry = MySpline[ Counter ][ 1 ];

This patch adds a new option to the transform syntax that modifies the transform to be suited for transforming normal vectors.

When a mesh is transformed by the transformation matrix M the normals need to be transformed with the transpose of the inverse of M. This is handled automatically by this patch.

Syntax is:

transform {
  ...
  normal on|off
}

The default value is off so you get a standard transform.

With MegaPOV, in every test using Inside of objects the bounding object has now priority. It first tests if the point is inside the bounding. If it is not then it knows that it can already decide that the point is outside (if the object is not inversed) or that the point is inside (if the object is inversed).

This should increase rendering speed of complicated CSG objects, since it could eliminate a lot of computing steps. The inside test is firstly done for the bounding object. Only when this test is inside the bounding, the tests against each of the objects composing the CSG object will be done.

Based on the text enhancement idea of Jamis Buck and Noel Bundy, but modified and extended.

Syntax is:

text {
  the usual text stuff
  ...
  [ h_align_left | h_align_center | h_align_right ]
  [ v_align_top | v_align_center | v_align_bottom ]
}

h_align_left By adding this keyword to the text block, the text string (including horizontal offset) is aligned horizontally so that its most left point touches the y-axis. This is identical to the default alignment.

h_align_center By adding this keyword to the text block, the text string (including horizontal offset) is aligned horizontally so that it extends equally on both sides of the y-axis.

h_align_right By adding this keyword to the text block, the text string (including horizontal offset) is aligned horizontally so that its most right point touches the y-axis.

v_align_top By adding this keyword to the text block, the text string (including vertical offset) is aligned vertically so that its highest point touches the x-axis.

v_align_center By adding this keyword to the text block, the text string (including vertical offset) is aligned vertically so that its middle height sits on the x-axis.

v_align_bottom By adding this keyword to the text block, the text string (including vertical offset) is aligned vertically so that its lowest point sits on the x-axis.

	Note
	When no alignment is specified, the POV-Ray™ defaults are used. Horizontally to the left and vertically on the base line. The old keyword "position" of previous MegaPOV versions is no longer supported.

The file format is simple: the first line describes the cloth dimensions (number of points n1 and n2, normalized length between 2 neighbors nlng), and the springs strength ks. The other lines describe the location in space and velocity of each point. All values (3 for location, 3 for speed) are separated by commas, and each line is terminated by a comma as well.

Then, there are the constraints definitions. Constraints are 3 coefficients (1 for each axis) that will control the velocity vector of a given point of the cloth. It will be possible, for instance, to slow down a corner of the cloth along one axis, to completely stop it along another axis, and let it free along the last one. A constraint is defined by an integer (index), and 3 floating point coefficients, representing the constraint (respectively on x, y, z axis), all this on the same line and separated by commas. The index is the rank of the point (beginning at 0) in order of declaration of the cloth points. Constraints can be declared in any order.

You could see the cloth as 2 arrays of vectors Points[n1][n2], and Velocity[n1][n2], and its constraints Indexn, coefn. The *.cth file will look like this:

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],

For an example of a macro writing such a file (see Section 4.1.1.1.1, “Writing a *.cth file”).

In POV-Ray™ 3.5 the messages concerning the max_gradient follow a heuristic method to be displayed. This means that the message only appears when the difference with the set max_gradient is more than a certain percentage. Also when using a loop with hundreds of isosurfaces which have different max_gradient's, you need to wait after the render for all those messages to be displayed: this can take several minutes. Basically, you cannot control these messages.

In MegaPOV 1.0 you can use the keyword message to control the message flow:

This keyword is used in the isosurface{} block and should be used after the function{} block and before any material.

By using conditional expressions, you can now control messages in a loop.

In POV-Ray™ 3.5 and earlier temporary files with cache of radiosity were named the same for every frame in the animation rendering. Since MegaPOV 1.0 the name of this file is concatenated from the name of the currently rendered image. Together with Frame_Step (see Section 2.1.1, “Frame_Step”) and this addition it is finally possible to start two parallel processes with radiosity rendering over one source.

The radiosity function in POV-Ray™ 3.5 uses an internal table of directions for the rays that are traced from a sampling point to determine the irradiance at that point. This patch allows to select alternative sets of sample ray directions. This can help both to overcome the limit for maximum count of 1600 as well as improve the quality of results at lower count values.

The syntax description of this feature is:

RADIOSITY_ITEMS:
    ...
    [ samples SAMPLES_ITEMS ]

SAMPLES_ITEMS:
    INT_SAMPLES_TYPE |
    {
      SAMPLES_COUNT,
      VECTOR_DIRECTION, ...
      [weight INT_WEIGHT_TYPE]
    }

2.7.2.2.1. internally generated directions

MegaPOV contains an internal generator for sample direction using the halton sequence written by Mael. It is activated by adding:

samples 1

to the radiosity{} block. The default value (0) uses the old internal direction table.

Table 2.4. internal sequence

50 rays	300 rays	1600 rays

Table 2.5. halton sequence

50 rays	300 rays	1600 rays

2.7.2.2.2. user defined directions

The sample ray directions can also be defined directly in the scene file:

samples {
  300, // number of directions given
  <0.78080, -0.36618, 0.50622>,
  <-0.26409, -0.01064, 0.96444>,
  ...
}

A number of sample direction sets is coming with MegaPOV as include files.

The coordinate system for these sample ray directions is relative to the surface at the sample position. The z-Axis points in normal direction. All directions should be in the upper hemisphere (z coordinate >0).

An optional weight parameter allows to weight the sample intensity with cos(theta) where theta is the angle between the normal vector and the ray direction. The sample ray directions should have a density distribution according to this function. If a uniform distribution is used instead weight 1 would weight the sample rays to compensate this. The default is 0 which turns off special weighting.

This patch is based on an idea by Michael Andrews. Normally the distribution of radiosity rays is identical for all sample points. This patch rotates the sample set around the vertical axis by a random angle for each sample taken. This can help to reduce artefacts in some cases.

This patch is activated the following way:

radiosity {
  ...
  randomize on
}

	Note
	Since this feature uses a random number for the sample direction rotation it is not safe to use it in animations. Also a partial render of a scene will produce different results than rendering the whole scene.

This patch introduces a new block in the global_settings{} section of the POV-Ray™ scene file.

The complete syntax description of this block is:

MECHSIM:
    mechsim { [MECHSIM_ITEMS...] }
MECHSIM_ITEM:
    method INTEGER | bounding INTEGER | 
    gravity VECTOR | time_step FLOAT |
    step_count INTEGER | time FLOAT | start_time FLOAT |
    end_time FLOAT
    environment { ENVIRONMENT_DEFINITION [ENVIRONMENT_ITEMS...] } |
    interaction { INTERACTION_DEFINITION ... } |
    field { FIELD_DEFINITION ... } |
    attach { ATTACH_DEFINITION ... } |
    collision { COLLISION_TOGGLE [COLLISION_ITEMS...] } |
    topology { [GROUP_DEFINITIONS...] [TOPOLOGY_ITEMS...]
               [save_file FILE_NAME [Type]] }
ENVIRONMENT_DEFINITION:
    function [(IDENT_LIST)] { FUNCTION_ITEMS } | object OBJECT
ENVIRONMENT_ITEM:
    stiffness FLOAT | damping FLOAT | friction FLOAT [, FLOAT] |
    method INTEGER
INTERACTION_DEFINITION:
    function [(IDENT_LIST)] { FUNCTION_ITEMS }
FIELD_DEFINITION:
    function { SPECIAL_COLOR_FUNCTION }
ATTACH_DEFINITION:
    function { SPLINE }
COLLISION_TOGGLE:
    [INT_MASS_MASS [, INT_MASS_FACE [, INT_CONNECTION_CONNECTION]]]
COLLISION_ITEM:
    stiffness FLOAT | damping FLOAT | friction FLOAT [, FLOAT]
GROUP_DEFINITION:
    group [(INT_GROUP_INDEX)] { TOPOLOGY_ITEMS... }
TOPOLOGY_ITEM:
    mass { V_POSITION, V_VELOCITY, F_RADIUS
           mass FLOAT | density FLOAT [attach INTEGER] [fixed BOOL] } |
    connection { INDEX1, INDEX2 [stiffness FLOAT] [damping FLOAT]
                 [length FLOAT] } |
    face { INDEX1, INDEX2, INDEX3 } |
    load_file FILE_NAME

2.7.3.1.1. The general settings

Some general parameters can be given in the top level of the mechsim{} section.

The default values are:

method : 1

bounding : 0

gravity : <0, 0, 0>

time_step : 0.1

step_count : 10

2.7.3.1.1.1. method

Selects the integration method used for solving the equations of movement.

Possible values are:

• 1 (MECHSIM_METHOD_EULER) simple forward Euler integration method
• 2 (MECHSIM_METHOD_HEUN) second order (Heun) integration method
• 3 (MECHSIM_METHOD_RUNGE_KUTTA) fourth order Runge Kutta integration method
• 4 (MECHSIM_METHOD_GRADIENT) gradient descent method

Method 1 is a first order integration method also known as explicit Euler method. With the differential equations of movement written as:

y being the state of the system (positions and velocities) and the initial conditions y(t₀)=y₀ the Euler method can be written as:

Method 2 is a second order integration method known as Heun's method. Its formula is:

Method 3 is a fourth order integration method known as the classical Runge-Kutta method:

2.7.3.1.1.2. bounding

Selects the bounding method to speed up collision detections.

Possible values are:

• 0 (MECHSIM_COLLISION_BOUNDING_NO) no bounding system
• 1 (MECHSIM_COLLISION_BOUNDING_AUTO) automatically select method 0, 2 or 3 depending on complexity
• 2 (MECHSIM_COLLISION_BOUNDING_BOX) speed up using bounding boxes
• 3 (MECHSIM_COLLISION_BOUNDING_HASH) speed up using spatial hashing

The bounding techniques have been implemented by Daniel Jungmann and are in an experimental state. The internal workings as well as the use are likely to change in future versions.

2.7.3.1.1.3. gravity

Applies an overall constant gravitational force to all masses.

A vector is expected, the unit is m/s².

Standard earth gravity (with y=up coordinates) is:

gravity <0, -9.81, 0>

With field functions (see Section 2.7.3.1.6, “Field forces”) non constant gravity can be simulated

2.7.3.1.1.4. simulation stepping

All simulation methods use discrete time steps for calculating the simulation. There are three parameters to steer this but only two are needed to correctly define the stepping. The formula for calculating the third is:

Step_Count = Time / Time_Step

An optional start_time value allows to specify a starting time different from 0. Changing this can influence the attach and environment function. (see Section 2.7.3.1.7, “Attaching masses” and Section 2.7.3.1.2, “The environments”) Specifying an end_time value instead of time is also possible.

	Important
	Using too large time steps can lead to instability in the simulation. MegaPOV will recognize this in most cases and stop simulation with an error message but this does not mean the simulation is correct as long as no error is reported. Simulation results should always be checked for plausibility.

#declare fn_Env=function(x, y, z, tim) { z-tim }

global_settings {
  ...
  mechsim {
    ...
    environment {
      function(x, y, z, tim) { fn_Env(x, y, z, tim) }
      ...
    }
  }
}

2.7.3.1.3. The collision settings

The collisions referred to here are not environment collisions but collisions between the simulation elements. Since detecting this kind of collision is quite computationally intensive it is turned off by default.

With three numbers at the beginning of the collision{} section collision can be toggled for mass-mass-collisions, mass-face-collisions and connection-connection-collisions. All these parameters are optional, the meaning of the possible values is:

• 0 (MECHSIM_COLLISION_NONE) No collisions of this kind are calculated.
• 1 (MECHSIM_COLLISION_ALL) Collisions between all simulation elements are calculated.
• 2 (MECHSIM_COLLISION_GROUP) Only collisions between elements of different groups are calculated.

Figure 2.3. Mass-mass collisions illustration

Figure 2.4. Mass-face collisions illustration

Figure 2.5. Connection-connection collisions illustration

Internal collisions are always calculated with forces. The same three parameters like in the environment settings can be used to specify the properties

• stiffness The elasticity parameter of the surface. The unit is N/m or kg/s².
• damping A damping constant (unit kg/s)
• friction The friction factor controls the amount of friction during collisions. An optional second parameter, the friction excess value should usually be slightly larger than 1 and causes the friction to occur already slightly before the collision. This can be helpful to obtain realistic results.

Example 2.11. An example for a complete collision{} section:

global_settings {
  ...
  mechsim {
    ...
    collision {
      2, /* mass-mass collisions between elements of different groups */
      0, /* no mass-face collisions */
      0  /* no connection-connection collisions */
      stiffness 20000
      damping 4000
      friction 0.2, 1.01
    }
  }
}

2.7.3.1.4. The topology

The topology{} section is the central part of the whole simulation settings. Here the simulation elements, their positions and properties, can be defined.

2.7.3.1.4.1. The topology items

There are three topology items: masses, connections and faces. Each of them has several parameters that can be set.

The mass block defines a point mass. These are the central elements of the simulation. Their movement is calculated by the simulation system.

The mass block contains the following elements:

• The first item is a vector specifying the position of them mass (unit: m).
• The second item, also a vector, represents the velocity of them mass (unit: m/s).
• The third item is a float standing for the radius of the mass (unit: m). This radius is only used in collision calculations (see Section 2.7.3.1.3, “The collision settings”). Otherwise the mass behaves as a point mass.

In addition either the mass (unit: kg) or the density (unit: kg/m³) of the element has to be given. If density is specified the resulting mass is calculated automatically. An optional boolean parameter (fixed) prevents the mass from moving if set to true.

A complete example for a mass definition:

mass {
  <0, 0, 1>, /* position */
  <1, 0, 0>, /* velocity */
  0.1        /* radius */
  density 600
  // mass 2
  // fixed true
}

The connection block defines a connection between two point masses. It can have elastic and dissipative properties.

The first two elements of this block are integer numbers specifying the indices of the masses to connect.

There are three optional parameters: The stiffness value specifies the elasticity of the connection (unit N/m or kg/s²). damping the velocity proportional damping factor (unit kg/s). The default value for both of these is zero. The third parameter allows to specify a relaxed length of the connection. If it is not specified the distance of the two masses is used for this property.

A complete example for a connection definition:

global_settings {
  ...
  mechsim {
    ...
    topology {
      mass { ... }  /* mass with index 0 */
      mass { ... }  /* mass with index 1 */

      connection {
        0,          /* index of the first mass */
        1           /* index of the second mass */
        stiffness 10000
        damping 2000
        // length 0.5
      }
      ...
    }
  }
}

The face block defines a triangular face between three point masses. It is used for collision calculations (see Section 2.7.3.1.3, “The collision settings”) and can be useful for generating a mesh from the simulation data for display.

There are three integer numbers in the block, the indices of the masses forming the face.

A complete example for a face definition:

global_settings {
  ...
  mechsim {
    ...
    topology {
      mass { ... }  /* mass with index 0 */
      mass { ... }  /* mass with index 1 */
      mass { ... }  /* mass with index 2 */

      face {
        0,          /* index of the first mass */
        1,          /* index of the second mass */
        2           /* index of the third mass */
      }
      ...
    }
  }
}

2.7.3.1.4.2. grouping elements

Simulation elements can be categorized into groups. The main purpose of this is to speed up collision tests. The group keyword can be followed by an integer number in parentheses to explicitly specify the group. Otherwise the group index is determined automatically.

global_settings {
  ...
  mechsim {
    ...
    topology {
      mass { ... }  /* these elements are group index 0 */
      ...
      group {
        mass { ... } /* these elements are group index 1 */
      }
      group {
        mass { ... } /* these elements are group index 2 */
      }
      group (1) {
        mass { ... } /* these elements are group index 1 */
      }

      ...
    }
  }
}

2.7.3.1.4.3. saving and loading topology data

The topology data can be written to and loaded from files. For the format of these files see Section 2.7.3.3, “The simulation data file format”.

save_file can only be added to the main topology{} block. It saves the complete data after the simulation to the specified file.

load_file can be placed anywhere in the topology{} section. If placed in a group the elements in the file are added to that group. Otherwise they are are placed in groups according to group index information in the file.

The same file name can be specified for both loading and saving the data. This is especially useful for animation when the following frame simulation should start with the result of the last frame:

global_settings {
  ...
  mechsim {
    ...
    topology {
      load_file "mechsim_data.dat"
      save_file "mechsim_data.dat"
    }
  }
}

#declare fn_Force=function(x, y, z, dist) { 1/(dist*dist) }

global_settings {
  ...
  mechsim {
    ...
    interaction {
      function(x, y, z, dist) { fn_Force(x, y, z, dist) }
      ...
    }
  }
}

#include "mechsim.inc"

global_settings {
  ...
  mechsim {
    ...
    field {
      function {
        Vector_Function(
          function {0},
          function {-1},
          function {0}
        )
      }
      ...
    }
  }
}

global_settings {
  ...
  mechsim {
    ...
    attach {
      function {
        spline {
          linear_spline
            0.0, <0,0,0>
            0.5, <1,0,0>
            1.0, <2,0,0>
          }
        }
      }
      ...
    }
  }
}

mass {
  <0, 0, 1>, <0, 0, 0>, 0.1
  density 600
  attach 2
}

The whole simulation data can be accessed anywhere in the POV-Script. This is achieved by adding new float/vector functions:

The complete syntax description of this block is:

FLOAT_FUNCTION:
    ... | mechsim : MECHSIM_ELEMENTS
MECHSIM_ELEMENTS:
    mass_count | connection_count | face_count |
    mass( INTEGER ) : MASS_FLOAT_ELEMENT |
    connection( INTEGER ) : CONNECTION_FLOAT_ELEMENT |
    face( INTEGER ) : FACE_FLOAT_ELEMENT
MASS_FLOAT_ELEMENT:
    radius | mass
CONNECTION_FLOAT_ELEMENT:
    index1 | index2 | length | stiffness | damping
FACE_FLOAT_ELEMENT:
    index1 | index2 | index3

VECTOR_FUNCTION:
    ... | mechsim : MECHSIM_ELEMENTS
MECHSIM_ELEMENTS:
    mass( INTEGER ) : MASS_VECTOR_ELEMENT
MASS_VECTOR_ELEMENT:
    position | velocity

These elements correspond to those set in the mechsim{} block in global_settings{}. The mass position and velocity are the ones that are modified during simulation. The mass_count connection_count and face_count values are especially useful inside the mechsim{} block to determine the current index:

global_settings {
  ...
  mechsim {
    ...
    topology {
      /* part 1 */
      mass { ... }
      mass { ... }
      connection { ... }
      ...

      #declare Start_Mass_Part2=mechsim:mass_count;
      #declare Start_Connection_Part2=mechsim:connection_count;

      /* part 2 */
      mass { ... }
      mass { ... }
      connection { ... }
      ...
    }
  }
}

The Start_Mass_Part2 and Start_Connection_Part2 variables can later be used to display the different parts of the simulation in different forms.

The file format used by the load_file and save_file options is a text format compatible to the POV-Ray™ #read and #write directives.

The different fields in the file (referred to as elements here) are separated by commas (,) and each contain either a string, an integer or float value or a vector.

The first element is a four character string ('MSIM') identifying the mechanics simulation file format. The second element is an integer number specifying the subformat of the file. Subformat 2 was used in Sim-POV 0.1.0 and Sim-POV 0.2.0 allows to write subformat 2 and 3.

The main difference is that type 3 files contain the attach index (see Section 2.7.3.1.7, “Attaching masses”) for each mass. In addition the subformat value is followed by a float for the start time in subformat 3. When the simulation data is saved after the simulation the time index at the beginning is increased by the simulation duration. This way environments and attachments are correctly moved during animations. The subformat can be specified with an additional number after the file name string in save_file. The default subformat is 2.

The following three integer numbers are the numbers of masses, connections and faces in the file. After them follows the data of all masses, connections and faces in that order.

For each mass there are the following elements:

For each connection:

For each face:

The files written by MegaPOV contain a line break after the subformat value, the mass count, connection count and face count value and after each mass, connection and face.

MSIM, 2,
3,
3,
1,
<-2, -2, 0>, <0, 0, 0>, 2.0, 0.05, 0, 0,
<2, -2, 0>, <0, 0, 0>, 2.0, 0.05, 0, 0,
<0, 2, 1>, <0, 0, 0>, 2.0, 0.05, 0, 0,
0, 1, 0.8, 12000, 6000, 0,
1, 2, 0.8, 12000, 6000, 0,
0, 2, 0.8, 12000, 6000, 0,
0, 1, 2, 0,

Post processing data is stored during rendering. This data contains several components: color of the pixel, intersection point, depth, normal - in other words all the information the raytracer receives for each of the pixels. For anti-aliased images only the data from the first ray is gathered. The storage is automatically turned on after the explicit call to one of predefined macros:

#version unofficial megapov 1.1;
#include "pprocess.inc"
// store data of the color and transparency
PP_Init_Alpha_Colors_Outputs()

// store data of the intersection point coordinates or <0,0,0>
PP_Init_IPoint_Outputs()

// store data of the normal at the intersection point or <0,0,0>
PP_Init_INormal_Outputs()

// store data of the perturbed normal at the intersection point or <0,0,0>
PP_Init_PNormal_Outputs()

// store the distance between camera and intersection point
PP_Init_Depth_Output()

// store the uv coordinates at the intersection point
PP_Init_UV_Outputs()

// allow access to intermediate post processing stages
// (color and transparency received from a previous post process stage)
PP_Init_PP_Alpha_Colors_Outputs()

	Important
	When using post_process { }, do not forget to include the file "pprocess.inc" because this include file is needed to access the internal data.

	Note
	If you do not need to store all the data mentioned in the macros listed above, you can pick one ore more of the dedicated internal functions mentioned further down. For example: store only the red component and the x coordinate of the intersection point for further usage. Check the content of the listed macros in the include file to find how to turn on only specific component storage.

Macros listed in the previous section enables internal functions with the following syntax:

// functions to access the color components and transparency
f_output_red(x,y)
f_output_green(x,y)
f_output_blue(x,y)
f_output_alpha(x,y)

// access to the intersection point coordinates
f_output_ipoint_x(x,y)
f_output_ipoint_y(x,y)
f_output_ipoint_z(x,y)

// access to the normal vector at the intersection point
f_output_inormal_x(x,y)
f_output_inormal_y(x,y)
f_output_inormal_z(x,y)

// access to the perturbed normal vector at the intersection point
f_output_pnormal_x(x,y)
f_output_pnormal_y(x,y)
f_output_pnormal_z(x,y)

// access to the distance between camera and intersection point
f_output_depth(x,y)

// access to the uv coordinates at the intersection point
f_output_u(x,y)
f_output_v(x,y)

// access to color and transparency of an earlier post processing stage
f_pp_red(x,y,Ref)
f_pp_green(x,y,Ref)
f_pp_blue(x,y,Ref)
f_pp_alpha(x,y,Ref)

The majority of the listed functions only need x and y parameters. These parameters are the location in the area of the rendered image. Not defined in pixels but in the range <0,1>.

f_output_red(0.5,0.5)

Note that <0,0> is not the value of the most top-left pixel, but the value at the top left corner of the most top left _pixel_. You have to shift it about <0.5/image_width,0.5/image_size> to hit the center of the most top left pixel. If you are not happy with the need of expressing coordinates in decimal form you can always express them in relation to the image size.

Some of the functions contain an additional Ref parameter. These are functions which refer to the result of the earlier calculated post processing stage. This parameter specifies to which stage we refer: 0 means output of rendering, 1 means output of first post processing, 2 means output of second postprocessing, etc.

Numbering depends on the order of appearence in the sources.

Postprocessing should be defined in the global_settings section of the scene file like this:

global_settings {
  post_process {
    function { ... } // calculation of red component
    function { ... } // calculation of green component
    function { ... } // calculation of blue component
    function { ... } // calculation of transparency component
    [ save_file FILENAME ]
  }
}

global_settings {
  post_process {
    function { f_output_red(x,y) }   // calculation of red component
    function { f_output_green(x,y) } // calculation of green component
    function { f_output_blue(x,y) }  // calculation of blue component
    function { f_output_alpha(x,y) } // calculation of transparency component
    save_file "duplication.png"
  }
}

The post_process block can appear a few times in the global_settings block. Note that saving to file is optional but only the saved blocks will be calculated. Also note that saving is always done in the same file format as the render output (regardless of the file extension).

#declare F_gray = function(r,g,b){0.297*r + 0.589*g + 0.114*b};
global_settings {
  post_process {
    function { F_gray(f_output_red(x,y),f_output_green(x,y),f_output_blue(x,y)) }
    function { F_gray(f_output_red(x,y),f_output_green(x,y),f_output_blue(x,y)) }
    function { F_gray(f_output_red(x,y),f_output_green(x,y),f_output_blue(x,y)) }
    function { f_output_alpha(x,y) }
    save_file "grayed.png"
  }
}

Because it could be difficult using functions to define your own post processing effects, some macros with user-friendly syntax have been added to the "pprocess.inc" include file. For an overview and some explanation on the parameters, (see Section 3.5.1, “Macros with effects”).

This macro generates POV-Ray™ shapes for all masses and connections or faces from a certain range of the simulation data.

Depending on the value of the Show_Faces parameter the macro will either generate a union of cylinders and spheres representing the masses and connections or a mesh with triangles representing the faces.

MechSim_Show_Objects(0, 0, 0, -1, -1, -1, -1, false, -1, "")

#declare Obj=MechSim_Show_Objects(0, 0, 0, -1, -1, -1, -1, true, -1, "")

MechSim_Show_Objects(0, 0, 0, 100, 300, 0, -1, false, 120, "sim01.inc")

Variation of the MechSim_Show_Objects() macro displaying all elements of the current simulation data.

MechSim_Show_All_Objects(-1, false, -1, "")

#declare Obj=MechSim_Show_All_Objects(-1, true, -1, "")

This macro generates a mesh from the outer surface of a grid topology created with the MechSim_Generate_Grid() macro (see Section 3.4.5.3, “MechSim_Generate_Grid()”).

MechSim_Show_Patch(0, 5, 5, 5, true, false, -1, "")

#declare Obj=MechSim_Show_Patch(0, 50, 50, true, true, 10, "sim01.inc")

Here a comparison between the different methods and variations:

Table 3.1. MechSim_Show_Grid() variations

cylinders and spheres	cylinders and spheres (stress visualization)	face triangles
no smooth	smooth	stress visualization

This macro generates a mesh from the patch topology created with the MechSim_Generate_Patch() macro (see Section 3.4.5.6, “MechSim_Generate_Patch()”). The mesh is generated in form of the new mesh2 type and optionally includes uv- and normal data depending on the parameters.

MechSim_Show_Patch(0, 50, 50, true, false, -1, "")

#declare Obj=MechSim_Show_Patch(0, 50, 50, true, true, -1, "sim01.inc")

Here a comparison between the different methods and variations:

Table 3.2. MechSim_Show_Patch() variations

cylinders and spheres	face triangles	patch macro (stress visualization)
no smooth, no uv	smooth	uv mapped

This macro generates a mesh from the outer surface of a grid topology created with the MechSim_Generate_Sphere() macro (see Section 3.4.5.10, “MechSim_Generate_Sphere()”).

MechSim_Show_Sphere(0, mechsim:face_count, false, false, -1, "")

#declare Obj=MechSim_Show_Sphere(0, mechsim:face_count, true, false, -1, "sim01.inc")

Most of the macros have a parameter named Connect_Arr. This is an array containing weighting factors for the different connections in.

The objects generated by the macros have different types of connections: axis-parallel connections, 2D and 3D diagonal connections and possibly bending connections. How these connections are weighted influences the properties of the object and can be controlled by the values in this array. Which value refers to which type of connection depends on the macro and is mentioned in the macro description.

This macro generates 3D rectangular grid of masses with connections and optionally faces on the outside. The density of the masses as well as the stiffness and damping of the connections can be varied with functions.

The generated box starts at the origin and extends in positive x, y and z-direction.

meaning of the 'Connect_Arr' entries:

See also Section 3.4.5.1, “The explanation of the Connect_Arr parameter”. If the first entry is 0 no connections are generated. The individual entries are used for the following connections. Only connections up to the size of the array are generated.

The following pictures illustrate the different sizes of the array:

Table 3.3. MechSim_Show_Patch() variations

0 (first element zero)	array size 1	array size 2
array size 3	array size 4

#declare Con_Array=array[3]
#declare Con_Array[0]=1;
#declare Con_Array[1]=1;
#declare Con_Array[2]=1;

#declare fn_Density=function(x, y, z) { 32000 }
#declare fn_Stiffness=function(x, y, z) { 1000 + x*1500 }
#declare fn_Damping=function(x, y, z) { 2000 + x*1500 }

MechSim_Generate_Grid_Fn(<0, 0, 0>, 0.08, fn_Density, fn_Stiffness, fn_Damping,
                         true, <0.4, 0.4, 0.4>, <4, 4, 4>, No_Trans, Con_Array)

This macro generates 3D rectangular grid of masses with connections and optionally faces on the outside. In contrast to the MechSim_Generate_Grid_Fn() macro (see Section 3.4.5.2, “MechSim_Generate_Grid_Fn()”) the density stiffness and damping values are fixed.

#declare Con_Array=array[3]
#declare Con_Array[0]=1;
#declare Con_Array[1]=1;
#declare Con_Array[2]=1;

MechSim_Generate_Grid(<0, 0, 0>, 0.08, 32000, 1000, 2000,
                      true, <0.4, 0.4, 0.4>, <4, 4, 4>, No_Trans, Con_Array)

This macro generates 3D rectangular grid of masses with connections and optionally faces on the outside. In contrast to the MechSim_Generate_Grid() macro (see Section 3.4.5.3, “MechSim_Generate_Grid()”) all connections all have the same stiffness and damping.

MechSim_Generate_Grid_Std(<0, 0, 0>, 0.08, 32000, 1000, 2000,
                          true, <0.4, 0.4, 0.4>, <4, 4, 4>, No_Trans, 3)

Variation of the MechSim_Generate_Grid_Std() macro (see Section 3.4.5.4, “MechSim_Generate_Grid_Std()”) where instead of the density of the individual masses the mass of the whole grid is given.

MechSim_Generate_Box(<0, 0, 0>, 0.08, 20, 1000, 2000,
                     true, <0.4, 0.4, 0.4>, <4, 4, 4>, No_Trans, 3)

This macro generates a rectangular patch of masses with connections and optionally faces forming the surface. The masses can be fixed with help of a function

meaning of the 'Connect_Arr' entries:

See also Section 3.4.5.1, “The explanation of the Connect_Arr parameter”. The following picture shows which entries in the array weight which connections. Only connections up to the size of the array are generated.

Figure 3.1. patch connection numbers

#declare fn_Fixed=function { -1 }
#declare Con_Array=array[3]
#declare Con_Array[0]=1;
#declare Con_Array[1]=1;
#declare Con_Array[2]=1;

MechSim_Generate_Patch(<0, 0, 0>, 0.065, 8000, 10000, 0,
                       true, <0.055, 0.055>, <50, 50>, No_Trans, fn_Fixed, Con_Array)

This macro generates a rectangular patch of masses with connections and optionally faces forming the surface. In contrast to the MechSim_Generate_Patch() macro (see Section 3.4.5.6, “MechSim_Generate_Patch()”) all connections all have the same stiffness and damping. Also none of the masses is fixed.

MechSim_Generate_Patch_Std(<0, 0, 0>, 0.065, 8000, 10000, 0,
                           true, <0.055, 0.055>, <50, 50>, No_Trans, 3)

This macro generates a line of connected masses and can be used for simulating things like ropes, chains, etc. The masses of the line can be fixed with help of a function

meaning of the 'Connect_Arr' entries:

See also Section 3.4.5.1, “The explanation of the Connect_Arr parameter”. The first element of the array weights the direct connections between two neighboring masses. Further values in the array weight the more distant connections that introduce bending stiffness to the line. Only connections up to the size of the array are generated.

#declare fn_Fixed=function { -1 }
#declare Con_Array=array[2]
#declare Con_Array[0]=1;
#declare Con_Array[1]=1;

MechSim_Generate_Line(<0, 0, 0>, 0.09, 8000, 10000, 0,
                      0.45, 10, <1, 1, 1>, No_Trans, fn_Fixed, Con_Array)

This macro generates a line of connected masses and can be used for simulating things like ropes, chains, etc.. In contrast to the MechSim_Generate_Line() macro (see Section 3.4.5.8, “MechSim_Generate_Line()”) only shortest distance connections are generated. Also none of the masses is fixed.

MechSim_Generate_Line(<0, 0, 0>, 0.09, 8000, 10000, 0,
                      0.45, 10, <1, 1, 1>, No_Trans)

This macro generates a sphere shaped grid of connected masses with an additional mass in the center and all surface masses connected to it. This shape can be used for simulating balls that rotate realistically and can deform as well. The masses are generated by subdividing an icosahedron.

MechSim_Generate_Sphere(<0, 0, 0>, 0.08, 32000, 1600, 2000, 32000, 1600, 2000, true, 1, 0.9, No_Trans)

post_process { PP_Clip_Colors(color_min,color_max) }

Clips all colors in the image to the range color_min and color_max

post_process { PP_Color_Matrix(Array) }
      
// Runs the color through a 3*3 matrix expressed in Array.
// The equation is:
// R = r*AA + g*AB + b*AC
// G = r*BA + g*BB + b*BC
// B = r*CA + g*CB + b*CC
// and Array means
// array[9]{AA, AB, AC, BA, BB, BC, CA, CB, CC}

Combination of colors.

post_process { PP_Convolution_Matrix(XDim,YDim,Divisor,Leveling,Matrix) }

Multiplies the pixel and the adjacent pixels (in the area defined by the matrix size) by the respective values in the matrix, adds the results together and divides by Divisor to get an average color. A leveling value can be added in before the final division.

post_process { PP_Depth(Field_Start,Field_Depth) }

The image is converted to a gray-scale image with the gray-value of the pixel depending of the depth location in the scene.

Field_Start specifies the beginning of the focal range in units from the camera.

Field_Depth specifies the length of the focal range.

post_process {
  PP_Find_Edges(Depth_Thresh,Normal_Thresh,Color_Thresh,Line_Radius,Sharpness,Pigment)
}

This post process effect finds the edges in an image using depth, normal, and color information. Separate thresholds are specified for each of the three methods of edge detection.

The width of the lines is controlled by the "Line_Radius" parameter.

The sharpness of the lines is controlled by the "Sharpness" parameter. A sharpness of 1.0 yields nicely anti-aliased lines. A sharpness value of 0.0 leads to blurry lines when larger radii are used, and a sharpness value of greater than 1.0 begins to remove anti-aliasing from the lines.

The color of the line is controlled by the pigment specified. This pigment is evaluated over the range of <x,y> = <0,0> ... <1,1> (with z=0) over the full size of the image. Using solid colors is usually a good idea, unless special effects are desired.

PP_Find_Edges( 1.0, 0.3, 0.15, 2, 1.0, rgb 0 )

Finds edges wherever there is a depth difference greater than 1.0, a normal difference greater than 0.3 (about 60 degrees), or a color difference of 0.15. It uses a line radius of 2.0, with black (rgb 0) antialiased (sharpness 1.0) lines.

The PP_Find_Edges macro is a straight implementation of the functionality of the effect available in previous versions of MegaPOV. In fact this macro is a wrapper to the more functional macro PP_Find_Edges_Back():

post_process {
  PP_Find_Edges_Back(
    Depth_Thresh,Normal_Thresh,Color_Thresh,Line_Radius,Sharpness,Pigment,
    Background,Background_Filter,Width,Height
  )
}

This macro adds four more parameters:

Background: a pigment as replacement to be placed between edges instead of the original rendering.

Background_Filter: pigment with a filter value for weighting between the "Background" parameter and the "Pigment" parameter.

Width,Height: the image sizes to make the parameter "Line_Radius" relative to the image area. It is usually image_width and image_height but can be something different in case somebody wants a special effect like larger rectangles instead of lines.

Before launching the simulation, it is initially necessary to create the starting *.cth file. It will contain a fresh cloth with the desired dimensions, normalized distances between points and strength coefficient of the springs connecting the points.

#macro WriteClothFile(filename, n1, n2, nlng, ks, ht)
  #debug "\nWriting new cth file\n"
  #fopen file filename write
  #write(file, n1, ", ", n2, ", ", nlng, ", ", ks, ",\n";)
  #local l1 = nlng*(n1-1);
  #local l2 = nlng*(n2-1);
  #local st = seed(1234);
  #local i=0;
  #while (i < n1)
    #local j=0;
    #while (j < n2)
      #local tempx = -l1/2 + i*nlng;
      #local tempz = -l2/2 + j*nlng;
      #local tempy = ht + (-1+2*rand(st))*nlng*0.1;
      #write(file, tempx, ",", tempy, ",", tempz, ", 0.0, 0.0, 0.0,\n")
      #set j=j+1;
    #end
    #set i=i+1;
  #end
  #fclose file
#end

#declare Table =
  union {
    cylinder { 8*y, 9*y, 8 }
    torus { 8, 05 sturm translate 85*y }
    cylinder { 85*y, 0, 05 }
    cylinder { 0, 05*y, 4 }
  }

4.1.1.1.3. Visualize the starting position of the fabric

To check that the simulation does not begin with part of the fabric IN the table, we can create the mesh Nappe, using 0 iterations in simcloth:

WriteClothFile("nappe.cth", 50, 50, 1.8/50, 10, 0.95)

simcloth {
  iterations 0
  input "nappe.cth"
  mesh_output "nappe.msh"
  uv_mesh on
}

#declare Nappe =
  mesh {
    #include "nappe.msh"
    uv_mapping
    texture {
      pigment {
        checker color rgb <1, 0.5, 0.2> color rgb <1, 0.8, 0.4>
        scale <1/10, 1/10, 1/10>
      }
    }
  }

Then, the ground, the walls, a light source, a camera, are added, and we obtain this:

4.1.1.1.4. Darling !!! Put the tablecloth on the table !!!

And for that, nothing better than the gravity (-0.4*y). Moreover, the table is rough (and the fabric also), one thus will put the coefficient of friction at 0 (high frictions). As the distance between each point is rather small, one will also take a rather small time interval between each iteration (0.03).

simcloth {
  environment Table
  friction 0
  gravity -0.4*y,
  damping 0.9,
  intervals 0.03
  iterations 50
  input "nappe.cth"
  output "nappe.cth"
  mesh_output "nappe.msh"
  smooth_mesh on
  uv_mesh on
}

Don't forget to look at the messages window (in Windows & Mac version) or output stream (in UNIX version), to know if the simulation ended OK or not (in case of problems while opening files, lack of memory, etc...).

The starting *.cth file can be calculated only once. By putting the WriteClothFile(...) macro in comments thereafter - or make it conditional for clock off: #if(clock_on=off) macro #end - , each simulation will begin again where the preceding one was stopped.

In order to avoid coincident surfaces, you can reduce very slightly the dimensions of the table, and level up the tablecloth a little...

object { Nappe translate 0.001*y }
object {
  Table scale <0.98, 1, 0.98>
  texture { T_Wood23 rotate <10, 20, 0> }
}

For those who are as I am (i.e. lazy), a complete script is available: nappe.pov

After 50 iterations ...

... 50 additional iterations ...

... and 100 more.

The difficulty in making a good-looking lying cloth is to well position the fabric at the beginning, and to make it so that it tends to gather in a smaller zone than its dimensions.

#declare R = 1;
#declare Cube =
  union {
    box { <R, 0, R>, <1-R, 1, 1-R> }
    box { <R, 0, 0>, <1-R, 1-R, 1> }
    box { <0, 0, R>, <1, 1-R, 1-R> }
    cylinder { <R, 0, R>,  <R, 1-R, R>, R }
    cylinder { <R, 0, 1-R>,  <R, 1-R, 1-R>, R }
    cylinder { <1-R, 0, R>,  <1-R, 1-R, R>, R }
    cylinder { <1-R, 0, 1-R>,  <1-R, 1-R, 1-R>, R }
    sphere { <R, 1-R, R>, R }
    sphere { <R, 1-R, 1-R>, R }
    sphere { <1-R, 1-R, R>, R }
    sphere { <1-R, 1-R, 1-R>, R }
    translate -0.02*x
  }

#declare Obstacle =
  union {
    plane { y, 0 }
    object { Cube }
  }

4.1.1.2.2. First test

We will reuse the WriteClothFile(...) macro from the preceding example, and we will create a rectangular cloth patch (30 X 50 points):

WriteClothFile("drape.cth", 30, 50, 2/50, 20, 1.5)
simcloth {
  environment Obstacle
  friction 0
  gravity -.5*y
  damping 0.9
  intervals 0.03
  iterations 200
  input "drape.cth"
  mesh_output "drape.msh"
  smooth_mesh on
  uv_mesh on
}

#declare Drap =
  mesh {
    #include "drape.msh"
    uv_mapping
    texture {
      pigment {
        checker color rgb <1, 0.5, 0.2> color rgb <1, 0.8, 0.4>
        scale <1/10, 3/50, 1>
      }
    }
  }

Well... hu... good, but it is not what is called pretty good-looking lying cloth (this one is rather banal...)

4.1.1.2.3. Starting position of the cloth

Let's modify the positioning of each point of the cloth, in the macro WriteClothFile(...), by carrying out a rotation of -60 degrees around axis Z, and slightly translating it towards the right, like this:

#local tempx = -l1/2 + i*nlng;
#local tempz = -l2/2 + j*nlng;
#local vtemp = ;
#local vtemp = vaxis_rotate(vtemp, z, -60);
#local tempy = ht + (-1+2*rand(st))*nlng*0.1;
#local vtemp = vtemp + tempy*y + .2*x;
#write(file, vtemp.x, ",", vtemp.y, ",", vtemp.z, ", 0.0, 0.0, 0.0,\n")

One does not forget "to level up" the cloth, and the starting position can be visualized:

And finally, let the nature... well, MegaPOV ... do its job:

For the lazy ones, there is a complete script: drape.pov

The fabric starts lying...

Some iterations further...

... and the result.

Obviously, the absence of internal test of collision (fabric against fabric) causes some "errors" (see in bottom of cloth)... . But, one can nevertheless obtain more or less satisfactory results.

The simplest thing that can be simulated with the mechanics simulation patch is the movement of individual point masses. Their movement under the influence of gravity and environment objects is handled in this part.

We start with a simple scene setup:

To simulate the movement of a single mass we add the following to the global_settings{}:

mechsim {
  gravity <0, 0, -9.81>
  method 1

  environment {
    object plane {  z, 0 }
    damping 0.9
    friction 0.3
    method 2
  }

  #if (clock_on)
    step_count 300
    time_step (1/30)/300

    topology {
      load_file "tut02.dat"
      save_file "tut02.dat"
    }
  #else
    step_count 0

    topology {
      mass { <-2.8, -8.0, 0.9>, <2, 5, 0>, 0.1 density 5000 }
      save_file "tut02.dat"
    }
  #end
}

The purpose of the individual lines of this block is the following:

gravity <0, 0, -9.81> activates a standard gravity force in negative vertical direction.

method 1 selects simulation method 1 (Euler integration).

The environment {} block contains the definition of the environment. It contains:

What follows is an #if conditional. It switches between two different blocks of code depending on whether the scene is rendered as an animation or not. This is useful for initializing the simulation.

The first part contains statements for the animation render:

Finding the right step size is probably something most difficult for the beginner. A smaller step size generally leads to more accurate results. Usually the step size has to be below a certain value depending on the other simulation settings to get usable results, but it is not always obvious if some strange result is due to large time steps. High stiffness values in environments, collision and connections usually require smaller time steps. If you experience unexpected results it is often worth trying to decrease the step size and see if problems vanish.

The topology{} block contains just load_file and save_file statements referring to the same file. This makes MegaPOV load the old simulation data at the beginning, calculate the steps for the current frame and save to the same file afterwards.

The second part contains statements for the still render

step_count is set to zero here so no simulation steps are calculated.

The topology{} block contains a singular mass{} section now. It contains:

The load_file statement finally saves this mass to a file.

To show the mass in the scene we can use a macro from the mechsim.inc include file:

#include "mechsim.inc"

MechSim_Show_All_Objects(-1, false, -1, "")

The meaning of the parameters of this macro is described in Section 3.4.4.2, “MechSim_Show_All_Objects()”.

Now all we need to do is render the scene once as a still to generate the initial data file and afterwards render it as an animation:

In the first part of the tutorial we have handled masses and their movement under the influence of gravity and the constraints of the environment. If several masses exist in the simulation collisions between them have to be taken into account.

For turning collision calculation on the following block is added to the mechsim{} section:

collision {
  1, 0
  stiffness 60000
  damping 3000
}

The first two numbers tell MegaPOV which collision to calculate. For details see Section 2.7.3.1.3, “The collision settings”. The numbers used here turn calculation on for all mass-mass collisions.

stiffness (unit kg/s²) and damping (unit kg/s) influence how the masses interact.

Another change made in this tutorial step is changing the environment to function based calculations. This usually leads to more accurate environment collisions, especially with more complex geometries but also tends to be slower and requires smaller integration steps.

Defining the environment as a function is fairy easy with the IsoCSG library. The definition in this case looks like:

#include "iso_csg.inc"

#declare fn_Env=
IC_Merge5(
  IC_Plane(z, 0),
  IC_Box(< 1.7,-1.7,-1.0>, < 1.5,1.7,0.5>),
  IC_Box(<-1.7,-1.7,-1.0>, <-1.5,1.7,0.5>),
  IC_Box(<-1.7, 1.7,-1.0>, <1.7, 1.5,0.5>),
  IC_Box(<-1.7,-1.7,-1.0>, <1.7,-1.5,0.5>)
)

Note that the stiffness, damping and friction parameters in the environment now have the same meaning as in the collision settings because it uses calculation method 1 (force based environment collisions).

This scene also adds new masses during the animation. This is achieved by adding the following code to the topology{} section:

#if (mod(frame_number, 6)=5)
  mass { < 1.3,-1.55,0.8>, <-0.2, 5, 0>, 0.18 density 5000 }
#end

It means that in every sixth frame a new mass is added at the starting position with the same starting velocity as the first mass.

Apart from masses there is another element that can be added to the topology{} section: connections. Connections can be seen as springs. They connect two point masses and exert a force on them depending on the current distance of the masses compared to the relaxed length of the connection. In addition there is a damping property generating dissipative forces.

A connection{} block is added to the topology{} section like a mass:

connection { 0, 1 stiffness 50000 damping 2000 }

It contains:

if no length is given the current distance of the masses is used.

The mass indices are counted in order of creation starting at zero. The three connected masses from the following scene are created with:

topology {
  mass { <0, 0, 2.4>, <0, 0, 0>, 0.1 density 5000 fixed on }
  mass { <1, 0, 2.4>, <0, 0, 0>, 0.1 density 5000 }
  mass { <2, 0, 2.4>, <0, 0, 0.6>, 0.15 density 5000 }
  connection { 0, 1 stiffness 50000 damping 2000 }
  connection { 1, 2 stiffness 50000 damping 2000 }
}

The fixed on in the first mass definition fixes the position of this mass.

With plenty of such connections we can form more complex shapes. The mechsim.inc include file (see Section 3.4, “The 'mechsim.inc' include file”) contains several macros forming grids of masses and connections.

Placing the following in the topology{} section generates a box-like grid of connected masses:

MechSim_Generate_Grid_Std(
  <0, 0, 0>, 0.07, 25000, 22000, 2000,
  true, <0.4,0.4,0.4>, <3, 12, 3>, Trans1, 3
)

The meaning of the different parameters is described in Section 3.4.5.4, “MechSim_Generate_Grid_Std()”. Trans1 is a transform moving the whole grid from its predefined position. It has to be declared before:

#declare Trans1 =
  transform {
    translate <-0.5, -6*0.4, 1.0>
  }

The resulting animation shows a moving and deforming box geometry.

The MechSim_Generate_Grid_Std() macro also generates faces for the outside surface of the box. Faces are triangles each connecting three masses. They can be used for collision calculations and for displaying the geometry as a mesh. The latter can be done easily by changing the parameters of the MechSim_Show_All_Objects() macro:

MechSim_Show_All_Objects(-1, true, -1, "")

Apart from 3D grids we of course can also create 2D rectangular patches. Such objects behave like cloth or foil and offer a very interesting field of simulation.

Like 3D grids rectangular patches can be created with macros from the mechsim.inc include file (see Section 3.4, “The 'mechsim.inc' include file”):

MechSim_Generate_Patch_Std(
  <0, 0, 0>, 0.03, 8000, 10000, 0,
  true, <0.055, 0.055>, <50, 50>, Trans1, 2
)

This creates a 50x50 masses patch, again movable with a transform. Description of the parameters can be found in Section 3.4.5.7, “MechSim_Generate_Patch_Std()”.

The following sample scene also uses a different simulation method than the previous scenes. It is called gradient descent method. It does not integrate the equations of movement like the other methods but moves the masses directly according to the forces influencing them. Inertia does not have effect with these method, therefore oscillations can't occur. Still the step size has to be chosen small enough for accurate results. The movement won't look very realistic in an animation but the final result can be used for a still render. Another disadvantage is the lack of friction, therefore the patch slides off the sphere in the end.

There is also a specialized macro for generating a mesh from a patch topology including normal vectors and uv coordinates. Rendering the previous topology with this macro results in the following picture:

There are a lot more aspects of the mechanics simulation patch that are not handled in this tutorial yet. Reading the reference (see Section 2.7.3, “Mechanics simulation patch”) and mechsim.inc include file documentation (see Section 3.4, “The 'mechsim.inc' include file”) should help learning about those things. The sample scenes show several examples what the simulation system can be used for but there are a lot more possibilities.

There are many different reasons for modifying the POV-Ray™ source. Most important are the fixing of bugs and extending POV-Ray™ with new features.

When fixing a bug it should be considered what is the right, expected behavior of the program, the fix should establish this. In many cases patches introduced as a bugfix are in fact feature extensions or only superficial fixes that do not solve the underlying problem.

When you are planning a new feature you should first think about how it should fit into the rest of POV-Ray™ features. A good patch can be used quite universally, not only for the purpose it was originally developed for. Do not try to reinvent the wheel but make use of existing techniques that already exist in the POV-Ray™ source. For things like status output and file reading use functions existing in POV-Ray™.

It is hard to describe good guidelines for the actual coding of a patch. Every programmer has own habits and methods including indention, placing of braces, inserting white spaces, favorite naming scheme. But there are some common rules POV-Ray™ patch writers usually follow. Here is our effort for a brief summary - mainly meant as a starting aid for beginning patch writers.

When coding make use of existing helper functions in POV-Ray™ like those in vector.h. Try to reduce changes in existing code to avoid damaging existing features.

Usually, people put something like #define MY_PATCH in a commonly used file:

Now you should enclose all patch-specific code in #ifdef ... [#else ...] #endif blocks, so removing (commenting) /* #define MY_PATCH */ causes compilation without your patch, and the modifications you make are clearly visible. Optional #else ... is suggested when you are making replacement for existing code (i.e. for bug fixes).

The most common system for patch naming are uppercased words separated with underscores. Names are usually concatenated with word PATCH somehow. In world of Apple mixed case variable names without underscores like MyPatch are also popular.

...
#define FAST_SQR_PATCH
...

...
#ifdef FAST_SQR_PATCH
  // new code
  Value = sqr( Parameter );
#else
  // old code
  Value = Parameter * Parameter;
#endif
...

Some additions can be also compiler specific changes required by lack of some builtin C function or different naming. In such cases you can use predefined compiler specific macros together with your own markup. Each compiler delivers several predefined macros (see Section 5.2, “Binaries”).

#ifdef __DJGPP__
  // some compiler specific code
#else
  // code for other compilers
#endif

#if defined( __WATCOMC__ ) && defined( MY_PATCH)
  // code here
#end

Of course it is a little bit more work to maintain changes this way but on the other hand it is also much more readable and allows to prepare two binaries for comparison. It is also much more easier to port your changes into other compilations like MegaPOV then.

Apart from the markup it is important to keep modifications portable. Patches using compiler specific features or functions from a proprietary library won't make it into a patch collection like MegaPOV.

When you add new elements to the POV-Ray scene description language it is a good idea to keep it consistent with the existing syntax. Even if you think a certain syntax would be much easier to use it is very likely to cause much confusion for the user when it differs from existing similar functions.

Some useful information about portability aspects can be found on http://predef.sourceforge.net/.

If you are unsure about a certain aspect of your patch implementation better ask (see Section 1.5.3, “Discussions”).

Once a patch is finished you may want to share this patch with the POV-Ray™ Community. Doing this in a wise way can make your patch popular and included in other unofficial custom compilations like MegaPOV is. So before you upload your changes somewhere first check if:

When your modifications are validated then it is time to publish it. There are some common methods in publishing patches:

It is hard to tell which method is the best. The choose of particular method depends on free time, complexity of changes and used sources.

Because MegaPOV is designed to turn on and off each patch separately, you must be careful whenever a patch is added. This patch changes many parts of the code and especially the definition of TPATTERN_FIELDS is a bit tricky. For example, the ANGLE_OF_INCIDENCE_PATCH is added to the TPATTERN_FIELDS definition like this in frame.h. First you define it like this:

#ifdef ANGLE_OF_INCIDENCE_PATCH
  #ifdef LESS_MEMORY_IN_PATTERNS_PATCH
    typedef struct  {  VECTOR AOI_origin;  unsigned char pt_fixed;
    }AOI, *AOIPTR ;
    #define AngleOfIncidenceDef  AOIPTR Aoi;
  #else
   #define AngleOfIncidenceDef struct { VECTOR AOI_origin; unsigned char pt_fixed; } Aoi;
  #endif
#else //ANGLE_OF_INCIDENCE_PATCH
  #define AngleOfIncidenceDef
 #endif

and then add it to the TPATTERN_FIELDS definition like this:

#define TPATTERN_FIELDS       \
 unsigned short Type, Wave_Type, Flags; \
 :            \
 union {                     \
   DENSITY_FILE *Density_File; \
   : \
   AngleOfIncidenceDef \
   : \
   ProjectionDef \
 } Vals;

AngleOfIncidenceDef is always defined to avoid two definitions for TPATTERN_FIELDS. If ANGLE_OF_INCIDENCE_PATCH isn't defined, AngleOfIncidenceDef is empty and is ignored, if ANGLE_OF_INCIDENCE_PATCH is defined, AngleOfIncidenceDef is a pointer or a struct, depending on whether LESS_MEMORY_IN_PATTERNS_PATCH is defined or not.

This leaves us with the problem of accessing the members of the members of Vals. In frame.h LESS_MEMORY_PATCH_MO is defined like this:

#ifdef LESS_MEMORY_IN_PATTERNS_PATCH
  #define LESS_MEMORY_PATCH_MO ->
#else
  #define LESS_MEMORY_PATCH_MO .
#endif

Whenever you access a member from an element of Vals you use

New->Vals.Crackle LESS_MEMORY_PATCH_MO lastseed = 0x8000000;

which results in

New->Vals.Crackle.lastseed = 0x8000000;
or
New->Vals.Crackle->lastseed = 0x8000000;

depending on the state of the switch LESS_MEMORY_IN_PATTERNS_PATCH.

For each pattern added, which uses a pointer, memory is allocated in the following functions:

Memory is freed for each new pattern in:

The best way to find all necessary changes is to find all occurrences of one patch and take a look on how it is implemented.