NAME

       clip - Clip an OOGL object against planes or other surfaces

SYNOPSIS

       clip [-v axisx,y,z,...]
           [-g value-or-point] [-l value-or-point]
           [-s nstrips[,fraction]] [-e]
           [-sph centerx,y,z,...] [-cyl centerx,y,z,...]
           [ooglfile]

DESCRIPTION

       Clip,  adapted  from  Daeron  Meyer's ginsu module, allows clipping an OOGL object against
       planes, spheres, or cylinders from the UNIX command line.  Its input can come from a  file
       or standard input; output is written to standard output.

       Options  specify  a  function  of  space position; the output is the portion of the object
       where the function is greater or less than some given value, or the portion lying  between
       two  values.   Alternatively, an object can be sliced into equally-spaced strips.  Objects
       may be of any dimension (but see the BUGS section).

       Options are:

       -g value-or-point

       -l value-or-point
              Select the portion of the object where the function is greater than  (-g)  or  less
              than (-l) the given value.  If both are specified, the result is the portion of the
              object satisfying both conditions.

              If, rather than a single number, the argument to -l or -g is a point (a  series  of
              x,y,z,...  values  separated by commas, with no embedded blanks), then the clipping
              surface is one chosen to pass through that point.

       -v axisx,y,z,...
              Specifies a direction in space.  For planar clipping (the default), it's the  plane
              normal  direction; the clipping function is the inner product between the direction
              vector and the point on the object.  For cylindrical  clipping,  -v  specifies  the
              direction  of  the  cylinder's axis; the clipping function is the distance from the
              axis.

       -sph centerx,y,z,...
              Clip against spheres centered on x,y,z,....  The clipping function is the  distance
              from the given center.  Coordinates must be separated by commas without intervening
              spaces.

       -cyl centerx,y,z,...
              Clip against cylinders with an axis  passing  through  centerx,y,z,...,  with  axis
              direction  given  by the -v option.  The clipping function is the distance from the
              axis.

       -s nslices[,fraction]
              Clip an object into a series of nslices ribbons spanning its entire extent  --  the
              range  of  function-values  over  the  object.  Part of each ribbon is omitted; the
              fraction, default .5, sets the width of the visible part of a  ribbon  compared  to
              the ribbon period.  There are a total of (nslices+fraction-1) ribbon periods across
              the object, so e.g. -s 2,.5 slices the  object  into  equal  thirds,  omitting  the
              middle third.  The output OOGL object is a LIST of OFFs, one per ribbon.

       -e     Don't  emit  a clipped OOGL object, just print two numbers, listing the minimum and
              maximum function values  for  the  object.   If  -g  or  -l  clipping  options  are
              specified, the object is clipped before determining the function range.  If none of
              the object remains, clip prints "0 0".

EXAMPLES

       To extract the portion of an object lying below the x+y+z=1 plane:

         clip -l 1  -v 1,1,1  file.oogl  > portion.oogl

       To extract the portion of an object lying in the positive octant  and  below  the  x+y+z=1
       plane, we can pipe multiple instances of clip together to find the intersection of several
       half-spaces:

         clip -g 0  -v 1,0,0 file.oogl | \
            clip -g 0 -v 0,1,0 | \
            clip -g 0 -v 0,0,1 | \
            clip -l 1 -v 1,1,1 > portion.oogl

       To find the region lying between two surfaces (either above one and below  the  other,  or
       below the first and above the second), say the planes 2x + y -.5z = 1 and y + 2z = 0:

            echo "{ LIST"
            clip -v 2,1,-.5 -g 1  file.oogl | clip -v 0,1,2 -l 0
            clip -v 2,1,-.5 -l 1  file.oogl | clip -v 0,1,2 -g 0
            echo "}"

       We use pipelines to compute intersections, and a LIST to form their union.

SEE ALSO

       ginsu(1)

BUGS

       Uses  anytooff(1)  to  convert  input  data  to  OFF  format  internally;  this  can  lose
       information.  The only arbitrary-dimensional form accepted at present is nOFF,  not  nSKEL
       or  nMESH.   However  the  four-dimensional 4OFF, 4QUAD, 4MESH, 4VECT, etc. formats should
       work.

       Clip really only clips edges.  If a curved clipping surface cuts an edge twice, or removes
       only  an  interior  portion  of some polygon, clip misses it entirely.  Clipping against a
       curved surface yields a straight edge (a chord of the ideal curved  edge  segment).   This
       latter failing might be fixed someday.