From 896e47c0c3d02762b9ded26bbefb5b3c2de94493 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20=C4=8Cejchan?= Date: Fri, 28 Nov 2025 15:46:16 +0100 Subject: [PATCH] Draft: Introduce `color_name` BFW-8775 --- data/main_fields.yaml | 20 ++++++-- docs_src/nfc_data_format.md | 34 ++++++++++++- tests/encode_decode/01_info.yaml | 9 +++- tests/encode_decode/02_info.yaml | 9 +++- tests/encode_decode/03_info.yaml | 8 +++- tests/encode_decode/04_info.yaml | 7 ++- tests/encode_decode/05_data.bin | Bin 0 -> 312 bytes tests/encode_decode/05_info.yaml | 76 ++++++++++++++++++++++++++++++ tests/encode_decode/05_input.yaml | 42 +++++++++++++++++ utils/opt_check.py | 62 +++++++++++++++++++++--- 10 files changed, 249 insertions(+), 18 deletions(-) create mode 100644 tests/encode_decode/05_data.bin create mode 100644 tests/encode_decode/05_info.yaml create mode 100644 tests/encode_decode/05_input.yaml diff --git a/data/main_fields.yaml b/data/main_fields.yaml index 7c2a477..2bce216 100644 --- a/data/main_fields.yaml +++ b/data/main_fields.yaml @@ -19,7 +19,7 @@ type: uuid description: - Universally unique identifier of the material. - - If not specified, can be deduced from `brand_uuid` + `material_name`. + - If not specified, can be deduced from `brand_uuid` + `material_name` + `color_name`. - See _UUID_ section for more details. - key: 3 @@ -81,16 +81,20 @@ - Coarse classification of the material. - Useful for determining default parameters for preheat an such that are not explicitly specified in the data. - If the material does not match any of the proposed material types, can be left unspecified. + - Also see Material naming guidelines. - key: 10 name: material_name type: string max_length: 31 - example: PC Blend Carbon Fiber Black + example: PC Blend Carbon Fiber required: recommended description: - Brand-specific material display string/identifier. - - In the UI, brand_name + material_name should be displayed together, for example "Prusament PLA Galaxy Black". + - In the UI, `brand_name` + `material_name` + `color_name` should be displayed together, for example "Prusament PLA Carbon Fiber Black". + - MAY contain color name as well (for example `PC Blend Carbon Fiber Black`), but it is recommended to store the color name separate in the `color_name` field. + - Defaults to `material_abbreviation` if not present. + - Also see Material naming guidelines. - key: 52 name: material_abbreviation @@ -183,6 +187,16 @@ unit: g description: Weight of the empty container. +- key: 57 + name: color_name + type: string + max_length: 32 + required: recommended + example: Galaxy Black + description: + - Display/brand/marketing name of the material color. + - Also see Material naming guidelines. + - key: 19 name: primary_color type: color_rgba diff --git a/docs_src/nfc_data_format.md b/docs_src/nfc_data_format.md index e6b0d33..993e688 100644 --- a/docs_src/nfc_data_format.md +++ b/docs_src/nfc_data_format.md @@ -109,7 +109,7 @@ If a brand decides to change name but wants to keep the original `brand_uuid` th 1. `brand_name = Pepament` (present in the data), `brand_uuid = ae5ff34e-298e-50c9-8f77-92a97fb30b0` (present in the data) -### 3.2.1 UUID derivation algorithm +#### 3.2.1 UUID derivation algorithm UUIDs are derived from the brand-specific IDs using UUIDv5 with the `SHA1` hash, as specified in [RFC 4122, section 4.3](https://datatracker.ietf.org/doc/html/rfc4122#section-4.3), according to the following table. 1. UUIDs are hashed in the binary form. 1. Strings are encoded as UTF-8. @@ -117,11 +117,13 @@ UUIDs are derived from the brand-specific IDs using UUIDv5 with the `SHA1` hash, 1. `+` represents binary concatenation. 1. NFC tag UID is represented as a bytestream with the MSB being the first byte in the bytestream. * **Important:** Various apps/readers report these UIDs in various byte orders, and sometimes as hex strings instead of bytestreams. For NFCV, the UID MUST be a 8 bytes long bytestream with `0xE0` as the **first** byte (SLIX2 then follows with `0x04, 0x01`). +1. If `material_name` is not present, it defaults to `material_abbreviation`, which in turn defaults to abbreviation of `material_type`. +1. The space between `material_name` and `color_name` SHALL be omitted if `color_name` is empty. | UID | Derviation formula | Namespace (`N`) | | --- | --- | --- | | `brand_uuid` | `N + brand_name` | `5269dfb7-1559-440a-85be-aba5f3eff2d2` | -| `material_uuid` | `N + brand_uuid + material_name` | `616fc86d-7d99-4953-96c7-46d2836b9be9` | +| `material_uuid` | `N + brand_uuid + material_name + [" " + color_name]` | `616fc86d-7d99-4953-96c7-46d2836b9be9` | | `package_uuid` | `N + brand_uuid + gtin` | `6f7d485e-db8d-4979-904e-a231cd6602b2` | | `instance_uuid` | `N + nfc_tag_uid` | `31062f81-b5bd-4f86-a5f8-46367e841508` | @@ -143,6 +145,12 @@ material_name = "PLA Prusa Galaxy Black" material_uuid = generate_uuid(material_namespace, brand_uuid.bytes, material_name.encode("utf-8")) print(f"material_uuid = {material_uuid}") +material_namespace = "616fc86d-7d99-4953-96c7-46d2836b9be9" +material_name = "PLA" +color_name = "Prusa Galaxy Black" +material_uuid = generate_uuid(material_namespace, brand_uuid.bytes, material_name.encode("utf-8"), " ".encode("utf-8"), color_name.encode("utf-8")) +print(f"material_uuid = {material_uuid}") + material_package_namespace = "6f7d485e-db8d-4979-904e-a231cd6602b2" gtin = "1234" material_package_uuid = generate_uuid(material_package_namespace, brand_uuid.bytes, gtin.encode("utf-8")) @@ -154,6 +162,28 @@ material_package_instance_uuid = generate_uuid(material_package_instance_namespa print(f"material_package_instance_uuid = {material_package_instance_uuid}") {% endpython %} +### 3.3 Material naming guidelines +The full material name is defined as `brand_name + " " + material_name + " " + color_name`. For some materials, it can be difficult to determine how to split the full name to the individual fields. It is recommended to follow these guidelines: +1. Material "families" (such as PolyLite or PolySonic from Polymaker) SHOULD be part of `material_name`. One company SHOULD generally have a single `brand_name` entry. + 1. __Note: This is to have a single `brand_uuid` for the brand__ +1. `material_name` SHOULD contain terms that affect primarily material physical properties, such as "high speed", "carbon fiber", "recycled" and so on. + 1. Case study: If the material name contains the "carbon fiber" term to indicate visual imitation without actually containing carbon fibers (should also be reflected by not having the `contains_carbon_fiber` tag), the term SHOULD be part of the `color_name` instead. +1. `color_name` SHOULD contain terms that affect primarily material visual properties, such as "matte", "silk", "glow", "rainbow" and individual color names. +1. If the separation between `material_name` and `color_name` is unclear or if the separation would break product name word order, `color_name` MAY be omitted and all terms (excluding brand name) MAY be stored in `material_name`. +1. Please note that the defaulting mechanics of `material_name` and `material_abbreviation` fields apply for both material name and UUID derivation. + +#### 3.3.1 Naming examples +| `brand_name` | `material_name` | `color_name` | `abbreviation` | Notes | +| - | - | - | - | +| Prusament | PLA | Prusa Galaxy Black | PLA | | +| Prusament | PC Blend Cabron Fiber | Black | PCCF | | +| Prusament | rPLA | Algae Pigment | rPLA | | +| Prusament | PETG V0 | Natural | PETGV0 | | +| Prusament | PLA Recycled | | rPLA | It is unclear whether "Recycled" stands for color or material name → defaulting everything to `material_name` | +| Polymaker | PolyLite PLA | White | PLA | +| Polymaker | PolySonic PLA | White | PLA | +| Polymaker | PolyLite Luminous PLA Rainbow | | PLA | "Luminous" should technically be a part of `color_name`, defaulting everything to `material_name` to preserve word order. | + ## 4. Meta section The meta section allows defining of region offsets (within the NDEF payload) and sizes. diff --git a/tests/encode_decode/01_info.yaml b/tests/encode_decode/01_info.yaml index 1bdbcae..73eec40 100644 --- a/tests/encode_decode/01_info.yaml +++ b/tests/encode_decode/01_info.yaml @@ -61,10 +61,15 @@ raw_data: aux: a000000000000000000000000000000000000000000000000000000000000000000000 uri: https://3dtag.org/s/334c54f088 opt_check: - warnings: [] + warnings: + - Missing recommended field 'color_name' errors: [] notes: [] - uuids: + deductions: + material_abbreviation: PLA + material_name: PLA Prusa Galaxy Black + extended_material_name: PLA Prusa Galaxy Black + full_material_name: Prusament PLA Prusa Galaxy Black brand_uuid: ae5ff34e-298e-50c9-8f77-92a97fb30b09 material_uuid: 1aaca54a-431f-5601-adf5-85dd018f487f package_uuid: 6e0aece2-1daf-5f2a-ba20-697968ec7d14 diff --git a/tests/encode_decode/02_info.yaml b/tests/encode_decode/02_info.yaml index e0184a8..4712405 100644 --- a/tests/encode_decode/02_info.yaml +++ b/tests/encode_decode/02_info.yaml @@ -57,10 +57,15 @@ raw_data: aux: a000000000000000000000000000000000000000000000000000000000000000000000 uri: https://3dtag.org/s/7ab2acb509 opt_check: - warnings: [] + warnings: + - Missing recommended field 'color_name' errors: [] notes: [] - uuids: + deductions: + material_abbreviation: PETG + material_name: PETG Jet Black + extended_material_name: PETG Jet Black + full_material_name: Prusament PETG Jet Black brand_uuid: ae5ff34e-298e-50c9-8f77-92a97fb30b09 material_uuid: 1378e978-35ed-534c-9dfa-a65525bf8649 package_uuid: 6f957b59-9725-5068-9102-15bb77807534 diff --git a/tests/encode_decode/03_info.yaml b/tests/encode_decode/03_info.yaml index 340f2c4..7f46223 100644 --- a/tests/encode_decode/03_info.yaml +++ b/tests/encode_decode/03_info.yaml @@ -58,6 +58,8 @@ uri: null opt_check: warnings: - Missing recommended field 'brand_name' + - Missing recommended field 'color_name' + - Failed to deduce 'full_material_name' errors: - 'Fields preheat_temperature (300), min_print_temperature (240): a <= b' - 'Fields preheat_temperature (300), max_print_temperature (210): a <= b' @@ -70,7 +72,11 @@ opt_check: - Failed to deduce material_uuid - Failed to deduce package_uuid notes: [] - uuids: + deductions: + material_abbreviation: PETG + material_name: PETG Jet Black + extended_material_name: PETG Jet Black + full_material_name: null brand_uuid: null material_uuid: null package_uuid: null diff --git a/tests/encode_decode/04_info.yaml b/tests/encode_decode/04_info.yaml index 2ed0e20..2746f94 100644 --- a/tests/encode_decode/04_info.yaml +++ b/tests/encode_decode/04_info.yaml @@ -62,11 +62,16 @@ uri: https://www.3dxtech.com/ opt_check: warnings: - Missing recommended field 'gtin' + - Missing recommended field 'color_name' - Missing recommended field 'preheat_temperature' errors: - Failed to deduce package_uuid notes: [] - uuids: + deductions: + material_abbreviation: PEKK-CF + material_name: CarbonX PEKK-A+CF15 Black + extended_material_name: CarbonX PEKK-A+CF15 Black + full_material_name: 3DXTech CarbonX PEKK-A+CF15 Black brand_uuid: 0d616a90-9d18-567b-92f9-ce471171f898 material_uuid: 09d4c3e3-f13c-5867-bee3-88eeccb48c6f package_uuid: null diff --git a/tests/encode_decode/05_data.bin b/tests/encode_decode/05_data.bin new file mode 100644 index 0000000000000000000000000000000000000000..8818827b44ab46b3daeab3e76cafbb5d9ceeb690 GIT binary patch literal 312 zcmaFppw7trpHY7zqj)HbaY{*Ix?X-!x_+^~v9U?AsY#lFg+-9e*TjN?oXq6JlFa-( z{j$6iz5IgIyn>?4yb_@Lg-jBc_OnPcFtA_vv)c71YZgK$2LmSqcV<9QX>nq1YF-JS zRL14w*99b*UkFMve-V;oln{2dwX>CwnJ@ldLiVT4Hwh()vl7Y@4<%G2R!OKzXh^6@ z*hr`g0T~(+nj#Wf5)KmD5+@{dBvK@FB}^nN<})z