File Formats

 
Extended VTK format: *.vti, *.vtu

Ready's file format is an extended version of VTK's format, which uses XML. These are the Ready-specific XML elements, in alphabetical order:

Here is a simple example of a *.vti file:

<?xml version="1.0"?> <VTKFile type="ImageData" version="0.1" byte_order="LittleEndian" compressor="vtkZLibDataCompressor"> <RD format_version="2"> <rule type="formula" name="Schlogl"> <param name="timestep"> 0.1 </param> <formula number_of_chemicals="1"> delta_a = laplacian_a + a - a*a*a; </formula> </rule> <initial_pattern_generator apply_when_loading="true"> <overlay chemical="a"> <overwrite /> <white_noise low="-0.1" high="0.1" /> <everywhere /> </overlay> </initial_pattern_generator> <render_settings> <low value="-1.0" /> <high value="1.0" /> <contour_level value="0" /> </render_settings> </RD> <ImageData WholeExtent="0 127 0 63 0 0" Origin="0 0 0" Spacing="1 1 1"> <Piece Extent="0 127 0 63 0 0"> <PointData> <DataArray type="Float32" Name="a" format="appended" RangeMin="0" RangeMax="0" offset="0" /> </PointData> <CellData> </CellData> </Piece> </ImageData> <AppendedData encoding="base64"> _AQAAAACAAAAAAAAANAAAAA==eJztwQEBAAAAgJD+r+4ICgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAYgAAAAQ== </AppendedData> </VTKFile>

This is the standard VTK format but with an RD element (inside the VTKFile element) that contains all the Ready-specific data.

Ready supports mesh-based systems as well (*.vtu) - these have UnstructuredGrid instead of ImageData sections. Both can be read as the standard VTK format, for example in ParaView.

The following sections describe the Ready-specific XML elements.

<RD>

Specifies the current rule and information about the pattern.

Attributes:

• format_version (required) : Integer value that is increased in later versions when the format changes. Used to alert the user that they might need to update their software.

Contains:

• <description> (optional).
• <rule> (required).
• <initial_pattern_generator> (optional).
• <render_settings> (optional).

<description>

A description of the pattern.

Contains:

Plain text. HTML can also be used but must be XML-escaped as in the table below. See the description in munafo_glider.vti for an example.

<	>	"	&	'
&lt;	&gt;	&quot;	&amp;	&apos;

<rule>

Attributes:

• type (required) : "inbuilt" or "formula" or "kernel".
• name (required) : The name of this rule. If type="inbuilt" then name must match one of the inbuilt rules (currently just "Gray-Scott").
• wrap (optional) : "1" if the data should wrap around, or "0" if the data should have a boundary. Currently only affects images (vti files), not meshes. Default: "1".
• neighborhood_type (optional) : "vertex" for vertex-neighbors, "edge" for edge-neighbors or "face" for face-neighbors. This parameter only affects meshes (vtu files). Default: "vertex".

Contains:

• <param> (multiple, optional).
• <formula> (required if rule type="inbuilt").
• <kernel> (required if rule type="kernel").

<param>

A parameter of the rule. Most rules require one or more named parameters, such as timestep.

Attributes:

• name (required) : The name of this parameter.

Contains:

The value of this parameter.

<formula>

Attributes:

• number_of_chemicals (required) : The number of chemicals used.
• block_size_x (optional) : The x component of the dimensions of the spatial unit processed by each kernel call. Default: 4x1x1
• block_size_y (optional) : The y component.
• block_size_z (optional) : The z component.
• accuracy (optional) : The stencil accuracy to use. "low", "medium" or "high". Default: "medium".

Contains:

An OpenCL kernel snippet, where the chemicals are named a, b, c, etc.

The formula can specify the rate of change of each chemical (delta_a, delta_b, etc.), typically using the Laplacian of each (laplacian_a, etc.). Example: delta_a = laplacian_a;

Alternatively the formula can write directly into the chemicals. Example: a = x_pos;

For a list of the keywords you can use, see Writing new rules.

In the kernel section below, the "delta_a = ..." lines show how the formula might be inserted at that location in a full kernel.

See the pattern files for more examples.

<kernel>

Attributes:

• number_of_chemicals (required) : The number of chemicals used.
• block_size_x (required for images) : The x component of the dimensions of the spatial unit processed by each kernel call. For float4 possible block size are: 4x1x1, 2x2x1, 1x4x1, etc. For float2: 2x1x1, etc. For float: 1x1x1.
• block_size_y (required for images) : The y component.
• block_size_z (required for images) : The z component.

Contains:

A full OpenCL kernel, as plain text. Below is an example kernel that works on a 2-chemical image. Arrays a_in and b_in contain the current state of the chemicals a and b, and a_out and b_out should get written with the new values.

__kernel void rd_compute(__global float4 *a_in,__global float4 *b_in,__global float4 *a_out,__global float4 *b_out) { const int x = get_global_id(0); // returns the x-coordinate of this kernel call const int y = get_global_id(1); const int z = get_global_id(2); const int X = get_global_size(0); // returns the x size of the image const int Y = get_global_size(1); const int Z = get_global_size(2); const int i_here = X*(Y*z + y) + x; // use this to get the array index of cell x,y,z float4 a = a_in[i_here]; // this kernel processes 4 floats at once, stored in a float4 type float4 b = b_in[i_here]; // parameters: float timestep = 1.0f; // update step: float delta_a = 0.0f; float delta_b = 0.0f; delta_a = 0.1f; // formula line delta_b = -0.2f; // formula line a_out[x] = a + timestep * delta_a; b_out[x] = b + timestep * delta_b; }

Below is an example that works on 2-chemical meshes. The cells can have different numbers of neighbors but for efficiency we pass in fixed-length arrays: neighbor_indices contains the index of each neighbor, neighbor_weights contains a normalized weight (non-zero for valid neighbors), while max_neighbors contains the size of the arrays. The code below shows how we can compute a Laplacian from this input.

__kernel void rd_compute(__global float *a_in,__global float *b_in,__global float *a_out,__global float *b_out, __global int* neighbor_indices,__global float* neighbor_weights,const int max_neighbors) { const int x = get_global_id(0); float a = a_in[x]; // this kernel processes single floats float b = b_in[x]; float laplacian_a = 0.0f; float laplacian_b = 0.0f; int offset = x * max_neighbors; for(int i=0;i<max_neighbors;i++) { laplacian_a += a_in[neighbor_indices[offset+i]] * neighbor_weights[offset+i]; laplacian_b += b_in[neighbor_indices[offset+i]] * neighbor_weights[offset+i]; } laplacian_a -= a; laplacian_b -= b; // scale the Laplacians to be more similar to the 2D square grid version, so the same parameters work laplacian_a *= 4.0f; laplacian_b *= 4.0f; // parameters: float timestep = 1.0f; float D_a = 0.082f; float D_b = 0.041f; float k = 0.06f; float F = 0.035f; // update step (Gray-Scott) float delta_a = 0.0f; float delta_b = 0.0f; delta_a = D_a * laplacian_a - a*b*b + F*(1.0f-a); // formula line delta_b = D_b * laplacian_b + a*b*b - (F+k)*b; // formula line a_out[x] = a + timestep * delta_a; b_out[x] = b + timestep * delta_b; }

See the pattern files for more examples.

<initial_pattern_generator>

Attributes:

• apply_when_loading (optional) : "true" if the initial pattern generator should overwrite the data when the file is loaded. Default: "true"
• zero_first (optional) : "true" if the values should be set to zero before applying. Default: "true"

Contains:

• overlay (multiple).

<overlay>

Attributes:

• chemical (required) : the chemical (a, b, c, etc.) that this overlay applies to.

Contains:

1. operation (required) : one of overwrite, add, subtract, multiply or divide.
2. fill (required) : one of constant, white_noise, perlin_noise, other_chemical, linear_gradient, radial_gradient, gaussian, sine or parameter.
3. shape (required) : one or more of everywhere, rectangle, circle or pixel. Any cell with a centroid inside the shape will be affected.

<overwrite>

<add>

<subtract>

<multiply>

<divide>

<constant>

Attributes:

• value (required) : the constant value.

<white_noise>

Attributes:

• low (required) : the random values will be above this value.
• high (required) : the random values will be below this value.

<perlin_noise>

Attributes:

• scale (optional) : larger values give peaks further apart. Default: 64.
• num_octaves (optional) : larger values give more detail. Default: 8.

<other_chemical>

Attributes:

• chemical (required) : the other chemical (a, b, c, etc.) to sample.

<linear_gradient>

Attributes:

• val1 (required) : the value at the start of the gradient.
• val2 (required) : the value at the end of the gradient.

Contains:

• point3d (required) : the start point for the gradient.
• point3d (required) : the end point for the gradient.

<radial_gradient>

Attributes:

• val1 (required) : the value at the center of the gradient.
• val2 (required) : the value at the edge of the gradient.

Contains:

• point3d (required) : the center point for the gradient.
• point3d (required) : the edge point for the gradient.

<gaussian>

Attributes:

• height (required) : the height of the peak of the Gaussian.
• sigma (required) : the width of the Gaussian, in the range [0,1] as a proportion of the largest image dimension.

Contains:

• point3d (required) : the center of the Gaussian.

<sine>

Attributes:

• amplitude (required) : the height of the sine wave.
• phase (required) : the phase of the sine wave, in radians [0,2pi].

Contains:

• point3d (required) : the start point.
• point3d (required) : the end point.

<parameter>

Attributes:

• name (required) : the name of the parameter.

<everywhere>

<rectangle>

Contains:

• point3d (required) : the first corner of the rectangle.
• point3d (required) : the second corner of the rectangle. All the coordinates should be higher than in the first corner.

<circle>

Attributes:

• radius (required) : the radius of the circle, in the range [0,1] as a proportion of the largest image dimension.

Contains:

• point3d (required) : the center of the circle.

<pixel>

Attributes:

• x (required) : the x-coordinate of the pixel, a 0-based integer.
• y (required) : the y-coordinate of the pixel, a 0-based integer.
• z (required) : the z-coordinate of the pixel, a 0-based integer.

<point3d>

Attributes:

• x (required) : the x-coordinate.
• y (required) : the y-coordinate.
• z (required) : the z-coordinate.

<render_settings>

• <surface_color r="1" g="1" b="1" />
  The RGB color to use for the surface (range: 0.0-1.0).
• <colormap value="spectral" />
  The colormap to use.
• <color_low r="0" g="0" b="1" />
  The color for low values (range: 0.0-1.0). If colormap is 'HSV blend'.
• <color_high r="1" g="0" b="0" />
  The color for high values (range: 0.0-1.0). If colormap is 'HSV blend'.
• <show_color_scale value="true" />
  Whether to show the color scale that maps values to colors.
• <show_multiple_chemicals value="true" />
  Whether to show all the chemicals, or just the active one.
• <active_chemical value="a" />
  The chemical to show (a, b, c, etc.).
• <low value="0" />
  The lowest value that chemicals in this system typically take. Used to determine the colors and the axes.
• <high value="1" />
  The highest value that chemicals in this system typically take.
• <vertical_scale_1D value="30" />
  The vertical size of the 1D line graphs.
• <vertical_scale_2D value="15" />
  The vertical size of the 2D surface plots.
• <contour_level value="0.25" />
  The value to use for the surface contour in 3D systems.
• <cap_contour value="true" />
  Whether to close the holes where the contours meet the boundary.
• <invert_contour_cap value="false" />
  If true, closes the contour holes on the other side.
• <use_wireframe value="false" />
  Whether to show the surface as wireframe or as smooth surface (false=surface, true=wireframe).
• <show_cell_edges value="false" />
  Whether to show the edges of the cells or not.
• <show_bounding_box value="true" />
  Whether to show the bounding box or not.
• <slice_3D value="true" />
  Whether to add a 2D color slice through the 3D volume.
• <slice_3D_axis value="z" />
  The axis that the slice should be perpendicular to.
• <slice_3D_position value="0.5" />
  The position along the slice_3D_axis to slice at (range: 0.0-1.0, relative to the overall size).
• <show_displacement_mapped_surface value="true" />
  Whether to show the height-mapped surface for 2D systems as well as the color-mapped image.
• <color_displacement_mapped_surface value="true" />
  Whether to show the color image on the height-mapped surface.
• <use_image_interpolation value="true" />
  Whether to interpolate the image or show sharp pixels (false=sharp pixels, true=interpolated).
• <timesteps_per_render value="100" />
  Determines the initial running speed by specifying how often the render window should be updated.
• <show_phase_plot value="true" />
  Whether to show the phase plot (a scatter graph of the chemicals for each pixel plotted against each other).
• <phase_plot_x value="a" />
  The chemical to show on the horizontal plot axis (a, b, c, etc.).
• <phase_plot_y value="b" />
  The chemical to show on the vertical plot axis (a, b, c, etc.).
• <phase_plot_z value="c" />
  The chemical to show on the inwards plot axis (a, b, c, etc.).
• <plot_ab_orthogonally value="false" />
  If true in a 1D pattern, we plot a and b against each other in the line graph, allowing us to show e.g. Schrodinger equation wave packets as a corkscrew.