skppy.data_structure.scene

Scene output data structures.

These classes provide a format-agnostic representation of a SketchUp model, suitable for consumption by any renderer or importer. Geometry, UVs, normals, and material names are already resolved to plain Python data.

All spatial coordinates are in SketchUp inches (the native unit). The consuming application is responsible for converting to its own unit system.

Example

def walk(node):
    yield node
    for child in node.children:
        yield from walk(child)

scene = skppy.load("input.skp").to_scene()
for node in walk(scene):
    if node.mesh:
        for face in node.mesh.faces:
            print(face.material_name, face.vertex_positions)
class skppy.data_structure.scene.IndexedPreparedMesh[source]

Bases: object

Indexed, renderer-neutral mesh generated from PreparedMesh.

This is the most general mesh output skppy provides to importers. It keeps geometry indexed while preserving per-face material, UV, normal, layer, and source-face metadata in parallel arrays.

Parameters:

  • vertex_positions (list of (float, float, float)) – Unique or per-corner vertex positions in SketchUp inches.

  • faces (list of list of int) – Polygon corner indices into vertex_positions.

  • face_uvs (list of list of (float, float) or None) – Per-loop UVs for each face. Entries align with faces.

  • face_normals (list of (float, float, float)) – Face normals aligned with faces.

  • face_material_names (list of str or None) – Resolved material names aligned with faces.

  • face_material_ids (list of int or None) – Resolved material IDs aligned with faces.

  • source_face_ids (list of int or None) – Original SKP face IDs aligned with faces.

  • layer_ids (list of int or None) – Source layer/tag IDs aligned with faces when known.

  • face_edge_ids (list of list of int or None) – Source SKP edge IDs for each indexed face boundary edge. Entries align with faces.

  • face_edge_flags (list of list of int) – Source SKP edge flags aligned with face_edge_ids.

__init__(vertex_positions: List[Tuple[float, float, float]], faces: List[List[int]], face_uvs: List[List[Tuple[float, float]] | None], face_normals: List[Tuple[float, float, float]], face_material_names: List[str | None], face_material_ids: List[int | None], source_face_ids: List[int | None], layer_ids: List[int | None], face_edge_ids: List[List[int | None]], face_edge_flags: List[List[int]]) → None
class skppy.data_structure.scene.PreparedFace[source]

Bases: object

A single planar polygon face, fully resolved and ready for export.

Parameters:

  • vertex_positions (list of (float, float, float)) – Ordered corner positions in definition-local SketchUp inches.

  • vertex_uvs (list of (float, float) or None) – Per-corner UV coordinates (u, v) in tile-fraction space (repeating at every integer boundary). None when the face carries no textured material.

  • normal ((float, float, float)) – Outward-facing unit normal (nx, ny, nz) from the face’s plane equation ax + by + cz + d = 0.

  • material_name (str or None) – Name of the front-face material, or None for un-materialed faces.

  • material_id (int or None) – Resolved effective material ID, or None for the default material.

  • source_face_id (int or None) – Original SKP face ID that produced this prepared face.

  • layer_id (int or None) – Reserved for the source layer/tag ID when entity-level layer data is available.

  • edge_ids (list of int or None, optional) – Source SKP edge IDs for each polygon boundary edge. Entry i describes the edge from corner i to corner (i + 1) % n. None marks generated edges such as triangulation diagonals.

  • edge_flags (list of int, optional) – Source SKP edge flags aligned with edge_ids. Generated edges use 0.

__init__(vertex_positions: List[Tuple[float, float, float]], vertex_uvs: List[Tuple[float, float]] | None, normal: Tuple[float, float, float], material_name: str | None, material_id: int | None = None, source_face_id: int | None = None, layer_id: int | None = None, edge_ids: List[int | None] | None = None, edge_flags: List[int] | None = None) → None
class skppy.data_structure.scene.PreparedMesh[source]

Bases: object

All faces belonging to one entities scope (a definition or root level).

Faces share no vertex array – each face owns its corner list. This mirrors the SKP model structure and simplifies importer code that works face-by-face (e.g. Blender bmesh insertion).

Parameters:

  • name (str) – Human-readable name (definition name or "RootGeometry").

  • faces (list of PreparedFace) – Ordered list of prepared faces.

__init__(name: str, faces: List[PreparedFace] = <factory>) → None
to_indexed(*, merge_vertices: bool = False, triangulate: bool = False, precision: int = 9) → IndexedPreparedMesh[source]

Convert this face-owned mesh into an indexed mesh.

Parameters:

  • merge_vertices (bool, optional) – Reuse vertices at identical positions. UVs remain per-loop, so texture seams are preserved even when positions are shared.

  • triangulate (bool, optional) – Emit triangles for faces with more than three corners using the skppy triangulator. Faces that cannot be triangulated fall back to a simple fan.

  • precision (int, optional) – Decimal places used when comparing positions for vertex merging.

Returns:

Indexed geometry plus per-face metadata, still in SketchUp inches.

Return type:

IndexedPreparedMesh

class skppy.data_structure.scene.SceneNode[source]

Bases: object

A node in the import scene hierarchy.

The tree mirrors the SketchUp component instance / group nesting:

  • The root node has transform = identity, mesh = None, and children for RootGeometry and every top-level instance/group.

  • A leaf node has a mesh and no children (or both, for mixed definitions).

  • Container nodes have children but may have mesh = None.

Parameters:

  • name (str) – Display name (instance name or definition name).

  • transform (list of float) – 13-float row-major SUTransformation as stored in the SKP TLV. The root node uses the identity transform.

  • mesh (PreparedMesh or None) – Pre-computed geometry for this node’s definition scope, or None if the definition has no direct faces.

  • children (list of SceneNode) – Sub-nodes for nested instances and groups, in the order they appear in the parent’s entities.

  • material_name (str or None) – Instance-level material override (applied to un-materialed faces in mesh). None if no override is set.

__init__(name: str, transform: List[float], mesh: PreparedMesh | None, children: List[SceneNode], material_name: str | None = None) → None