# G-code Mass Matrix Analyzer
A Python package for extracting mass matrices from 3D printer G-code files, including support for zipped G-code files (.3mf) from slicers like BambuLab.
## Features
- **Material Detection**: Automatically detects material types (PLA, PETG, TPU, etc.) from G-code headers
- **Density Mapping**: Uses built-in material density database or extracts from G-code
- **Motion Analysis**: Analyzes all extrusion movements including:
- G1: Linear moves with extrusion
- G2: Clockwise arc moves with extrusion
- G3: Counterclockwise arc moves with extrusion
- **Smart Arc Subdivision**: Configurable angle-based arc subdivision
- Small arcs (< min_arc_angle) treated as straight lines
- Large arcs subdivided based on angular resolution for accuracy
- **Volume Calculation**: Calculates volume of each extrusion segment (linear and arc segments)
- **Multi-Material Tracking**: Tracks extruder changes and uses correct material density per segment
- **Mass Matrix Computation**: Generates mass matrix with inertia tensor and total mass
- **Usage Statistics**: Detailed breakdown of material usage by extruder
- **3mf File Support**: Handles `.gcode.3mf` files with automatic extraction and G-code detection, but you need to rename it first to `.gcode.zip`
## Installation
### From PyPI
```bash
pip install gcode-mass-matrix-analyzer
```
### From Source
```bash
git clone https://github.com/your-username/gcode-mass-matrix-analyzer
cd gcode-mass-matrix-analyzer
pip install -e .
```
## Usage
### Command Line
#### Regular G-code files
```bash
python -m gcode_mass_matrix_analyzer example.gcode
```
#### Zipped G-code files
The `.gcode.3mf` file need to be first rename to `.gcode.zip`.
```bash
python -m gcode_mass_matrix_analyzer ~/example.gcode.zip
python -m gcode_mass_matrix_analyzer ~/example.gcode.zip 0.05 # Custom arc angle
```
#### Using the command-line tool
```bash
gcode-mass-analyzer example.gcode
gcode-mass-analyzer ~/example.gcode.zip 0.05
```
### Python Script
```python
from gcode_mass_matrix_analyzer import GCodeMassMatrixAnalyzer
# Default settings (min_arc_angle = 0.1 rad ≈ 5.7°)
analyzer = GCodeMassMatrixAnalyzer("example.gcode")
# Custom angle threshold (0.05 rad ≈ 2.9°)
analyzer = GCodeMassMatrixAnalyzer("example.gcode", min_arc_angle=0.05)
mass_matrix, stats = analyzer.analyze()
print(f"Total mass: {mass_matrix[3,3]:.6f} kg")
```
### Test with Example File
```bash
python test_analyzer.py
```
## Output
The program generates:
1. **Console Output**: Detailed analysis results including:
- Material properties detected
- Object centroid coordinates
- Total volume and mass
- Mass matrix
- Inertia tensor
2. **Saved Results**: NumPy archive file (`*_mass_matrix.npz`) containing:
- Mass matrix array
- Centroid coordinates
- Total volume
## Mass Matrix Format
The mass matrix has the following structure:
```
┌─────────────────────────────┐
│ Ixx -Ixy -Ixz 0 │
│ -Ixy Iyy -Iyz 0 │
│ -Ixz -Iyz Izz 0 │
│ 0 0 0 mass │
└─────────────────────────────┘
```
Where:
- `Ixx`, `Iyy`, `Izz`: Moments of inertia (kg⋅m²)
- `Ixy`, `Ixz`, `Iyz`: Products of inertia (kg⋅m²)
- `mass`: Total mass (kg)
## Supported Materials
The program includes density data for common 3D printing materials:
| Material | Density (g/cm³) |
|----------|----------------|
| PLA | 1.24 |
| PLA-CF | 1.30 |
| PETG | 1.27 |
| PETG-CF | 1.35 |
| TPU | 1.20 |
| ABS | 1.04 |
| PA (Nylon)| 1.13 |
| PA-GF | 1.35 |
| ASA | 1.05 |
## Technical Details
### Volume Calculation
Each extrusion segment is modeled as a rectangular cuboid with:
- **Length**: Distance between start and end points
- **Width**: Line width (estimated from nozzle diameter × 1.2)
- **Height**: Layer height (extracted from G-code)
### Inertia Calculation
The program treats each extrusion segment as a point mass at its center and applies the parallel axis theorem to calculate moments and products of inertia about the object's centroid.
### Coordinate System
- **Origin**: Object centroid
- **Units**:
- Mass: kg
- Inertia: kg⋅m²
- Distance: mm (converted to m for inertia calculations)
## Limitations
1. **Simplified Geometry**: Treats extrusions as rectangular cross-sections
2. **Point Mass Approximation**: Each segment treated as point mass at center
3. **Single Extruder Focus**: Currently optimized for single-material analysis
4. **BambuLab Format**: Designed for BambuLab slicer G-code format
5. **Absolute Offset**: The inertia tensor is relative to the absolute coordinate of the printer, but not the object it self.
6. **Inaccurate Mass**: The mass estimation is not the same as that from the printer.
7. **Material Missalign**: If the material has the same name, it will just take the first density for estimation. This need to be fixed by reading the material mapping from config file.
## Example Output
```
Analyzing G-code file: example.gcode
Materials: ['PLA', 'PLA', 'TPU-AMS', 'PETG', 'PLA']
Material densities: [1.19, 1.26, 1.26, 1.25, 1.26] g/cm³
Layer height: 0.08 mm
Filament diameter: 1.75 mm
Object centroid: (174.875, 163.612, 12.620) mm
Total mass: 23.950 g (0.023950 kg)
Mass Matrix (kg⋅m²):
┌─────────────────────────────────────────────────────────┐
│ 2.345678e-06 -1.234567e-07 -2.345678e-08 0 │
│ -1.234567e-07 3.456789e-06 -3.456789e-08 0 │
│ -2.345678e-08 -3.456789e-08 4.567890e-06 0 │
│ 0 0 0 0.023950 │
└─────────────────────────────────────────────────────────┘
Total Mass: 0.023950 kg (23.950 g)
```
## Contributing
Feel free to submit issues and enhancement requests!
## Warning
This code is generated by claude with human supervision. There could still be errors besides the mentionds limitations. Please use at your own risk.
Raw data
{
"_id": null,
"home_page": null,
"name": "gcode-mass-matrix-analyzer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "3d-printing, gcode, mass-matrix, inertia, bambulab, 3d-printer",
"author": null,
"author_email": "GitHub Copilot and Boya <noreply@github.com>",
"download_url": "https://files.pythonhosted.org/packages/81/9c/bfc869c3b7064732ece73cbd18b9e879ae6cf540a7bf895216a3abef06f3/gcode_mass_matrix_analyzer-1.0.0.tar.gz",
"platform": null,
"description": "# G-code Mass Matrix Analyzer\n\nA Python package for extracting mass matrices from 3D printer G-code files, including support for zipped G-code files (.3mf) from slicers like BambuLab.\n\n## Features\n\n- **Material Detection**: Automatically detects material types (PLA, PETG, TPU, etc.) from G-code headers\n- **Density Mapping**: Uses built-in material density database or extracts from G-code\n- **Motion Analysis**: Analyzes all extrusion movements including:\n - G1: Linear moves with extrusion\n - G2: Clockwise arc moves with extrusion \n - G3: Counterclockwise arc moves with extrusion\n- **Smart Arc Subdivision**: Configurable angle-based arc subdivision\n - Small arcs (< min_arc_angle) treated as straight lines\n - Large arcs subdivided based on angular resolution for accuracy\n- **Volume Calculation**: Calculates volume of each extrusion segment (linear and arc segments)\n- **Multi-Material Tracking**: Tracks extruder changes and uses correct material density per segment\n- **Mass Matrix Computation**: Generates mass matrix with inertia tensor and total mass\n- **Usage Statistics**: Detailed breakdown of material usage by extruder\n- **3mf File Support**: Handles `.gcode.3mf` files with automatic extraction and G-code detection, but you need to rename it first to `.gcode.zip`\n\n## Installation\n\n### From PyPI\n```bash\npip install gcode-mass-matrix-analyzer\n```\n\n### From Source\n```bash\ngit clone https://github.com/your-username/gcode-mass-matrix-analyzer\ncd gcode-mass-matrix-analyzer\npip install -e .\n```\n\n## Usage\n\n### Command Line\n\n#### Regular G-code files\n```bash\npython -m gcode_mass_matrix_analyzer example.gcode\n```\n\n#### Zipped G-code files\nThe `.gcode.3mf` file need to be first rename to `.gcode.zip`.\n\n```bash\npython -m gcode_mass_matrix_analyzer ~/example.gcode.zip\npython -m gcode_mass_matrix_analyzer ~/example.gcode.zip 0.05 # Custom arc angle\n```\n\n#### Using the command-line tool\n```bash\ngcode-mass-analyzer example.gcode\ngcode-mass-analyzer ~/example.gcode.zip 0.05\n```\n\n### Python Script\n```python\nfrom gcode_mass_matrix_analyzer import GCodeMassMatrixAnalyzer\n\n# Default settings (min_arc_angle = 0.1 rad \u2248 5.7\u00b0)\nanalyzer = GCodeMassMatrixAnalyzer(\"example.gcode\")\n\n# Custom angle threshold (0.05 rad \u2248 2.9\u00b0)\nanalyzer = GCodeMassMatrixAnalyzer(\"example.gcode\", min_arc_angle=0.05)\n\nmass_matrix, stats = analyzer.analyze()\nprint(f\"Total mass: {mass_matrix[3,3]:.6f} kg\")\n```\n\n### Test with Example File\n```bash\npython test_analyzer.py\n```\n\n## Output\n\nThe program generates:\n\n1. **Console Output**: Detailed analysis results including:\n - Material properties detected\n - Object centroid coordinates\n - Total volume and mass\n - Mass matrix\n - Inertia tensor\n\n2. **Saved Results**: NumPy archive file (`*_mass_matrix.npz`) containing:\n - Mass matrix array\n - Centroid coordinates\n - Total volume\n\n## Mass Matrix Format\n\nThe mass matrix has the following structure:\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Ixx -Ixy -Ixz 0 \u2502\n\u2502 -Ixy Iyy -Iyz 0 \u2502\n\u2502 -Ixz -Iyz Izz 0 \u2502\n\u2502 0 0 0 mass \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\nWhere:\n- `Ixx`, `Iyy`, `Izz`: Moments of inertia (kg\u22c5m\u00b2)\n- `Ixy`, `Ixz`, `Iyz`: Products of inertia (kg\u22c5m\u00b2)\n- `mass`: Total mass (kg)\n\n## Supported Materials\n\nThe program includes density data for common 3D printing materials:\n\n| Material | Density (g/cm\u00b3) |\n|----------|----------------|\n| PLA | 1.24 |\n| PLA-CF | 1.30 |\n| PETG | 1.27 |\n| PETG-CF | 1.35 |\n| TPU | 1.20 |\n| ABS | 1.04 |\n| PA (Nylon)| 1.13 |\n| PA-GF | 1.35 |\n| ASA | 1.05 |\n\n## Technical Details\n\n### Volume Calculation\nEach extrusion segment is modeled as a rectangular cuboid with:\n- **Length**: Distance between start and end points\n- **Width**: Line width (estimated from nozzle diameter \u00d7 1.2)\n- **Height**: Layer height (extracted from G-code)\n\n### Inertia Calculation\nThe program treats each extrusion segment as a point mass at its center and applies the parallel axis theorem to calculate moments and products of inertia about the object's centroid.\n\n### Coordinate System\n- **Origin**: Object centroid\n- **Units**: \n - Mass: kg\n - Inertia: kg\u22c5m\u00b2\n - Distance: mm (converted to m for inertia calculations)\n\n## Limitations\n\n1. **Simplified Geometry**: Treats extrusions as rectangular cross-sections\n2. **Point Mass Approximation**: Each segment treated as point mass at center\n3. **Single Extruder Focus**: Currently optimized for single-material analysis\n4. **BambuLab Format**: Designed for BambuLab slicer G-code format\n5. **Absolute Offset**: The inertia tensor is relative to the absolute coordinate of the printer, but not the object it self.\n6. **Inaccurate Mass**: The mass estimation is not the same as that from the printer.\n7. **Material Missalign**: If the material has the same name, it will just take the first density for estimation. This need to be fixed by reading the material mapping from config file.\n\n## Example Output\n\n```\nAnalyzing G-code file: example.gcode\nMaterials: ['PLA', 'PLA', 'TPU-AMS', 'PETG', 'PLA']\nMaterial densities: [1.19, 1.26, 1.26, 1.25, 1.26] g/cm\u00b3\nLayer height: 0.08 mm\nFilament diameter: 1.75 mm\nObject centroid: (174.875, 163.612, 12.620) mm\nTotal mass: 23.950 g (0.023950 kg)\n\nMass Matrix (kg\u22c5m\u00b2):\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 2.345678e-06 -1.234567e-07 -2.345678e-08 0 \u2502\n\u2502 -1.234567e-07 3.456789e-06 -3.456789e-08 0 \u2502\n\u2502 -2.345678e-08 -3.456789e-08 4.567890e-06 0 \u2502\n\u2502 0 0 0 0.023950 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\nTotal Mass: 0.023950 kg (23.950 g)\n```\n\n## Contributing\n\nFeel free to submit issues and enhancement requests!\n\n## Warning\n\nThis code is generated by claude with human supervision. There could still be errors besides the mentionds limitations. Please use at your own risk.\n",
"bugtrack_url": null,
"license": null,
"summary": "Extract mass matrices from 3D printer G-code files",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/your-username/gcode-mass-matrix-analyzer#readme",
"Homepage": "https://github.com/your-username/gcode-mass-matrix-analyzer",
"Issues": "https://github.com/your-username/gcode-mass-matrix-analyzer/issues",
"Repository": "https://github.com/your-username/gcode-mass-matrix-analyzer"
},
"split_keywords": [
"3d-printing",
" gcode",
" mass-matrix",
" inertia",
" bambulab",
" 3d-printer"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "646730c8916706d308f84c5774c7783f9e9e85be996ee13c8da38474dad4bc15",
"md5": "8864f8153024a09d35cce103e7616edb",
"sha256": "27dc8f8b75d65006c842ce0e2028622bb3b050d196238a574c33469ff9cdaa32"
},
"downloads": -1,
"filename": "gcode_mass_matrix_analyzer-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8864f8153024a09d35cce103e7616edb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 15369,
"upload_time": "2025-08-20T09:46:57",
"upload_time_iso_8601": "2025-08-20T09:46:57.683700Z",
"url": "https://files.pythonhosted.org/packages/64/67/30c8916706d308f84c5774c7783f9e9e85be996ee13c8da38474dad4bc15/gcode_mass_matrix_analyzer-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "819cbfc869c3b7064732ece73cbd18b9e879ae6cf540a7bf895216a3abef06f3",
"md5": "b52eb2f0b303f8bd3072019d7bcaf659",
"sha256": "6609eac6c4d71a53e2877973b52c773b9ddb40e44ba248c37e070c03f9665766"
},
"downloads": -1,
"filename": "gcode_mass_matrix_analyzer-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "b52eb2f0b303f8bd3072019d7bcaf659",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 18890,
"upload_time": "2025-08-20T09:46:58",
"upload_time_iso_8601": "2025-08-20T09:46:58.834048Z",
"url": "https://files.pythonhosted.org/packages/81/9c/bfc869c3b7064732ece73cbd18b9e879ae6cf540a7bf895216a3abef06f3/gcode_mass_matrix_analyzer-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 09:46:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your-username",
"github_project": "gcode-mass-matrix-analyzer#readme",
"github_not_found": true,
"lcname": "gcode-mass-matrix-analyzer"
}
JSON
