autoforge 1.1.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (15) hide show
  1. autoforge-1.1.2/PKG-INFO +178 -0
  2. autoforge-1.1.2/README.md +156 -0
  3. autoforge-1.1.2/pyproject.toml +36 -0
  4. autoforge-1.1.2/setup.cfg +4 -0
  5. autoforge-1.1.2/src/AutoForge.egg-info/PKG-INFO +178 -0
  6. autoforge-1.1.2/src/AutoForge.egg-info/SOURCES.txt +13 -0
  7. autoforge-1.1.2/src/AutoForge.egg-info/dependency_links.txt +1 -0
  8. autoforge-1.1.2/src/AutoForge.egg-info/entry_points.txt +2 -0
  9. autoforge-1.1.2/src/AutoForge.egg-info/requires.txt +14 -0
  10. autoforge-1.1.2/src/AutoForge.egg-info/top_level.txt +1 -0
  11. autoforge-1.1.2/src/autoforge/__init__.py +0 -0
  12. autoforge-1.1.2/src/autoforge/__main__.py +8 -0
  13. autoforge-1.1.2/src/autoforge/auto_forge.py +713 -0
  14. autoforge-1.1.2/src/autoforge/filamentcolors_library.py +123 -0
  15. autoforge-1.1.2/src/autoforge/helper_functions.py +655 -0
autoforge-1.1.2/PKG-INFO ADDED
@@ -0,0 +1,178 @@
1
+ Metadata-Version: 2.2
2
+ Name: AutoForge
3
+ Version: 1.1.2
4
+ Summary: AutoForge is a Python tool for generating 3D printed layered models from an input image.
5
+ Author-email: Hendric Voss <hvoss@techfak.uni-bielefeld.de>
6
+ License: CC BY-NC-SA 4.0
7
+ Requires-Python: >=3.9
8
+ Description-Content-Type: text/markdown
9
+ Requires-Dist: numpy>=1.19.0
10
+ Requires-Dist: jax>=0.3.10
11
+ Requires-Dist: jaxlib>=0.3.10
12
+ Requires-Dist: opencv-python>=4.2.0.32
13
+ Requires-Dist: matplotlib>=3.3.0
14
+ Requires-Dist: configargparse>=1.2.3
15
+ Requires-Dist: tqdm>=4.50.0
16
+ Requires-Dist: pandas>=1.1.0
17
+ Requires-Dist: scikit-image
18
+ Requires-Dist: scikit-learn
19
+ Requires-Dist: optax>=0.1.3
20
+ Provides-Extra: gpu
21
+ Requires-Dist: jax[cuda12]; extra == "gpu"
22
+
23
+ # AutoForge
24
+
25
+ AutoForge is a Python tool for generating 3D printed layered models from an input image. Using a learned optimization strategy with a Gumbel softmax formulation, AutoForge assigns materials per layer and produces both a discretized composite image and a 3D-printable STL file. It also generates swap instructions to guide the printer through material changes during a multi-material print. \
26
+
27
+ **TLDR:** It uses a picture to generate a 3D layer image that you can print with a 3d printer. Similar to [Hueforge](https://shop.thehueforge.com/), but without the manual work (and without the artistic control).
28
+
29
+
30
+
31
+
32
+ ## Example
33
+ All examples use only the 13 BambuLab Basic filaments, currently available in Hueforge.
34
+ <div style="display: flex; justify-content: center; gap: 20px;">
35
+ <div style="text-align: center;">
36
+ <h3>Input Image</h3>
37
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/lofi.jpg" width="300" />
38
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/nature.jpg" width="300" />
39
+ </div>
40
+ <div style="text-align: center;">
41
+ <h3>Autoforge Output (75 color layers (3.0mm) + 10 gray background layers (0.4mm)) </h3>
42
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/lofi_discretized.jpg" width="300" />
43
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/nature_discretized.jpg" width="300" />
44
+ </div>
45
+ <div style="text-align: center;">
46
+ <h3>Imported Hueforge View</h3>
47
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/lofi_hueforge.png" width="300" />
48
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/nature_hueforge.png" width="300" />
49
+ </div>
50
+ </div>
51
+
52
+ If someone uses this program and 3d prints something with it, please let me know :) \
53
+ I would love to see what you made!
54
+
55
+
56
+ ## Features
57
+
58
+ - **Image-to-Model Conversion**: Converts an input image into a layered model suitable for 3D printing.
59
+ - **Learned Optimization**: Optimizes per-pixel height and per-layer material assignments using JAX and Optax.
60
+ - **Gumbel Softmax Sampling**: Leverages the Gumbel softmax method to decide material assignments for each layer.
61
+ - **STL File Generation**: Exports an ASCII STL file based on the optimized height map.
62
+ - **Swap Instructions**: Generates clear swap instructions for changing materials during printing.
63
+ - **Live Visualization**: (Optional) Displays live composite images during the optimization process.
64
+ - **Hueforge export**: Outputs a project file that can be opened with hueforge.
65
+
66
+
67
+ ## Installation
68
+
69
+ 1. **Clone the Repository**
70
+
71
+ ```bash
72
+ git clone https://github.com/hvoss-techfak/AutoForge.git
73
+ cd AutoForge
74
+ ```
75
+
76
+ 2. **Set Up a Virtual Environment (Optional but Recommended)**
77
+
78
+ ```bash
79
+ python -m venv venv
80
+ source venv/bin/activate # On Windows: venv\Scripts\activate
81
+ ```
82
+
83
+ 3. **Install Dependencies**
84
+
85
+ ```bash
86
+ pip install -r requirements.txt
87
+ ```
88
+
89
+ See the [requirements.txt](requirements.txt) file for a complete list of dependencies.
90
+ The optimizer is built using JAX, which benefits from a CUDA-compatible GPU for optimal performance.
91
+ Without a dedicated GPU the process can take significantly longer (up to 10-20x slower).
92
+ If you have a GPU, you can install the GPU version of JAX by running:
93
+
94
+ ```bash
95
+ pip install -U "jax[cuda12]"
96
+ ```
97
+
98
+ Currently, jax gpu support is only available under linux. \
99
+ If you use Windows, please install WSL2 to use the GPU version of jax.
100
+
101
+ ## Usage
102
+
103
+ The script is run from the command line and accepts several arguments. Below is an example command:
104
+
105
+ > **Note:** You will need [Hueforge](https://shop.thehueforge.com/) installed to export your filament CSV.
106
+ > To get your CSV file, simply go to the "Filaments" menu in Hueforge, click the export button, select your filaments, and export them as a CSV file.
107
+
108
+ > If you want to limit the amount of colors the program can use, you can simply delete the colors you don't want from the CSV file.
109
+
110
+ ```bash
111
+ python auto_forge.py --input_image path/to/input_image.jpg --csv_file path/to/materials.csv --output_folder outputs
112
+ ```
113
+
114
+ ### Command Line Arguments
115
+
116
+ - `--config`: *(Optional)* Path to a configuration file with the settings.
117
+ - `--input_image`: **(Required)** Path to the input image.
118
+ - `--csv_file`: **(Required)** Path to the CSV file containing material data. The CSV should include columns for the brand, name, color (hex code), and TD values.
119
+ - `--output_folder`: **(Required)** Folder where output files will be saved.
120
+ - `--iterations`: Number of optimization iterations (default: 20000).
121
+ - `--learning_rate`: Learning rate for the optimizer (default: 5e-3).
122
+ - `--layer_height`: Layer thickness in millimeters (default: 0.04).
123
+ - `--max_layers`: Maximum number of layers (default: 75).
124
+ **Note:** This is about 3mm + the background height
125
+ - `--background_height`: Height of the background in millimeters (default: 0.4).
126
+ **Note:** The background height must be divisible by the layer height.
127
+ - `--background_color`: Background color in hexadecimal format (default: `#8e9089` aka Bambulab Grey).
128
+ - `--max_size`: Maximum dimension (width or height) for the resized target image (default: 512).
129
+ - `--decay`: Final tau value for the Gumbel-Softmax formulation (default: 0.01).
130
+ - `--loss`: Loss function to use. Choices are `mse`, `perceptual`, or `perceptual_l1` (default: `mse`).
131
+ - `--visualize`: Flag to enable live visualization of the composite image during optimization.
132
+
133
+ ## Outputs
134
+
135
+ After running, the following files will be created in your specified output folder:
136
+
137
+ - **Discrete Composite Image**: `discrete_comp.png`
138
+ - **STL File**: `final_model.stl`
139
+ - **Swap Instructions**: `swap_instructions.txt`
140
+
141
+ Just a heads-up, this program is mainly concerned with realistic output and will give you VERY long swap instructions.
142
+ Expect to switch your filament every 1-2 layers!
143
+
144
+ For more artistic control or to reduce the number of swaps, consider buying [Hueforge](https://shop.thehueforge.com/).
145
+
146
+ ## Known Bugs
147
+
148
+ - There is a color discrepancy between our output and hueforge. If anyone has an idea what the problem is, please don't hesitate to submit a pull request :) \
149
+ Although I would love to be it fully color compatible with hueforge, I don't think this will happen without a lot of work or the hueforge source code.
150
+ - The optimizer can sometimes get stuck in a local minimum. If this happens, try running the optimization again with different settings.
151
+ - Hueforge can't open STL files under linux. This is a known bug in hueforge.
152
+ - The first version used a learnable height map which was nice but resulted in a lot of problems. Right now we compute the height map from the luminance values and slightly adjust the result. If somebody has an idea to make this better, please don't hesitate to submit a pull request :)
153
+
154
+ ## License
155
+
156
+ AutoForge © 2025 by Hendric Voss is licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/).
157
+
158
+ ## Acknowledgements
159
+
160
+ First and foremost:
161
+ - [Hueforge](https://shop.thehueforge.com/) for providing the filament data and inspiration for this project.
162
+ Without it, this project would not have been possible.
163
+
164
+ AutoForge makes use of several open source libraries:
165
+
166
+ - [JAX](https://github.com/google/jax)
167
+ - [Optax](https://github.com/deepmind/optax)
168
+ - [OpenCV](https://opencv.org/)
169
+ - [Matplotlib](https://matplotlib.org/)
170
+ - [Pandas](https://pandas.pydata.org/)
171
+ - [TQDM](https://github.com/tqdm/tqdm)
172
+ - [ConfigArgParse](https://github.com/bw2/ConfigArgParse)
173
+
174
+ Example Images:
175
+ <a href="https://www.vecteezy.com/free-photos/anime-girl">Anime Girl Stock photos by Vecteezy</a>
176
+ <a href="https://www.vecteezy.com/free-photos/nature">Nature Stock photos by Vecteezy</a>
177
+
178
+ Happy printing!
autoforge-1.1.2/README.md ADDED
@@ -0,0 +1,156 @@
1
+ # AutoForge
2
+
3
+ AutoForge is a Python tool for generating 3D printed layered models from an input image. Using a learned optimization strategy with a Gumbel softmax formulation, AutoForge assigns materials per layer and produces both a discretized composite image and a 3D-printable STL file. It also generates swap instructions to guide the printer through material changes during a multi-material print. \
4
+
5
+ **TLDR:** It uses a picture to generate a 3D layer image that you can print with a 3d printer. Similar to [Hueforge](https://shop.thehueforge.com/), but without the manual work (and without the artistic control).
6
+
7
+
8
+
9
+
10
+ ## Example
11
+ All examples use only the 13 BambuLab Basic filaments, currently available in Hueforge.
12
+ <div style="display: flex; justify-content: center; gap: 20px;">
13
+ <div style="text-align: center;">
14
+ <h3>Input Image</h3>
15
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/lofi.jpg" width="300" />
16
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/nature.jpg" width="300" />
17
+ </div>
18
+ <div style="text-align: center;">
19
+ <h3>Autoforge Output (75 color layers (3.0mm) + 10 gray background layers (0.4mm)) </h3>
20
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/lofi_discretized.jpg" width="300" />
21
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/nature_discretized.jpg" width="300" />
22
+ </div>
23
+ <div style="text-align: center;">
24
+ <h3>Imported Hueforge View</h3>
25
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/lofi_hueforge.png" width="300" />
26
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/nature_hueforge.png" width="300" />
27
+ </div>
28
+ </div>
29
+
30
+ If someone uses this program and 3d prints something with it, please let me know :) \
31
+ I would love to see what you made!
32
+
33
+
34
+ ## Features
35
+
36
+ - **Image-to-Model Conversion**: Converts an input image into a layered model suitable for 3D printing.
37
+ - **Learned Optimization**: Optimizes per-pixel height and per-layer material assignments using JAX and Optax.
38
+ - **Gumbel Softmax Sampling**: Leverages the Gumbel softmax method to decide material assignments for each layer.
39
+ - **STL File Generation**: Exports an ASCII STL file based on the optimized height map.
40
+ - **Swap Instructions**: Generates clear swap instructions for changing materials during printing.
41
+ - **Live Visualization**: (Optional) Displays live composite images during the optimization process.
42
+ - **Hueforge export**: Outputs a project file that can be opened with hueforge.
43
+
44
+
45
+ ## Installation
46
+
47
+ 1. **Clone the Repository**
48
+
49
+ ```bash
50
+ git clone https://github.com/hvoss-techfak/AutoForge.git
51
+ cd AutoForge
52
+ ```
53
+
54
+ 2. **Set Up a Virtual Environment (Optional but Recommended)**
55
+
56
+ ```bash
57
+ python -m venv venv
58
+ source venv/bin/activate # On Windows: venv\Scripts\activate
59
+ ```
60
+
61
+ 3. **Install Dependencies**
62
+
63
+ ```bash
64
+ pip install -r requirements.txt
65
+ ```
66
+
67
+ See the [requirements.txt](requirements.txt) file for a complete list of dependencies.
68
+ The optimizer is built using JAX, which benefits from a CUDA-compatible GPU for optimal performance.
69
+ Without a dedicated GPU the process can take significantly longer (up to 10-20x slower).
70
+ If you have a GPU, you can install the GPU version of JAX by running:
71
+
72
+ ```bash
73
+ pip install -U "jax[cuda12]"
74
+ ```
75
+
76
+ Currently, jax gpu support is only available under linux. \
77
+ If you use Windows, please install WSL2 to use the GPU version of jax.
78
+
79
+ ## Usage
80
+
81
+ The script is run from the command line and accepts several arguments. Below is an example command:
82
+
83
+ > **Note:** You will need [Hueforge](https://shop.thehueforge.com/) installed to export your filament CSV.
84
+ > To get your CSV file, simply go to the "Filaments" menu in Hueforge, click the export button, select your filaments, and export them as a CSV file.
85
+
86
+ > If you want to limit the amount of colors the program can use, you can simply delete the colors you don't want from the CSV file.
87
+
88
+ ```bash
89
+ python auto_forge.py --input_image path/to/input_image.jpg --csv_file path/to/materials.csv --output_folder outputs
90
+ ```
91
+
92
+ ### Command Line Arguments
93
+
94
+ - `--config`: *(Optional)* Path to a configuration file with the settings.
95
+ - `--input_image`: **(Required)** Path to the input image.
96
+ - `--csv_file`: **(Required)** Path to the CSV file containing material data. The CSV should include columns for the brand, name, color (hex code), and TD values.
97
+ - `--output_folder`: **(Required)** Folder where output files will be saved.
98
+ - `--iterations`: Number of optimization iterations (default: 20000).
99
+ - `--learning_rate`: Learning rate for the optimizer (default: 5e-3).
100
+ - `--layer_height`: Layer thickness in millimeters (default: 0.04).
101
+ - `--max_layers`: Maximum number of layers (default: 75).
102
+ **Note:** This is about 3mm + the background height
103
+ - `--background_height`: Height of the background in millimeters (default: 0.4).
104
+ **Note:** The background height must be divisible by the layer height.
105
+ - `--background_color`: Background color in hexadecimal format (default: `#8e9089` aka Bambulab Grey).
106
+ - `--max_size`: Maximum dimension (width or height) for the resized target image (default: 512).
107
+ - `--decay`: Final tau value for the Gumbel-Softmax formulation (default: 0.01).
108
+ - `--loss`: Loss function to use. Choices are `mse`, `perceptual`, or `perceptual_l1` (default: `mse`).
109
+ - `--visualize`: Flag to enable live visualization of the composite image during optimization.
110
+
111
+ ## Outputs
112
+
113
+ After running, the following files will be created in your specified output folder:
114
+
115
+ - **Discrete Composite Image**: `discrete_comp.png`
116
+ - **STL File**: `final_model.stl`
117
+ - **Swap Instructions**: `swap_instructions.txt`
118
+
119
+ Just a heads-up, this program is mainly concerned with realistic output and will give you VERY long swap instructions.
120
+ Expect to switch your filament every 1-2 layers!
121
+
122
+ For more artistic control or to reduce the number of swaps, consider buying [Hueforge](https://shop.thehueforge.com/).
123
+
124
+ ## Known Bugs
125
+
126
+ - There is a color discrepancy between our output and hueforge. If anyone has an idea what the problem is, please don't hesitate to submit a pull request :) \
127
+ Although I would love to be it fully color compatible with hueforge, I don't think this will happen without a lot of work or the hueforge source code.
128
+ - The optimizer can sometimes get stuck in a local minimum. If this happens, try running the optimization again with different settings.
129
+ - Hueforge can't open STL files under linux. This is a known bug in hueforge.
130
+ - The first version used a learnable height map which was nice but resulted in a lot of problems. Right now we compute the height map from the luminance values and slightly adjust the result. If somebody has an idea to make this better, please don't hesitate to submit a pull request :)
131
+
132
+ ## License
133
+
134
+ AutoForge © 2025 by Hendric Voss is licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/).
135
+
136
+ ## Acknowledgements
137
+
138
+ First and foremost:
139
+ - [Hueforge](https://shop.thehueforge.com/) for providing the filament data and inspiration for this project.
140
+ Without it, this project would not have been possible.
141
+
142
+ AutoForge makes use of several open source libraries:
143
+
144
+ - [JAX](https://github.com/google/jax)
145
+ - [Optax](https://github.com/deepmind/optax)
146
+ - [OpenCV](https://opencv.org/)
147
+ - [Matplotlib](https://matplotlib.org/)
148
+ - [Pandas](https://pandas.pydata.org/)
149
+ - [TQDM](https://github.com/tqdm/tqdm)
150
+ - [ConfigArgParse](https://github.com/bw2/ConfigArgParse)
151
+
152
+ Example Images:
153
+ <a href="https://www.vecteezy.com/free-photos/anime-girl">Anime Girl Stock photos by Vecteezy</a>
154
+ <a href="https://www.vecteezy.com/free-photos/nature">Nature Stock photos by Vecteezy</a>
155
+
156
+ Happy printing!
autoforge-1.1.2/pyproject.toml ADDED
@@ -0,0 +1,36 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "AutoForge"
7
+ version="1.1.2"
8
+ description = "AutoForge is a Python tool for generating 3D printed layered models from an input image."
9
+ authors = [{ name = "Hendric Voss", email = "hvoss@techfak.uni-bielefeld.de" }]
10
+ readme = "README.md"
11
+ requires-python = ">=3.9"
12
+ license = { text = "CC BY-NC-SA 4.0" }
13
+ dependencies = [
14
+ "numpy>=1.19.0",
15
+ "jax>=0.3.10",
16
+ "jaxlib>=0.3.10",
17
+ "opencv-python>=4.2.0.32",
18
+ "matplotlib>=3.3.0",
19
+ "configargparse>=1.2.3",
20
+ "tqdm>=4.50.0",
21
+ "pandas>=1.1.0",
22
+ "scikit-image",
23
+ "scikit-learn",
24
+ "optax>=0.1.3"
25
+ ]
26
+
27
+ [tool.setuptools]
28
+ package-dir = {"" = "src"}
29
+
30
+ [project.optional-dependencies]
31
+ gpu = [
32
+ "jax[cuda12]",
33
+ ]
34
+
35
+ [project.scripts]
36
+ autoforge = "autoforge.auto_forge:main"
autoforge-1.1.2/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
autoforge-1.1.2/src/AutoForge.egg-info/PKG-INFO ADDED
@@ -0,0 +1,178 @@
1
+ Metadata-Version: 2.2
2
+ Name: AutoForge
3
+ Version: 1.1.2
4
+ Summary: AutoForge is a Python tool for generating 3D printed layered models from an input image.
5
+ Author-email: Hendric Voss <hvoss@techfak.uni-bielefeld.de>
6
+ License: CC BY-NC-SA 4.0
7
+ Requires-Python: >=3.9
8
+ Description-Content-Type: text/markdown
9
+ Requires-Dist: numpy>=1.19.0
10
+ Requires-Dist: jax>=0.3.10
11
+ Requires-Dist: jaxlib>=0.3.10
12
+ Requires-Dist: opencv-python>=4.2.0.32
13
+ Requires-Dist: matplotlib>=3.3.0
14
+ Requires-Dist: configargparse>=1.2.3
15
+ Requires-Dist: tqdm>=4.50.0
16
+ Requires-Dist: pandas>=1.1.0
17
+ Requires-Dist: scikit-image
18
+ Requires-Dist: scikit-learn
19
+ Requires-Dist: optax>=0.1.3
20
+ Provides-Extra: gpu
21
+ Requires-Dist: jax[cuda12]; extra == "gpu"
22
+
23
+ # AutoForge
24
+
25
+ AutoForge is a Python tool for generating 3D printed layered models from an input image. Using a learned optimization strategy with a Gumbel softmax formulation, AutoForge assigns materials per layer and produces both a discretized composite image and a 3D-printable STL file. It also generates swap instructions to guide the printer through material changes during a multi-material print. \
26
+
27
+ **TLDR:** It uses a picture to generate a 3D layer image that you can print with a 3d printer. Similar to [Hueforge](https://shop.thehueforge.com/), but without the manual work (and without the artistic control).
28
+
29
+
30
+
31
+
32
+ ## Example
33
+ All examples use only the 13 BambuLab Basic filaments, currently available in Hueforge.
34
+ <div style="display: flex; justify-content: center; gap: 20px;">
35
+ <div style="text-align: center;">
36
+ <h3>Input Image</h3>
37
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/lofi.jpg" width="300" />
38
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/nature.jpg" width="300" />
39
+ </div>
40
+ <div style="text-align: center;">
41
+ <h3>Autoforge Output (75 color layers (3.0mm) + 10 gray background layers (0.4mm)) </h3>
42
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/lofi_discretized.jpg" width="300" />
43
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/nature_discretized.jpg" width="300" />
44
+ </div>
45
+ <div style="text-align: center;">
46
+ <h3>Imported Hueforge View</h3>
47
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/lofi_hueforge.png" width="300" />
48
+ <img src="https://github.com/hvoss-techfak/AutoForge/blob/main/images/nature_hueforge.png" width="300" />
49
+ </div>
50
+ </div>
51
+
52
+ If someone uses this program and 3d prints something with it, please let me know :) \
53
+ I would love to see what you made!
54
+
55
+
56
+ ## Features
57
+
58
+ - **Image-to-Model Conversion**: Converts an input image into a layered model suitable for 3D printing.
59
+ - **Learned Optimization**: Optimizes per-pixel height and per-layer material assignments using JAX and Optax.
60
+ - **Gumbel Softmax Sampling**: Leverages the Gumbel softmax method to decide material assignments for each layer.
61
+ - **STL File Generation**: Exports an ASCII STL file based on the optimized height map.
62
+ - **Swap Instructions**: Generates clear swap instructions for changing materials during printing.
63
+ - **Live Visualization**: (Optional) Displays live composite images during the optimization process.
64
+ - **Hueforge export**: Outputs a project file that can be opened with hueforge.
65
+
66
+
67
+ ## Installation
68
+
69
+ 1. **Clone the Repository**
70
+
71
+ ```bash
72
+ git clone https://github.com/hvoss-techfak/AutoForge.git
73
+ cd AutoForge
74
+ ```
75
+
76
+ 2. **Set Up a Virtual Environment (Optional but Recommended)**
77
+
78
+ ```bash
79
+ python -m venv venv
80
+ source venv/bin/activate # On Windows: venv\Scripts\activate
81
+ ```
82
+
83
+ 3. **Install Dependencies**
84
+
85
+ ```bash
86
+ pip install -r requirements.txt
87
+ ```
88
+
89
+ See the [requirements.txt](requirements.txt) file for a complete list of dependencies.
90
+ The optimizer is built using JAX, which benefits from a CUDA-compatible GPU for optimal performance.
91
+ Without a dedicated GPU the process can take significantly longer (up to 10-20x slower).
92
+ If you have a GPU, you can install the GPU version of JAX by running:
93
+
94
+ ```bash
95
+ pip install -U "jax[cuda12]"
96
+ ```
97
+
98
+ Currently, jax gpu support is only available under linux. \
99
+ If you use Windows, please install WSL2 to use the GPU version of jax.
100
+
101
+ ## Usage
102
+
103
+ The script is run from the command line and accepts several arguments. Below is an example command:
104
+
105
+ > **Note:** You will need [Hueforge](https://shop.thehueforge.com/) installed to export your filament CSV.
106
+ > To get your CSV file, simply go to the "Filaments" menu in Hueforge, click the export button, select your filaments, and export them as a CSV file.
107
+
108
+ > If you want to limit the amount of colors the program can use, you can simply delete the colors you don't want from the CSV file.
109
+
110
+ ```bash
111
+ python auto_forge.py --input_image path/to/input_image.jpg --csv_file path/to/materials.csv --output_folder outputs
112
+ ```
113
+
114
+ ### Command Line Arguments
115
+
116
+ - `--config`: *(Optional)* Path to a configuration file with the settings.
117
+ - `--input_image`: **(Required)** Path to the input image.
118
+ - `--csv_file`: **(Required)** Path to the CSV file containing material data. The CSV should include columns for the brand, name, color (hex code), and TD values.
119
+ - `--output_folder`: **(Required)** Folder where output files will be saved.
120
+ - `--iterations`: Number of optimization iterations (default: 20000).
121
+ - `--learning_rate`: Learning rate for the optimizer (default: 5e-3).
122
+ - `--layer_height`: Layer thickness in millimeters (default: 0.04).
123
+ - `--max_layers`: Maximum number of layers (default: 75).
124
+ **Note:** This is about 3mm + the background height
125
+ - `--background_height`: Height of the background in millimeters (default: 0.4).
126
+ **Note:** The background height must be divisible by the layer height.
127
+ - `--background_color`: Background color in hexadecimal format (default: `#8e9089` aka Bambulab Grey).
128
+ - `--max_size`: Maximum dimension (width or height) for the resized target image (default: 512).
129
+ - `--decay`: Final tau value for the Gumbel-Softmax formulation (default: 0.01).
130
+ - `--loss`: Loss function to use. Choices are `mse`, `perceptual`, or `perceptual_l1` (default: `mse`).
131
+ - `--visualize`: Flag to enable live visualization of the composite image during optimization.
132
+
133
+ ## Outputs
134
+
135
+ After running, the following files will be created in your specified output folder:
136
+
137
+ - **Discrete Composite Image**: `discrete_comp.png`
138
+ - **STL File**: `final_model.stl`
139
+ - **Swap Instructions**: `swap_instructions.txt`
140
+
141
+ Just a heads-up, this program is mainly concerned with realistic output and will give you VERY long swap instructions.
142
+ Expect to switch your filament every 1-2 layers!
143
+
144
+ For more artistic control or to reduce the number of swaps, consider buying [Hueforge](https://shop.thehueforge.com/).
145
+
146
+ ## Known Bugs
147
+
148
+ - There is a color discrepancy between our output and hueforge. If anyone has an idea what the problem is, please don't hesitate to submit a pull request :) \
149
+ Although I would love to be it fully color compatible with hueforge, I don't think this will happen without a lot of work or the hueforge source code.
150
+ - The optimizer can sometimes get stuck in a local minimum. If this happens, try running the optimization again with different settings.
151
+ - Hueforge can't open STL files under linux. This is a known bug in hueforge.
152
+ - The first version used a learnable height map which was nice but resulted in a lot of problems. Right now we compute the height map from the luminance values and slightly adjust the result. If somebody has an idea to make this better, please don't hesitate to submit a pull request :)
153
+
154
+ ## License
155
+
156
+ AutoForge © 2025 by Hendric Voss is licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/).
157
+
158
+ ## Acknowledgements
159
+
160
+ First and foremost:
161
+ - [Hueforge](https://shop.thehueforge.com/) for providing the filament data and inspiration for this project.
162
+ Without it, this project would not have been possible.
163
+
164
+ AutoForge makes use of several open source libraries:
165
+
166
+ - [JAX](https://github.com/google/jax)
167
+ - [Optax](https://github.com/deepmind/optax)
168
+ - [OpenCV](https://opencv.org/)
169
+ - [Matplotlib](https://matplotlib.org/)
170
+ - [Pandas](https://pandas.pydata.org/)
171
+ - [TQDM](https://github.com/tqdm/tqdm)
172
+ - [ConfigArgParse](https://github.com/bw2/ConfigArgParse)
173
+
174
+ Example Images:
175
+ <a href="https://www.vecteezy.com/free-photos/anime-girl">Anime Girl Stock photos by Vecteezy</a>
176
+ <a href="https://www.vecteezy.com/free-photos/nature">Nature Stock photos by Vecteezy</a>
177
+
178
+ Happy printing!
autoforge-1.1.2/src/AutoForge.egg-info/SOURCES.txt ADDED
@@ -0,0 +1,13 @@
1
+ README.md
2
+ pyproject.toml
3
+ src/AutoForge.egg-info/PKG-INFO
4
+ src/AutoForge.egg-info/SOURCES.txt
5
+ src/AutoForge.egg-info/dependency_links.txt
6
+ src/AutoForge.egg-info/entry_points.txt
7
+ src/AutoForge.egg-info/requires.txt
8
+ src/AutoForge.egg-info/top_level.txt
9
+ src/autoforge/__init__.py
10
+ src/autoforge/__main__.py
11
+ src/autoforge/auto_forge.py
12
+ src/autoforge/filamentcolors_library.py
13
+ src/autoforge/helper_functions.py
autoforge-1.1.2/src/AutoForge.egg-info/entry_points.txt ADDED
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ autoforge = autoforge.auto_forge:main
autoforge-1.1.2/src/AutoForge.egg-info/requires.txt ADDED
@@ -0,0 +1,14 @@
1
+ numpy>=1.19.0
2
+ jax>=0.3.10
3
+ jaxlib>=0.3.10
4
+ opencv-python>=4.2.0.32
5
+ matplotlib>=3.3.0
6
+ configargparse>=1.2.3
7
+ tqdm>=4.50.0
8
+ pandas>=1.1.0
9
+ scikit-image
10
+ scikit-learn
11
+ optax>=0.1.3
12
+
13
+ [gpu]
14
+ jax[cuda12]
autoforge-1.1.2/src/AutoForge.egg-info/top_level.txt ADDED
@@ -0,0 +1 @@
1
+ autoforge
autoforge-1.1.2/src/autoforge/__init__.py ADDED
File without changes
autoforge-1.1.2/src/autoforge/__main__.py ADDED
@@ -0,0 +1,8 @@
1
+ import sys
2
+ from .auto_forge import main
3
+
4
+ def main_cli():
5
+ main()
6
+
7
+ if __name__ == "__main__":
8
+ main_cli()