Skip to content

Commit 24ccf01

Browse files
ansonlansonl
committed
update docs
1 parent 5098815 commit 24ccf01

File tree

3 files changed

+49
-33
lines changed

3 files changed

+49
-33
lines changed

‎README.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,19 @@
44

55
Add colored [isolines (contour lines/elevation lines)](https://en.wikipedia.org/wiki/Contour_line) and recolor [elevation ranges](https://desktop.arcgis.com/en/arcmap/latest/map/styles-and-symbols/working-with-color-ramps.htm) to [3D printable map models](https://ansonliu.com/maps/). **3D G-code Map Feature Modifier (MFM)** is a G-code Post Processor made for 3D topo map models but any 3D model can be recolored with 2 additional colors.
66

7-
Use the latest version of MFM in 1 of 3 ways → [Getting Started](#getting-started)
7+
**Use the latest version of MFM in 1 of the following 3 ways → [Getting Started](#getting-started)**
88

99
- [MFM App](https://github.com/ansonl/mfm/releases) - Easiest to use and get started with a graphical user interface. Precompiled for Windows/Linux/Mac
1010
- [Integrated Post Processing Script in PrusaSlicer/Bambu Studio/Orca Slicer](https://github.com/ansonl/mfm/archive/refs/heads/master.zip) - Runs automatically after slicing.
1111
- [Python Script](https://github.com/ansonl/mfm/archive/refs/heads/master.zip) - Runnable from command line.
1212

13-
1413
**MFM adds additional features to the model by post processing sliced [3D printer G-code](https://marlinfw.org/meta/gcode/). 3D models and printing g-code can be recolored at either layer or individual feature/line level granularity.**
1514

1615
- **Feature/Line Type Scoping** - Recoloring can be set to only affect specific printing feature/line types. *Recolor only the top surfaces or walls at certain heights with MFM!*
1716

1817
- **G-code Feature Print Order Optimization** - Printed features are rearranged for faster, more consistent prints. Nozzle pressure is maintained and the number of toolchanges is decreased.
1918

20-
- **Wipe/Coasting Compensation** - Existing Wipe/Coasting flow compensation generated by the slicer is retained even when g-code features are relocated.
19+
- **Wipe/Coasting Compensation** - Existing Wipe/Coasting flow compensation generated by the slicer is retained even when g-code features are relocated. MFM has a customizable flush volume based on the color used and can do a **Long retraction after cut** to reduce filament waste.
2120

2221
- **Prime Tower Aware** - Existing Prime Towers are reused for optimal filament flow and color flushing. *No prime tower or large prime tower? Both configurations are supported.*
2322

@@ -54,7 +53,7 @@ Set up your slicer and printer for MFM by following the steps on each page below
5453

5554
2. [MFM Command Setup](terminal-setup.md) (not needed for GUI)
5655

57-
3. [Options](configuration-setup.md)
56+
3. [Options](mfm-configuration-options-setup.md)
5857

5958
4. [Minimal Toolchange G-code](minimal-toolchange-gcode.md)
6059

@@ -102,7 +101,7 @@ Bambu printer users can use [FTPS](https://forum.bambulab.com/t/we-can-now-conne
102101
| --- | --- |
103102
| How do I convert a 3D model into G-code for printing? | After importing and slicing your model in a slicer software, export the 3D printer commands as [ASCII] G-code. MFM can be process and recolor this saved G-code file. |
104103
| MFM did not add or change any colors. | Setup your slicer for MFM through [Slicer Setup](slicer-setup.md) |
105-
| How can MFM recoloring be customized? | Read [Options](configuration-setup.md) for details. |
104+
| How can MFM recoloring be customized? | Read [Options](mfm-configuration-options-setup.md) for details. |
106105
| How can MFM be used with a material other than PLA and customized toolchange? | See [Minimal Toolchange G-code](minimal-toolchange-gcode.md) on recommendations on how to setup your own toolchange. I may add an option to set toolchange temperatures based on material in the future. Open an issue with your use cases. |
107106
| Incorrect color was printed even though previewing the exported G-code in the slicer shows the correct color slots being used. | Assign a different filament to each slot in the Bambu AMS. Every slot with a different color **must have a different color assigned** in AMS. Otherwise Bambu AMS [Autoswitch](https://forum.bambulab.com/t/automatic-material-switch-over/4189) feature may try to use a single slot's filament for a shared material and color between multiple slots. |
108107
| Mixed OS line endings in the same file will lead to G-code errors. MFM tries to auto detect the line ending used with first line ending found. | Select the correct line ending of your G-code instead of auto detect. Either convert the entire G-code file with Unix line endings to Windows line endings before post processing or generate the G-code on Windows. [Python on Windows does not handle Unix line endings correctly.](https://stackoverflow.com/questions/15934950/python-file-tell-giving-strange-numbers) |

‎configuration-setup.md renamed to ‎mfm-configuration-options-setup.md

Lines changed: 35 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# MFM Configuration
22

3-
## Feature Options
4-
53
**Use Premade Options in [premade_options](./premade_options/) for the [3D printable map models](https://ansonliu.com/maps/) collection.**
64

75
The options file is formatted as a JSON dictionary with the following keys.
@@ -10,24 +8,16 @@ Options values are provided for each [3D printable map model](https://ansonliu.c
108

119
You can test configurations with the sample dual color dice G-code files in the `sample_models` folder.
1210

11+
## Color Assignment
12+
1313
Filament/color positions are 0-based. The first position is represented by `0`. The recommended filament order is:
1414

1515
| Physical Position (left to right) → | 1 | 2 | 3 | 4 |
1616
| -------- | ------- | ------- | ------- | ------ |
1717
| 0-based tool index in software | `0` | `1` | `2` | `3` |
1818
| **Purpose** | Primary (base) | Secondary (hydro) | *Isoline (contour line)* | *Elevation Color Change* |
1919

20-
### Filament Color data in G-code
21-
22-
If the final post processed G-code preview does not seem to show the right colors, you can set the filament color data in the `;CONFIG_BLOCK_START` of the G-code.
23-
24-
```gcode
25-
; filament_colour = #00FF80;#0080FF;#FFFF00;#FF0000
26-
```
27-
28-
This may happen when the tool indexes are not populated with colors in the slicer prior to exporting the G-code.
29-
30-
### Example Options file with Isoline and Elevation Change features
20+
## Example Options file with Isoline and Elevation Change features
3121

3222
```json
3323
{
@@ -49,10 +39,23 @@ This may happen when the tool indexes are not populated with colors in the slice
4939
"realWorldElevationReplacementColorEnd": 30000,
5040
"replacementColorIndex": 3,
5141
"replacementOriginalColorIndex": 0,
52-
"extraPurgePreviousColors": []
42+
"extraPurgePreviousColors": [2]
5343
}
5444
```
5545

46+
A map processed with this set of options will have the following appearance:
47+
48+
- Sea level start at 3.6mm in printed height.
49+
50+
- The first isoline (contour line) will start at 500m of real world height and future isolines will appear at 500m intervals (1000, 1500, 2000, etc). The isolines will stop at 30000m which is high enough to mean that the isolines will not stop on a normal map. The isoline color will use the filament loaded at index 2.
51+
- The isoline color will affect all wall/perimeter features.
52+
53+
- High elevation (snow line) replacement color will start at 2000m and end at 30000m. All uses of the filament at index 0 will be replaced with filament at index 3 when printing in the replacement color range.
54+
55+
- Whenever a color swap (toolchange) has the previous color of index 2, extra purging (150mm³) will be done.
56+
57+
## All Options
58+
5659
### Required Options
5760

5861
| Key | Value | Cardinality | Description |
@@ -74,13 +77,22 @@ This may happen when the tool indexes are not populated with colors in the slice
7477
| `isolineColorIndex` | `integer` | 1 | Isoline filament/color loaded position. Recommended index is 2 (third slot). |
7578
| `isolineColorFeatureTypes` | `[string]` | ≥0 | List of printing object feature/line types (extrusion roles) to recolor at isoline elevations. Empty array will recolor all feature types. Feature types are case sensitive. |
7679

80+
### Elevation Change Options
81+
82+
| Key | Value | Cardinality | Description |
83+
| -------- | ------- | ------- | ------- |
84+
| `realWorldElevationReplacementColorStart` | `float` | 1 | Elevation based replacement color start elevation in real world units. |
85+
| `realWorldElevationReplacementColorEnd` | `float` | 1 | Elevation based replacement color end elevation in real world units. |
86+
| `replacementColorIndex` | `integer` | 1 | Elevation based replacement color filament/color loaded position. Recommended index is 3 (fourth slot). |
87+
| `replacementOriginalColorIndex` | `integer` | 1 | Elevation based replacement color **replaced** filament/color loaded position. Recommended index is 0 (first slot). |
88+
7789
### Purge/Flush Options
7890

7991
| Key | Value | Cardinality | Description |
8092
| -------- | ------- | ------- | ------- |
8193
| `extraPurgePreviousColors` | `[int]` | ≥0 | Tool indices to add extra purging to when that tool is the previous tool in a toolchange. |
8294

83-
#### Feature Types (Extrusion Roles)
95+
### Feature Types (Extrusion Roles)
8496

8597
3D printed Feature Types are different categories used to define printing order and settings of printing travel and extrusion movements.
8698

@@ -98,11 +110,12 @@ Feature Types vary depending on the slicer used to generate the G-code. You can
98110

99111
MFM rearranges printing order of features to reduce the number of toolchanges a layer. Isoline recolored features are printed first. This may affect print quality of supported parts but you can work around that by specifying the `Support` and `Bridge` feature types for recoloring.
100112

101-
### Elevation Change Options
113+
### Filament Color data in G-code (Bambu/Orca)
102114

103-
| Key | Value | Cardinality | Description |
104-
| -------- | ------- | ------- | ------- |
105-
| `realWorldElevationReplacementColorStart` | `float` | 1 | Elevation based replacement color start elevation in real world units. |
106-
| `realWorldElevationReplacementColorEnd` | `float` | 1 | Elevation based replacement color end elevation in real world units. |
107-
| `replacementColorIndex` | `integer` | 1 | Elevation based replacement color filament/color loaded position. Recommended index is 3 (fourth slot). |
108-
| `replacementOriginalColorIndex` | `integer` | 1 | Elevation based replacement color **replaced** filament/color loaded position. Recommended index is 0 (first slot). |
115+
If the final post processed G-code preview does not seem to show the right colors, you can set the filament color data in the `;CONFIG_BLOCK_START` of the G-code.
116+
117+
```gcode
118+
; filament_colour = #00FF80;#0080FF;#FFFF00;#FF0000
119+
```
120+
121+
This may happen when the tool indexes are not populated with colors in the slicer prior to exporting the G-code.

‎minimal-toolchange-gcode.md

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Current premade printer toolchanges:
1414

1515
- Generic (firmware managed tool change with `T`)
1616
- Generic Manual (manual filament swap, requires `M600` filament change support in firmware)
17-
- Bambu X1/P1 series
17+
- Bambu X1/P1 series *(Recommended: `bambu-x1-p1-series-long-retraction-107mm3-flush.gcode`)*
1818
- Bambu A1
1919
- Bambu A1 mini
2020
- Prusa XL
@@ -23,13 +23,17 @@ Every 3D printer is different and you should manually verify that the provided G
2323

2424
## Requirements to Create a Minimal Toolchange
2525

26-
1. The location for next extruder index (the tool/filament/color being switched to) **must** be replaced with `XX` in this text file. MFM will replace all instances of `XX` with the next extruder index. *E.g. When switching to extruder 1, `TXX` will become `T1`*
26+
1. The location for next tool index (the tool/filament/color being switched to) **must** be replaced with `XX` in this text file. MFM will replace all instances of `XX` with the next tool index. *E.g. When switching to extruder 1, `TXX` will become `T1`*
2727

28-
2. It is recommended to convert movement coordinates that change depending on the current print progress from absolute to relative.
28+
1. The location for the previous tool index **must** be replaced with `YY` in this text file. This is only needed for G-code that needs the previous tool index e.g. `M620.11`.
2929

30-
3. All movements that are specific to a specific model must be removed or generalized to not interfere with printed models possibly being located anywhere in the print volume.
30+
1. MFM will insert extra purge G-code if needed after any occurance of `; EXTRA_PURGE_INSERTION`.
3131

32-
4. If possible, it is recommended to restore the printing state's original Z coordinate at the end of the minimal toolchange. MFM will add G-code to restore the original X/Y/Z position and acceleration values after the toolchange.
32+
1. It is recommended to convert movement coordinates that change depending on the current print progress from absolute to relative.
33+
34+
1. All movements that are specific to a specific model must be removed or generalized to not interfere with printed models possibly being located anywhere in the print volume.
35+
36+
1. If possible, it is recommended to restore the printing state's original Z coordinate at the end of the minimal toolchange. MFM will add G-code to restore the original X/Y/Z position and acceleration values after the toolchange.
3337

3438
> **TODO:** Fan speed is currently hardcoded to 78% at the end of the X1/P1 minimal toolchange. I may track fan speed to be restored in the future.
3539
@@ -56,4 +60,4 @@ A properly set up tool change g-code in firmware example for a multi-extruder 3D
5660

5761
## Contributing
5862

59-
If you would like to contribute your tested toolchange G-Code, please make a pull request on this Github repo.
63+
If you would like to contribute your tested toolchange G-Code or have feedback, please make an issue or pull request on this Github repo.

0 commit comments

Comments
 (0)