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.


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>
  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.

"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.


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 to be executed in a specific sequence.


Statistics:

  stats

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