OrcaSlicer/doc/developer-reference/filament_id.md

Filament IDs (filament_id)

filament_id identifies a material family: one commercial product line = one id, shared by all of that material's per-printer / per-nozzle variants. Devices use it to match a physical spool or tray to a filament preset. It is never per-color, per-printer, per-nozzle, or per-preset (per-preset identity is setting_id).

This page is the rule for authoring filament_id in system profiles (resources/profiles/**). CI enforces everything below; the short version is:

Important

Never write a filament_id value by hand. New families get their id from python scripts/assign_filament_ids.py; existing families already have one — inherit it.

Who consumes the id

Every device integration funnels a tray material id (tray_info_idx) through the same matching pipeline (PresetBundle::sync_ams_list and friends):

Ecosystem	Where the id comes from
Bambu AMS	device side (RFID / user tray setting) — the GF* catalog
Qidi box	built from device enums (QD_*); needs an exactly matching visible preset
Creality CFS	runtime brand/type scoring returns the current preset's id
Klipper (AFC / Happy Hare)	runtime lookup by filament type
Snapmaker	runtime color/vendor/type match

Tray-to-preset matching is printer-scoped, but several consumers match globally by id alone, first hit wins: tray display names, filament_is_support, vitrification warnings, and multi-nozzle filament grouping in the slicing pipeline. Two different materials sharing one id feed wrong data to those consumers even when the presets live in different vendors — so cross-material id sharing is never safe. Within one printer, duplicate ids silently break AMS matching (first match wins, the tray-edit dialog hides the second preset); the profile validator's -f check rejects this.

Do I need a new id? The one-question test

Would a user consider this a different spool product than anything already in the tree?

Different polymer, different sub-brand (Basic / Matte / Silk / HF), fiber-filled sibling, or a second selectable diameter → new family, new id. The same spool tuned for another printer or nozzle → join the existing family (inherit its @base, write no id key). Tuning a generic material → join the OrcaFilamentLibrary family (inherit Generic X @System, keep the Generic X base name, write no id key).

Situation	id
Per-printer / per-nozzle variant of an existing material	same id (inherit, never write the key)
Sub-brand or product line (PLA vs PLA Matte vs PLA Silk vs PLA HF)	new id each
Color	never a new id
Second diameter selectable on the same printer (1.75 + 2.85)	sibling family, new id
"High-speed" tuned for a different printer model	same id (it is a printer variant)
"High-speed" selectable alongside the normal preset on one printer	new id (it is a product line)

Structure rules

1. Only family roots carry the key. Root presets (any preset not marked "instantiation": "true", typically <Family> @base with "instantiation": "false") declare filament_id; instantiated variants inherit a root and never write the key. A family may have several roots (e.g. per-series bases) — all of them must declare the identical id.
2. The family name is the base name: the preset name with everything from the first (optionally space-preceded) @ stripped. MyBrand PLA @Orca 3D Fuse1 and MyBrand PLA@HS both belong to family MyBrand PLA.
3. Within a family, variants' compatible_printers are pairwise disjoint — per printer preset, at most one compatible instantiated preset per id. The C++ validator (-f) enforces this.
4. Generics belong to OrcaFilamentLibrary. A vendor tuning a generic material inherits Generic X @System, keeps the Generic X base name (that alias is what hides the library preset on your printers), sets a non-empty compatible_printers, and writes no id key. A vendor-branded filament never rides a generic family id.
5. Ids are immutable once shipped. Renaming a family does not change its id — use renamed_from. A shipped id is never recycled for a different material: old ids live on in user presets and 3mf files and a recycled id would silently match the wrong material.

Minting — nobody invents ids

New ids are deterministic, computed exactly like the setting_id precedent (scripts/assign_vendor_setting_ids.py):

FILAMENT_ID_NAMESPACE = uuid5(setting-id NAMESPACE, "filament_id")
                      = c4d3ff49-4c32-5534-a3e3-00894157ab97
filament_id = "OF" + base62_6( uuid5(FILAMENT_ID_NAMESPACE, "filament_family/<vendor>/<family>") )

base62_6 is the low 6 base62 digits (alphabet 0-9A-Za-z) of the UUID taken as a big-endian integer, most-significant digit first — 8 chars total, within the AMS length limit. <vendor> is the vendor bundle name (the stem of the vendor index json, e.g. Qidi, OrcaFilamentLibrary); <family> is the family base name. On the rare collision with any existing or retired id, the minter salts the input (…/1, …/2, …) until free and the result is frozen in the file. Example: family MyBrand PLA in vendor Orca 3D mints OFvCEY5V.

Workflow for a new family:

# 1. Author the family with NO filament_id key anywhere.
python scripts/assign_filament_ids.py                    # 2. mint + insert ids into the family root(s)
python scripts/assign_filament_ids.py --update-snapshot  # 3. record the new claims in the ledger
python scripts/assign_filament_ids.py --check            # 4. verify — the same checks CI runs
# 5. Commit the profile edits together with scripts/filament_id_snapshot.json.

--mint "Vendor/Family" prints the id for one family without touching anything. The default run is idempotent and never rewrites a valid existing id.

If you skip the tooling, CI fails and prints the remedy: the expected id for your family, and the instruction to run python scripts/assign_filament_ids.py --update-snapshot and commit the resulting diff.

Reserved namespaces — never mint or hand-write into

Space	Owner	Rule
GF*	Bambu AMS/RFID catalog	BBL vendor only; byte-copies elsewhere only where the snapshot already sanctions them
QD_*	Qidi device protocol	frozen device contract; Qidi vendor only
P + 7 hex chars (case-insensitive), "null"	user-created custom filaments (CreatePresetsDialog.cpp)	never appears in system profiles
every already-shipped id	grandfather snapshot	frozen as-is; new claims need maintainer sign-off
every retired id	scripts/retired_filament_ids.json	never used again, for anything

How CI enforces this

Profile CI (check_profiles.yml → scripts/orca_extra_profile_check.py) runs check_filament_ids() tree-wide. Its ground truth is scripts/filament_id_snapshot.json — the sanctioned state: the id state derived from the tree must equal the snapshot exactly, in both directions. Any change to the id landscape therefore surfaces as a diff to that file, and that snapshot diff is what maintainers review and gate in a PR. Never edit the snapshot by hand — --update-snapshot regenerates it deterministically (running it twice changes nothing).

The checks, in brief:

• Format — every id is either in the snapshot, OF + 6 base62 chars, BBL's, or Qidi QD_*.
• Snapshot equality — tree claims == snapshot claims, both directions.
• Mint conformance — a non-grandfathered OF* claim must equal the mint (or a salt iteration) of its (vendor, family); the error prints the expected id.
• Retired reuse — any tree id present in scripts/retired_filament_ids.json is an error. Ids that fully vanish from the tree are appended there by --update-snapshot; the file is append-only.
• Alias hygiene — a tuned generic must keep the library preset's base name and a non-empty compatible_printers (structure rule 4); the error names the rename as the cause.
• Reserved namespaces — GF* outside BBL, QD_* outside Qidi, P<7-hex> or null anywhere, unless that exact claim is grandfathered in the snapshot.
• Structure — no filament_id key on instantiated presets; no declared-vs-inherited id drift; every instantiated system filament must resolve an effective id through its inherits chain (an id-less one is a hard load error in C++ that discards the whole vendor bundle).

Sharing a reserved-catalog id with a new family or vendor (e.g. shipping a Bambu-cataloged product under another vendor with its authentic GF* id) is refused by --update-snapshot unless you pass --allow-shared-catalog — and it still lands in the snapshot diff for maintainer review. Any other new sharing of an existing id is caught by the mint-conformance check instead.

FAQ

• A new color of an existing product? Never a new id — colors are not families.
• A second diameter (1.75 mm and 2.85 mm) of the same product? A sibling family with its own id: two diameters are separately selectable spool products.
• A high-speed tune of an existing material for another printer model? Same family: inherit the family's root, write no id key.
• A tuned generic ("our profile for Generic PLA")? Inherit Generic PLA @System, keep the Generic PLA base name, set compatible_printers, write no id key.
• I need to rename a family. Keep the id, add renamed_from. Ids never change.
• CI says my family needs an id. Run python scripts/assign_filament_ids.py, then --update-snapshot, and commit both diffs. Do not type an id by hand.

For general profile authoring, see the profile development guide on the OrcaSlicer wiki.