Metadata-Version: 2.4
Name: scadbatch
Version: 2.0.0rc1
Summary: Batch export models from parametric OpenSCAD designs using CSV or Customizer JSON parameter sets.
Author-email: "Cameron K. Brooks" <cambrooks3393@gmail.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/CameronBrooks11/scadbatch
Project-URL: Issues, https://github.com/CameronBrooks11/scadbatch/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# scadbatch

This repository provides a tool to automate the export of STL models from OpenSCAD using CSV or JSON files of parameters. It offers a simple and user-friendly solution for batch exporting models with different parameter sets and includes a graphical user interface (GUI) for ease of use. Inspired by:

[18107/OpenSCAD-batch-export-stl](https://github.com/18107/OpenSCAD-batch-export-stl)

[OutwardBuckle/OpenSCAD-Bulk-Export](https://github.com/OutwardBuckle/OpenSCAD-Bulk-Export)

## Features

- Batch export STL, 3MF, OFF, PNG and any other format OpenSCAD can write, with parameters defined in CSV or JSON files.
- Convert between CSV and JSON parameter files.
- Easy-to-use command-line interface and GUI.
- Handles boolean, numeric, and string parameter types correctly.
- Supports advanced selection options for parameter sets.
- Includes multiple example projects to get started.
- Tested and validated on a number of test cases.

## Quick Start

For easy usage, simply click on the **Releases** section on the right-hand side of the GitHub page and download the appropriate binary for your operating system (e.g., `.exe` for Windows, or equivalent for macOS and Linux). Install and start using the tool right away!

## Requirements

- Python 3.10 or later.
- OpenSCAD installed and added to your system PATH.

## Installation

### From Source

1. **Clone the repository:**

    ```
    git clone https://github.com/CameronBrooks11/scadbatch.git
    ```

    ```
    cd scadbatch
    ```

2. **Install the Python library:**

    ```
    pip install .
    ```

3. **Ensure OpenSCAD is installed and accessible from the command line. Add it to your PATH if necessary.**

4. **If you encounter the following warning:**

    ```
    WARNING: The script scadbatch.exe is installed in 'C:\Users\<YourUserName>\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.11_<somenumbers>\LocalCache\local-packages\Python311\Scripts' which is not on PATH.
    Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.
    ```

    **You can resolve it by adding the directory returned by:**

    ```
    python -m site --user-base
    ```

    **Append the Scripts subdirectory of the output path to your system's PATH. For example:**

    ```
    C:\Users\<YourUserName>\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.11_<somenumbers>\LocalCache\local-packages\Python311\Scripts
    ```

5. **To modify the tool, reinstall it after making changes:**

    ```
    pip install --upgrade .
    ```

## Usage

Once installed, the tool can be called from anywhere using the `scadbatch` command. (It was called `openscad-export` before; that name still works and will be removed after v2.0.) The tool provides three primary modes:

1. **Export STL Files**
2. **Convert CSV to JSON**
3. **Convert JSON to CSV**

### Using the GUI

Launch the graphical interface for an intuitive way to configure and perform batch exports. Run the following command:

```
scadbatch gui
```

From the GUI, you can:

- Select your `.scad` file, parameter file (CSV or JSON), and output folder.
- Configure export settings like format, selection range, and sequential processing.
- Monitor progress and view logs of the operation.
- Convert between CSV and JSON parameter files.

### Using the CLI

#### 1. Export STL Files

Export STL files using either a CSV or JSON parameter file.

**Command Structure:**

```
scadbatch export <scad_file> <parameter_file> <output_folder> [--openscad-path PATH] [--format EXT ...] [--export-format asciistl|binstl] [--select SELECTION] [-j N] [--skip-existing | --overwrite] [--dry-run] [--timeout SECONDS] [--summary PATH.json] [--name-template TEMPLATE] [--encoding NAME]
```

**Parameters:**

- `<scad_file>`: Path to the OpenSCAD `.scad` file.
- `<parameter_file>`: Path to the CSV or JSON file containing parameters. A JSON file is an OpenSCAD Customizer parameter-set file and is handed to OpenSCAD natively (`-p FILE -P SET`, OpenSCAD 2019.05+), so each value is typed by the model's own default and keys missing from a set keep the model's defaults; the CSV conventions below (quote-wrapping to force a string, `undef`) do not apply, OpenSCAD reads the values itself. CSV rows are passed as `-D` flags. A case never gets both.
- `<output_folder>`: Directory where STL files will be saved.

**Options:**

- `--openscad-path`: Path to the OpenSCAD executable. If omitted, `$OPENSCAD` is used, then `openscad` on PATH, then the platform's default install location (`C:\Program Files\OpenSCAD` on Windows, `/Applications/OpenSCAD.app` on macOS).
- `--format EXT`: Output format by file extension, as OpenSCAD's `-o` accepts it (`stl`, `off`, `3mf`, `png`, `csg`, ... — a format the detected OpenSCAD does not advertise in its `--help` is warned about; one it really cannot write fails per case with OpenSCAD's own message). Repeat the flag to export every case in several formats. Defaults to `stl`.
- `--export-format`: STL flavour, `asciistl` or `binstl`. Defaults to `binstl`. Only applies to `stl`.
- `--camera`, `--imgsize`, `--colorscheme`: passed straight to OpenSCAD for `png` output, e.g. `--format png --imgsize 1024,768 --camera 0,0,0,55,0,25,140`. OpenSCAD 2021.01 needs a display to render PNG (`xvfb-run scadbatch ...` on a headless Linux box); current builds render offscreen.
- `-j N`, `--jobs N`: run up to N OpenSCAD processes at once. Defaults to the number of CPUs. Ctrl-C stops the running renders and abandons the rest. (`--sequential` is a deprecated alias for `--jobs 1`.)
- `--skip-existing`: leave a case alone when its output file already exists, and say so in the summary. The default (`--overwrite`) re-exports everything.
- `-n`, `--dry-run`: print the OpenSCAD command for every case and run nothing; no files or folders are created.
- `--timeout SECONDS`: kill a case that runs longer than this; it is recorded as timed out and the batch continues.
- `--summary PATH.json`: write a machine-readable record of the run — OpenSCAD path and version, the inputs, and for every case its status (`ok`, `failed`, `timeout`, `skipped`, `dry-run`), return code, duration, OpenSCAD message lines (`WARNING:`, `ECHO:`, `ERROR:`, `EXPORT-WARNING:`, ...) and the exact command line, plus the tool version and a UTC timestamp. Written for failed and dry runs too, so CI can check it in; the directory is created if needed.
- `--name-template TEMPLATE`: how to name output files (without extension). Fields: `{name}` (the Customizer set name or `exported_filename`, else `model_<index>`), `{index}`, and any parameter, e.g. `{name}_d{diameter}` or `part_{index:03d}`. Names are always made filesystem-safe (`lid/large` becomes `lid_large`; the original set name still goes to OpenSCAD), and two cases producing the same file name are refused before anything runs.
- `--encoding NAME`: text encoding of the parameter file. Defaults to UTF-8, tolerating the byte-order mark Excel writes; pass e.g. `cp1252` for a spreadsheet export that is not UTF-8. Files this tool writes are always UTF-8.
- `--select SELECTION`: Select specific parameter sets to export using indices and ranges. Format examples: `'0-5'`, `'1-3,7,10-12'`, `'2,4'`. Indices are zero-based.

**Examples:**

- **Export with CSV:**

    ```
    scadbatch export examples/simpleCube/simpleCube.scad examples/simpleCube/simpleCube.csv output
    ```

- **Selective Export:**

    Export parameter sets from index 0 to 5:

    ```
    scadbatch export examples/candleStand/candleStand.scad examples/candleStand/candleStand.csv output --select "0-5"
    ```

- **Export from JSON:**

    Convert CSV to JSON first:

    ```
    scadbatch csv2json examples/simpleCube/simpleCube.csv examples/simpleCube/simpleCube.json
    ```

    Then, export using the JSON file:

    ```
    scadbatch export examples/simpleCube/simpleCube.scad examples/simpleCube/simpleCube.json output
    ```

#### 2. Convert CSV to JSON

Convert a CSV parameter file to JSON format compatible with OpenSCAD's customizer.

**Command Structure:**

```
scadbatch csv2json <csv_file> <json_file> [--encoding NAME]
```

Values are read with the same rules the exporter uses, so a cell means the same thing either way. A vector is stored as an OpenSCAD literal in a string, because OpenSCAD ignores a JSON array; nested vectors, ranges and `undef` are warned about, since current OpenSCAD builds ignore those in a parameter-set file and keep the model's default (export the CSV directly to apply them).

**Example:**

```
scadbatch csv2json examples/candleStand/candleStand.csv examples/candleStand/candleStand.json
```

#### 3. Convert JSON to CSV

Convert a JSON parameter file back to CSV format.

**Command Structure:**

```
scadbatch json2csv <json_file> <csv_file> [--encoding NAME]
```

**Example:**

```
scadbatch json2csv examples/sign/sign.json examples/sign/sign_converted.csv
```

## CSV File Structure

- The CSV file should have a header row with parameter names.
- Each subsequent row defines a set of parameters for the OpenSCAD model.
- An `exported_filename` column names the output files; without it files are named `model_<index>`, or use `--name-template`. Names are made filesystem-safe automatically, and two rows may not share a name.
- Files are read as UTF-8 (a byte-order mark is tolerated) and written as UTF-8. For a spreadsheet export in another encoding, pass `--encoding`; note that Excel's "Unicode text" export is UTF-16 **and tab-separated**, which this tool does not read — save as "CSV UTF-8" instead.

**Example CSV file (`simpleCube.csv`):**

| exported_filename | depth | height | width |
|-------------------|-------|--------|-------|
| cube_small        | 10    | 10     | 10    |
| cube_medium       | 20    | 20     | 20    |
| cube_large        | 30    | 30     | 30    |

## JSON File Structure

The JSON file should follow the structure used by OpenSCAD's customizer profiles. It should contain a `parameterSets` object, where each key is the `exported_filename` and its value is a dictionary of parameters.

**Example JSON file (`simpleCube.json`):**

```
{
    "parameterSets": {
        "cube_small": {
            "width": "10",
            "height": "10",
            "depth": "10"
        },
        "cube_medium": {
            "width": "20",
            "height": "20",
            "depth": "20"
        },
        "cube_large": {
            "width": "30",
            "height": "30",
            "depth": "30"
        }
    },
    "fileFormatVersion": "1"
}
```

## OpenSCAD File Structure

The OpenSCAD file must define a model that uses parameters from the parameter file. For example:

**Example OpenSCAD file (`simpleCube.scad`):**

```
module model() { cube([width, height, depth]); }
```

## Example Files

The `examples/` directory contains multiple projects demonstrating how to use the exporter with different OpenSCAD models.

### 1. Simple Cube

A basic example of a customizable cube with varying dimensions.

**Files:**

- `examples/simpleCube/simpleCube.scad`
- `examples/simpleCube/simpleCube.csv`
- `examples/simpleCube/simpleCube.json`

### 2. Candle Stand

A more complex model featuring a candle stand with options for customization from the [OpenSCAD Parametric Examples](https://github.com/openscad/openscad/tree/master/examples/Parametric).

**Files:**

- `examples/candleStand/candleStand.scad`
- `examples/candleStand/candleStand.csv`
- `examples/candleStand/candleStand.json`

### 3. Sign

A customizable sign with adjustable message, size, and resolution parameters from the [OpenSCAD Parametric Examples](https://github.com/openscad/openscad/tree/master/examples/Parametric).

**Files:**

- `examples/sign/sign.scad`
- `examples/sign/sign.csv`
- `examples/sign/sign.json`

## Contributing

Contributions are welcome! Please open an issue or submit a pull request with improvements or suggestions.

## License

This project is licensed under the AGPL v3 License. See the LICENSE file for details.
