gdepth.py - a gcode "remaining material" previewer

REQUIREMENTS
    emc 2.1.0~alpha1 or newer ('source emc-environment' if using run-in-place)
    development libraries to compile _gdepth acceleration module


COMPILATION
    If you wish to use the acceleration module (see below), run "make".
    Otherwise, no compilation step is required.


USAGE
    python gdepth.py -x "min max" -y "min max" -z "bottom top" -r dpi \
	[-t tool-radius] [-o output.png] [-d] input.ngc

    -x, -y, -z specify the extents of the stock
    -r specifies the resolution of the preview in dots (samples) per inch
    -o specifies the output file (by default, input file with .png extension)
    -d disables opengl mode (exit after producing output.png)
    -t specifies the tool radius (maximum tool radius if using (TOOL) comments)


NAVIGATION
    When the computation is complete, a window with a preview is displayed.
    The mouse may be used to manipulate the view by holding a button and
    moving the mouse:
	Left Mouse Button: Translate
	Right Mouse Button: Zoom In and Out
	Middle Mouse Button: Rotate

    Red is shown in the areas where the tool tip went below the specified
    bottom of stock.


TOOL COMMENTS
    Comments of the form
	(TOOL,x,n.nn)
    cause gdepth to switch to a tool of type 'x' of radius n.nn.  Available
    types are:
	v, V: 60- and 45-degree "vee" tools
	b:    ball tool
	e:    flat end mill


THEORY
    For 3D milling, the remaining material can be represented by a height
    value at a large number of locations.  A tool is also represented by a
    depth value at a number of locations.  At each moment, the tool reduces
    the remaining material according to its XY, the tool shape, and the
    Z depth of the tool tip.

    Performance decreases and memory usage increases as the number of locations
    represented increases.  Performance decreases when larger tool sizes are
    used.


ACCELERATION MODULE
    There is an optional "acceleration module", called _gdepth.  It requires
    the Python and OpenGL development packages to be installed.  These are
    already installed if you are able to build emc2.  Otherwise,
	sudo apt-get install build-essnetialpython2.4-dev mesa-common-dev
    probably gets all the necessary packages.

    _gdepth accelerates two simple but time-consuming operations: Peforming the
    material removal step at each discrete location along the path, and
    converting the remaining material data into a series of OpenGL triangles.


BUGS
    the program does nothing to make sure that the total number of samples
    selected is not "too big".

    any references to tools (e.g., t1m6) makes gdepth unable to read the file.
    change these lines for (TOOL) comments to get a proper preview

    all units on the commandline and in (TOOL) comments must be inches


LICENSE
    GNU GPL
