skppy.data_structure.model¶

Top-level SketchUp document model and its high-level builder API.

Model is returned by skppy.load() and accepted by skppy.save(). It owns root entities plus document-wide registries such as materials, layers, component definitions, scenes, cameras, styles, and fonts. Builder methods allocate stable model IDs and should be preferred over manually appending objects to those registries.

Example

import skppy

model = skppy.new_model()
walls = model.add_layer("Walls")
paint = model.add_material("Paint", skppy.Color(230, 230, 220))
face = model.entities.add_face(
    [(0, 0, 0), (144, 0, 0), (144, 0, 96), (0, 0, 96)]
)
face.layer_id = walls.id
face.front_material_id = paint.id
skppy.save(model, "wall.skp")

class skppy.data_structure.model.Model[source]

Bases: object

Fully parsed SketchUp model.

Top-level container returned by skppy.load(). Holds the entire document: geometry, materials, layers, component definitions, cameras, scenes, and all model metadata.

header

Binary file header – version string, timestamps, UUID.

Type:: SkpHeader or None

document

ZIP container metadata and raw entry access.

Type:: SkpDocument or None

entities

Root-level geometry (vertices, edges, faces, instances, groups, images).

Type:: Entities

definitions

All component definitions in the document.

Type:: list of ComponentDefinition

materials

All materials.

Type:: list of Material

layers

All layers (called “Tags” in modern SketchUp).

Type:: list of Layer

layer_folders

Layer folder hierarchy.

Type:: list of LayerFolder

cameras

Camera records stored in the file.

Type:: list of Camera

active_layer_id

ID of the layer that was active when the file was saved.

Type:: int or None

scenes

Named scenes (pages / saved views).

Type:: list of Scene

background_image

Default model-level background/match-photo image when present.

Type:: PageBackgroundImage or None

rendering_options

Parsed rendering/display options from either container format.

Type:: RenderingOptions or None

shadow_info

Geo-referenced shadow settings (0x0204).

Type:: ShadowInfo or None

watermark_manager

Watermark manager (0x0203).

Type:: WatermarkManager or None

styles_registry

Styles registry (0x0206).

Type:: StylesRegistry or None

fonts

Font definitions (0x01FD).

Type:: list of Font

text_style

Text style settings (0x01FE).

Type:: TextStyle or None

dimension_style

Dimension style settings (0x01FF).

Type:: DimensionStyle or None

line_styles

Line style definitions (0x0208).

Type:: list of LineStyle

options_manager

Options manager (0x0200).

Type:: OptionsManager or None

environment_data

Environment data (0x0210).

Type:: EnvironmentData or None

sun_data

Sun data (0x0213).

Type:: SunData or None

model_view_axes

Sketch axes orientation (0x01FC).

Type:: ModelViewAxes or None

attribute_dictionaries

Attribute dictionaries (0x0209).

Type:: list of AttributeDictionary

attribute_dictionaries_by_object_id

Attribute dictionaries grouped by model-level definition, material, or layer ID.

Type:: dict

legacy_archive

Parser provenance decoded from a pre-ZIP legacy binary envelope.

Type:: object or None

Builder API

-----------

Create a new model and populate it programmatically::: model = Model.new() layer = model.add_layer(“Walls”) brick = model.add_material(“Brick”, color=Color(180, 80, 60)) defn = model.add_definition(“MyCube”) face = defn.entities.add_face([(0,0,0),(100,0,0),(100,100,0),(0,100,0)]) model.entities.add_instance(defn) model.save(“output.skp”)

__init__(header: 'SkpHeader' | None = None, document: 'SkpDocument' | None = None, entities: Entities = <factory>, definitions: List[ComponentDefinition] = <factory>, materials: List['Material'] = <factory>, layers: List['Layer'] = <factory>, layer_folders: List['LayerFolder'] = <factory>, cameras: List[Camera] = <factory>, active_layer_id: int | None = None, scenes: List['Scene'] = <factory>, background_image: 'PageBackgroundImage' | None = None, rendering_options: RenderingOptions | None = None, shadow_info: ShadowInfo | None = None, watermark_manager: WatermarkManager | None = None, styles_registry: StylesRegistry | None = None, fonts: List[Font] = <factory>, text_style: TextStyle | None = None, dimension_style: DimensionStyle | None = None, line_styles: List[LineStyle] = <factory>, options_manager: OptionsManager | None = None, environment_data: EnvironmentData | None = None, sun_data: SunData | None = None, model_view_axes: ModelViewAxes | None = None, attribute_dictionaries: List[AttributeDictionary] = <factory>, attribute_dictionaries_by_object_id: Dict[int, List[AttributeDictionary]]=<factory>, legacy_archive: Any | None = None) → None

add_definition(name: str, description: str = '') → ComponentDefinition[source]

Create a new component definition with empty geometry and add it to the model.

After calling this method, populate the definition’s geometry via defn.entities.add_face(...) and then place instances with model.entities.add_instance(defn, ...). Alternatively use add_group() for a single-use inline group.

Parameters:

name (str) – Display name for the definition (shown in the Components panel).
description (str, optional) – Optional description text.

Return type:

ComponentDefinition

add_group(name: str | None = None, transform: Transform | None = None) → tuple[ComponentDefinition, Group][source]

Create a named group (an immediately-placed anonymous definition).

A new ComponentDefinition is created and a Group instance is placed in self.entities.groups at the given transform.

Parameters:

name (str, optional) – Display name. Defaults to "Group#N" where N is the current definition count.
transform (Transform, optional) – Placement transform. Defaults to the identity transform.

Returns:

Add geometry to defn.entities; the group is already registered in self.entities.groups.

Return type:

tuple of (ComponentDefinition, Group)

add_layer(name: str, visible: bool = True) → Layer[source]

Create a new layer and add it to this model.

Parameters:

name (str) – Display name (called “Tag” in SketchUp 2020+).
visible (bool, optional) – Initial visibility state. Defaults to True.

Return type:

Layer

add_material(name: str, color: 'Color' | None = None, alpha: float = 1.0, metallic: float = 0.0, roughness: float = 1.0) → Material[source]

Create a new material and add it to this model.

Parameters:

name (str) – Unique display name.
color (Color, optional) – Base diffuse colour. Defaults to white (255, 255, 255).
alpha (float, optional) – Opacity: 0.0 = fully transparent, 1.0 = fully opaque.
metallic (float, optional) – PBR metallic factor (0.0 to 1.0).
roughness (float, optional) – PBR roughness factor (0.0 to 1.0).

Return type:

Material

dump_zip(output_dir: str) → Path[source]

Extract the ZIP contents of the loaded .skp file to output_dir.

Parameters:: output_dir (str) – Destination directory for the extracted files.
Raises:: RuntimeError – If the model was not loaded from a .skp file (i.e. created programmatically with new()).

See also

SkpDocument.dump_zip: Underlying implementation.

get_definition(name: str) → ComponentDefinition | None[source]

Return the first component definition whose name matches, or None.

Parameters:: name (str) – Definition name to search for.
Return type:: ComponentDefinition or None

get_layer(name: str) → 'Layer' | None[source]

Return the first layer whose name matches, or None.

Parameters:: name (str) – Layer name to search for.
Return type:: Layer or None

get_material(name: str) → 'Material' | None[source]

Return the first material whose name matches, or None.

Parameters:: name (str) – Material name to search for.
Return type:: Material or None

classmethod new() → Model[source]

Create an empty Model ready to receive geometry.

Returns:: New model with empty containers and default metadata fields.
Return type:: Model

save(filepath: str | Path, *, header: 'SkpHeader' | None = None, format: Literal['modern', 'sketchup_2017'] = 'modern', export_vray_materials: bool = False) → Path[source]

Write this model to a SketchUp .skp file.

Parameters:

filepath (str or pathlib.Path) – Destination file path.
header (SkpHeader or None, optional) – Explicit modern VFF header.
format ({"modern", "sketchup_2017"}, optional) – Output container format.
export_vray_materials (bool, optional) – Generate V-Ray material metadata from public material values.

Returns:

Destination path after serialization.

Return type:

pathlib.Path

to_scene() → SceneNode[source]

Convert this Model into a SceneNode tree ready for any importer or exporter.

The returned tree has the following structure:

SceneNode("Scene")           <- root, identity transform, no mesh
+-- SceneNode("RootGeometry") <- root-level faces (if any)
+-- SceneNode(inst.name)      <- one per root instance / group
    +-- mesh                  <- pre-computed PreparedMesh
    +-- children             <- nested instances / groups

All spatial coordinates are in SketchUp inches (definition-local). Transforms are the 13-float row-major SUTransformation as stored in the TLV (identity transform for the root and RootGeometry nodes).

Returns:: Root of the scene hierarchy.
Return type:: SceneNode