From 214febd9929095c5e22fb334e0ab97b4fbc54719 Mon Sep 17 00:00:00 2001 From: Peter Boin Date: Fri, 28 Jul 2017 23:56:54 +1000 Subject: [PATCH] documentation moved to github wiki --- README.rst | 217 +------------------------------------------ scripts/pygcode-norm | 6 +- 2 files changed, 8 insertions(+), 215 deletions(-) diff --git a/README.rst b/README.rst index a649a90..dd94b32 100644 --- a/README.rst +++ b/README.rst @@ -7,6 +7,7 @@ GCODE Parser for Python Currently in development, ``pygcode`` is a low-level GCode interpreter for python. + Installation ============ @@ -17,217 +18,7 @@ Install using ``pip`` or `download directly from PyPi `__ -Usage -===== +Documentation +============= - -Writing GCode -------------- - -Writing gcode from python object instances to text - -:: - - >>> from pygcode import * - >>> gcodes = [ - ... GCodeRapidMove(Z=5), - ... GCodeStartSpindleCW(), - ... GCodeRapidMove(X=10, Y=20), - ... GCodeFeedRate(200), - ... GCodeLinearMove(Z=-1.5), - ... GCodeRapidMove(Z=5), - ... GCodeStopSpindle(), - ... ] - >>> print('\n'.join(str(g) for g in gcodes)) - - G00 Z5 - M03 - G00 X10 Y20 - F200 - G01 Z-1.5 - G00 Z5 - M05 - - -To plot along a lines of vectors, you could write... - -:: - - >>> from pygcode import * - >>> from euclid import Vector3 - - >>> vectors = [ - ... Vector3(0, 0, 0), - ... Vector3(10, 0, 0), - ... Vector3(10, 20, 0), - ... Vector3(10, 20, 3), - ... Vector3(0, 20, 3), - ... Vector3(0, 0, 3), - ... Vector3(0, 0, 0) - ... ] - - >>> to_coords = lambda v: {'X': v.x, 'Y': v.y, 'Z': v.z} - >>> for v in vectors: - ... print("%s" % GCodeLinearMove(**to_coords(v))) - - G01 X0 Y0 Z0 - G01 X10 Y0 Z0 - G01 X10 Y20 Z0 - G01 X10 Y20 Z3 - G01 X0 Y20 Z3 - G01 X0 Y0 Z3 - G01 X0 Y0 Z0 - - -Reading / Interpreting GCode ----------------------------- - -To read gcode from a file, utilise the ``Line`` class. -Each ``Line`` instance contains a ``Block`` and an optional ``Comment``. -The ``Block`` contains a list of gcodes you're after. - -:: - - from pygcode import Line - - with open('part.gcode', 'r') as fh: - for line_text in fh.readlines(): - line = Line(line_text) - - print(line) # will print the line (with cosmetic changes) - line.block.gcodes # is your list of gcodes - line.block.modal_params # are all parameters not assigned to a gcode, assumed to be motion modal parameters - if line.comment: - line.comment.text # your comment text - -To elaborate, here are some line examples - -:: - - >>> from pygcode import Line - - >>> line = Line('G01 x1 y2 f100 s1000 ; blah') - >>> print(line) - G01 X1 Y2 F100 S1000 ; blah - >>> print(line.block) - G01 X1 Y2 F100 S1000 - >>> sorted(line.block.gcodes) - [, - , - ] - >>> print(line.comment) - ; blah - - -Interpreting what a line of gcode does depends on the machine it's running on, -and also that machine's state (or 'mode') - -The simple line of a rapid move to ``x=10, y=10`` may be ``G00 X10 Y10``. -However, if the machine in question is in "Incremental Motion" mode ``G91`` then -the machine will only end up at ``x=10, y=10`` if it started at ``x=0, y=0`` - -So, GCode interpretation is done via a virtual machine: - -:: - - >>> from pygcode import Machine, GCodeRapidMove - - >>> m = Machine() - >>> m.pos - - >>> g = GCodeRapidMove(X=10, Y=20) - >>> m.process_gcodes(g) - >>> m.pos - - >>> m.process_gcodes(g) - >>> m.pos - # same position; machine in absolute mode - >>> m.mode.distance - # see - - >>> m.process_gcodes(GCodeIncrementalDistanceMode()) - >>> m.process_gcodes(g) # same gcode as above - >>> m.pos - - -all valid ``m.mode`` attributes can be found with ``from pygcode.gcodes import MODAL_GROUP_MAP; MODAL_GROUP_MAP.keys()`` - -Also note that the order codes are interpreted is important. -For example, the following code is WRONG - -:: - - from pygcode import Machine, Line - m = Machine() - line = Line('G0 x10 y10 G91') - m.process_gcodes(*line.block.gcodes) # WRONG! - -This will process the movement to ``x=10, y=10``, and **then** it will change the -distance mode to *Incremental*... there are 2 ways to do this correctly. - -- ``m.process_gcodes(*sorted(line.block.gcodes))``, or simply -- ``m.process_block(line.block)`` - -sorting a list of gcodes will sort them in execution order (as specified by -`LinuxCNC's order of execution `__). -``process_block`` does this automatically. - -If you need to process & change one type of gcode (usually a movement), -you must split a list of gcodes into those executed before, and after the one -in question. - -:: - - from pygcode import GCodeRapidMove, GCodeLinearMove - from pygcode import Machine, Line, split_gcodes - m = Machine() - line = Line('M0 G0 x10 y10 G91') - (befores, (g,), afters) = split_gcodes(line.block.gcodes, (GCodeRapidMove, GCodeLinearMove)) - m.process_gcodes(*sorted(befores)) - if g.X is not None: - g.X += 100 # shift linear movements (rapid or otherwise) - m.process_gcodes(g) - m.process_gcodes(*sorted(afters)) - - -For a more practical use of machines & interpreting gcode, have a look at -`pygcode-normalize.py `__ - -At the time of writing this, that script converts arcs to linear codes, and -expands drilling cycles to basic movements (so my -`GRBL `__ machine can understand them) - - -Development -=========== - -This library came from my own needs to interpret and convert erroneous -arcs to linear segments, and to expand canned drilling cycles, but also -as a means to *learn* GCode. - -As such there is no direct plan for further development, however I'm -interested in what you'd like to use it for, and cater for that. - -Generally, in terms of what to support, I'm following the lead of: - -- `GRBL `__ and -- `LinuxCNC `__ - -More support will come with increased interest. -So that is... if you don't like what it does, or how it's documented, make some -noise in the `issue section `__. -if you get in early, you may get some free labour out of me ;) - - -Supported G-Codes ------------------ - -All GCodes supported by `LinuxCNC `__ can be written, and -parsed by ``pygcode``. - -Few GCodes are accurately interpreted by a virtual CNC ``Machine`` instance. -Supported movements are currently; - -- linear movements -- arc movements -- canned drilling cycles +`Check out the wiki `__ for documentation. diff --git a/scripts/pygcode-norm b/scripts/pygcode-norm index 1c967da..d9bd32f 100755 --- a/scripts/pygcode-norm +++ b/scripts/pygcode-norm @@ -81,7 +81,9 @@ DEFAULT_ARC_LIN_METHOD = 'm' DEFAULT_CANNED_CODES = ','.join(str(w) for w in sorted(c.word_key for c in _subclasses(GCodeCannedCycle) if c.word_key)) # --- Create Parser -parser = argparse.ArgumentParser(description='Normalize gcode for machine consistency using different CAM software') +parser = argparse.ArgumentParser( + description="Normalize gcode for machine consistency when using different CAM software" +) parser.add_argument( 'infile', type=argparse.FileType('r'), help="gcode file to normalize", @@ -121,7 +123,7 @@ group.add_argument( '--arc_lin_method', '-alm', dest='arc_lin_method', type=arc_lin_method_type, default=DEFAULT_ARC_LIN_METHOD, help="Method of linearizing arcs, i=inner, o=outer, m=mid. List 2 " - "for ,, eg 'i,o'. 'i' is equivalent to 'i,i'. " + "for ,, eg 'i,o'. 'i' is equivalent to 'i,i'. " "(default: '%s')" % DEFAULT_ARC_LIN_METHOD, metavar='{i,o,m}[,{i,o,m}]', )