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.

Normally area lights are handled as area lights in all situations. This means that every shadow ray test against an area light source is sampled across the area of the light source. This patch allows to specify a max_trace_level for the area light which turns off the soft shadows above the specified trace level.

Syntax is:

light_source {
  LOCATION, COLOR
  [LIGHT_MODIFIERS...]
  max_trace_level INTEGER
}

If you for example specify:

light_source {
  <1.0,2.0,2.0>
  color rgb 1.0
  area_light 0.5*x 0.5*y 9,9 jitter adaptive 1 circular orient
  max_trace_level 1
}

this will only result in soft shadows on directly visible surfaces. In reflections, refractions and radiosity the light source will be treated as a point light.

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.3.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.3.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.

The POV-Ray™ radiosity feature uses the error_bound parameter to decide when to reuse radiosity samples already in the cache and when to take a new sample because there are not enough samples nearby. Setting a low error_bound makes POV-Ray™ take a new sample very often and therefore leads to more accurate calculation of the diffuse illumination but at the same time is prone to artefacts when used with a low number of sample rays (count).

Especially with geometries containing sharp edges the sample density can become very high because POV-Ray™ recognizes the lighting changes very rapidly there. In such cases it will not be possible to take all required samples during pretrace which is unfortunate because it leads to slow renders, increasing memory requirements during the render and makes splitting the render into multiple tasks more difficult. POV-Ray™ already offers the always_sample option that reduces the necessity of additional samples in the final render pass by setting nearest_count to 1 on the final pass so only one sample is required per radiosity evaluation but this only reduces the problem a bit and is prone to artefacts.

The adaptive error_bound allows you to set a range the error_bound value is automatically chosen from as well as an overestimation factor used to find the optimal error_bound value. This means the radius from which cached radiosity samples are used is increased if not enough samples are found in the area defined by the original error_bound. In a way this is similar to the adaptive search radius used in photon mapping.

This patch is activated by using the following syntax instead of the standard error_bound parameter:

RADIOSITY_ITEMS:
    ...
    [ error_bound ERROR_BOUND_DEFINITION ]

ERROR_BOUND_DEFINITION:
    FLOAT_ERROR_BOUND |
    {
      FLOAT_ERROR_BOUND
      [adaptive FLOAT_EB_OVERESTIMATION [, FLOAT_ERROR_BOUND_MAX] ]
    }

The default values are:

FLOAT_EB_OVERESTIMATION : 1.5

FLOAT_ERROR_BOUND_MAX : 10.0

The following code for example might be used for an adaptive error_bound:

radiosity {
  ...
  error_bound { 0.3 adaptive 2.0, 20 }
}

Note it can be necessary to use fairly large maximum values to avoid final pass radiosity samples to be necessary. The overestimation factor increases the render time when chosen too small and will result in unnecessarily large errors when very large. Values between 1.5 and 2 are usually a good choice.

The patch introduces some additional statistics showing the number of samples taken in pretrace and final pass and separately for the different recursion levels. This can be useful for optimizing the radiosity settings.

The purpose of the radiosity pretrace is to take care of an optimal distribution of radiosity samples in the scene. For achieving this the view area is sampled with increasing density until pretrace_end. During pretrace pass the error_bound is also reduced with low_error_factor. The results are usually quite good but this is unnecessarily slow in a lot of scenes where different areas require a very different sample density. Also the standard pretrace only samples down to a 2 pixel density which is not sufficient in many cases.

Because of these limitation practical use of radiosity usually does not take all radiosity samples during the pretrace. Sometimes it is even more efficient to totally avoid the pretrace.

This patch introduces a new pretrace mode which no more samples the whole view with the same density but adapts the sampling to the scene's requirements. To accomplish this the pretrace no more traces the different subdivision levels one after the other but subdivides the view in a recursive way.

In addition the new pretrace can also subdivide to a sub-pixel density (by using pretrace_end smaller than 1/image_width). This can of course be quite slow depending on the scene, render- and radiosity-settings.

The new pretrace is activated the following way:

radiosity {
  ...
  adaptive 1
}

The following values can be used for the radiosity parameter:

The POV-Ray™ radiosity code contains code to visualize the way radiosity works internally in the rendered images. This code is deactivated by default. This patch offers access to these features from SDL with some new parameters in the radiosity block.

The syntax of these parameters is the following:

RADIOSITY_ITEMS:
    ...
    [ show_samples FLOAT_RADIUS, COLOR ]
    [ show_low_count COLOR_LOW_COUNT, COLOR_GATHER_FINAL ]

2.7.3.7.1. sample locations

The show_samples parameter activates the marking of the radiosity sample locations with the specified color. Note this color only sets the ambient value returned by the radiosity function. The other finish components are added to this. Therefore it might be necessary to use quite extreme color values for this. The radius parameter influences how large the sample spots are marked.

2.7.3.7.2. low sample count areas

The show_low_count activates the marking of areas where the sample density is too low so less than nearest_count samples are available for the radiosity estimation. The color of these areas is chosen with the first parameter. This is only visible when always_sample is off, otherwise additional samples are taken in the final pass and the area is colored with the second color specified.

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 | 
    accuracy FLOAT[, FLOAT] |
    environment { ENVIRONMENT_DEFINITION [ENVIRONMENT_ITEMS...] } |
    interaction { INTERACTION_DEFINITION ... } |
    field { FIELD_DEFINITION ... } |
    force { FORCE_DEFINITION ... } |
    attach [VECTOR] { ATTACH_DEFINITION ... } |
    fixed VECTOR |
    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 }
FORCE_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] [force INTEGER] [fixed BOOL] } |
    connection { INDEX1, INDEX2 [stiffness FLOAT] [damping FLOAT]
                 [length FLOAT] } |
    viscoelastic { INDEX1, INDEX2 [stiffness FLOAT] [length FLOAT]
                 [accuracy FLOAT] [ VE_ELEMENTS...  ] } |
    face { INDEX1, INDEX2, INDEX3 } |
    load_file FILE_NAME
VE_ELEMENT:
    element { F_STIFFNESS, F_DAMPING [, F_POSITION ] ] }

2.7.4.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.4.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, in contrast to method 1 and 2 it automatically controls the time steps (see Section 2.7.4.1.1.6, “adaptive time stepping”):

2.7.4.1.1.2. bounding

Selects the bounding method to speed up collision detections between masses, connections and faces.

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.

2.7.4.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.4.1.6, “Field forces”) non constant gravity can be simulated

2.7.4.1.1.4. global fixation

All movements in the simulation system can be fixed in one or two directions using the fixed option.

This can be used to make the MechSim system perform simulation of 2D and 1D systems. Note however that the simulation still runs in 3D internally.

by adding:

fixed <0, 0, 1>

to the mechsim{} block you can for example perform a simulation in the x-y-plane.

2.7.4.1.1.5. 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.4.1.7, “Attaching masses” and Section 2.7.4.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.

2.7.4.1.1.6. adaptive time stepping

Simulation method 3 automatically controls the used time steps. This is done by calculating every step with double steps size and comparing the results. So the local discretization error is automatically kept below a specified threshold. You can specify this threshold and the minimum allowed step size with the accuracy keyword:

accuracy THRESHOLD, MIN_STEP

the minimum step size is optional, default values are:

THRESHOLD : 1.0e-5

MIN_STEP : 1.0e-7

The step size to start with can be specified with time_step. It is usually not critical but can be necessary to be set sufficiently low for a successful simulation.

The render statistics show the actual minimum, average and maximum time steps used during the simulation.

Example 2.13. Adaptive time stepping

A simulation setup for adaptive time stepping could look like:

mechsim {
  ...
  method 3
  time 1/30
  accuracy 1e-5, 1e-6
  ...
}

	Note
	Adaptive time stepping guarantees a certain local accuracy of the simulation, it does not prevent instability though. It will not be possible to simulate a system that does not run with fixed time steps.

#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.4.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.14. 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.4.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.

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

2.7.4.1.4.1. Point masses

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.4.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
}

2.7.4.1.4.2. Connections

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.

Connections simulate a parallel elasticity and linear damping element - a so called Voigt-Kelvin-Element.

The force they exhibit on the masses they connect is:

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 (x₀) of the connection. If it is not specified the distance of the two masses at the time the connection is created 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
      }
      ...
    }
  }
}

2.7.4.1.4.3. Faces

The face block defines a triangular face between three point masses. It is used for collision calculations (see Section 2.7.4.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.4.1.4.4. Viscoelastic connections

Viscoelastic connections allow you to simulate more complex material properties than conventional connections. Conventional connections simulate a parallel elasticity and linear damping element - a so called Voigt-Kelvin-Element (see Section 2.7.4.1.4.2, “Connections”). With this element the force of the connection only depends on the momentaneous distance and velocity of the masses. Viscoelastic connections use a more complex model that also allows you to simulate effects like relaxation.

The element definition contains the index of the two masses it connects and a relaxed length - just like conventional connections. The stiffness value specifies the static elasticity of the connection (unit N/m or kg/s²). Furthermore you can specify an arbitrary number of parallel Maxwell-Elements. Each contains two mandatory parameters: the stiffness (unit N/m or kg/s²) and the damping (unit kg/s)

The force viscoelastic connections exhibit on the masses they connect is:

y_i are the inner coordinates of the Maxwell-Elements that get calculated by the simulation system.

A complete example for a connection definition:

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

      viscoelastic {
        0,               /* index of the first mass */
        1                /* index of the second mass */
        stiffness 10000  /* static stiffness */
        element {        /* first maxwell element */ 
          2000,          /*   - stiffness */
          5000           /*   - damping */
        }
        element {        /* second maxwell element */  
          4000,          /*   - stiffness */ 
          2000           /*   - damping */ 
        }
        // length 0.5
      }
      ...
    }
  }
}

	Note
	In contrast to normal connections viscoelastic connections do not participate in collisions. If you want connection-connection collisions in your simulation you have to use normal connections in addition.

2.7.4.1.4.5. 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.4.1.4.6. 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.4.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, m1, m2) { (m1*m2)/(dist*dist) }

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

#include "mechsim.inc"

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

global_settings {
  ...
  mechsim {
    ...
    attach <1,1,0> {
      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:
    time | mass_count | connection_count | face_count |
    mass( INTEGER ) : MASS_FLOAT_ELEMENT |
    connection( INTEGER ) : CONNECTION_FLOAT_ELEMENT |
    viscoelastic( INTEGER ) : VISCOELASTIC_FLOAT_ELEMENT |
    face( INTEGER ) : FACE_FLOAT_ELEMENT
MASS_FLOAT_ELEMENT:
    radius | mass
CONNECTION_FLOAT_ELEMENT:
    index1 | index2 | length | stiffness | damping
VISCOELASTIC_FLOAT_ELEMENT:
    index1 | index2 | length | stiffness | accuracy | count | 
    element( INTEGER ) : stiffness | damping | position
FACE_FLOAT_ELEMENT:
    index1 | index2 | index3

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

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 force is the summed force that accelerated the mass in the last simulation step. 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 time value returns the current time index of the simulation (in seconds). Inside the mechsim block this is the start time of the simulation, afterwards it returns the time index when the simulation ended.

The force values return the force a connection exerts on the masses it connects. This value is a scalar, the force is always in direction of the connection. Note this value can of course be calculated manually as well, it is supplied for convenience.

The file format used for storing the simulation data has changed in MegaPOV 1.2. Backwards compatibility is provided for reading MegaPOV 1.1 style simulation data files. The new file format is especially introduced for being forward compatible with future versions of MegaPOV. This means that data files written by newer versions of MegaPOV should still be possible to read with MegaPOV 1.2 - it will just ignore the data it cannot handle.

The file format - like the old one - is a ASCII text file format. It starts with a four character string ('MSIM') identifying the mechanics simulation file format. The second element (seperated by a comma) is an integer number specifying the subformat of the file. Subformat 4 is the current new format. Subformat 3 and lower are read with the backwards compatibility feature.

After that follows a line break and the first character of every line following indicates what kind of data is stored in that line. The following characters are recognized right now:

MSIM, 4,
I 3 2 0
T 0.133333 0.00182897 16
M 0.000000000000 0.000000000000 2.400000000000 0.000000000000 0.000000000000 0.000000000000 20.944 0.1 1 0 -1 -1
M 0.998031324856 0.000000000000 2.309705370342 -0.078825113822 0.000000000000 -1.298327808122 20.944 0.1 0 0 -1 -1
M 1.996410451933 0.000000000000 2.390382496553 -0.094947075882 0.000000000000 -0.744192468433 70.6858 0.15 0 0 -1 -1
C 0 1 1 50000 2000 0
C 1 2 1 50000 2000 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, "")

Variation of the MechSim_Show_All_Objects() using default values for all parameters. If there are faces in the simulation data only faces are shown, otherwise connections and masses. No file is written.

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.5, “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.13, “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.18, “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")

This macro generates a cylinder for a single connection. In contrast to the other macros the cylinder is generated without texture.

This macro generates a cylinder for a single viscoelastic connection. In contrast to the other macros the cylinder is generated without texture.

Most of the lower level 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.

The VE_Elements parameter has to be specified for all macros generating viscoelastic connections (see Section 2.7.4.1.4.4, “Viscoelastic connections”).

It is a 2d array containing the stiffness and damping values of all the maxwell elements of the viscoelastic connections. The first index specifies the number of the maxwell element (and the size of the array sets the number of maxwell elements). The size of the array in the second dimension should be 2 - the first value is the stiffness and the second the damping.

#declare VE_Elements1=array[3][2]
				#declare VE_Elements1[0][0]=2000;
				#declare VE_Elements1[0][1]=240000;
				#declare VE_Elements1[1][0]=7000;
				#declare VE_Elements1[1][1]=12000;
				#declare VE_Elements1[2][0]=120000;
				#declare VE_Elements1[2][1]=1600;

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. Additional functions control the fixed and attached masses.

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, “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 }
#declare fn_Fixed=function { -1 }
#declare fn_Attach=function { -1 }


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, fn_Fixed, fn_Attach, Con_Array)

Variant of MechSim_Generate_Grid_Fn() generating viscoelastic connections instead of normal connections. Parameters are the same but instead of fn_Damping there are the following:

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.3, “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)

Variant of MechSim_Generate_Grid() generating viscoelastic connections instead of normal connections. Parameters are the same but instead of Damping there are the following:

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.5, “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)

Variant of MechSim_Generate_Grid_Std() generating viscoelastic connections instead of normal connections. Parameters are the same but instead of Damping there are the following:

Variation of the MechSim_Generate_Grid_Std() macro (see Section 3.4.5.7, “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)

Variant of MechSim_Generate_Box() generating viscoelastic connections instead of normal connections. Parameters are the same but instead of Damping there are the following:

Variation of the MechSim_Generate_Box() macro (see Section 3.4.5.9, “MechSim_Generate_Box()”) where you specify two corner coordinates like for the POV-Ray™ box{} shape instead of a Cube_Scale parameter.

MechSim_Generate_Block(<0, 0, 0>, 0.08, 20, 1000, 2000,
                       true, <0, 0, 0>, <1, 1, 1>, <4, 4, 4>, No_Trans, 3)

Variant of MechSim_Generate_Block() generating viscoelastic connections instead of normal connections. Parameters are the same but instead of Damping there are the following:

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, “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 fn_Attach=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, fn_Attach, Con_Array)

Variant of MechSim_Generate_Patch() generating viscoelastic connections instead of normal connections. Parameters are the same but instead of Damping there are the following:

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.13, “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, “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.16, “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.1
    method 2
  }

  time_step (1/30)/300
  step_count 300
		
  #if (frame_number=1)
    topology {
      mass { <-2.8, -8.0, 0.9>, <2, 5, 0>, 0.1 density 5000 }
      save_file "tut02.dat"
    }
  #else
    topology {
      load_file "tut02.dat"
      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:

The next two lines specify the timing of the simulation:

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.

There is also the possibility to use adaptive time stepping that will be introduced in the next part of this tutorial.

What follows is an #if conditional. It makes sure the mass is generated in the first frame and saved to the file while the following frames load and save the simulation data.

The first part contains statements for the first frame:

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

The save_file statement finally saves this mass to a file.

The second part contains the variant for the subsequent frames.

The topology{} block here 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.

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 using the render options that can be found in the scene file comment and we get the following result:

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 have to be taken into account.

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

collision {
  1, 0, 0
  stiffness 60000
  damping 4000
}

The first three numbers tell MegaPOV which collision to calculate. For details see Section 2.7.4.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.

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).

Force based environment collisions lead to a more realistic simulation of the interaction of the masses with the environment since the movement of the masses does not abruptly change. Using this method is necessary for all higher order integration methods which will be introduced later.

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 important 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_Block(
  <0, 0, 0>, 0.07, 1500, 22000, 2000, true,
  <-0.5, -2.75, 1.0>, <0.5, 2.75, 2.0>, <3, 12, 3>, No_Trans, 3
)

The meaning of the different parameters is described in Section 3.4.5.11, “MechSim_Generate_Block()”.

Apart from the grid macro we introduce a different simulation method in this scene. method 3 uses adaptive time stepping. This means you don't need to specify a step size but instead specify how accurate the simulation should be. The accuracy option takes two parameters: the maximum allowed local discretization error and the minimum step size to use.

Note that you might still need to specify an appropriate starting step size using time_step - the default value might not be appropriate.

In addition to the accuracy settings the total time per frame is specified using the time parameter.

The resulting animation shows a moving and deforming box geometry.

The MechSim_Generate_Block() 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.15, “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.4, “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.

Masses can not only collide but also can interact in a freely definable way. This way you can simulate physical effect like electromagnetic fields and gravity.

Mass interaction is defined globally with theinteraction keyword in the mechsim{} block. For the inverse square law of gravity you for example could use the following setup:

// Gravitation constant: 6.672e-11 m^3*kg^-1*s^-2
#declare G=6.672e-11;

// Newton's law of gravitation
#declare fn_Gravity=
  function(x, y, z, dist, m1, m2) {
    (G*m1*m2)/(dist*dist)
  }

global_settings {
  mechsim {
    ...
    interaction {
      function(x, y, z, dist, m1, m2) { fn_Gravity(x, y, z, dist, m1, m2) }
    }
    ...
  }
}

As you can see the interaction function has 6 parameters. The first three are the usual coordinates so you can define an interactions that differs depending on the absolute position. The last three are optional, the first of them is the distance between the masses and the other two the masses of the two masses that interact.

The simulation system calls this function for every pair of masses in every simulation step. This can of course be quite slow with a lot of masses. But in this simple example we only want to simulate the movement of the earth around the sun which is done with the following topology definition:

#declare Mio_km=1.0e9;

topology {
  // Sun
  mass { <0,0,0>, <0,0,0>, 696.0e6 mass 1.99e30 }
  // Earth
  mass { <149.6*Mio_km,0,0>, <0,29.8*1000,0>, (6371.0)*1000 mass 5.97e24 }

  save_file "tut09.dat"
}

Simulating this with 1 step per day is done with the following code:

step_count 2000

// 1 day per step
time_step (24*3600)/2000

topology {
  load_file "tut09.dat"
  save_file "tut09.dat"
}

And results in the following movement. The size of the sun and earth is of course strongly exaggerated. You can find a more complex simulation of all the inner planets in the planets.pov sample scene.