off2pov - converts an OFF file to POV format

Usage | Examples | Notes | POV File Structure

Usage

Description

Convert OFF files to POV format for display with POV-ray.

Options

input_files: input files in OFF format, or if not given the program reads from standard input

-h: program help
-v <rad>: radius of vertex spheres (0 for no vertex sphere), or 'b' to have radius of balls in the first file of the maximum size without overlap (default: ball_rad/12)
-e <rad>: radius of edge cylinders (default: vertex_rad/1.5)
-x <elems>: hide elements. The element string can include v, e and f to hide, respectively, vertices, edges and faces
-n: show vertex numbers
-O <type>: output type, can be: a all in one POV file (default), s separate files, o objects only, t template only
-I <fils>: include files (separated by commas) for the POV scene file. Files default_pov.inc and the name of the output file with '.' changed to '_' and followed by .inc are always included.
-J <fils>: include files (separated by commas) ) containing additional POV objects for the POV scene file. These objects will be included alongside the objects created from input files.
-i <fils>: include files (separated by commas) for every POV geometry. Files default_off_i.inc and the name of the input file with '.' changed to '_' and followed by _off_i.inc are always included with each geometry.
-o <file>: write output to file, if this option is not used the program writes to standard output

Viewing Options

-D <dist>: distance to camera
-C <cent>: centre of points, in form "x_val,y_val,z_val" (default: calculated)
-L <look>: point to look at, in form "x_val,y_val,z_val" (default: points centre)
-R <rot>: rotate about axes through centre of points, in form "x_val,y_val,z_val" (degrees)
-P <pers>: narrow the angle of perspective (range 0-100, default: 2 mono, 4 stereo)
-W <shad>: use lighting with shadows can be 0 (default) yes for mono no for stereo, 1 yes, 2 no
-S <ster>: produce stereo output, val is 0 (default) mono, 1 stereo with one image file, 2 stereo with two image files (use something like povrays +KFF2 option for output), 3 mono with four views around the object
-B <col>: background colour, a POV colour vector in form "r_val,g_val,b_val" with values ranging 0 to 1

Precision Options

-d <dgts>: number of significant digits for output (default 17) or if negative then the number of digits after the decimal point
-t: display type for faces 0 POV polygons, 1 (default) flattened POV polygons, 2 triangulate polygons by joining each edge to a centre point. (Incomplete solution to rendering non-simple polygons. Will not render all polygons correctly.)

Examples

Draw a ball pack as balls

   off2pov -v b -o pack.pov pack.off

Draw the other side of it

   off2pov -v b -R 0,180,0 -o pack.pov pack.off

Draw an icosahedron without its faces

   unipoly icosahedron | off2pov -x f -o icosa.pov

Draw an icosahedron without its vertex or edge elements

   unipoly icosahedron | off2pov -x ve -o icosa.pov

Draw an icosahedron with thin vertex and edge elements

   unipoly icosahedron | off2pov -v 0.01 -e 0.008 -o icosa.pov

Notes

The output POV file is easy to edit in a text editor. Many of the program options which are used when creating the file can also be set afterwards by editing the file. See POV Files Structure.

Vertices coinciding, or very close together, may cause no elements to be drawn for the vertices or edges if default sizes are used. Instead, a value can be set with -v or -e.

Use -v b to draw ball packs.

Shapes with self-intersecting faces generally need the -t option, otherwise they may be displayed with missing areas. However this option may draw parts of the face outside of the edges.

POV-ray may not be able to display the output, or may display it incorrectly. I have tried to make the generated file robust, but precision issues could cause problems in apparently correct POV files.

Including files and making changes by hand may easily break some of the basic functionality, for example vertex numbering and some stereo options.

POV Files Structure

The POV files output by off2pov contain a number of preset values. These are either values that were given as options to the program, or were generated automatically by the program. The POV file has been structured so that it may be easily changed using include files passed to the program and by hand editing of the file itself.

Variables

Scene Variables

These are the variables that appear in the POV scene file. They appear only once in any set of output.

Width: Maximum distace between 2 points. A figure for the size of all the objects in the file.
StereoType: Stereo type may be 0 - mono, 1 - single image stereo, 2 - double image file stereo, or 3 a composite of four views. If 2 then use the povray option +KFF2 to produce the left and right stereo views in separate image files.
Distance: Distance from viewer to point looked at.
Centre: The centre of all the objects. The point the objects are rotated about.
PerspFactor: A value for the width of perspective. If 0 then use 2 for stereo views and 4 for mono views. There probably won't be noticeable change above 50. Perspective works by moving the viewing distance back and enlarging the area which is looked at.
LookAt: The point the camera looks at.
Rotation: Rotation about the centre.
Shadow: Whether the lights cast shadows. 0 - shadows mono no shadows stereo, 1 - no shadows, 2 - shadows.
BgColour: Background colour.
MaxTraceLevel: POV-Ray's max_trace_level. Use a higher value if black areas appear when using transparency.

A set of default geometry variables may also appear. They have the same name as the geometry variables but are prefixed by glob_. The geometries may then set their individual variables to these global values.

A different camera and different lights can be given in an include file. The default camera or lights can be excluded.

ExcludeDefCamera: 0 (or undefined) - include default camera, 1 - exclude default camera.
ExcludeDefLights: 0 (or undefined) - include default lights, 1 - exclude default lights.

Geometry Variables

These are the variables associated with each geometry. The geometries are processed sequentially and new values are written to these variables at the start of processing.

show: 1 - show object, 0 - don't show object.
verts_show: 1 - show vertices, 0 - don't show vertices.
edges_show: 1 - show edges, 0 - don't show edges.
faces_show: 1 - show faces, 0 - don't show faces.
vert_nums_show: 1 - show vertex numbers, 0 - don't show vertex numbers.
vert_rad: Radius of default vertex spheres.
vert_col: Colour of default vertex spheres.
vert_trans: Transparency of default vertex spheres.
edge_rad: Radius of default edge cylinders.
edge_col: Colour of default edge cylinders.
edge_trans: Transparency of default edge cylinders.
face_col: Colour of default face polygons.
face_trans: Transparency of default face polygons.
face_dtype: Display type for faces, may be 0 - POV-ray polygons, 1 - flattened polygons, 2 - triangulated polygons by joining each edge to a centre point.
col_map: Array mapping colour indexes to colours.
tex_map: Array mapping colour indexes to textures.
vert_col_map: Array mapping vertex colour indexes to colours.
vert_tex_map: Array mapping vertex colour indexes to textures.
edge_col_map: Array mapping edge colour indexes to colours.
edge_tex_map: Array mapping edge colour indexes to textures.
face_col_map: Array mapping face colour indexes to colours.
face_tex_map: Array mapping face colour indexes to textures.

The elements and colour indexes are held in the following arrays

verts: Vertex coordinates. The array size is held in num_verts.
v_cols: Vertex colours and colour indexes.
edges: Edges, each entry is a two item array holding two indexes into the verts array. The array size is held in num_edges.
e_cols: Edge colours and colour indexes.
faces: Faces, a sequential array of the face values from an OFF file. There are two kinds of value, a first number says how many vertices are in the face polygon, the next values are the indexes into the verts array for these vertices. The next number is the number of vertices in the next face, and so on. The array size is held in num_face_items. The number of faces is held in num_faces.
f_cols: Face colours and colour indexes.

Macros

The elements are drawn using POV-ray macros. These may be overriden, using an include file passed with option -i or by editing the POV file, allowing processing and custom drawing of the elements.

Colour Maps

col_to_tex(col, elem_tex_map, elem_col_map, def_col)

The col_to_tex macro maps a colour or colour index to a texture. col is the colour vector, if the first coefficient is negative then its positive value is a colour index, otherwise the vector represents a POV-ray colour. elem_tex_map maps indexes to textures. elem_col_map maps indexes to colours. def_col is the default colour. The texture is found in the following way

If col is a POV colour then use a default texture with this colour
If index col has been set in elem_tex_map then use this texture
If index col has been set in elem_col_map then use a default texture with this colour.
If index 0 has been set in elem_tex_map then use this texture
If index 0 has been set in elem_col_map then use a default texture with this colour.
use a default texture with colour def_col

In other words textures are preferred over colours, and you can overide the default by setting the first map array item (index 0) to the new texture or colour.

Display Vertex

   disp_vertex(vertex, col)

vertex is the index into the verts array. col is the colour.

Display Edge

   disp_edge(edge, col)

edge is the index into the edges array. col is the colour.

Display Face

   disp_face(face, idx, col)

face is the face number. idx is the index into the face array (pointing to the value giving the number of vertices in the face). col is the colour.

The default macro calls one of the following macros, determined by the value of face_dtype, to actually display the face

   disp_face_polygon(face, idx, col)
   disp_face_flattened_polygon(face, idx, col)
   disp_face_triangles(face, idx, col)

Display Extra

   disp_extra()

Called once for each geometry. The default macro does nothing.

Up: Programs and Documentation
Next: off2eig - converts an OFF file to EIG format

Antiprism Documentation 9.2.2007 - http://www.antiprism.com/