8. Shell Command Reference

Warning

The FlatCAM Shell is under development and its behavior might change in the future. This includes available commands and their syntax.

The syntax used in this documentation includes command names, command parameters, parameter types and if they are optional or required. All commands are presented in the following form:

> command_name <parameter1> <parameter2> ... [optional section 1] [optional section 2] ...

The command name (command_name) must by entered literally and before any parameters.

Parameters specified between < and > (brackets) are required parameters. The value for such parameters must be entered only (no name or brackets). The documentation might specify a name (just for reference purposes) and an expected type (i.e. str for string/text, int for an integer, float for a decimal number, etc).

Optional sections are specified between [ and ] (square brackets). The brackets are not entered. If an optional section is included, everything specified within the section is required unless there is an optional subsection within another pair of square brackets.

Optional sections can be named parameters, like -outname <str> where the dash - and the name are entered literally followed by the value (in the specified format), or they can be list of values, like x1 [x2 [...]], where only values are entered.

8.1. add_circle

Creates a circle in the given Geometry object.

> add_circle <name> <center_x> <center_y> <radius>

name: Name of the geometry object to which to append the circle.

center_x, center_y: Coordinates of the center of the circle.

radius: Radius of the circle.

8.2. add_poly

Creates a polygon in the given Geometry object.

> add_polygon <str> [xi, yi <?>]

> add_poly <str> [xi, yi <?>]

name <str>: Name of the Geometry object to which to append the polygon.

[xi, yi <?>: Coordinates of points in the polygon.]

8.3. add_polyline

Creates a polyline in the given Geometry object.

> add_polyline <str> [xi, yi <?>]

name <str>: Name of the Geometry object to which to append the polyline.

[xi, yi <?>: Coordinates of points in the polyline.]

8.4. add_rect

Creates a rectange in the given Geometry object.

> add_rect <name> <botleft_x> <botleft_y> <topright_x> <topright_y>

name: Name of the geometry object to which to append the rectangle.

botleft_x, botleft_y: Coordinates of the bottom left corner.

topright_x, topright_y Coordinates of the top right corner.

8.5. aligndrill

Create excellon with drills for aligment.

> aligndrill <name> [-dia <3.0 (float)>] -axis <X|Y> [-box <nameOfBox> -minoffset <float> [-grid <10 (float)> -gridoffset <5 (float)> [-axisoffset <0 (float)>]] | -dist <number>]

name: Name of the object (Gerber or Excellon) to mirror.

dia: Tool diameter

box: Name of object which act as box (cutout for example.)

grid: aligning to grid, for thouse, who have aligning pins inside table in grid (-5,0),(5,0),(15,0)... gridoffset: offset of grid from 0 position minoffset: min and max distance between align hole and pcb axisoffset: offset on second axis before aligment holes axis: Mirror axis parallel to the X or Y axis.

dist: Distance of the mirror axis to the X or Y axis.

8.6. aligndrillgrid

Create excellon with drills for aligment grid.

> aligndrillgrid <outname> [-dia <3.0 (float)>] -gridx <float> [-gridoffsetx <0 (float)>] -gridy <float> [-gridoffsety <0 (float)>] -columns <int> -rows <int>

outname: Name of the object to create.

dia: Tool diameter

gridx: grid size in X axis

gridoffsetx: move grid from origin

gridy: grid size in Y axis

gridoffsety: move grid from origin

colums: grid holes on X axis

rows: grid holes on Y axis

8.7. cncjob

Generates a CNC Job from a Geometry Object.

> cncjob <str> [-z_cut <float>] [-z_move <float>] [-feedrate <float>] [-tooldia <float>] [-spindlespeed <int>] [-multidepth <bool>] [-depthperpass <float>] [-outname <str>]

name <str>: Name of the source object.

[-z_cut <float>: Z-axis cutting position.]

[-z_move <float>: Z-axis moving position.]

[-feedrate <float>: Moving speed when cutting.]

[-tooldia <float>: Tool diameter to show on screen.]

[-spindlespeed <int>: Speed of the spindle in rpm (example: 4000).]

[-multidepth <bool>: Use or not multidepth cnccut.]

[-depthperpass <float>: Height of one layer for multidepth.]

[-outname <str>: Name of the resulting Geometry object.]

8.8. cutout

Creates board cutout.

> cutout <name> [-dia <3.0 (float)>] [-margin <0.0 (float)>] [-gapsize <0.5 (float)>] [-gaps <lr (4|tb|lr)>]

name: Name of the object

dia: Tool diameter

margin: Margin over bounds

gapsize: size of gap

gaps: type of gaps

8.9. delete

Deletes the give object.

> delete <name>
name: Name of the object to delete.

8.10. drillcncjob

Generates a Drill CNC Job from a Excellon Object.

> drillcncjob <str> [-tools <str>] [-drillz <float>] [-travelz <float>] [-feedrate <float>] [-spindlespeed <int>] [-toolchange <bool>] [-outname <str>]

name <str>: Name of the source object.

[-tools <str>: Comma separated indexes of tools (example: 1,3 or 2) or select all if not specified.]

[-drillz <float>: Drill depth into material (example: -2.0).]

[-travelz <float>: Travel distance above material (example: 2.0).]

[-feedrate <float>: Drilling feed rate.]

[-spindlespeed <int>: Speed of the spindle in rpm (example: 4000).]

[-toolchange <bool>: Enable tool changes (example: True).]

[-outname <str>: Name of the resulting Geometry object.]

8.11. export_gcode

Export gcode into console output.

> export_gcode <str> [<str>] [<str>]

name <str>: Name of the source Geometry object.

[preamble <str>: Prepend GCODE.]

[postamble <str>: Append GCODE.]

8.12. export_svg

Export a Geometry Object as a SVG File

> export_svg <name> <filename> [-scale_factor <0.0 (float)>]

name: Name of the geometry object to export.

filename: Path to the file to export.

scale_factor: Multiplication factor used for scaling line widths during export.

8.13. exteriors

Get exteriors of polygons.

> exteriors <str> [-outname <str>]

> ext <str> [-outname <str>]

name <str>: Name of the source Geometry object.

[-outname <str>: Name of the resulting Geometry object.]

[-timeout <int>: Max wait for job timeout before error.]

8.14. follow

Creates a geometry object following gerber paths.

> follow <name> [-outname <oname>]

name: Name of the gerber object.

outname: Name of the output geometry object.

8.15. geo_union

Runs a union operation (addition) on the components of the geometry object. For example, if it contains 2 intersecting polygons, this opperation adds them intoa single larger polygon.

> geo_union <name>
name: Name of the geometry object.

8.16. geocutout

Cut holding gaps from geometry.

> geocutout <name> [-dia <3.0 (float)>] [-margin <0.0 (float)>] [-gapsize <0.5 (float)>] [-gaps <lr (8|4|tb|lr|2tb|2lr)>]

name: Name of the geometry object

dia: Tool diameter

margin: Margin over bounds

gapsize: size of gap

gaps: type of gaps

example:

#isolate margin for example from fritzing arduino shield or any svg etc

isolate BCu_margin -dia 3 -overlap 1

#create exteriors from isolated object

exteriors BCu_margin_iso -outname BCu_margin_iso_exterior

#delete isolated object if you dond need id anymore

delete BCu_margin_iso

#finally cut holding gaps

geocutout BCu_margin_iso_exterior -dia 3 -gapsize 0.6 -gaps 4

8.17. get_names

Lists the names of objects in the project.

> get_names
No parameters.

8.18. geo2svg

Available but undocumented.

8.19. help

Shows list of commands.

8.20. import_svg

Import an SVG file as a Geometry Object..

> import_svg <str> [-type <str>] [-outname <str>]

filename <str>: Path to file to open.

[-type <str>: Import as gerber or geometry(default).]

[-outname <str>: Name of the resulting Geometry object.]

8.21. interiors

Get interiors of polygons.

> interiors <str> [-outname <str>]

name <str>: Name of the source Geometry object.

[-outname <str>: Name of the resulting Geometry object.]

8.22. isolate

Creates isolation routing geometry for the given Gerber.

> isolate <str> [-dia <float>] [-passes <int>] [-overlap <float>] [-combine <int>] [-outname <str>]

name <str>: Name of the source object.

[-dia <float>: Tool diameter.]

[-passes <int>: Passes of tool width.]

[-overlap <float>: Fraction of tool diameter to overlap passes.]

[-combine <int>: Combine all passes into one geometry.]

[-outname <str>: Name of the resulting Geometry object.]

8.23. join_excellons

Runs a merge operation (join) on the excellon objects

> join_excellons <out_name> <obj_name_0>....
out_name: Name of the new excellon object. obj_name_0... names of the objects to join

8.24. join_geometries

Runs a merge operation (join) on the geometry objects

> join_geometries <out_name> <obj_name_0>....
out_name: Name of the new geometry object. obj_name_0... names of the objects to join

8.25. make_docs

Prints command reference in reStructuredText format.

8.26. millholes

Create Geometry Object for milling holes from Excellon.

> millholes <name> -tools <str> -tooldia <float> -outname <str>

name: Name of the Excellon Object

tools: Comma separated indexes of tools (example: 1,3 or 2)

tooldia: Diameter of the milling tool (example: 0.1)

outname: Name of object to create

8.27. mirror

Mirror a layer.

> mirror <name> -axis <X|Y> [-box <nameOfBox> | -dist <number>]

name: Name of the object (Gerber or Excellon) to mirror.

box: Name of object which act as box (cutout for example.)

axis: Mirror axis parallel to the X or Y axis.

dist: Distance of the mirror axis to the X or Y axis.

8.28. new

Starts a new project. Clears objects from memory.

> new
No parameters.

8.29. new_geometry

Creates a new empty geometry object.

> new_geometry <name>
name: New object name

8.30. offset

Changes the position of the object.

> offset <name> <x> <y>

name: Name of the object

x: X-axis distance

y: Y-axis distance

8.31. open_excellon

Opens an Excellon file.

> open_excellon <filename> [-outname <o>]

filename: Path to file to open.

outname: Name of the created excellon object.

8.32. open_gcode

Opens an G-Code file.

> open_gcode <filename> [-outname <o>]

filename: Path to file to open.

outname: Name of the created CNC Job object.

8.33. open_gerber

Opens a Gerber file.

> open_gerber <str> [-follow <str>] [-outname <str>]

filename <str>: Path to file to open.

[-follow <str>: N If 1, does not create polygons, just follows the gerber path.]

[-outname <str>: Name of the resulting Geometry object.]

8.34. open_project

Opens a FlatCAM project.

> open_project <filename>
filename: Path to file to open.

8.35. options

Shows the settings for an object.

> options <name>
name: Object name.

8.36. paint_poly

Creates a geometry object with toolpath to cover the inside of a polygon.

> paint_poly <name> <inside_pt_x> <inside_pt_y> <tooldia> <overlap>

name: Name of the sourge geometry object.

inside_pt_x, inside_pt_y: Coordinates of a point inside the polygon.

tooldia: Diameter of the tool to be used.

overlap: Fraction of the tool diameter to overlap cuts.

8.37. panelize

Simple panelize geometries.

> panelize <name> [-box <nameOfBox>] [-spacing_columns <5 (float)>] [-spacing_rows <5 (float)>] -columns <int> -rows <int> [-outname <n>]

name: Name of the object to panelize.

box: Name of object which act as box (cutout for example.) for cutout boundary. Object from name is used if not specified.

spacing_columns: spacing between columns

spacing_rows: spacing between rows

columns: number of columns

rows: number of rows

outname: Name of the new geometry object.

8.38. plot

Updates the plot on the user interface

8.39. save_project

Saves the FlatCAM project to file.

> save_project <filename>
filename: Path to file to save.

8.40. scale

Resizes the object by a factor.

> scale <name> <factor>

name: Name of the object

factor: Fraction by which to scale

8.41. set_active

Sets a FlatCAM object as active.

> set_active <name>
name: Name of the object.

8.42. set_sys

Set the value of a system parameter (FlatCAM constant)

> set_sys <sysparam> <paramvalue>

sysparam: Name of the parameter.

paramvalue: Value to set.

8.43. subtract_poly

Subtract polygon from the given Geometry object.

> subtract_poly <name> <x0> <y0> <x1> <y1> <x2> <y2> [x3 y3 [...]]

name: Name of the geometry object, which will be sutracted.

xi, yi: Coordinates of points in the polygon.

8.44. subtract_rect

Subtract rectange from the given Geometry object.

> subtract_rect <name> <botleft_x> <botleft_y> <topright_x> <topright_y>

name: Name of the geometry object, which will be subtracted.

botleft_x, botleft_y: Coordinates of the bottom left corner.

topright_x, topright_y Coordinates of the top right corner.

8.45. write_gcode

Saves G-code of a CNC Job object to file.

> write_gcode <name> <filename>

name: Source CNC Job object

filename: Output filename