---
library_name: keras
license: mit
pipeline_tag: tabular-regression
tags:
  - 3d-printing
  - resin
  - regression
  - tabular
  - ensemble
  - xgboost
  - keras
  - uvtools
model-index:
  - name: MiniRes
    results: []
---
# MiniRes: Resin Usage Predictor for 3D Printed Miniatures

MiniRes is a small Python library + pretrained ensemble model that predicts **resin usage in grams** for pre-supported 3D printed miniatures.

It takes tabular features exported from your slicing & analysis pipeline (UVtools, PrusaSlicer, trimesh, etc.) and returns a single float per part: the estimated resin usage in grams.

Under the hood, MiniRes is an ensemble model with:

- A **Keras neural network** +
- An **XGBoost regressor**

The model weights are hosted on Hugging Face and downloaded/cached automatically.

Hugging Face model repo:  
https://huggingface.co/nicolamustone/minires

## How it works (high level)

The original dataset was built via this pipeline:
* Input: STL files from multiple miniature artists (multipart heroes, monsters, display pieces, etc.).
* Slicing: each STL is sliced in batch with PrusaSlicer using a consistent profile (CLI) with resin density of 1.1/g.
* Resin stats: UVtools inspects the .ctb/.sl1 files and exports resin stats, including resin usage in grams. This is the label.
* Geometry features: trimesh extracts mesh-level features: volume, surface area, implied mass, Euler characteristic, bounding box sizes, etc.
* Feature engineering: simple interaction & ratio features are added: volume × mass, surface/volume, surface/mass, bounding-box/volume, and similar.
* MiniRes is trained on this tabular data to predict UVtools’ “grams used” based only on these engineered features.

## Installation

Install the required dependencies:

```bash
pip install tensorflow xgboost pandas numpy huggingface_hub
```

Then add `minires.py` to your project (or install this repo as a package if you set it up that way).

## Basic usage

```python
import pandas as pd
from minires import minires

# Load your data
df = pd.read_csv("my_miniatures_features.csv")

# Create the model (downloads weights from Hugging Face on first run)
model = minires(verbose=1)

# Predict resin usage (grams)
y_pred = model.predict(df)

print(y_pred[:10])
```

`verbose=1` prints the ensemble weights and Keras progress. You can pass the full dataframe; the model will select the features it needs.

## Required features

The model expects a fixed set of feature columns (the same ones used in training).

You can inspect them at runtime:
```python
model = minires()
print(model.features)
```

Your dataframe must contain at least these columns. Extra columns are ignored. If any required columns are missing, `minires` will raise an error listing them.

Example single-row usage:
```python
import pandas as pd
from minires import minires

model = minires()

row = {
    "kb": 123.4,
    "volume": 56.7,
    "surface_area": 1234.5,
    "bbox_area": 789.1
    "euler_number": -1,
    "scale": 76.76
    "surface_volume_ratio": 0.8,
}

df_single = pd.DataFrame([row])
pred = model.predict(df_single)[0]

print("Predicted grams:", pred)
```

## Notes

The model approximates UVtools resin usage based on geometry/feature data.

Make sure you compute the same features as listed in `model.features`.

Weights are cached locally by `huggingface_hub` after the first download.

## CLI: Extract STL features with `trimesh`

This project includes two small command-line scripts:
1. `stl-scanner.py`: scans STL files and exports geometric features to a CSV using `trimesh`. The resulting CSV file is ready-to-use with MiniRes.
2. `mini-pricing.py`: takes the resulting CSV from `stl-scanner.py` (or any other CSV) and calculates the total cost of each file for you.

### Script: `stl-scanner.py`

The script accepts two optional arguments:

- `--stl_path`  
  - Path to a single `.stl` file **or** a folder containing `.stl` files (non-recursive).  
  - If omitted, the current directory (`.`) is used.
- `--output_path`  
  - Folder where the resulting CSV will be saved.  
  - If omitted, the current directory (`.`) is used.

If `--stl_path` points to:

- A **file** → only that STL is processed.  
- A **folder** → all `.stl` files directly in that folder are processed (no subfolders).

The output CSV contains one row per STL file with the following columns:

- `file_name`  
- `file_path`  
- `kb`
- `volume`  
- `surface_area`  
- `scale`  
- `bbox_area`
- `euler_number`  
- `surface_volume_ratio`  

### Usage examples

Process all STL files in the current directory and write `stl_features.csv` here:
```bash
python stl-scaner.py
```

Process a specific STL file and save the CSV to `./out`:
```bash
python stl-scaner.py --stl_path /path/to/model.stl --output_path ./out
```

Process all STL files in a folder (non-recursive) and save the CSV to ./features:
```bash
python stl-scaner.py --stl_path /path/to/stls --output_path ./features
```

After running the script, you’ll find `stl_features.csv` in the `output_path` folder, ready to be used as input for MiniRes or for your own analysis.

### Script: `mini-pricing.py`

Open the file with a text editor and adjust the constants at the top:
```python
RESIN_COST_PER_GRAM = 0.06   # in your currency, e.g. 0.06 = €0.06/gram
OVERHEAD_PER_MINI = 1.50     # fixed overhead per miniature (packaging, time, etc.)
INPUT_CSV = Path("stl_features.csv")
OUTPUT_CSV = Path("mini_pricing.csv")
```

Run the script via terminal:
```bash
python mini-pricing.py
```

and inspect the resulting `minipricing.csv` for a list of all your miniatures, with their total cost.


## MIT License

Copyright 2025 Nicola Mustone (<https://buthonestly.io>)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.