Getting Started

Quick introduction to the two components of the project.

---

Loading a SketchUp file

import skppy

model = skppy.load("my_model.skp")

load() returns a Model containing all geometry, materials, layers, component definitions, and cameras:

print(model.header.product_name)    # "SketchUp 2023"
print(model.header.version_string)  # "{23.1.340}"

# Layers
for layer in model.layers:
    print(f"  layer: {layer.name!r}, visible={layer.visible}")

# Materials
for mat in model.materials:
    print(f"  mat: {mat.name!r}, color={mat.color}")

# Component definitions
for defn in model.definitions:
    print(f"  defn: {defn.name!r}, faces={len(defn.entities.faces)}")

# Saved cameras / scenes
for cam in model.cameras:
    print(f"  cam: {cam.name!r}, eye={cam.eye}")

---

Traversing geometry

Root-level geometry lives in model.entities. Nested geometry is inside component definitions accessed via model.definitions.

entities = model.entities

# Raw geometry (all lengths in inches)
for vertex in entities.vertices:
    print(vertex.id, vertex.position)   # Vector3D(x, y, z)

for edge in entities.edges:
    print(edge.start_vertex_id, "->", edge.end_vertex_id)

for face in entities.faces:
    print(face.id, "plane:", face.plane)
    print("  front material id:", face.front_material_id)

# Instances at the root
for inst in entities.component_instances:
    defn = next(d for d in model.definitions if d.id == inst.definition_id)
    print(f"instance {inst.name!r} -> definition {defn.name!r}")

for grp in entities.groups:
    defn = next(d for d in model.definitions if d.id == grp.definition_id)
    print(f"group {grp.name!r} -> definition {defn.name!r}")

---

Preparing geometry for importers

Entities.prepare_mesh() resolves material inheritance from instances and returns a PreparedMesh suitable for use in any 3D engine. It keeps simple polygons as polygons; faces with holes are triangulated by default, or a single-hole face can be split into two simple n-gons with split_holes_to_ngons=True:

material_lookup = {m.id: m for m in model.materials}

mesh = model.entities.prepare_mesh(
    name="root",
    material_lookup=material_lookup,
    inherited_material_id=None,
    split_holes_to_ngons=True,
)

for face in mesh.faces:
    # Positions as (x, y, z) tuples in inches
    for pos in face.vertex_positions:
        print(pos)
    # UV as (u, v) tuples, present when the resolved material is textured
    for uv in face.vertex_uvs or []:
        print(uv)
    print("material:", face.material_name)

For importer backends that need indexed geometry, convert the prepared mesh to the general mesh form:

indexed = mesh.to_indexed(merge_vertices=True, triangulate=True)
print(indexed.vertex_positions)
print(indexed.faces)
print(indexed.face_material_ids)
print(indexed.face_uvs)

---

Creating a model from scratch

import skppy

# Start with an empty model
model = skppy.new_model()

# Add a layer and a material
floor_layer = model.add_layer("Floor", visible=True)
concrete = model.add_material(
    "Concrete",
    color=skppy.Color(180, 180, 180),
    roughness=0.9,
)

# Define a component: a simple square
slab = model.add_definition("Slab")
e = slab.entities

v0 = e.add_vertex(0,   0,   0)
v1 = e.add_vertex(200, 0,   0)
v2 = e.add_vertex(200, 200, 0)
v3 = e.add_vertex(0,   200, 0)

e.add_edge(v0.id, v1.id)
e.add_edge(v1.id, v2.id)
e.add_edge(v2.id, v3.id)
e.add_edge(v3.id, v0.id)
e.add_face([v0, v1, v2, v3], material_id=concrete.id)

# Place two instances
t1 = skppy.Transform.from_translation(0, 0, 0)
t2 = skppy.Transform.from_translation(250, 0, 0)
model.entities.add_instance(slab, t1, name="Slab-A")
model.entities.add_instance(slab, t2, name="Slab-B")

skppy.save(model, "two_slabs.skp")

---

Handling legacy files

Pre-ZIP files use a CArchive binary format. skppy.load() detects this container and maps its supported geometry, materials, layers, definitions, instances, cameras, and metadata into the same public classes used by modern files:

model = skppy.load("legacy.skp")
if model.legacy_archive is not None:
    print(model.header.version_string)
    print(len(model.legacy_archive.version_map))

---

Using the Blender addon

After installing (see Installing the Blender Addon):

1. Open Blender and go to File -> Import -> SketchUp (.skp).

2. Select a .skp file.

3. Adjust import options in the side panel (scale, materials, cameras, etc.).

4. Click Import SketchUp.

The model will appear as a collection of mesh objects.

For a full description of each import option see Blender Addon -> Import options.

---

Next steps

Document	Description
API Reference	Complete class and function reference
How-To Guides	Tutorials for specific tasks
Blender Addon	Detailed addon documentation
File Format	SKP binary format internals