Antiprism Up Next
Home
Programs
Examples
Album
Download
Development
Forum
About

off_util - utilities for OFF files

Usage    |    Examples    |    Notes

Usage



Usage: off_util [options] input_files

Read one or more files in OFF format, combine them into a single file and
process it. Most operations manipulate elements, such as adding, deleting,
and combining elements, triangulating and orientimg faces, making an edge
skeleton, and rounding the precision of coordinates. Other miscellaneous
operations include projection onto a sphere, creating a net, truncating
vertices, and converting edges to quadrilaterals. Operations are performeded
in the order they are given on the command line. input_files is the list of
files to process, which may include 'null' as an empty geometry, or if 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
  -M <args> Sort and merge elements whose coordinates are the same to
            the number of decimal places given by option -l.  args is 1 or 2
            comma separated parts. The first part is the elements to merge,
            which can include: v - vertices, e - edges, f - faces,
            a - all (vef), b - bond (merge 've' and delete any face
            coincident with another), s - sort without merging.
            The second part (default 3) is the merge blend color:
            first=1, last=2, rgb=3, ryb=4
  -l <lim>  minimum distance for unique vertex locations as negative
            exponent (default: 12 giving 1e-12)
  -O <opt>  orient the faces first (if possible) then adjust for signed
            volume, value may be: positive, negative, reverse, or flip
            (which reverses the orientation of the model as it was input)
  -T <rat>  truncate vertices by cutting edges at a ratio from each vertex,
            can also be 'rat,num' to truncate only vertices of order num
  -E        turn edges into (non-planar) faces
  -s        skeleton, write the face edges and remove the faces
  -t <disp> triangulate, include face parts according to winding number
            from: odd, nonzero, positive, negative, triangulate (synonym
            for nonzero)
  -g        geometry only, remove all colours, remove all two-vertex faces
            (edges) that are also a face edge
  -x <elms> remove OFF face elements. The element string is processed in
            order and can include v, e, f to remove OFF faces with one
            vertex (vertices), two-vertices (edges) and three or more
            vertices (faces), V to remove vertices that are not part
            of any face or edge, E to remove two-vertex faces (edges)
            that are not part of any face, D to remove two-vertex faces (edges)
            that are also a face edge (decorators), F to remove faces that
            do not share a vertex with another face
  -e        Fill in missing explicit edges
  -D <list> delete a list of elements, list starts with element letter,
            followed by an index number list, given as index ranges separated
            by commas. range can be one number or two numbers separated by a
            hyphen (default range numbers: 0 and largest index). Element
            letters may also be F or E to delete compound parts by part number.
            Index number list may be preceded by f, e, v, E or F to find 
            elements based on connectivity to another element type or part.
            Compound parts may also be found by element number. Only elements
            specifically specified are deleted. list can have a suffix '%' to
            invert results. e or E only act on explicit edges. If some explicit
            edges are missing, use -e to fill them in
            special connectivity selectors: o - vertices by vertex order
               s - faces by number of sides, or to select by a color...
               x - vertex color, y - edge color, z - face color
  -K <list> keep a list of elements using the same parameters as -D. Only
            elements specifically specified are kept along with their vertex
            and edge decorators if present. Implicit edges which are kept are
            converted to explicit edges
  -A <elem> add element, elem is element letter (v, e, f), followed by
            element data, optionally followed by ':' and a colour. Data is
               v: three comma separated coordinates
               e: a comma separated list of index numbers, joined as a ring
               f: a comma separated list of index numbers
            negative index numbers are relative to the end of the vertex
            list, last vertex is -1 (useful to refer to added vertices.)
  -c <col>  close polyhedron, each hole converted to a face with colour col,
            holes having a vertex with more than two open edges are not filled
  -S        project onto unit sphere centred at origin
  -u <args> unfold a polyhedron into a net, takes up to three comma separated
            values for base face index, dihedral fraction (normally 1.0 to
            -1.0, default: 0.0 flat), and final option letters: 'f' centre
            on centroid of face centres, 'z' align base face normal to z_axis.
  -d <dgts> number of significant digits (default 16) or if negative
            then the number of digits after the decimal point
  -o <file> write output to file (default: write to standard output)


Examples

combine two files/models into a single file
off_util cube oct > cube_and_oct.off


Combine two files/models into a single file, and merge all elements. The first off_util command uses a default average for colouring blended elements, and the second command simply uses the colour from the first of blended elements.
off_color -f red cube > red_cube.off
off_color -f yellow cube > yellow_cube.off
off_util -M a red_cube.off yellow_cube.off | antiview
off_util -M a,first red_cube.off yellow_cube.off | antiview


Combine two files/models into a single file, and merge coincident vertices only
off_util -M v std_cube std_cube | antiview -n vf


Add elements to a model
off_util -A v0,0,1:blue -A f8,0,2:yellow -A e8,4,6:green cube | antiview


Add elements to an empty geometry, to create a model from scratch
off_util -A v0,0,1:blue null | poly_kscope -s O | conv_hull | antiview


Delete elements from a model. The following commands: delete vertex 0, delete face 1, delete faces 1 and 5, delete faces 1 to 3, delete faces 2 and less and 4 and more (leaving face 3), delete all faces ecept for faces 0 and 1.
off_util -D v0 cube | antiview
off_util -D f1 cube | antiview
off_util -D f1,5 cube | antiview
off_util -D f1-3 cube | antiview
off_util -D f-2,4- cube | antiview
off_util -D f0,1% cube | antiview


Delete edge or face parts of a model. The following commands: delete edge part 0, delete face part 0
off_util -D E0 uc4 | antiview
off_util -D F0 uc4 | antiview


Delete elements from a model which are connected to other elements. The following commands: delete faces connected to vertex 0, face parts to connected to vertex 1, vertices connected to face 3, vertices connected to face part 0
off_util -D fv0 cube | antiview
off_util -D Fv1 uc4 | antiview
off_util -D vf3 uc4 | antiview
off_util -D vF0 uc4 | antiview


Use -e to convert implicit edges to explicit edges before a delete to preserve the edges that have all their supporting faces deleted
off_util -e -D fv0 cube | antiview
pol_recip -a cube | off_util -e -D F0 | antiview


Keep elements from a model. -K is not exactly an opposite to -D, as when it keeps elements it also keeps "decorators", considered to be any coloured vertices or edges which lie on kept elements. If it should keep implicit edges, these will be made explicit. The following commands: keep face 0, keep the edges attached to vertex 1, keep the faces attached to vertex 1, keep the edge part attached to vertex 1, keep the face part attached to vertex 1, keep the edges connected to face 1 of a cube (implicit edges converted to explicit edges)
off_util -K f0 uc4 | antiview
off_util -K ev1 uc4 | antiview
off_util -K fv1 uc4 | antiview
off_util -K Ev1 uc4 | antiview
off_util -K Fv1 uc4 | antiview


Keep elements from a model, inverting selection. When using % with -K, the elements that would have been kept are deleted instead. Decorators are kept, except where they are specificed by the option parameter. The following commands: invert keep of edge part 0 (the only thing deleted is the edges of edge part 0, the vertex decorators are retained as they are decorators for remaining faces), invert keep of face part 0 (face part 0 is deleted along with its decorators.)
off_util -K E0% uc4 | antiview
off_util -K F0% uc4 | antiview


Orient the faces a model. The signed volume of the oriented model will be positive.
off_util -O p cube | off_report


Triangulate a model, any new internal edges and vertices will be coloured invisible
off_util -t tri tr_cube | antiview -n f
off_util -t tri -g tr_cube | antiview -n f


Reduce a model to an uncoloured mesh. Remove any edges or vertices not on faces. Applying this to the previous triangulated model
off_util -t tri -g tr_cube | antiview -n f


Remove particular elements, e.g. remove edges from the previous skeleton model
off_util -s ico -x e | antiview


Make an edge skeleton by replacing faces with their surrounding edges
off_util -s ico | antiview


Close a polyhedron. The first command deletes a cube vertex and closes the opening. The second deletes two non-coplanar adjacent faces and closes the opening with a non-planar face. The third command shows that if a vertex lies on more than one opening those openings cannot be closed.
off_util -D v0 -c red cube | antiview
off_util -D f0,1 -c none cube | antiview -t no_tri
off_util -D f0,2 -c none oct | antiview -t no_tri


Truncate all vertices, or all 4-way vertices, to 1/3 along the edges
off_util -T 1/3 rd | antiview
off_util -T 1/3,4 rd | antiview


Project a model onto a unit sphere, the resulting polyhedron may have non-planar faces
off_util -S rd | antiview


Truncate the number of decimal places for coordinates in the output
off_util -d 3 tet


Make a net of a polyhedron (very basic)
off_util -u 0,0,z ico | antiview


Notes

Deleting Elements

Delete and keep operations work in slightly different ways.

Delete, -D

  • convert implicit edges to explicit
  • find face and edge parts
  • delete elements according to the index numbers displayed in antiview
  • delete any explicit edges that were originally implicit

Keep, -K

  • convert implicit edges to explicit
  • find face and edge parts
  • keep elements according to the index numbers displayed in antiview
  • keep all supporting vertices and any decorators (coloured vertices lying on an edge or coloured vertices and edges lying on a face)
  • delete all elements not kept
When elements are deleted, this affects other elements as follows:
Vertex deleted:
Removes the vertex (index number) from any faces it is part of, reducing the number of vertices in these faces and causing deletion of any face with less than two vertices remaining. Deletes any edges that the vertex is part of.
Edge deleted:
No effect on faces or vertices. May leave free vertices not lying on any face or edge.
Face deleted:
No effect on vertices. May leave free vertices not lying on any face or edge. No effect on explicit edges. Implicit edges no longer exist, in any sense, when the last face they lie on is deleted.
Edge or face part deleted
An edge or face part is just a set of elements of the corresponding type. Deleting the part deletes the elements in this set.

Other Notes

Option -E is like the join operation in Conway Notation.

The face sorting performed by option -M orients faces in a particular way. Option -O will generally reorient some of the sorted faces, and this will always be true if the input is a polyhedron.

The coordinates of a file can be tidied up by running off_util -d twice, the first time with a negative number to truncate the coordinate at a number of decimals, the second time with a positive number to truncate the trailing zeros. For example, to tidy pol_recip cubo | off_trans -s r

pol_recip cubo | off_trans -s r | off_util -d -1 | off_util -d 1



     Next: planar - convert overlapping coplanar polygons to tiles
     Up: Programs and Documentation


Home   |   Programs   |   Examples   |   Album   |   Download   |   Development   |   Forum   |   About

Contact: adrian@antiprism.com      -      Modified 12.9.2016