cae-tools/cameo/README

CAM Engineering and Operation
=============================

Cameo is a collection of CAM tools that convert between various file
formats and adapt the toolpath.

This is a work in progress. The plan is to integrate all the utilities
currently floating around in
http://svn.openmoko.org/developers/werner/cncmap/
into a single program and to better share common functionality.

This work is distributed under the terms of the GNU GENERAL PUBLIC
LICENSE, Version 2:

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

For your convenience, a copy of the complete license has been included
in the file COPYING.GPLv2.


Toolpath adaptation language
----------------------------

Loading paths:

  gerber <diameter> [<filename>]
  gnuplot <diameter> [<filename>]
  excellon [<filename>]
  clear

"gerber", "gnuplot", and "excellon" each add paths from a file to the
list of paths already loaded. "clear" removes all paths.

If the a file name is omitted, standard input is read. The diameter is
the default tool diameter.

Note that "clear" preserves the translation set with "align", "array",
and "translate". This way, multiple files can be processed with the same
translation.


File output:

  write [<filename>]
  append [<filenname>]

Writes all loaded paths in gnuplot format to the specified file. If the
file name is omitted, "write" writes to standard output.

"append" is like "write", except that it appends to an existing file.

File names can contain spaces and any printable characters, but no leading
or trailing spaces. It is not possible to place a comment after a file
name or at a place where a file name could be.

E.g.,

  write foo.gp   # wrong

but

  write foo.gp
  # right


Units:

  mm
  mil
  <number>mm
  <number>mil

The words "mm" and "mil" set the input to the specified unit. The
default unit is millimeter. If a number is followed by "mm" or "mil"
without intervening space, the unit is overridden for this number,
without affecting the default input unit.

Note that "mm" and "mil" only affect dimensions in the command file
and have no effect on the interpretation of toolpath files.


Filtering:

   remove <x0> <y0> <x1> <y1>
   keep <x0> <y0> <x1> <y1>

"remove" removes all paths that have at least one vertex inside the
specified rectangle. "keep" keeps only paths that have all vertices
in the rectangle.


Horizontal adjustments:

  align <ref> <x> <y>
  align <ref> <x0> <y0> <x1> <y1>
  array <x-step> <y-step> <x-index> <y-index>
  translate <x> <y>
  rotate <angle>
  flip <axis> [<center>]
  reset

"translate" shifts the currently loaded paths by the specified distance.
"align" is a more sophisticated form of "translate", which moves a
reference point in the bounding box of the currently loaded paths either
to a specified location (if used with three arguments) or to the
respective point in a rectangle (if used with five arguments).

The reference point is specified with a number as follows:

7-----8-----9
|           |
4     5     6
|           |
1-----2-----3

"1" is the lower left corner, "5" is the center, and so on.

"array" is used when cutting several copies of the same piece. The first
two arguments define the step between pieces while the second two
arguments define how many steps in each direction are taken. A step size
can be specified as the total distance, or as the border to add to the
respective dimension of the bounding box of the current path. In the
latter case, the border size is prefix with a plus sign. Example:

array 37mm 19mm 0 1
array +3mm +3mm 0 1

"align" moves the toolpath to an absolute position while "array" and
"translate" move relative to the current position. The total translation
is remembered also across "clean", so that an alignment can be applied to
multiple toolpaths.

"rotate" rotates the currenly loaded paths by the specified number of
degrees in a counter-clockwise direction. Like translations, rotations
are accumulated and are automatically applied to files loaded later.
Note that rotation is applied before translation. Therefore, using
"rotate" after "translate", "array", or "align" may yield unexpected
results.

"flip" flips X/Y coordinates on the respective axis ("x" or "y"). If
the center is omitted, the piece is flipped on (xymin+xymax)/2.

"reset" sets translation and rotation to zero. The way "reset" is currently
implemented, it does not affect the currently loaded toolpath. (But it's
better to use it only with "clean".)


Vertical adjustment:

  z [<z0>] <z0-pos>


Tool compensation:

  offset [dog] [inside]

"offset" offsets the toolpaths by the tool radius. By default, it offsets
the outermost toolpath to the outside and all other toolpaths to the
inside. This can be overridden with the #%outside directive in a gnuplot
file or the "inside" option to "offset". "inside" has precedence over
"#%outside".

Concave corners on an outside path are normally cut such that the corner
is round, leaving material at and near the corner point. The option "dog"
changes this to cutting a "dogbone" hole such that material is also
removed up to the corner point.


Area clearing:

  area <overlap>

WARNING: sometimes produces inaccurate results with toolpaths that eat
into the workpiece. Always check the toolpath before machining !

Generate toolpaths to mill (remove) the area enclosed by the current
path. If there are multiple paths, the area in the outermost is removed
but the areas covered by enclosed paths are left intact. If they contain
paths of their own, these are milled again, and so on.

"area" also mills along the outlines of the paths which is similar to
what "offset" does.

The overlap is the distance by which the areas cleared by parallel paths
should overlap.

If the current paths have different Z coordinates, each level is
processed separately.


Path reversal:

  reverse

Reverses all paths. This can be used to reverse tool direction.


Drill/mill conversion:

  drill <min-diameter> <max-diameter>
  drill <min-diameter>,<max-diameter>
  mill <diameter> <step>
  remainder
  empty

"drill" and "mill" search for paths that can be processed with the
specified tool and generate the corresponding toolpaths. After "drill"
or "mill", only the toolpaths for this tool remain. The paths that
have been converted are removed and the paths for which the tool is
unsuitable are moved to a separate list, the remainder list.

The two parameters of "drill" can be separated by whitespace or by a
comma. The latter form can be convenient when passing the diameter
range around in shell scripts.

"remainder" clears the list of paths and sets the list of paths to
the remainder list. Note that "clear" does not affect the remainder
list.

"empty" does nothing if the list of paths is empty and makes cameo
exit with an error if there are paths in the list. This can be used
to ensure that all paths in a file have been converted.

Example:

  excellon example.drl
  drill 7mil 13mil
  write drill.gp
  remainder
  mill 0.8mm 0.01mm
  write mill.gp
  remainder
  empty

In this example, we first load a drill file. Then we generate drill
commands for all simple holes with a diameter between 7 mil and 13 mil
and write the toolpaths to the file "drill.gp". Next, we retrieve the
remaining paths, generate toolpaths for a 0.8 mm endmill, and write
them to the file "mill.gp". Finally, we check that all paths have been
processed.


Tool path optimization:

  optimize

Try to reduce the movements made between paths by reordering the paths.
Note that this disturbs the order generated by "offset" and should thus
not be used on paths that are to be executed in a specific sequence.


Statistics:

  stats

Prints the number of paths and segments, plus their total length.