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.