antiprism-0.23
Up Next

# off2pov - convert an OFF file to POV format

Usage | Examples | Notes | POV-Ray File Structure

## Usage

    Usage: off2pov [options] input_files

    Convert files in OFF format to POV format for display in POV-ray. If
    input_files are not given the program reads from standard input.

    Options
      -h,--help this help message (run 'off_util -H help' for general help)
      --version version information
      -v <rad>  radius of vertex spheres, or 'b' to have radius of balls
                of the maximum size without overlap (default: ball_rad/15)
      -e <rad>  radius of edge cylinders (default: vertex_rad/1.5)
      -V <col>  default vertex colour, in form 'R,G,B,A' (3 or 4 values
                0.0-1.0, or 0-255) or hex 'xFFFFFF' (default: 1.0,0.5,0.0)
      -E <col>  default edge colour, in form 'R,G,B,A' (3 or 4 values
                0.0-1.0, or 0-255) or hex 'xFFFFFF', 'x' to hide implicit edges
                (default: 0.8,0.6,0.8)
      -F <col>  default face colour, in form 'R,G,B,A' (3 or 4 values
                0.0-1.0, or 0-255) or hex 'xFFFFFF' (default: 0.8,0.9,0.9)
      -x <elms> hide elements. The element string can include v, e and f
                to hide vertices, edges and faces
      -n <elms> show element index number labels. The element string can
                include v, e and f to label vertices, edges and faces
      -s <syms> show symmetry elements. The element string can include
                   x - rotation axes
                   m - mirror planes
                   r - rotation-reflection planes
                   a - all elements (same as xmr)
      -m <maps> a comma separated list of colour maps used to transform colour
                indexes, a part consisting of letters from v, e, f, selects
                the element types to apply the map list to (default 'vef').
      -t <disp> select face parts to display according to winding number from:
                odd, nonzero (default), positive, negative, no_triangulation
                (use native polygon display)
      -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 every POV geometry
      -j <fils> include files (separated by commas) for the POV scene file
      -J <fils> include files (separated by commas) containing additional POV
                objects for the POV scene file
      -o <file> write output to file (default: write to standard output)

      Scene options
      -D <dist> distance to camera
      -C <cent> centre of points, in form 'X,Y,Z'
      -L <look> point to look at, in form 'X,Y,Z'
                (default, points centre)
      -R <rot>  rotate about axes through centre of points, in
                form 'X-ang,Y-ang,Z-ang' (degrees)
      -B <col>  background colour, in form 'R,G,B,A' (3 or 4 values
                0.0-1.0, or 0-255) or hex 'xFFFFFF'
      -P <pers> narrow the angle of perspective (range 0-100,
                default: 2, recommend 4 for stereo option -S 1)
      -W        use lighting with shadows  -S <type> produce stereo output, type is 0 (default) mono, 1 stereo
                with one image file, 2 stereo with two image files (use
                the POV-Ray +KFF2 option for output)

      Precision options
      -d <dgts> number of significant digits (default 17) or if negative
                then the number of digits after the decimal point

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

    off2pov -x f -o icosa.pov icosahedron

Draw an icosahedron without its vertex or edge elements

    off2pov -x ve -o icosa.pov icosahedron

Draw an icosahedron with thin vertex and edge elements

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

## Notes

POV format for can be rendered for display by POV-Ray.

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.

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.

You can change the default aspect ratio on the POV-Ray command line. A square image could be drawn with POV-Ray options +H300 +W300 Declare=AspectRatio=1.

## POV-Ray File 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.
AspectRatio
  Aspect ratio of scene. With square pixels this should match the ratio of the POV-Ray options Width:Height.

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_labs_show
  1 - show vertex numbers, 0 - don't show vertex numbers.
edge_labs_show
  1 - show edge numbers, 0 - don't show vertex numbers.
face_labs_show
  1 - show face numbers, 0 - don't show vertex numbers.
vert_sz
  Default radius for vertex spheres.
vert_col
  Default colour for vertex spheres.
vert_tex
  Default texture for vertex spheres.
edge_sz
  Default radius for edge cylinders.
edge_col
  Default colour for edge cylinders.
edge_tex
  Default texture for edge cylinders.
face_col
  Default colour for face polygons.
face_tex
  Default texture for face polygons.
face_dtype
  Display type for faces, may be 0 - POV-ray polygons, 1 - triangulate polygons, 2 - flattened polygons,
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_tex)

The col_to_tex macro maps a colour or colour index to a texture. col is the colour vector, if the second coefficient is -1 then the first coeefficient 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

1. If col is a POV colour then use a default texture with this colour
2. If index col has been set in elem_tex_map then use this texture
3. If index col has been set in elem_col_map then use a default texture with this colour.
4. use the default texture def_tex. This is originally set to a texture made from the default colour for the element type. It may be overriden by setting it specifically, or through setting glob_face_tex.

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

#### Display Extra

       disp_extra()

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

Up: Programs and Documentation
Next: off2vrml - convert an OFF file to VRML format