diff options
Diffstat (limited to 'docs/cli.rst')
| -rw-r--r-- | docs/cli.rst | 237 |
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) |