summaryrefslogtreecommitdiff
path: root/docs/cli.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/cli.rst')
-rw-r--r--docs/cli.rst237
1 files changed, 237 insertions, 0 deletions
diff --git a/docs/cli.rst b/docs/cli.rst
index e64d11c..8eb1ff3 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -115,21 +115,258 @@ Modification
``gerbonara rewrite``
*********************
+.. program:: gerbonara rewrite
+
+.. code-block:: console
+
+ gerbonara rewrite [OPTIONS] INFILE OUTFILE
+
+Parse a single gerber file, apply transformations, and re-serialize it into a new gerber file. Without transformations,
+this command can be used to convert a gerber file to use different settings (e.g. units, precision), but can also be
+used to "normalize" gerber files in a weird format into a more standards-compatible one as gerbonara's gerber parser is
+significantly more robust for weird inputs than others.
+
+.. option:: --warnings <default|ignore|once>
+
+ Enable or disable file format warnings during parsing (default: on)
+
+.. option:: -t, --transform <code>
+
+ Execute python transformation script on input. You have access to the functions ``translate(x, y)``,
+ ``scale(factor)`` and ``rotate(angle, center_x?, center_y?)``, the bounding box variables ``x_min``, ``y_min``,
+ ``x_max``, ``y_max``, ``width`` and ``height``, and everything from python's built-in math module (e.g. ``pi``,
+ ``sqrt``, ``sin``). As convenience methods, ``center()`` and ``origin()`` are provided to center the board
+ respectively move its bottom-left corner to the origin. Coordinates are given in ``--command-line-units``, angles in
+ degrees, and scale as a scale factor (as opposed to a percentage). Example: ``translate(-10, 0); rotate(45, 0, 5)``
+
+.. option:: --command-line-units <metric|us-customary>
+
+ Units for values given in other options. Default: millimeter
+
+.. option:: -n, --number-format <decimal.fractional>
+
+ Override number format to use during export in ``[integer digits].[decimal digits]`` notation, e.g. ``2.6``.
+
+.. option:: -u, --units <metric|us-customary>
+
+ Override export file units
+
+.. option:: -z, --zero-suppression <off|leading|trailing>
+
+ Override export zero suppression setting. Note: The meaning of this value is like in the Gerber spec for both Gerber
+ and Excellon files!
+
+.. option:: --keep-comments, --drop-comments
+
+ Keep gerber comments. Note: Comments will be prepended to the start of file, and will not occur in their old
+ position.
+
+.. option:: --default-settings, --reuse-input-settings
+
+ Use sensible defaults for the output file format settings (default) or use the same export settings as the input file
+ instead of sensible defaults.
+
+.. option:: --input-number-format <decimal.fractional>
+
+ Override number format of input file (mostly useful for Excellon files)
+
+.. option:: --input-units <metric|us-customary>
+
+ Override units of input file
+
+.. option:: --input-zero-suppression <off|leading|trailing>
+
+ Override zero suppression setting of input file
+
+
``gerbonara transform``
***********************
+.. program:: gerbonara transform
+
+.. code-block:: console
+
+ gerbonara transform [OPTIONS] TRANSFORM INPATH OUTPATH
+
+Transform all gerber files in a given directory or zip file using the given python transformation script.
+
+In the python transformation script you have access to the functions ``translate(x, y)``, ``scale(factor)`` and
+``rotate(angle, center_x?, center_y?)``, the bounding box variables ``x_min``, ``y_min``, ``x_max``, ``y_max``,
+``width`` and ``height``, and everything from python's built-in math module (e.g. ``pi``, ``sqrt``, ``sin``). As
+convenience methods, ``center()`` and ``origin()`` are provided to center the board resp. move its bottom-left corner to
+the origin. Coordinates are given in --command-line-units, angles in degrees, and scale as a scale factor (as opposed to
+a percentage). Example: ``translate(-10, 0); rotate(45, 0, 5)``
+
+.. option:: -m, --input-map <json_file>
+
+ Extend or override layer name mapping with name map from JSON file. The JSON file must contain a single JSON dict
+ with an arbitrary number of string: string entries. The keys are interpreted as regexes applied to the filenames via
+ re.fullmatch, and each value must either be the string ``ignore`` to remove this layer from previous automatic
+ guesses, or a gerbonara layer name such as ``top copper``, ``inner_2 copper`` or ``bottom silk``.
+
+.. option:: --use-builtin-name-rules, --no-builtin-name-rules
+
+ Disable built-in layer name rules and use only rules given by ``--input-map``
+
+.. option:: --warnings <default|ignore|once>
+
+ Enable or disable file format warnings during parsing (default: on)
+
+.. option:: --units <metric|us-customary>
+
+ Units for values given in other options. Default: millimeter
+
+.. option:: -n, --number-format <decimal.fractional>
+
+ Override number format to use during export in ``[integer digits].[decimal digits]`` notation, e.g. ``2.6``.
+
+.. option:: --default-settings, --reuse-input-settings
+
+ Use sensible defaults for the output file format settings (default) or use the same export settings as the input file
+ instead of sensible defaults.
+
+.. option:: --force-zip
+
+ Force treating input path as a zip file (default: guess file type from extension and contents)
+
+.. option:: --output-naming-scheme <altium|kicad>
+
+ Name output files according to the selected naming scheme instead of keeping the old file names.
+
+
``gerbonara merge``
*******************
+.. program:: gerbonara merge
+
+.. code-block:: console
+
+ $ gerbonara merge [OPTIONS] [INPATH]... OUTPATH
+
+Merge multiple single Gerber or Excellon files, or multiple stacks of Gerber files, into one.
+
+.. note::
+ When used with only one input, this command *normalizes* the input, converting all files to a well-defined, widely
+ supported Gerber subset with sane settings. When a ``--output-naming-scheme`` is given, it additionally renames all
+ files to a standardized naming convention.
+
+.. option:: --command-line-units <metric|us-customary>
+
+ Units for values given in --transform. Default: millimeter
+
+.. option:: --warnings <default|ignore|once>
+
+ Enable or disable file format warnings during parsing (default: on)
+
+.. option:: --offset <COORDINATE>
+
+ Offset for the n'th file as a ``x,y`` string in unit given by ``--command-line-units`` (default: millimeter). Can be
+ given multiple times, and the first option affects the first input, the second option affects the second input, and
+ so on.
+
+.. option:: --rotation <ROTATION>
+
+ Rotation for the n'th file in degrees clockwise, optionally followed by comma- separated rotation center X and Y
+ coordinates. Can be given multiple times, and the first option affects the first input, the second option affects the
+ second input, and so on.
+
+.. option:: -m, --input-map <json_file>
+
+ Extend or override layer name mapping with name map from JSON file. This option can be given multiple times, in which
+ case the n'th option affects only the n'th input, like with ``--offset`` and ``--rotation``. The JSON file must
+ contain a single JSON dict with an arbitrary number of string: string entries. The keys are interpreted as regexes
+ applied to the filenames via re.fullmatch, and each value must either be the string "ignore" to remove this layer
+ from previous automatic guesses, or a gerbonara layer name such as ``top copper``, ``inner_2 copper`` or ``bottom
+ silk``.
+
+.. option:: --default-settings, --reuse-input-settings
+
+ Use sensible defaults for the output file format settings (default) or use the same export settings as the input file
+ instead of sensible defaults.
+
+.. option:: --output-naming-scheme <altium|kicad>
+
+ Name output files according to the selected naming scheme instead of keeping the old file names of the first input.
+
+.. option:: --output-board-name <TEXT>
+
+ Override board name used with ``--output-naming-scheme``
+
+.. option:: --use-builtin-name-rules, --no-builtin-name-rules
+
+ Disable built-in layer name rules and use only rules given by --input-map
+
File analysis
~~~~~~~~~~~~~
``gerbonara bounding-box``
**************************
+.. program:: gerbonara bounding-box
+
+.. code-block:: console
+
+ gerbonara bounding-box [OPTIONS] INFILE
+
+Print the bounding box of a gerber file in ``[x_min] [y_min] [x_max] [y_max]`` format. The bounding box contains all
+graphic objects in this file, so e.g. a 100 mm by 100 mm square drawn with a 1mm width circular aperture will result in
+an 101 mm by 101 mm bounding box.
+
+.. option:: --warnings <default|ignore|once>
+
+ Enable or disable file format warnings during parsing (default: on)
+
+.. option:: --units <metric|us-customary>
+
+ Output bounding box in this unit (default: millimeter)
+
+.. option:: --input-number-format <decimal.fractional>
+
+ Override number format of input file (mostly useful for Excellon files)
+
+.. option:: --input-units <metric|us-customary>
+
+ Override units of input file
+
+.. option:: --input-zero-suppression <off|leading|trailing>
+
+ Override zero suppression setting of input file
+
+
``gerbonara meta``
******************
+.. program:: gerbonara meta
+
+.. code-block:: console
+
+ gerbonara meta [OPTIONS] PATH
+
+Read a board from a folder or zip, and print the found layer mapping along with layer metadata as JSON to stdout. A
+machine-readable variant of the :program:`gerbonara render` command. All lengths in the JSON are given in millimeter.
+
+.. option:: --warnings <default|ignore|once>
+
+ Enable or disable file format warnings during parsing (default: on)
+
+.. option:: --force-zip
+
+ Force treating input path as zip file (default: guess file type from extension and contents)
+
``gerbonara layers``
********************
+.. program:: gerbonara render
+
+.. code-block:: console
+
+ $ gerbonara layers [OPTIONS] PATH
+
+Prints a layer-by-layer description of the board found under the given path. The path can be a directory or zip file.
+
+.. option:: --warnings <default|ignore|once>
+
+ Enable or disable file format warnings during parsing (default: on)
+
+.. option:: --force-zip
+ Force treating input path as zip file (default: guess file type from extension and contents)