gcode_reader.interface

Attributes

FLAVOR_ALIASES

Functions

export_event_series_from_gcode(filepath[, machine, ...])

Processes a G-code file and exports a process model event series.

gcode_file_to_dataframe(→ pandas.DataFrame)

Reads a G-code file into a pandas DataFrame with optional machine emulation.

gcode_file_to_dataframe_simple(filepath[, flavor])

Reads a G-code file directly into a pandas DataFrame (parsing only, no emulation).

gcode_to_additive_part(...)

Parses a G-code file into a structured AdditivePart object.

gcode_to_operation(filepath[, machine])

Parses a G-code file into a structured Operation object.

list_supported_machines()

List all supported machine types and their aliases.

operation_to_dataframe(→ pandas.DataFrame)

Converts a processed Operation to a pandas DataFrame with emulation data.

Module Contents

gcode_reader.interface.export_event_series_from_gcode(filepath: str, machine: str = 'default', spatial_scale_factor: float = 0.001, destination: str | None = None)[source]

Processes a G-code file and exports a process model event series.

This function provides a direct pipeline from a G-code file to a saved Additive Event Series (.aes) file.

The resulting event series is saved to a CSV-based file and is also returned as a pandas DataFrame for immediate use.

Parameters:

  • filepath (str) – The absolute or relative path to the G-code file.

  • machine (str, optional) – A string identifying the machine model to be used for parsing and emulation. Defaults to “default”.

  • spatial_scale_factor (float, optional) – A multiplicative factor to convert spatial units from the G-code (typically millimeters) to the desired output units for analysis (typically meters). Defaults to 1e-3 (mm to m).

  • destination (str | None, optional) – The full path for the output file. If None, a path is automatically generated by appending _event_series.aes to the input filename. Defaults to None.

Returns:

A DataFrame containing the time-stamped event

series, with columns representing machine states over time.

Return type:

pandas.DataFrame

Raises:

  • ValueError – If the machine is not a recognized key or alias in the MACHINE_TYPE_MAP.

  • FileNotFoundError – If the filepath does not exist.

Examples

>>> import gcode_reader as gr
>>>
>>> # Generate and save the event series file ('part1_event_series.aes')
>>> event_series_df = gr.export_event_series_from_gcode(
...     'part1.gcode',
...     machine='cincinnati'
... )
>>>
>>> # The returned DataFrame can be used immediately.
>>> print(event_series_df)
gcode_reader.interface.gcode_file_to_dataframe(filepath: str, machine: str = 'default', flavor: str | None = None, fast: bool = False) → pandas.DataFrame[source]

Reads a G-code file into a pandas DataFrame with optional machine emulation.

This is the primary way to get G-code data as a DataFrame. It combines parsing, optional machine emulation, and DataFrame conversion into a single call.

For fast parsing without machine emulation (10-50x faster), set fast=True. For full machine simulation with kinematics, leave fast=False.

Parameters:

  • filepath (str) – Path (absolute or relative) to a G-code file.

  • machine (str, optional) – A string identifying the machine model to use for emulation. This is not case-sensitive and ignores spaces. See list_supported_machines() for all available options. Ignored if fast=True. Defaults to “default”.

  • flavor (str, optional) – G-code syntax flavor (for compatibility). If provided, overrides the machine parameter. Supports ‘default’, ‘marlin’, ‘reprap’, ‘cead’, ‘flexbot’, ‘hendrick’, ‘juggerbot’, ‘ingersoll’, ‘cincinnati’, ‘baam’.

  • fast (bool, optional) – If True, use fast parsing without machine emulation (50-100x faster). If False, use full machine emulation with kinematics. Defaults to False.

Returns:

A DataFrame with process data. Columns include:

  • Coordinates: x, y, z (machine position)

  • Deltas: dx, dy, dz (coordinate changes)

  • Distance: distance (move distance)

  • Time: time (elapsed time in seconds)

  • Tags: tags (contextual information)

Return type:

pandas.DataFrame

Raises:

Examples

>>> import gcode_reader as gr
>>>
>>> # Fast parsing without emulation (10-50ms)
>>> df = gr.gcode_file_to_dataframe('part.gcode', fast=True)
>>>
>>> # Full machine emulation with kinematics (much slower)
>>> df = gr.gcode_file_to_dataframe('part.gcode', machine='cead', fast=False)
>>> print(df[['x', 'y', 'z', 'time']].head())
gcode_reader.interface.gcode_file_to_dataframe_simple(filepath: str, flavor: str = 'default')[source]

Reads a G-code file directly into a pandas DataFrame (parsing only, no emulation).

This function provides fast parsing without machine emulation. The resulting DataFrame includes raw G-code parsing results with columns for coordinates, distances, elapsed time estimates, contextual tags, and more. For full machine simulation results, use gcode_file_to_dataframe() instead.

Parameters:

  • filepath (str) – Path (absolute or relative) to a G-code file.

  • flavor (str, optional) – The G-code syntax flavor to use. Supports: ‘default’, ‘marlin’, ‘reprap’, ‘cead’, ‘flexbot’, ‘hendrick’, ‘juggerbot’, ‘ingersoll’, ‘cincinnati’, ‘baam’. Defaults to “default”.

Returns:

A DataFrame with parsed G-code data. Columns include:

  • Coordinates: x, y, z (machine position)

  • Deltas: dx, dy, dz (distance changes)

  • Time: time (estimated seconds)

  • Tags: contextual information (move type, extrusion, etc.)

  • Raw words: individual G-code words (G, M, X, Y, Z, E, F, etc.)

Return type:

pandas.DataFrame

Raises:

Examples

>>> import gcode_reader as gr
>>>
>>> # For quick parsing without machine emulation
>>> df = gr.gcode_file_to_dataframe_simple('part.gcode')
>>> print(df[['x', 'y', 'z', 'time']].head())
>>>
>>> # For full emulation results, use gcode_file_to_dataframe() instead
>>> df_emulated = gr.gcode_file_to_dataframe('part.gcode', machine='cead')
gcode_reader.interface.gcode_to_additive_part(filepath: str, bead: gcode_reader.emulate.additive_part.Bead, machine: str = 'default', layer_normal: tuple[float, float, float] | None = None) → gcode_reader.emulate.additive_part.AdditivePart[source]

Parses a G-code file into a structured AdditivePart object.

This function is a convenience pipeline from a G-code file to an AdditivePart, combining machine emulation and part construction in a single call.

Parameters:

  • filepath (str) – The absolute or relative path to the G-code file.

  • bead (Bead) – The uniform cross-sectional bead geometry to apply to all extruded filaments (width, height, density, shape).

  • machine (str, optional) – A string identifying the machine model to be used for parsing and emulation. Not case-sensitive and ignores spaces. See list_supported_machines() for available options. Defaults to “default”, a generic machine.

  • layer_normal (tuple[float, float, float] | None, optional) – The plane normal direction used to identify layers. If None, the default layer detection logic is applied. Defaults to None.

Returns:

A structured part containing layers, segments, and

process data derived from the G-code file.

Return type:

AdditivePart

Raises:

Examples

>>> import gcode_reader as gr
>>>
>>> bead = gr.emulate.additive_part.Bead(width=8.0, height=2.0, density=1200.0)
>>> part = gr.gcode_to_additive_part('part.gcode', bead, machine='cincinnati')
>>> print(f"Layers: {part.n_layers}")
gcode_reader.interface.gcode_to_operation(filepath: str, machine: str = 'default')[source]

Parses a G-code file into a structured Operation object.

This function is the primary entry point for loading manufacturing instructions into the emulation environment. It reads a G-code file and interprets its commands in the context of a specific machine model.

The result is an Operation object (or a specialized subclass like AdditiveOperation) that contains a sequence of commands and associated process data.

Parameters:

  • filepath (str) – The absolute or relative path to the G-code file.

  • machine (str, optional) – A string identifying the machine model to be used for parsing. This is not case-sensitive and ignores spaces. See the MACHINE_TYPE_MAP dictionary for a full list of supported aliases (e.g., “Cincinnati BAAM”, “CEAD”, “Default”). Defaults to “default”, a generic machine.

Returns:

An Operation instance containing the commands parsed from

the G-code file and associated process data. The specific type (e.g., AdditiveOperation, SubtractiveOperation) depends on the selected machine model.

Return type:

Operation

Raises:

ValueError – If the machine is not a recognized key or alias in the MACHINE_TYPE_MAP.

Examples

>>> # Assume a G-code file named 'part1.gcode' exists.
>>> import gcode_reader as gr
>>>
>>> # Load the file using the default machine profile.
>>> operation = gr.gcode_file_to_operation(
...     'part1.gcode'
... )
>>>
>>> # The returned object is now ready for further processing.
>>> print(f"Loaded operation: {operation.name}")
>>> print(f"All locations in G-code: {operation.get_all_locations()}")
gcode_reader.interface.list_supported_machines()[source]

List all supported machine types and their aliases.

Returns:

A dictionary mapping machine names/aliases to their class types.

Use the keys to identify machines for gcode_to_operation().

Return type:

dict

Examples

>>> import gcode_reader as gr
>>> machines = gr.list_supported_machines()
>>> print(list(machines.keys()))
['baam', 'cead', 'cincinnati', 'default', 'desktop', ...]
gcode_reader.interface.operation_to_dataframe(operation: gcode_reader.emulate.operations.Operation) → pandas.DataFrame[source]

Converts a processed Operation to a pandas DataFrame with emulation data.

This function provides direct access to the emulation results as a DataFrame, allowing for analysis of machine kinematics, motion profiles, and timing after full machine simulation.

The resulting DataFrame includes all process data from the operation including coordinates, velocities, feed rates, elapsed time, and motion profile information.

Parameters:

operation (Operation) – A processed Operation object (result of gcode_to_operation() or equivalent). Must have been processed by a machine (i.e., operation.processed_by_machine must not be None).

Returns:

A DataFrame with simple process data. Columns include:

  • Coordinates: x, y, z (machine position)

  • Deltas: dx, dy, dz (coordinate changes)

  • Distance: distance (move distance)

  • Time: time (elapsed time in seconds)

  • Tags: tags (contextual information)

Return type:

pandas.DataFrame

Raises:

ValueError – If the operation has not been processed by a machine.

Examples

>>> import gcode_reader as gr
>>>
>>> # Load and process a G-code file with full machine emulation
>>> operation = gr.gcode_to_operation('part.gcode', machine='cead')
>>>
>>> # Convert to DataFrame for analysis
>>> df = gr.operation_to_dataframe(operation)
>>> print(df[['x', 'y', 'z', 'time']].head())
>>>
>>> # Analyze motion profile
>>> print(f"Total elapsed time: {df['time'].iloc[-1]:.2f}s")
>>> print(f"Average distance: {df['distance'].mean():.2f}")
gcode_reader.interface.FLAVOR_ALIASES