Metadata-Version: 2.4
Name: fatcat-metadata
Version: 0.1.0
Summary: C++ metadata and project-settings composition for slicer 3MF projects
License-Expression: AGPL-3.0-only
License-File: COPYRIGHT.md
License-File: LICENSE
License-File: NOTICE.md
License-File: licenses/third-party/nlohmann-json/LICENSE.MIT
License-File: licenses/third-party/pybind11/LICENSE
License-File: licenses/third-party/slicer-profiles/anycubic-slicer-next/LICENSE.txt
License-File: licenses/third-party/slicer-profiles/bambu-studio/LICENSE
License-File: licenses/third-party/slicer-profiles/elegooslicer/LICENSE.txt
License-File: licenses/third-party/slicer-profiles/flash-studio/LICENSE.txt
License-File: licenses/third-party/slicer-profiles/orcaslicer/LICENSE.txt
License-File: licenses/third-party/slicer-profiles/prusaslicer/LICENSE
License-File: licenses/third-party/slicer-profiles/qidi-studio/LICENSE
License-File: licenses/third-party/slicer-profiles/snapmaker-orca/LICENSE.txt
License-File: licenses/third-party/tinyxml2/LICENSE.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Project-URL: Homepage, https://github.com/MOVIBALE/fatcat-metadata
Project-URL: Documentation, https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/API.md
Project-URL: Issues, https://github.com/MOVIBALE/fatcat-metadata/issues
Requires-Python: <3.15,>=3.12
Provides-Extra: examples
Requires-Dist: neroued-3mf==0.4.0; extra == "examples"
Description-Content-Type: text/markdown

# FatCat Metadata

[![CI](https://github.com/MOVIBALE/fatcat-metadata/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/MOVIBALE/fatcat-metadata/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/fatcat-metadata)](https://pypi.org/project/fatcat-metadata/)
[![License: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-blue.svg)](https://github.com/MOVIBALE/fatcat-metadata/blob/main/LICENSE)
![C++17](https://img.shields.io/badge/C%2B%2B-17-blue.svg)
![Python 3.12–3.14](https://img.shields.io/badge/Python-3.12%E2%80%933.14-blue.svg)

**Native slicer settings and 3MF metadata for your own model generator.**

FatCat Metadata is a C++17 library with Python bindings. It resolves native
printer, process and material profiles, composes final project settings, and
describes the metadata a 3MF writer needs for a selected slicer.
It can be used independently of Lumina or any other application.

[English](https://github.com/MOVIBALE/fatcat-metadata/blob/main/README.md) · [简体中文](https://github.com/MOVIBALE/fatcat-metadata/blob/main/README_CN.md) · [API guide](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/API.md) · [Examples](https://github.com/MOVIBALE/fatcat-metadata/tree/main/cpp/examples/python_neroued_consumer/) · [Report an issue](https://github.com/MOVIBALE/fatcat-metadata/issues)

**Start here:** [first result, command-line usage and complete 3MF example](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/FIRST_USE.md).
Use it to discover native choices, generate a model without Lumina, preserve
user-project tuning, or compose merged material slots through the same core.

## See the same custom process in seven slicers

One 20 mm cube, one shared process JSON, and eight target-specific exports:
OrcaSlicer with Bambu A1 mini/P1S, Bambu Studio with P1S, and five other native
slicers. The installed example changes layer height, widths, walls, shells,
gyroid infill and brim settings. Each shown project was actually opened and
sliced in the application; the animation uses enlarged GUI keyframes and
compresses waiting time.

![Custom process metadata opened and sliced in seven native applications](https://raw.githubusercontent.com/MOVIBALE/fatcat-metadata/main/docs/images/custom-process-slicers.gif)

[Reproduce the exports and read the observed results](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/SHOWCASE.md).
All eight representative projects sliced successfully. Bambu/Snapmaker import
notices and QIDI/Anycubic plate-label differences are recorded there. This is
evidence for the listed combinations, rather than all printers or physical
print quality. A separate 3MF is composed for each target.

## Project status

The first PyPI release is **0.1.0**, an early public SDK. Install a matching
prebuilt wheel using the command below. Source users should pin an exact commit;
a published version is fixed and is not replaced with later development code.

| Language | Current entry point |
| --- | --- |
| C++17 | Standalone static library, public headers and an installable CMake SDK; Python is not required. |
| Python 3.12–3.14 | Compiled bindings to the same C++ core, dictionary/JSON APIs and editor type hints. |
| Other languages | No shipped C ABI or language bindings yet. A bridge to the C++ core is required. |

## What it provides

- Native profile selection by exact slicer version, printer, nozzle, material and build plate.
- Resolution of profile inheritance and includes from bundled upstream JSON snapshots.
- Composition of native projects, user-supplied project settings and merged material slots.
- Preservation of source material identity, temperatures, flow, unknown project fields and recorded provenance.
- Slicer-specific metadata parts, content types, relationships and root-model descriptions for a writer.
- An optional Neroued adapter and independent Python/C++ examples.

## How it fits into a generator

```mermaid
flowchart LR
    G[Your generator] -->|Target, materials and model facts| F[FatCat Metadata]
    G -->|Meshes, object IDs and placement| W[3MF writer]
    F -->|Final settings and metadata description| W
    W --> P[3MF project]
```

Your generator owns geometry, material choices and placement. FatCat owns
profile selection and metadata composition. The writer assembles and writes
the archive. Metadata uses the writer's real object IDs and material indices;
images and other binary resources remain caller-supplied.

Neroued is optional: the core package has no Neroued runtime dependency, and
another writer can consume the metadata description. FatCat does not perform
slicing or send print jobs.

## Supported slicer snapshots

These are the exact versions currently bundled with the library:

| Application | `slicer_id` | Version |
| --- | --- | --- |
| Bambu Studio | `BambuStudio` | `02.08.02.61` |
| OrcaSlicer | `OrcaSlicer` | `2.4.2` |
| QIDI Studio | `QIDIStudio` | `02.07.02.60` |
| ElegooSlicer | `ElegooSlicer` | `1.5.3.5` |
| Anycubic Slicer Next | `AnycubicSlicerNext` | `2.0.0.3` |
| Flash Studio | `FlashStudio` | `1.7.18` |
| Snapmaker Orca | `SnapmakerOrca` | `2.4.0` |
| PrusaSlicer (preview) | `PrusaSlicer` | `3.0.0-alpha12` |

The [target manifest](https://github.com/MOVIBALE/fatcat-metadata/blob/main/compatibility/current-src/translations/supported-targets.json)
is the authoritative version list. Unknown targets and incompatible selections
are rejected. A supported slicer does not imply every printer/nozzle/material/plate
combination is available; inspect its native source catalogue.

The seven stable snapshots were checked against official macOS downloads on
2026-10-06. PrusaSlicer is an explicitly supported preview, checked on 2026-10-07;
its new native project format is separate from PrusaSlicer 2.x. Anycubic's Linux 2.0.0.5 build
is a different release and is not claimed by the macOS 2.0.0.3 snapshot.

Explicit [process settings](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/PROCESS_SETTINGS.md) use a discoverable contract:
known equivalents are normalized, target array formats are respected, and
unknown or unsupported inputs raise actionable errors. The seven stable targets cover 38 fields,
not every slicer feature or every interaction between settings.
Use `fatcat fields --slicer BambuStudio` or Python `list_native_fields` to inspect
versioned native evidence and process coverage. Missing SDK support is reported
separately from an excluded native enum token; absent fields remain unverified.

Some combinations use explicitly recorded historical sources. OrcaSlicer 2.4.2
U1 0.4 mm, for example, uses a recorded 2.2.4 process and textured-plate material.
The result identifies their actual versions. See [compatibility notes](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/COMPATIBILITY.md).

### PrusaSlicer 3 preview

The SDK composes native `Metadata/PrusaSlicer3_project.json` from Prusa's own
configuration exports. Its catalogue contains 32 default-nozzle FFF hardware
selections, including MK4S, CORE One, MINI, MMU and XL. A single nozzle with MMU
material slots and multiple independent tools retain their distinct native
configuration structures. Native process overrides and per-material temperature
and flow settings use the exact application's schema.

```bash
fatcat catalog --slicer PrusaSlicer
python -m fatcat_metadata_examples.prusa --machine prusa:mk4s --output prusa.3mf
```

The complete example requires the optional Neroued writer. MK4S, MK4S + MMU3
and XL 5T samples were opened and sliced in the actual alpha12 GUI. This does
not establish every catalogue combination or physical print quality. See the
[Prusa guide](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/PRUSA.md) for configuration imports, aliases and limits.

## Python quick start

### Install from PyPI

Use 64-bit CPython 3.12, 3.13 or 3.14 on Windows AMD64, macOS 14+ Apple Silicon,
or Linux x86_64 with glibc 2.28+. Pip selects the matching precompiled extension
and native command. The option below prevents an unexpected source build on
unsupported platforms; installing a matching wheel requires no C++ compiler.

```bash
python -m pip install --only-binary=:all: fatcat-metadata==0.1.0
fatcat --version
fatcat catalog
```

For the complete 3MF examples, install `fatcat-metadata[examples]==0.1.0` instead.
The optional extra adds Neroued; the metadata core remains usable on its own.
Downloads are also available on the [PyPI files page](https://pypi.org/project/fatcat-metadata/0.1.0/#files).
Alpine/musl, Intel Macs, Windows ARM and free-threaded Python have no prebuilt
wheel in this release. Building from source requires a compatible toolchain.
Read the [distribution guide](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/DISTRIBUTIONS.md) for build and publishing details.

The [installed cube example](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/FIRST_USE.md#generate-a-complete-3mf--生成完整-3mf)
was opened and sliced in the pinned Bambu Studio version:

![Installed cube, A1 mini and real slicing preview](https://raw.githubusercontent.com/MOVIBALE/fatcat-metadata/main/docs/images/first-use-preview.png)

This demonstrates one example's settings and toolpaths. It does not establish
all printer combinations or physical print quality.

No installed slicer is needed. Query choices before composing settings:

```bash
fatcat choices --slicer BambuStudio --application-version 02.08.02.61 \
  --machine bambu-lab:a1-mini --nozzle nozzle:0.4mm --plate plate:textured-pei
```

### Compose native project settings

```python
import fatcat_metadata as fatcat

result = fatcat.compose_project_settings({
    "project_source": "fatcat_native",
    "slicer_id": "BambuStudio",
    "application_version": "02.08.02.61",
    "machine_uid": "bambu-lab:a1-mini",
    "nozzle_uid": "nozzle:0.4mm",
    "build_plate_uid": "plate:textured-pei",
    "source_materials": [
        {"name": "Bambu PLA Basic", "material_type": "PLA Basic", "colour": "#E63946"}
    ],
})
project = result["project_settings"]
```

Supply the final dictionary and your real model facts to
`compose_model_metadata(project, model_request)` for the writer-facing description.
For a user-provided project, use `compose_project_settings(source_project, request)`.
Existing JSON-string calls remain supported. See the [API guide](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/API.md)
for both request contracts.

### Write a complete example 3MF

Install the optional writer and run the example shipped by the wheel, without
cloning this repository:

```bash
python -m pip install 'neroued-3mf==0.4.0'
python -m fatcat_metadata_examples.minimal --output fatcat-cube.3mf
```

The [minimal example](https://github.com/MOVIBALE/fatcat-metadata/blob/main/cpp/examples/python_neroued_consumer/minimal.py) shows
settings composition, real geometry/ID creation, metadata application and one
archive write. It uses Neroued's public core assembly layout. The
[complete guide](https://github.com/MOVIBALE/fatcat-metadata/blob/main/cpp/examples/python_neroued_consumer/README.md) covers custom
sources, U1 compatibility and writer requirements for optional external
production-model layouts.

### Build from source

Source builds require a C++17 toolchain, CMake 3.18+ and Python 3.12–3.14.
The build fetches pinned JSON/XML dependencies if suitable system packages are
absent. Check out the reviewed full SHA for a reproducible integration.

```bash
git clone https://github.com/MOVIBALE/fatcat-metadata.git
cd fatcat-metadata
python -m pip install .
```

Use source builds for unsupported platforms or expired download artifacts.

All current builds are version 0.1.0. Inspect the installed build with:

```python
import fatcat_metadata as fatcat

print(fatcat.__version__)
print(fatcat.__source_revision__)
print(fatcat.__source_dirty__)
```

The revision identifies the actual build checkout; PR CI may use a merge
revision. Git-free archives report `"unknown"` and `None` unless their packaging
workflow supplies build provenance. See the [distribution guide](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/DISTRIBUTIONS.md).
These build fields
are separate from the selected profiles' provenance.

## Standalone C++ SDK

Build and install the core without Python. Replace the installation prefix
below with an absolute path on your machine:

```bash
cmake -S cpp -B build-sdk -DCMAKE_BUILD_TYPE=Release \
  -DFATCAT_BUILD_PYTHON=OFF -DFATCAT_BUILD_TESTS=OFF -DFATCAT_INSTALL_CPP=ON
cmake --build build-sdk --config Release --parallel
cmake --install build-sdk --config Release --prefix /absolute/path/to/fatcat-sdk
```

Point your CMake project's `CMAKE_PREFIX_PATH` at that installation, then link
your existing `my_generator` target:

```cmake
find_package(FatCatMetadata 0.1.0 CONFIG REQUIRED)
target_link_libraries(my_generator PRIVATE FatCatMetadata::Core)
```

Pass `FatCatMetadata_DATA_DIR` to the public composition APIs; the library
resolves its internal profile/target paths. System JSON/XML packages used to
build the SDK must also be available to the consumer. Python wheels do not
include this C++ development SDK. See the [C++ guide](https://github.com/MOVIBALE/fatcat-metadata/blob/main/cpp/README.md) and
[external CMake consumer](https://github.com/MOVIBALE/fatcat-metadata/tree/main/cpp/examples/out_of_tree_consumer/) for complete examples.

## Data and validation

Native profiles are bundled JSON snapshots from the listed slicer releases.
Normal calls read that packaged data; they do not query installed slicers or
download profiles at runtime. Upstream files retain their original content and
inheritance relationships. Library-maintained target contracts and source
indices are separate from those raw profiles.

CI checks C++ Debug/Release builds, Python wheel installation, composition,
independent consumers and generated archive structure on Windows, Linux and
macOS. Native GUI opening/slicing and physical printer behavior require separate
acceptance. See [validation scope](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/VALIDATION.md) for what each check establishes.

## Documentation and repository layout

| Guide | Purpose |
| --- | --- |
| [API](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/API.md) | Settings/metadata requests, dictionary and JSON calls, and build provenance. |
| [First result](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/FIRST_USE.md) | Installed CLI, choice discovery and the complete cube example. |
| [Custom process showcase](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/SHOWCASE.md) | Seven-slicer GUI montage, editable process JSON and eight reproducible exports. |
| [Distributions](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/DISTRIBUTIONS.md) | PyPI installation, portable builds, Trusted Publishing and source/hash receipts. |
| [Python examples](https://github.com/MOVIBALE/fatcat-metadata/blob/main/cpp/examples/python_neroued_consumer/README.md) | Complete independent generator and optional writer integration. |
| [C++ SDK](https://github.com/MOVIBALE/fatcat-metadata/blob/main/cpp/README.md) | Source builds, installation and downstream CMake consumption. |
| [Compatibility](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/COMPATIBILITY.md) | Historical profiles and unavailable combinations. |
| [Maintenance](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/MAINTAINERS.md) | Updating snapshots, target bindings and source provenance. |
| [Validation](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/VALIDATION.md) | Automated checks and separate native GUI acceptance. |

```text
cpp/            C++ core, public headers, Python bindings and examples
python/         Optional Neroued adapter and Python type signatures
compatibility/  Native profile snapshots, source indices and target contracts
scripts/        Source refresh and installed-package checks
docs/           API, compatibility, maintenance and validation guides
licenses/       Third-party license texts and source manifest
```

## Contributing

Use [Issues](https://github.com/MOVIBALE/fatcat-metadata/issues) for bug reports
and feature proposals, and submit pull requests against `main`. Include the
library source revision, OS, exact slicer version, printer/nozzle/material/plate
selection and a minimal input in reports. Remove private geometry and customer
data before sharing a reproduction.

Keep public interfaces compatible, adopt new helpers in a real consumer and
document behavior changes. Profile updates need exact upstream sources and
license records: follow the [maintenance guide](https://github.com/MOVIBALE/fatcat-metadata/blob/main/docs/MAINTAINERS.md). Existing
build/check commands are in the [C++ guide](https://github.com/MOVIBALE/fatcat-metadata/blob/main/cpp/README.md) and
[CI workflow](https://github.com/MOVIBALE/fatcat-metadata/blob/main/.github/workflows/ci.yml). Record actual application versions and
GUI outcomes separately from CI results.

## License

Original FatCat code is licensed under **AGPL-3.0-only**; see [LICENSE](https://github.com/MOVIBALE/fatcat-metadata/blob/main/LICENSE).
Third-party profile data and dependencies retain their respective licenses.
Their sources and notices are recorded in [NOTICE.md](https://github.com/MOVIBALE/fatcat-metadata/blob/main/NOTICE.md) and the
[third-party manifest](https://github.com/MOVIBALE/fatcat-metadata/blob/main/licenses/third-party/manifest.json).
[COPYRIGHT.md](https://github.com/MOVIBALE/fatcat-metadata/blob/main/COPYRIGHT.md) explains copyright ownership and separate licensing
terms for original code. Neroued is a separate project with its own terms.
