skppy.parser.material_parser

Parser for the materials section (tag 0x01F7) of model.dat.

Combines:

  • Binary TLV records (identity, name, and record context)

  • material.xml files from the ZIP archive (color, texture, PBR fields)

Edge Cases and Known Strategies

Windows-encoded ZIP filenames (CP437 mojibake)

SKP files saved on Windows may store non-ASCII material folder names with their raw UTF-8 bytes un-flagged. Python’s zipfile module falls back to CP437 when the UTF-8 flag is absent, producing mojibake filenames. build_zip_name_map builds a {utf8-corrected -> stored} lookup so that _zip_read can find entries by their intended Unicode name regardless of how they were stored.

Missing material.xml

Not all materials have an accompanying material.xml (e.g. default colours created programmatically, or very old SKP files). When the XML entry is absent, appearance remains at neutral public defaults; colour uses neutral grey and texture image data remains absent. A DEBUG log message is emitted and parsing continues.

XML namespace variance

SketchUp’s material.xml uses a Google namespace (http://sketchup.google.com/schemas/sketchup/1.0/material). Some files produced by third-party tools omit the namespace prefix. All root.find() calls therefore try the namespaced path first and fall back to the bare element name.

Absolute Windows texture paths

The textureFilename XML attribute often stores an absolute Windows path (e.g. C:\Users\...\texture.png). Only the os.path.basename is used to locate the file inside the ZIP archive under materials/<name>/<basename>.

ZIP-relative image paths (preferred)

When the <images> child element is present its <image path="..."> attribute is tried first. Paths starting with ./ are resolved relative to materials/<name>/; paths starting with materials/ are treated as ZIP-root-relative; all other paths are assumed to be material-folder-local.

Missing texture data

If the texture image file cannot be found in the ZIP a Texture object is still created with data=None so that downstream code knows a texture was intended (useful for UV generation) without crashing. A DEBUG log message records the missing path.

PBR fields

pbrMR (metallic-roughness) elements are parsed when present. SketchUp stores factors as child elements in observed files, with enable_* flags deciding whether the factors are active. Models from SketchUp versions prior to 2021 typically omit this block, in which case metallic=0.0 and roughness=1.0 are used.

Opacity encoding

SketchUp stores opacity as trans (0=opaque, 1=fully transparent) gated by useTrans. The parsed alpha field is always in the conventional range 0.0 (transparent) … 1.0 (opaque).

skppy.parser.material_parser.build_zip_name_map(zip_file: ZipFile) → Dict[str, str][source]

SKP files created on Windows sometimes store non-ASCII filenames with their UTF-8 bytes un-flagged, so Python’s zipfile decodes them as CP437 (mojibake). Build a lookup map {utf8_corrected_path -> actual_stored_path} so we can find entries by their proper Unicode name.

skppy.parser.material_parser.parse_material_record(record_payload: bytes, *, fallback_id: int = 0, zip_file: ZipFile | None = None, zip_name_map: Mapping[str, str] | None = None, attribute_dictionaries_by_object_id: dict[int, list[AttributeDictionary]] | None = None, import_vray_materials: bool = False) → Material[source]

Parse one MATERIAL_RECORD payload from any modern model section.

Layer display colors use the same nested record as entries in the global material manager. Keeping one decoder prevents those two representations from drifting as material fields are discovered.

skppy.parser.material_parser.parse_materials(materials_container_payload: bytes, zip_file: ZipFile | None = None, *, zip_name_map: Mapping[str, str] | None = None, attribute_dictionaries_by_object_id: dict[int, list[AttributeDictionary]] | None = None, import_vray_materials: bool = False) → List[Material][source]

Parse the materials-container payload and return a list of Material objects.

Parameters:

  • materials_container_payload (bytes) – Raw payload of the MATERIALS_CONTAINER (0x30D4) TLV record.

  • zip_file (zipfile.ZipFile or None) – Open ZIP archive for reading material.xml files. When None, materials are populated from TLV identity and name only.

Returns:

Parsed materials with color, texture, and PBR fields when XML is available.

Return type:

list of Material