Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# The real models are plain binaries in git (no LFS): never converted, merged or diffed as text.
assets/built/*.glb binary
*.glb binary
13 changes: 13 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -7,3 +7,16 @@ dist/
.DS_Store
Thumbs.db
release/

# real models: the raw downloads are not in git (see scripts/assets and assets/models). The built files are not either, except those of the models a release
# carries (CC0, each pinned by hash in its manifest): they are committed as plain binaries (see .gitattributes), so a fresh clone can build and pack a release.
# A model held back from releases is never listed here.
assets/cache/
assets/built/*
!assets/built/alarm-clock.glb
!assets/built/bolt-cutters.glb
!assets/built/camera.glb
!assets/built/drill.glb
!assets/built/electric-motor.glb
!assets/built/measuring-tape.glb
!assets/built/mousetrap.glb
4 changes: 4 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ The app works on your real screen: be careful with `--visible-to-capture` and wi

The app's windows are hidden from screen capture only for the moment of its own screenshot (`src/main/capture-shield.ts`), so they show in a person's recordings and screen shares the rest of the time. `--visible-to-capture` keeps them in our own screenshots too, which is only for looking at a run. `node_modules/.bin/electron scripts/capture-check.cjs` (needs a visible window, so run it yourself, not in CI) checks that our drawing is absent from our capture and present otherwise, and finds how long the change needs to take effect on your machine.

## Real models

The 3D models of real things (a heart, a brain) are described by manifests in `assets/models`; their sources are fetched once into an ignored cache, never committed, and the finished files of the models a release carries (the CC0 objects) are committed in `assets/built` as plain binaries; see [docs/real-models.md](docs/real-models.md). Without them the app still runs: a scene that uses one of those models shows the stage without it and says so, and the tests that read a built file skip when it is absent.

## Testing

```
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Windows is the first platform. Mouse circling and model dragging have reported f

## Contribute

Talkthrough is open source under the [MIT license](LICENSE). The scene language, overlay, and adapters are documented in [CONTRIBUTING.md](CONTRIBUTING.md), [the scene language guide](docs/scene-language.md), and [the overlay notes](docs/overlay.md). Mac and Linux support are planned.
Talkthrough is open source under the [MIT license](LICENSE), which covers its code only: the real 3D models it can show are separate works under their own licences, named in [assets/CREDITS.md](assets/CREDITS.md), and are not part of the MIT grant. The scene language, overlay, and adapters are documented in [CONTRIBUTING.md](CONTRIBUTING.md), [the scene language guide](docs/scene-language.md), and [the overlay notes](docs/overlay.md). Mac and Linux support are planned.

For a development checkout, install Node.js 24 or newer, then run:

Expand Down
130 changes: 130 additions & 0 deletions assets/CREDITS.md

Large diffs are not rendered by default.

Binary file added assets/built/alarm-clock.glb
Binary file not shown.
Binary file added assets/built/bolt-cutters.glb
Binary file not shown.
Binary file added assets/built/camera.glb
Binary file not shown.
Binary file added assets/built/drill.glb
Binary file not shown.
Binary file added assets/built/electric-motor.glb
Binary file not shown.
Binary file added assets/built/measuring-tape.glb
Binary file not shown.
Binary file added assets/built/mousetrap.glb
Binary file not shown.
221 changes: 221 additions & 0 deletions assets/models/alarm-clock.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,221 @@
{
"id": "alarm-clock",
"name": "Alarm clock",
"description": "A twin-bell alarm clock with its glass, hour, minute and second hands, as a textured model",
"aliases": [
"alarm clock",
"clock",
"bedside clock"
],
"format": "gltf",
"licence": {
"id": "CC0-1.0",
"version": "1.0",
"statedOn": "https://polyhaven.com/license",
"statement": "Our assets are all licensed as CC0. You do not need to give credit."
},
"source": {
"name": "Poly Haven",
"url": "https://polyhaven.com/a/alarm_clock_01",
"version": "Alarm Clock 01, 1k glTF, published 2021-08-13",
"authors": [
"Yann Kervran (rigging)",
"James Ray Cock (modelling and texturing)"
],
"cacheFolder": "ph-alarm-clock-01"
},
"retrieved": "2026-11-08",
"changes": "Passed through: geometry, UV coordinates, materials and the 1k textures are the source's own, unchanged. Added: a root that puts the model on the scene's axes, in metres, centred on its own middle, and a tag on each named part.",
"orient": {
"up": "y+",
"front": "z+"
},
"scale": {
"unitsToMetres": 1
},
"caveats": [],
"files": [
{
"entry": "alarm_clock_01.bin",
"url": "https://dl.polyhaven.org/file/ph-assets/Models/gltf/8k/alarm_clock_01/alarm_clock_01.bin",
"bytes": 284408,
"sha256": "74b589dc31596fe9350e8ef6d123571955d58cee9955060d831fa0f3055758c6"
},
{
"entry": "alarm_clock_01_1k.gltf",
"url": "https://dl.polyhaven.org/file/ph-assets/Models/gltf/1k/alarm_clock_01/alarm_clock_01_1k.gltf",
"bytes": 10056,
"sha256": "ca16e83e334e28f8eaf2bf1fbf8ce043b7e4fe5d0e171d01a264b12f5f42a78c"
},
{
"entry": "textures/alarm_clock_01_arm_1k.jpg",
"url": "https://dl.polyhaven.org/file/ph-assets/Models/jpg/1k/alarm_clock_01/alarm_clock_01_arm_1k.jpg",
"bytes": 538163,
"sha256": "99727eb8908dfea5aac2a2353af7ff60857e40c50b396d7efbe15df685fe4918"
},
{
"entry": "textures/alarm_clock_01_diff_1k.jpg",
"url": "https://dl.polyhaven.org/file/ph-assets/Models/jpg/1k/alarm_clock_01/alarm_clock_01_diff_1k.jpg",
"bytes": 404998,
"sha256": "deb82094c2c1aa8cda0a0ce7192b193a81c5376743344503764abbcd2db19ac1"
},
{
"entry": "textures/alarm_clock_01_nor_gl_1k.jpg",
"url": "https://dl.polyhaven.org/file/ph-assets/Models/jpg/1k/alarm_clock_01/alarm_clock_01_nor_gl_1k.jpg",
"bytes": 420026,
"sha256": "a0a7b35de5712e23d06832e49516ec0e1170aa159eb60ec9b2af0b0df2102fa4"
}
],
"parts": [
{
"key": "body",
"name": "Clock body and glass",
"aliases": [
"clock body",
"case",
"face"
],
"confidence": "atlas",
"nodes": [
"alarm_clock_01"
]
},
{
"key": "hour-hand",
"name": "Hour hand",
"aliases": [
"hour hand",
"short hand"
],
"confidence": "atlas",
"nodes": [
"houd_hand"
],
"hub": "node",
"explode": [
0,
0,
0.012
]
},
{
"key": "minute-hand",
"name": "Minute hand",
"aliases": [
"minute hand",
"long hand"
],
"confidence": "atlas",
"nodes": [
"minute_hand"
],
"hub": "node",
"explode": [
0,
0,
0.024
]
},
{
"key": "second-hand",
"name": "Second hand",
"aliases": [
"second hand"
],
"confidence": "atlas",
"nodes": [
"second_hand"
],
"hub": "node",
"explode": [
0,
0,
0.036
]
}
],
"built": {
"file": "alarm-clock.glb",
"bytes": 3017188,
"sha256": "783a73ee344b333a8a878d2a02254fe47f1622aef8752a0aaa014c00c63a3096",
"triangles": 8985,
"size": [
0.131651,
0.174155,
0.066749
],
"parts": {
"body": {
"center": [
0,
0,
0
],
"size": [
0.131651,
0.174155,
0.066749
],
"closed": false,
"triangles": 8560
},
"hour-hand": {
"center": [
0.00588,
-0.039252,
0.016068
],
"size": [
0.02046,
0.0447,
0.000593
],
"closed": false,
"triangles": 200,
"hub": [
0,
-0.021252,
-0.009132
]
},
"minute-hand": {
"center": [
-0.021117,
-0.010284,
0.015462
],
"size": [
0.050875,
0.030578,
0.000602
],
"closed": false,
"triangles": 152,
"hub": [
0,
-0.021252,
-0.009132
]
},
"second-hand": {
"center": [
0.009105,
0.001433,
0.015015
],
"size": [
0.024956,
0.052116,
0.000158
],
"closed": false,
"triangles": 73,
"hub": [
0,
-0.021252,
-0.009132
]
}
}
}
}
109 changes: 109 additions & 0 deletions assets/models/bolt-cutters.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
{
"id": "bolt-cutters",
"name": "Bolt cutters",
"description": "Long-handled bolt cutters, as one textured object",
"aliases": [
"bolt cutters",
"bolt cutter",
"bolt croppers"
],
"format": "gltf",
"licence": {
"id": "CC0-1.0",
"version": "1.0",
"statedOn": "https://polyhaven.com/license",
"statement": "Our assets are all licensed as CC0. You do not need to give credit."
},
"source": {
"name": "Poly Haven",
"url": "https://polyhaven.com/a/bolt_cutters_01",
"version": "Bolt Cutters 01, 1k glTF, published 2022-12-02",
"authors": [
"Yann Kervran (rigging)",
"Antanas Kep (modelling and texturing)"
],
"cacheFolder": "ph-bolt-cutters-01"
},
"retrieved": "2026-11-08",
"changes": "Passed through: geometry, UV coordinates, materials and the 1k textures are the source's own, unchanged. Added: a root that puts the model on the scene's axes, in metres, centred on its own middle, and a tag on each named part.",
"orient": {
"up": "y+",
"front": "z+"
},
"scale": {
"unitsToMetres": 1
},
"caveats": [
"A single scanned or modelled object: it can be labelled as a whole, but has no named parts to cut or take apart."
],
"files": [
{
"entry": "bolt_cutters_01.bin",
"url": "https://dl.polyhaven.org/file/ph-assets/Models/gltf/4k/bolt_cutters_01/bolt_cutters_01.bin",
"bytes": 94700,
"sha256": "ca59727481d2edca3a3177966d816c2e074f7ee182cef94b7fc4b67d6ded8aa2"
},
{
"entry": "bolt_cutters_01_1k.gltf",
"url": "https://dl.polyhaven.org/file/ph-assets/Models/gltf/1k/bolt_cutters_01/bolt_cutters_01_1k.gltf",
"bytes": 2797,
"sha256": "eedd7c98341e85013c753af0406bac3b58d4e485a2730e611c08dcb4cc2f3a81"
},
{
"entry": "textures/bolt_cutters_01_arm_1k.jpg",
"url": "https://dl.polyhaven.org/file/ph-assets/Models/jpg/1k/bolt_cutters_01/bolt_cutters_01_arm_1k.jpg",
"bytes": 810127,
"sha256": "1335d3c5e266be103dcf983c34450213d23796d66b1c7ba0bfc1026ee77041b2"
},
{
"entry": "textures/bolt_cutters_01_diff_1k.jpg",
"url": "https://dl.polyhaven.org/file/ph-assets/Models/jpg/1k/bolt_cutters_01/bolt_cutters_01_diff_1k.jpg",
"bytes": 777857,
"sha256": "e525175e4e94d2e7800dd24e8f1005ae0b34b06572cd71ef144b5fabe245fb24"
},
{
"entry": "textures/bolt_cutters_01_nor_gl_1k.jpg",
"url": "https://dl.polyhaven.org/file/ph-assets/Models/jpg/1k/bolt_cutters_01/bolt_cutters_01_nor_gl_1k.jpg",
"bytes": 812150,
"sha256": "49228dda2096f76534907f3b93b632a5129eda96d48e4102565fdb84ca74a5f1"
}
],
"parts": [
{
"key": "whole",
"name": "Bolt cutters",
"aliases": [],
"confidence": "atlas",
"nodes": [
"bolt_cutters_01"
]
}
],
"built": {
"file": "bolt-cutters.glb",
"bytes": 2496808,
"sha256": "470c491d351b1bf2831d69511bcdb18a01243a5eaf8881db0de84874f13217a0",
"triangles": 3410,
"size": [
0.151046,
0.802581,
0.036027
],
"parts": {
"whole": {
"center": [
0,
0,
0
],
"size": [
0.151046,
0.802581,
0.036027
],
"closed": false,
"triangles": 3410
}
}
}
}
Loading
Loading