Skip to content
hew3dPublic

About

An open-source clean-room reader/writer and specification for the SketchUp `.skp` file formats.

Resources

Contributing

Stars

15 stars

Watchers

0 watching

Forks

Repository files navigation

Skpwright

An open, clean-room reader, writer and specification for the SketchUp .skp file format: releases 3 to 8 and 2013 to 2020 (the stream container) and the 2026 container that SketchUp 2026 and 2027 save, read and written through one library. Releases 2021 to 2025 are supported through the 2026 container; see the support matrix.

SketchUp's native format has no public specification and, until now, no open-source reader; the only way to read a .skp has been Trimble's proprietary SDK. Skpwright documents the two containers, reads any file into one model, and writes that model back out as a file of any stream release or of the 2026 container (see the support matrix):

  • A format specification — docs/SKP_FORMAT.md plus the Kaitai Struct grammar ksy/skp.ksy, detailed enough to build an independent parser.
  • A Rust SDK — crates/skpwright, a pure-Rust library (its only dependency is a DEFLATE decoder) that reads meshes, materials, UVs, hierarchy, layers, scenes, attributes, and the document's settings (camera, rendering options, shadows, units, styles, watermarks, and text/dimension annotations), and writes a model as a file of a stream-container release or the 2026 container, or edits a file in place.
  • A CLI and a C ABI — skpwright, which converts a file between the supported releases, summarises it and prints it as JSON (skpwright --help), and libskpwright with a plain-C header for every other language.
  • An evidence corpus — corpus/, the authored minimal pairs, per-release checkpoint sets and ground-truth exports behind every format claim, doubling as the test suite's oracle.

Everything derives from observing .skp files, SketchUp's own exports of them (COLLADA, and model dumps scripted in its Ruby console), and public knowledge of MFC CArchive serialization and the ZIP format. No Trimble SDK, headers, or SDK-derived knowledge is used; SketchUp is only ever operated, never read — see the clean-room policy in CONTRIBUTING.md.

The format in one paragraph

Every observed release is stored in one of two containers. Both begin with the same two UTF-16 string records, which carry the version string ({3.x} … {20.x}, {26.x}, {27.x}).

The stream container holds releases 3 to 8 and 2013 to 2020 ({3.x} to {20.x}): after the header comes one uncompressed MFC CArchive object stream with a single shared object map, where classes are defined lazily inline and object references index that map. The layout in §2–§13 is written as release 2017 writes it; §14 derives every other release from it as delta rules.

The 2026 container ({26.x} and {27.x}, as saved by SketchUp 2026 and 2027, and by 2021 to 2025) follows the header strings with a ZIP archive. Its model.dat is a tree of tagged records (u16 tag | u32 length | payload) holding the entities, their persistent ids, transforms, and every document setting; materials are XML files next to their texture images.

Both store the same model: a half-edge kernel (CVertex / CEdge / CEdgeUse / CLoop / CFace) in f64 inches, components and groups placing shared definitions through 13-value transforms, and textures mapped through per-face projective matrices. The full account is in docs/SKP_FORMAT.md: §2–§14 for the stream container, §16 for the 2026 container.

Quick start

git clone https://github.com/hew3d/skpwright
cd skpwright

cargo run -p skpwright-cli --release -- model corpus/2026/house-plus.skp
cargo run -p skpwright-cli --release -- mesh  corpus/2026/box.skp   # JSON out
cargo run -p skpwright-cli --release -- model corpus/2017/house.skp  # stream container, release 2017
cargo run -p skpwright-cli --release -- model corpus/8/box.skp       # stream container, release 8
cargo run -p skpwright-cli --release -- convert --to 2013 corpus/2026/box.skp out.skp

As a library:

let model = skpwright::Model::read("model.skp")?;   // any observed release
for run in &model.geometry {
    // a 1 m box: 8 vertices / 12 edges / 6 faces
    println!("{:?}", run.topology);
}
for node in model.scene() {
    // composed world transforms, inherited materials
}

From C (or anything that speaks JSON):

skpwright_model *m = skpwright_open("model.skp");
puts(skpwright_mesh_json(m));    /* meshes + composed scene */
skpwright_free(m);

See docs/SDK.md for the full API tour.

How correctness is established

The corpus is the oracle. Every decoded structure is validated three ways: by construction (files authored with typed exact dimensions, so the right bytes are knowable in advance), against COLLADA (SketchUp's own exports provide ground-truth coordinates, connectivity, colors, and UVs), and at scale (a 10.6 MB production model must match its export exactly — 41,725 world vertices, 26,918 face rings, and 7,649 textured faces' UVs do).

cargo test --workspace --release     # the acceptance suite
./scripts/verify.sh                  # Kaitai grammar + reference-parser checks

verify.sh needs a Python venv with kaitaistruct and an npm install kaitai-struct-compiler js-yaml.

Support matrix

The stream container (releases 3 to 8 and 2013 to 2020) is read and written through one grammar, and every one of its releases has files SketchUp wrote. The 2026 container (a ZIP archive holding model.dat) has two observed versions: {26.2.0} (revision 17, the web app) and {27.0.267} (revision 18, SketchUp Pro 2027). SketchUp 2027's "save as 2021" option writes the same {27.0.267} format, so desktop saves of 2021 to 2025 use the same container. The container is one format whose model revision (meta/meta.dat, spec §16.27), not its version label, is the gate: SketchUp 2027 opened every revision tried up to 18 under every label tried. A hand-edited file of revision 19 or above was refused by SketchUp 2027 desktop (the web app accepted it); no real file above 18 exists. The reader reads any revision (one above 18 as 18, with a diagnostic; records are length-framed and unknown tags are reported). The writer emits only revision 17 as {26.2.0} or revision 18 as {27.0.267}, the lowest that holds the model unless asked for one. Releases 2021 to 2025 are supported: files from them read like any revision up to 18 (a 2021 file observed holds revision 8, a 2022 file 13). The writer's revision 17 is the lowest it emits; no application of 2021 to 2025 has opened a file of it.

Status words: native files in corpus (files a SketchUp release wrote are committed and read whole), written by Skpwright and accepted by SketchUp N (a file Skpwright wrote was opened and re-saved by SketchUp N with matching content), supported by the shared container.

release container read evidence write evidence
3, 4, 5, 6, 7, 8 stream (§14.4) native files in corpus (10 per release, written by SketchUp Make 2017 saving to the release) written by Skpwright and accepted by SketchUp Make 2017
2013 to 2016 stream (§14.2) native files in corpus (10 per release, written by SketchUp Make 2017) written by Skpwright and accepted by SketchUp Make 2017
2017 stream (§2-§13) native files in corpus (92 authored pairs, third-party models) written by Skpwright and accepted by SketchUp Make 2017
2018 stream (§14.5) native files in corpus (SketchUp 2027's save of each of the 92 2017 models read equivalent, 15 committed) written by Skpwright (all 92 models) and accepted by SketchUp 2027 with matching content
2019 stream (§14.5) as 2018 (16 committed) as 2018
2020 stream (§14.5) as 2018 (20 committed) as 2018
2021 to 2025 desktop 2026 (§16) supported through the shared container; the revision is the gate (§16.27); two real files observed outside the corpus ({21.0.0}, revision 8; {22.0.353}, revision 13), read whole revision 17 files are written; not opened in those apps, and below the revision 17 the tool writes, so whether they open there is untested
2026 ({26.2.0}) 2026 (§16) native files in corpus (91, saved by the web app; no hatch, environment, CRS or procedure sections) written by Skpwright and accepted by the SketchUp web app and by SketchUp 2027 with no integrity warning
2027 ({27.0.267}) 2026 (§16) native files in corpus (88 one-change files, SketchUp Pro 2027; its saves of the 92 2017 models read equivalent) written by Skpwright (every corpus file) and accepted by SketchUp 2027 with no integrity warning

Notes: a file whose header strings are followed by a ZIP archive is read as the 2026 container whatever its version string. Releases before 2017 were checked against the full 92-file same-session save sets (outside the repository, pinned by hash) as well as the committed checkpoint sets. Writing to an earlier release drops what that release cannot hold and reports each drop as a note. Any Model writes as a stream-container release 3 to 2020 or as the 2026 container at revision 17 or 18; releases 2021 to 2025 have no label of their own and take revision 17. A file's version string is {A.B.C}: A is the release, and B.C (the saving build) varies within one without changing the layout of the stream container (spec §2); the 2026 container's gate is the model revision.

  • Reading at scale. Every 2017 corpus file but section-plane-deactivated.skp has a 2026 twin; each twin reads equivalent to its original (geometry, hierarchy, materials, layers, UVs, scenes, guides, document settings), and the COLLADA-oracle tests run on both containers. The 2026 reader is the faster and lighter of the two (a 122 MB production model: 1.2 s and 384 MB as a 60 MB 2026 file, 2.2 s and 544 MB as the release 2017 original). The stream container's walk reads production-scale models well beyond the corpus (a 464 MB third-party house in 12 s and 2 GB; these are local models outside the repository, see SKPWRIGHT_EXTERNAL_MODELS in docs/DEVELOPMENT.md) with no desync; a process that cannot hold the model gets a named out-of-memory error instead of aborting.
  • Damaged records. A damaged record is skipped and reported as a diagnostic; a record tag this reader does not know, at the top level or in an entity container, is reported rather than dropped.
  • Writing 2026 files. A 2026 file round-trips byte for byte through the lossless Document (its DEFLATE streams re-encoded exactly), any Model — read from either container or built by another program — writes as a 2026 file with Model::write that SketchUp 2027 and the web app opened and re-saved with matching content and that reads back equivalent, and a Document takes surgical edits (a colour, a transform, a coordinate) that change one record and nothing else (docs/WRITING.md).
  • Writing stream-container files. Every byte of a stream-container file is read as records and written back identical through a store map assigned anew, so any Model also writes as a file of any release 3 to 2020 (Model::write_as, skpwright convert --to <release>) and reads back equivalent. Every written release up to 2017 was opened and re-saved by SketchUp Make 2017 without a dialog, with matching content, and the releases 2018 to 2020 by SketchUp 2027 (docs/DEVELOPMENT.md, SketchUp acceptance). Writing to an earlier release drops what that release cannot hold and reports each drop as a note. A StreamDocument takes in-place edits byte for byte. What a written file carries, what it leaves behind and what is unknown is inventoried in docs/WRITING.md.
  • Post-2017 features. What SketchUp 2027 adds to the 2026 container (hatch patterns, layer folders and line styles, physically based materials, environments, ambient occlusion, a coordinate reference system, snaps and Solid Tools results, and the newer page settings) reads into Model::features and writes back, pinned by the one-change files of corpus/2027 and specified in docs/SKP_FORMAT.md §16.17 to §16.26. A stream-container file holds none of it, and writing one drops it with a note per kind.

Caveats. Every observed file of releases 3 to 6 and 2013 to 2016 was written by SketchUp Make 2017 saving to that release; releases 7 and 8 have also been read from files SketchUp 7 and 8 themselves wrote, models outside the repository; nothing written by SketchUp 3 to 6 themselves has been seen, so a few layout details of those releases are marked candidate in the spec. Release 2017 has 92 authored minimal pairs, COLLADA oracles and production-scale third-party models, and 2026 has a twin of every 2017 file but one plus a production model; each other release has ten committed files (eleven from 2018; the checkpoint set, corpus/README.md), a mutation test showing those files detect every per-release rule that reading them or writing them back consults (docs/DEVELOPMENT.md), and the releases before 2017 also a pinned 92-file same-session save set checked when SKPWRIGHT_YEARS_DIR is set. The files of 2018 to 2020 were written by SketchUp 2027 saving to that release. Reading is the same code path for all; the volume of evidence behind each release is not equal. Releases 2021 to 2025 are supported: a file whose header strings are followed by a ZIP archive is read as a 2026 file at the revision its meta/meta.dat declares.

Repository layout

docs/       SKP_FORMAT.md (the spec) · SDK.md (using the SDK) · DEVELOPMENT.md
ksy/        skp.ksy — Kaitai Struct grammar (header + record catalogue)
crates/     skpwright (core library) · skpwright-cli · skpwright-capi (C ABI)
corpus/     the evidence base: authored 2017 minimal pairs and their 2026
            twins, a checkpoint set for each other release (3 to 8 and
            2013–2016, 2018–2020), one-change files saved by SketchUp
            2027, ground-truth exports in model/, a full-scale
            third-party benchmark in both containers (see corpus/README.md)
tools/      Python analysis instruments and the frozen reference parser
scripts/    verify.sh

License

GPL-3.0-only — see LICENSE. Alternative commercial licensing may be offered in the future; contributions are accepted under the terms in CONTRIBUTING.md, which keep that possible.

SketchUp is a trademark of Trimble Inc. This project is independent of and unaffiliated with Trimble; it interoperates with the .skp format based on clean-room analysis of files. Texture images embedded in the corpus .skp files are third-party content outside the GPL grant — see corpus/README.md.

About

An open-source clean-room reader/writer and specification for the SketchUp `.skp` file formats.

Resources

Contributing

Stars

15 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages