skppy.loader

Load a SketchUp .skp file and return a fully parsed Model.

The load() function is the primary entry point for reading .skp files. It handles header parsing, ZIP extraction, and delegates to the model parser to produce a fully-populated Model.

Example

import skppy

model = skppy.load("architecture.skp")
print(model.header.version_string)   # e.g. "{23.1.340}"
print(len(model.materials))
print(len(model.definitions))
skppy.loader.load(filepath: str | PathLike[str], *, cancellation_check: Callable[[], bool] | None = None, import_vray_materials: bool = False) → Model[source]

Load a SketchUp .skp file and return a fully parsed Model.

Modern versionless ZIP-based files (SketchUp 2021+) are parsed through the TLV parser. Earlier binary files are parsed through the version-aware CArchive parser. Container detection is automatic.

Parameters:

  • filepath (str or os.PathLike) – Path to the .skp file (absolute or relative to the current directory).

  • cancellation_check (callable, optional) – Zero-argument callback returning True when parsing should stop. Cancellation raises LoadCancelledError and is never converted to InvalidSkpError.

  • import_vray_materials (bool, optional) – Prefer V-Ray PBR attributes over SketchUp material appearance. The default is False so normal SketchUp materials remain authoritative.

Returns:

Fully populated model containing:

  • header – SkpHeader with product name, version, and zip offset.

  • document – SkpDocument for raw ZIP entry access.

  • entities – Root-level geometry (vertices, edges, faces, component instances, groups, images, curves, arc curves, guide points/lines, section planes).

  • definitions – List of ComponentDefinition, each with their own nested entities and behavior flags.

  • materials – List of Material (colour, optional texture, PBR metallic/roughness).

  • layers – List of Layer.

  • layer_folders – List of LayerFolder.

  • cameras – List of Camera (saved views).

  • scenes – List of Scene (named pages).

  • active_layer_id – ID of the layer active when the file was saved.

  • rendering_options – RenderingOptions (edge display, fog, ground, shadows, AO, etc.).

  • shadow_info – ShadowInfo (geo-referenced shadows).

  • model_view_axes – ModelViewAxes (sketch axes).

  • line_styles – List of LineStyle.

  • options_manager – OptionsManager (app-level settings).

  • environment_data – EnvironmentData (sky/IBL presets).

  • attribute_dictionaries – List of AttributeDictionary.

Return type:

Model

Raises:

  • FileNotFoundError – If filepath does not exist.

  • InvalidSkpError – If an existing file cannot be decoded as a supported SKP model.

Examples

Basic usage:

import skppy

model = skppy.load("architecture.skp")
print(model.header.version_string)   # e.g. "{23.1.340}"
print(len(model.materials))
print(len(model.definitions))

Traversing geometry:

for face in model.entities.faces:
    print(face.id, face.plane)
    triangles = face.triangulate(model.entities)

Inspecting legacy archive provenance:

model = skppy.load("legacy.skp")
if model.legacy_archive is not None:
    print(model.legacy_archive.archive_offset)