Przejdź do treści
Biblioteka skilli
Projektowanie i UX · Budowanie i kod

3d-model

/3d-model

Buduje sparametryzowany model 3D domu ze skanów LiDAR i pomiarów, publikowany jako przeglądarkowy podgląd.

Repozytorium
3d-model-skill ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Buduje sparametryzowany model 3D domu ze skanów LiDAR i pomiarów, publikowany jako przeglądarkowy podgląd.

Oryginalny opis (EN)

Build a measured, parametric 3D model of a house from phone LiDAR scans, tape measurements and spec sheets, and publish it as a static web viewer (GitHub Pages or Cloudflare). Use when someone wants to scan a house or room, turn a scan into a clean model, show design options (paint, siding, a new door, porch colors) in a browser, register a scan to a model, make construction drawings, a cut list or a buy list from the model, record an animated walkthrough, or publish or fix the viewer, including Walk mode and the phone joystick.

Jak działa

  1. 1. Capture
  2. 2. Register
  3. 3. Model
  4. 4. Parameters
  5. 5. Check and look
  6. 6. Drawings, cut list, buy list
  7. 7. Publish: ask which
  8. Measure the model
  9. Keep it cheap: a thin lead and a worker per part
  10. Viewer controls
Sekcje z nagłówków SKILL.md, w oryginale · 274 linii, 2 662 słów
Podgląd SKILL.md
---
name: 3d-model
description: Build a measured, parametric 3D model of a house from phone LiDAR scans, tape measurements and spec sheets, and publish it as a static web viewer (GitHub Pages or Cloudflare). Use when someone wants to scan a house or room, turn a scan into a clean model, show design options (paint, siding, a new door, porch colors) in a browser, register a scan to a model, make construction drawings, a cut list or a buy list from the model, record an animated walkthrough, or publish or fix the viewer, including Walk mode and the phone joystick.
---

# 3d-model

The model is a clean, editable house built from measured numbers. It is not the scan.
Scans are lumpy and stop where the phone stopped. The scan is the evidence the numbers
answer to. The repo this skill ships in is a working example: a made-up rowhouse with
four claddings, eight paints, porch colors and sliders, three real sliding doors,
construction drawings for each, and two animated tours.

```
capture (LiDAR + tape) -> register -> model/house.yaml (numbers + sources)
  -> model/build.py -> site/ (house.glb, options/*.glb, controls.json)
  -> model/drawings.py -> site/drawings/ (sheets, cut list, buy list, PDFs)
  -> model/check.py -> publish (GitHub Pages or Cloudflare)
```

Read the doc for the step you're on: `docs/capture.md`, `docs/model.md`, `docs/viewer.md`,
`docs/parameters.md`, `docs/drawings.md`, `docs/publish.md`.

## 1. Capture

Ask which phone they have. LiDAR means an iPhone Pro (12 Pro or later) or an iPad Pro.
Recommend Scaniverse (free, on-device, exports GLB mesh and PLY points from one
capture). Give them `docs/capture.md`'s walking rules: short overlapping scans under 5
minutes, slow, about 5 m range, exteriors as a loop in both directions, glass and blinds
lie, tape one dimension per scan.

**Getting the scans off the phone.** Walk them through it one step at a time and wait for
them to confirm each step. Every scan goes out twice, mesh first and then points:

1. In Scaniverse, tap the scan to open it.
2. Tap **Share**.
3. Tap **Export Model**.
4. Pick **GLB** (color images). Send it to the laptop: **AirDrop** is easiest on a Mac;
   otherwise use Files / iCloud Drive or email.
5. Back on the same scan: **Share → Export Model → PLY** (point cloud). Send that too.
6. Repeat for each scan.

When the files land (AirDrop puts them in `~/Downloads`), rename both files of a pair to
the same date and place (`2026-09-11-rear-yard.glb` and `.ply`) and move them into
`captures/`. Check that every GLB has a PLY with the same name. A missing half means a
re-export, not a re-scan.

Without LiDAR: photos plus COLMAP or VGGT get shape but not trustworthy scale. Tape more.

## 2. Register

Fix one origin on a durable feature (outside face of a masonry wall at finished floor)
and never move it. `uv run tools/register_scan.py scan.ply site/model/house.glb --out out/<name>`
levels, aligns (FPFH + RANSAC, then point-to-plane ICP) and writes residuals plus a
deviation cloud. When the automatic coarse step fails, pick 3 matching points by eye
and pass `--seed`. Record the residual with the transform and don't claim better.
Run `make demo-scan` first if anyone doubts the tool.

Then make the scan-vs-model sheets (`uv run tools/scan_sheets.py <registered.ply>`): plan
cuts per floor and a long section, scan in black, model in red, 1' grid, with the
median distance printed. Read every sheet. A mismatch is a measurement to fix or furniture
to ignore, and the sheet can't tell which. Ship the registered points as the viewer's
scan layer (`site/scan/points.glb`) so anyone can ghost the model and check.

## 3. Model

Numbers go in `model/house.yaml` in feet and inches, each group with a `source`
(`tape`, `scan`, `drawing`, `spec`, `estimate`). Use actual lumber sizes, not nominal (a 6x6
is 5 1/2"), and measure old members rather than rounding them to modern sizes.
Geometry comes from generators in `model/build.py`, written in wall coordinates
(u along, z up, t out), so cladding, trim and windows work on any wall.

Products come from the maker's sheet: unit size, rough opening, jamb depth, colors,
and the URL go in YAML with `source: spec`. Mark anything the sheet doesn't publish as
an estimate. Maker colors have names, not hex values. Approximate the hex and say so.

Also set, before anyone looks at it:

- `existing:` in `options.yaml`: the house as measured. The viewer's Existing / Proposed
  switch shows it without losing the design.
- `site:` in `house.yaml`: `anchor` lat/long, `y_bearing` (compass bearing of +Y) and
  `lot_depth`. They drive the real sun, the compass and the lot lines. Take the bearing
  from a map and check it against a dated photo's shadows.
- `lights:` for dusk (porch ceiling, sconces, a lamp per room) and `section` views (a cut
  height in inches) for floor plans.

## 4. Parameters

Four kinds, cheapest first (details in `docs/parameters.md`):

- **color**: recolor every material with a given name (`paint.body`). Name materials for the
  paint, not the part.
- **swap**: build one GLB per value, chosen by a slot template
  (`options/rear-{door}-{cladding}.glb`). Something that depends on two choices is a
  cross product, so keep those parts small.
- **range**: move a named node (`door.operable`) by a distance the generator wrote from
  the spec.
- **steps**: a slider over a few values that change shape (porch depth, roof pitch,
  guard height). Build every stop as its own GLB. Don't stretch geometry in the browser:
  the drawings and cut list have to describe the porch on screen. Pick the stops from
  real limits (36" guard minimum, 1/2 in 12 for metal roofing) and check them.

**Tours** are keyframes (eye, target, time, optional `set`) in `options.yaml`. The viewer
plays them; `tools/record_tour.py` renders them frame by frame to MP4 and GIF. Check a
new path with `--every 1` and read the contact sheet before recording. Keep the target
on the subject when swinging around, because a camera passing over its own target flips.
Walk through the open half of a slider, not the meeting stiles.

Add the field to `model/options.yaml`, build the geometry, `make check`. The viewer
should rarely need a change.

## 5. Check and look

`make check` catches sources, door fit, code basics (riser 7 3/4" max, tread 10" min,
baluster gap under 4", guard 36"), missing option files, the phone weight budget, a stale
build (the `source_sha256` fingerprint), drawings that disagree with the GLBs, and model
materials missing from a drawing set's coverage table.
Then look: `make serve` and `make shots` (Playwright, desktop and phone). Read every
screenshot before showing anyone. Look for z-fighting stripes, black faces, clipped
views, and a panel covering the subject. Read them tiled, not one by one:
`make sheet OUT=out/sheet.jpg STILLS="street-dusk inside rear-none"` makes one labelled
sheet under 1568 px. After three rounds on one surface, call it an estimate instead of
tuning the measurement.

## 6. Drawings, cut list, buy list

Follow `docs/drawings.md`. The rule is **one set of numbers**: drawings call the same
layout functions the 3D generator does (`build.rear_opening`, `build.rail_runs`,
`build.baluster_layout`), never a copy. Add new ones to `build.py` and use them in
both places.

1. Write the brief first in `model/drawings.yaml`: title, what was asked, confidence,
   open items. The sheet prints all three.
2. Draw with the `Svg` kit in `model/drawings.py`: `dim()` for dimensions, `note()` for
   callouts, classes (`brick`, `pt`, `steel`, `eng`) instead of colors. One set per
   option that changes the drawing, and link it from the viewer section with a
   `drawings:` template.
3. Pieces go on the cut list from the same layout; `buy()` packs them with kerf.
   `make check` proves drawn = cut = bought and no board is bought for nothing.
4. `make check-drawings` must pass: no overlapping or crossed labels, nothing off the
   sheet, crossing leaders, or labels under 9 px on a phone. The first run on a new
   sheet usually fails. Move the label; don't shrink it.
5. Screenshot every sheet and read it. A passing check doesn't make a sheet clear.
6. Anything structural gets "by engineer" and an open item. The sheets say "not for
   construction".
7. Fill the set's `coverage:` table: every material in its GLBs is either `buy` or says
   whose it is. A buy list with silent gaps looks complete, and that's worse than having none.
8. Where it can, `check.py` cuts the GLB and compares it with the drawing (the hole in the
   brick against the masonry opening, baluster sections against the cut list). Add a cut
   check like that for each new kind of sheet.

## 7. Publish: ask which

Ask: **"GitHub Pages or Cloudflare?"** Then follow `docs/publish.md`.

- **GitHub Pages** (default for open source and demos). The included workflow builds,
  checks and deploys on push to `main`. Enable it with
  `gh api -X POST repos/OWNER/REPO/pages -f build_type=workflow`.
- **Cloudflare Workers static assets** (for a real house with its own domain).
  `npx wrangler@4 deploy` with `wrangler.jsonc`, plus a `custom_domain` route if the zone
  is on Cloudflare. Tokens stay in the environment, never in git.

Publishing is outward-facing. Confirm before the first deploy, and strip private notes
(addresses, correspondence, security details) from anything that goes into a GLB.

Serve it compressed (`docs/publish.md`, "Compression"). A GLB is mostly floats that
repeat, so it shrinks 5-20x, but only if something compresses it. Check with
`curl -sI -H 'Accept-Encoding: gzip, br' <url>/model/house.glb` and look for
`content-encoding`. GitHub Pages gzips GLBs. Cloudflare doesn't by default, since
`model/gltf-binary` isn't on its list. For a big real model, run `gltf-transform meshopt`
on the export too. Never `gltf-transform optimize`: its dedup and join steps merge
materials and nodes, and the viewer finds them by name.

After a deploy, prove it: `uv run tools/verify_live.py <url>` compares every file with
the live site, byte for byte, plus the fingerprint. The Pages workflow's `verify` job does
it against the exact artifact it deployed. "CI is green" isn't proof the site is right.

## Measure the model

Size is something to show, not to cut. Never decimate, simplify or split a model to make
it smaller: serve it compressed instead (float geometry brotlis about 4x) and let people
see what it weighs. `make build` writes `site/stats.json` (bytes raw, gzip and brotli,
triangles, vertices, draw calls, materials, textures, scan points per GLB) and the viewer's
"Model details" shows it for what's on screen. `make stats` prints it. Say the size when
you publish.

Log every modelling session: `make tokens SESSION=<id prefix> TITLE="..."` appends its
tokens, lead and workers apart, to `model/worklog.yml`, and the viewer's work log prices it
as an API list-price equivalent. Details in `docs/publish.md`, "Size, stats and the work log".

## Keep it cheap: a thin lead and a worker per part

A modelling session's cost is turns times context, not this file. One lead that read a
250 KB site file and full-size stills carried them on every later turn, and re-read about
300M cached tokens over ~640 turns. A redesign of the same scale run the way below used
about 40% of the tokens and of the cost.

- **Split before designing.** When `build.py` (or one site file) passes about 60 KB, split it
  into one module and one numbers file per part (a room, a facade, the yard) before any
  design work, and prove the split is a no-op: the build writes byte-identical GLBs (`cmp`, or
  the `sha256` in `controls.json` assets).
- **The lead stays thin.** It reads the request and the outline (`rg -n "^def "`), writes
  one shared brief (frame, levels, layers, the loop, what counts as a stand-in) and a
  paragraph of design direction per part, and reads one contact sheet per part per round.
  It never reads a big file whole or a full-size still.
- **One worker per part, on a cheaper model** (`model: sonnet` on the Agent call), each
  owning its module and numbers file. Workers draft small (half-size, low-sample stills;
  for the viewer, a small Playwright viewport), tile them into one sheet, pipe build output
  through `tail`, and hand back about 250 words, the sheet's path, and "still weak". The
  lead sends one polish round to the same worker (SendMessage), so its context is reused.
- **Shared checkout rules**, in the brief:
  - Keep your module importable at all times. Write a big rewrite to `<module>_next.py`,
    compile it (`python -m py_compile`), then swap it in one step; a half-written module
    breaks every sibling's build.
  - Prefix new material names with your part (`kitchen.counter`), so recolors and the
    drawings' coverage table don't collide.
  - Interiors must be lit: a dark tile is a bug, not a mood. The commonest worker failure is a
    correct room rendered nearly black. Check a dusk still too, and make it show something the
    day still doesn't (lit windows, lamps).
  - Shared files (views, materials, `options.yaml`) get small targeted edits; the lead does
    the full build, `make check` and the drawings at the end.
- **Cap machine load** when the machine is shared: one render at a time behind a lock (for
  example `flock /tmp/render.lock <cmd>`), at low priority (`nice -n 10`). Two renders at once
  are rarely faster than one after the other.
- **Watch the size each round.** Detail multiplies: ask every worker for the face count of
  each repeated part (a tree, a chair, a baluster) and how many it placed, and look at
  `make stats` before the next round. Big is fine; big by accident isn't.
- **Stand-ins read as cheap**: ball shrubs, a flat green board for a hedge, glowing signs,
  string lights everywhere. Use what a built project has: real materials, planters of
  leaning blades, signs lit from above, light in the structure. Workers list the stand-ins
  they left under "still weak"; read that list before you accept a sheet.

After each session, log it (`make tokens`), so the next one can see what this cost.

## Viewer controls

`site/app.js`. Lessons that cost time to learn:

- **Orbit** with `rotateSpeed` 0.45 and `dampingFactor` 0.1, so a swipe doesn't spin the
  house. Double-tap flies to the spot at half the distance (clamped 3 to 12 m) over 0.6 s.
- **Walk starts where you are.** Keep the camera and its look, and level only the roll.
  Leaving Walk orbits a point 3 m ahead.
- **Look** is a YXZ Euler, pitch clamped to ±1.5. Track `clientX/Y` yourself, because iOS
  leaves `movementX` at 0 for touches. Look follows only the pointer that started it.
- **Stay level:** flatten the facing vector, and divide by `max(1, hypot(x, y))` so
  diagonals aren't faster.
- **Joystick** only on `(pointer: coarse)`: a 128 px disc and 48 px rim, analogue, with pointer capture.
- **Hold to speed up:** 1.5 m/s for 1.2 s, then a smoothstep to 3x over 2.5 s.
- **Double-tap** is your own detector (iOS sends no `dblclick`): 350 ms, 30 px, one finger.
  Skip glass. In Walk, a floor stands you on it at 1.6 m and a wall stops you 0.6 m short.
- **Touch hygiene:** `touch-action: none` while walking. Clear keys on `blur`.
- Portrait phones need a wider vertical FOV (72 vs 50). On a desktop, `setViewOffset`
  centers the picture beside the panel.
- Test in a browser, not by reading code. Headless renders under 20 fps, so test that speed
  rises over a hold rather than the absolute speed.

## Gotchas

- GLTFLoader strips dots from `object.name` (`door.operable` becomes `dooroperable`). Match
  nodes on `userData.name`, which keeps the original. Material names keep their dots.
- trimesh boxes share vertices. `unmerge_vertices()` before export, or faces shade smooth.
- trimesh writes no normals unless you ask. Without them three skips shadows with no
  warning. Export with `include_normals=True` and set flat vertex normals yourself
  (`np.repeat(face_normals, 3, axis=0)` on unmerged faces).
- Open3D's tensor mesh keeps one material. Build the raycast mesh from bare geometry.
- One RANSAC run on a house is a coin flip. Try several and keep the best ICP fitness.
- Coplanar faces z-fight, and here it showed as plaster-white stripes in the brick three
  times (party walls, the wing corner). Raycast the pixel to find the two faces
  (`window.viewer` is exposed for that), then give each wall its own volume.
- Headless WebGL can run at 5 fps, and the viewer caps each frame's step, so a 0.6 s
  flight takes seconds. Tests wait on state (`viewer.moving()`, `viewer.walkPace()`),
  never on fixed sleeps.
- A stair with n risers has n - 1 treads. The last step lands on the walk.
- Brick and other textures on a box-built model: project world position per face
  (no UVs needed), and set anisotropy or it shimmers at grazing angles.

Record what you learn here when it would have saved time.

Wersje

RepozytoriumWynikLicencja
Ta strona · kylefritz/3d-model-skill100MIT
yesith0106/craft3d100MIT

Migawka bazy z 13.11.2026 · wersja paczki f7cd094c4af6 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100web3d-model-viewer
    Osadza produkty 3D w stronie przez komponent model-viewer: AR na iOS i Androidzie, plakaty, hotspoty i warianty.
  • 100bigbangplanner
    Buduje interaktywny model 3D domu z planu i zdjęć, z chodzeniem w pierwszej osobie, pomiarami i widokiem pokoju.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.