2.6. Global Settings

This addition simulates decrease of reactive chemicals in film emulsion during exposure. The areas that have received more light react less than other areas. Useful for high contrast scenes as it brings up the dark areas and limit bright areas.

There are two new keywords in the global_settings block:

exposure FLOAT
exposure_gain FLOAT

where exposure_gain is optional and has default value 1. Both parameters have to be greater than 0 to influence rendering.

exposure can be thought as film speed, aperture and exposure time multiplied together. The value is not absolute. If the light source intensities in the scene are multiplied by 10 and exposure value is divided by 10 the resulting image will be the same.

exposure_gain can be used to brighten scenes with low maximum intensity when also low exposure value is used.

The equation for such behavior of color used in MegaPOV is:

color = exposure_gain * (1 - exp( - exposure * color )).

The mechanics simulation system is integrated into the POV-Ray™ rendering system. The simulation parameters are set in the global_settings{} block of the scene file. While parsing the scene MegaPOV calculates the simulation exactly where it occurs in the file. This way the simulation can interact with the scene by using objects, functions and values set before the mechsim{} block in the scene file. But additionally the simulation data can also be used in the scene later on for placing objects according to the simulation results.

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

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

The default values are:

method : 1

gravity : <0, 0, 0>

time_step : 0.1

step_count : 10

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.6.3.1.7 and Section 2.6.3.1.2) Specifying an end_time value instead of time is also possible.

[Important]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.

Environments are shapes the simulated masses are supposed to interact with. Several of them can be created with environment{} blocks.

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 two numbers at the beginning of the collision{} section collision can be toggled for both mass-mass-collisions and mass-face-collisions. Both 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.

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

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.

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:

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.6.3.1.3) 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 */
      }
      ...
    }
  }
}

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

  • The position (vector), unit: m
  • The velocity (vector), unit: m/s
  • The mass (float), unit: kg
  • The radius (float), unit: m
  • A flag (integer) currently only containing the fixed value. This flag could contain other boolean values in the future (connected with logical OR) so it should be tested accordingly (if (flag & 1))
  • The group index (integer)
  • Only for subformat 3: The attach index (integer)

For each connection:

  • The index of the first mass (integer)
  • The index of the second mass (integer)
  • The relaxed length (float), unit: m
  • The stiffness (float), unit: N/m or kg/s²
  • The damping constant (float), unit: kg/s
  • The group index (integer)

For each face:

  • The index of the first mass (integer)
  • The index of the second mass (integer)
  • The index of the third mass (integer)
  • The group index (integer)

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.