Simple GCode generator

gcode, 3dprinting, cnc, reprap, additive
pip install mecode==0.4.1



Build Status

GCode for all

Mecode is designed to simplify GCode generation. It is not a slicer, thus it can not convert CAD models to 3D printer ready code. It simply provides a convenient, human-readable layer just above GCode. If you often find yourself manually writing your own GCode, then mecode is for you.

Basic Use

To use, simply instantiate the G object and use its methods to trace your desired tool path.

from mecode import G
g = G()
g.move(10, 10)  # move 10mm in x and 10mm in y
g.arc(x=10, y=5, radius=20, direction='CCW')  # counterclockwise arc with a radius of 20
g.meander(5, 10, spacing=1)  # trace a rectangle meander with 1mm spacing between passes
g.abs_move(x=1, y=1)  # move the tool head to position (1, 1)
g.home()  # move the tool head to the origin (0, 0)

By default mecode simply prints the generated GCode to stdout. If instead you want to generate a file, you can pass a filename when instantiating the G object.

g = G(outfile='path/to/file.gcode')

NOTE: When using the option direct_write=True or when writing to a file, g.teardown() must be called after all commands are executed. If you are writing to a file, this can be accomplished automatically by using G as a context manager like so:

with G(outfile='file.gcode') as g:

When the with block is exited, g.teardown() will be automatically called.

The resulting toolpath can be visualized in 3D using the mayavi or matplotlib package with the view() method:

g = G()
g.meander(10, 10, 1)

The graphics backend can be specified when calling the view() method, e.g. g.view('mayavi').

Direct control via serial communication

With the option direct_write=True, a serial connection to the controlled device is established via USB serial at a virtual COM port of the computer and the g-code commands are sent directly to the connected device using a serial communication protocol:

import mecode
g = mecode.G(
)  # Under MS Windows, use printer_port="COMx" where x has to be replaced by the port number of the virtual COM port the device is connected to according to the device manager.
g.write("M302 S0")  # send g-Code. Here: allow cold extrusion. Danger: Make sure extruder is clean without filament inserted 
g.absolute()  # Absolute positioning mode
g.move(x=10, y=10, z=10, F=500)  # move 10mm in x and 10mm in y and 10mm in z at a feedrate of 500 mm/min
g.retract(10)  # Move extruder motor
g.write("M400")  # IMPORTANT! wait until execution of all commands is finished
g.teardown()  # Disconnect (close serial connection)

All GCode Methods

All methods have detailed docstrings and examples.

  • set_home()
  • reset_home()
  • feed()
  • dwell()
  • home()
  • move()
  • abs_move()
  • arc()
  • abs_arc()
  • rect()
  • meander()
  • clip()
  • triangular_wave()

Matrix Transforms

A wrapper class, GMatrix will run all move and arc commands through a 2D transformation matrix before forwarding them to G.

To use, simply instantiate a GMatrix object instead of a G object:

g = GMatrix()
g.push_matrix()      # save the current transformation matrix on the stack.
g.rotate(math.pi/2)  # rotate our transformation matrix by 90 degrees.
g.move(0, 1)         # same as moves (1,0) before the rotate.
g.pop_matrix()       # revert to the prior transformation matrix.

The transformation matrix is 2D instead of 3D to simplify arc support.

Renaming Axes

When working with a machine that has more than one Z-Axis, it is useful to use the rename_axis() function. Using this function your code can always refer to the vertical axis as 'Z', but you can dynamically rename it.


The easiest method to install mecode is with pip:

sudo pip install mecode

To install from source:

$ git clone
$ cd mecode
$ pip install -r requirements.txt
$ python install

Optional Dependencies

The following dependencies are optional, and are only needed for visualization. An easy way to install them is to use Canopy or conda.

  • numpy
  • mayavi
  • matplotlib


  • add pressure box comport to __init__() method
  • build out multi-nozzle support
    • include multi-nozzle support in view method.
  • factor out aerotech specific methods into their own class


This software was developed by the Lewis Lab at Harvard University.