@needle-tools/image-3d 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Needle Tools
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,19 @@
1
+ # Notices
2
+
3
+ Third-party notices for the Image 3D runtime.
4
+
5
+ The standalone runtime and surface-search code were extracted from Needle's
6
+ Mesh Effects project and retain its [MIT notice](mesh-effects-MIT.txt).
7
+
8
+ Studio shading follows Three.js's IBL and ACES math. The compact RoomEnvironment
9
+ asset contains resampled PMREM and BRDF integration data. These retain the
10
+ [Three.js MIT notice](three-MIT.txt); Three.js is not a browser runtime dependency.
11
+
12
+ The optional XUASTC entry incorporates Basis Universal (Apache-2.0) and
13
+ Zstandard (BSD). Their source revision, build flags and artifact checksums are
14
+ pinned in `src/xuastc/source.json`; licenses and notices are beside that file
15
+ and embedded in the distributed decoder entry. The development-only Basis
16
+ transcoder under `tools/basis/` retains its upstream notice in the JavaScript.
17
+
18
+ The glTF format adapter, native conversion helpers, test metrics and demo tools
19
+ are Needle-authored code extracted for this standalone project.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Needle Tools
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,21 @@
1
+ The MIT License
2
+
3
+ Copyright © 2010-2026 three.js authors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,167 @@
1
- # Temporary Holding Version
1
+ # Image 3D
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Display an interactive 3D capture with a regular HTML image and one JavaScript file. The browser runtime has no dependencies and uses WebGPU or WebGL 2.
4
+
5
+ ## Quick start: use an `<img>`
6
+
7
+ Place `img-3d.js` and your capture on your website, then add `data-img-3d` to the image:
8
+
9
+ ```html
10
+ <script type="module" src="./img-3d.js"></script>
11
+ <img data-img-3d src="./model.webp" alt="Product">
12
+ ```
13
+
14
+ The WebP contains both a normal image and the 3D capture. The browser displays the image first; the script adds drag-to-rotate interaction when the capture is ready. Without JavaScript, the image still displays normally. Printing also uses the image.
15
+
16
+ Use a WebP packaged for Image 3D, such as the included [owl capture](demo/public/owl-512-i3d/live.webp), or [create a capture](#create-a-capture). Regular image resizing and re-encoding can remove the embedded 3D data, so serve the packaged file unchanged.
17
+
18
+ ## Size it like an image
19
+
20
+ Use the usual image attributes and CSS. `width` and `height` reserve space while the image loads; `max-width` and `height: auto` make it fit smaller screens.
21
+
22
+ ```html
23
+ <img data-img-3d src="./model.webp" alt="Product"
24
+ width="400" height="400"
25
+ style="max-width:100%;height:auto">
26
+ ```
27
+
28
+ Set `width` and `height` to the actual dimensions of your WebP. No special layout CSS is required for the 3D view. The runtime keeps it aligned with the image.
29
+
30
+ Native `srcset`, `sizes` and `<picture>` work too. For example, using the two included owl captures:
31
+
32
+ ```html
33
+ <img data-img-3d src="./demo/public/owl-512-i3d/live.webp" alt="Owl"
34
+ srcset="./demo/public/owl-512-i3d/live.webp 464w,
35
+ ./demo/public/owl-1024-i3d/live.webp 956w"
36
+ sizes="(max-width:400px) 100vw, 400px"
37
+ width="464" height="872"
38
+ style="width:100%;max-width:400px;height:auto">
39
+ ```
40
+
41
+ The browser chooses the file, and the 3D view uses that same file. The `w` values are the WebPs' actual pixel widths; the packaging tool prints them for you.
42
+
43
+ To enhance a whole `<picture>`, put `data-img-3d` on the `<picture>` instead of its `<img>`.
44
+
45
+ ## Control the view with JavaScript
46
+
47
+ You can also enhance an image already on the page:
48
+
49
+ ```html
50
+ <img id="product" src="./model.webp" alt="Product">
51
+
52
+ <script type="module">
53
+ import {enhanceImage} from './img-3d.js';
54
+
55
+ const preview = enhanceImage(document.querySelector('#product'));
56
+ preview.element.yaw = 0.8;
57
+ preview.element.pitch = 0.2;
58
+ await preview.element.draw();
59
+ </script>
60
+ ```
61
+
62
+ `yaw` and `pitch` are in radians. `distance` controls zoom. Call `draw()` after changing these settings. Call `preview.disconnect()` to restore the plain image. The same API is available when the image was enhanced automatically with `data-img-3d`.
63
+
64
+ ## Use the `<img-3d>` element
65
+
66
+ For a dedicated 3D element, use `<img-3d>` with a `.i3d` capture or a packaged WebP. Load the same `img-3d.js` script as above.
67
+
68
+ ```html
69
+ <style>
70
+ img-3d {
71
+ display: block;
72
+ width: 300px;
73
+ height: 300px;
74
+ }
75
+ </style>
76
+
77
+ <img-3d src="./model.i3d" alt="Product"></img-3d>
78
+ ```
79
+
80
+ The CSS gives the custom element a size before JavaScript loads, so the page doesn't shift when it appears. This is only needed for the custom element; a regular `<img>` already has native image sizing.
81
+
82
+ Both forms support `object-fit` and `object-position`. Framing stays fixed while rotating by default. Add `data-orbit-fit="auto"` to let the frame expand for wider viewing angles.
83
+
84
+ Drag or use the arrow keys to rotate, use `+`, `-` or Alt+wheel to zoom, and double-click or press Home to reset. Vertical touch gestures allow page scrolling.
85
+
86
+ See the [runtime API and capture format](docs/format.md) for lighting, responsive `.i3d` sources and other options.
87
+
88
+ ## Create a capture
89
+
90
+ Create and host Image 3D captures with [Needle Cloud](https://cloud.needle.tools).
91
+ Upload your 3D asset, generate an Image3D variant, and use its WebP URL in your
92
+ `<img data-img-3d>` element. Cloud handles capture generation and hosting.
93
+
94
+ ### Local conversion
95
+
96
+ The following commands run from a checkout of this repository with its development
97
+ dependencies installed.
98
+
99
+ The converter takes a GLB containing [`NEEDLE_box_impostor`](https://needle.click/mesh-baker) capture data, with uncompressed PNG capture maps. Animated inputs must be frozen first. It does not convert an ordinary mesh or photograph into a 3D capture.
100
+
101
+ ```sh
102
+ npm run convert -- capture.glb output --webp
103
+ ```
104
+
105
+ This writes `output/model.i3d` and `output/model.webp`, and prints the image dimensions. WebP poster generation requires Chrome. You can also package an existing `.i3d` file:
106
+
107
+ ```sh
108
+ node tools/package-image.mjs capture.i3d model.webp
109
+ ```
110
+
111
+ Add `--poster image.webp` to provide your own poster. Its camera view, framing and dimensions should match the capture. To check the converted capture:
112
+
113
+ ```sh
114
+ npm run validate -- output --dense
115
+ ```
116
+
117
+ ## Try the demo
118
+
119
+ After installing dependencies, start the demo:
120
+
121
+ ```sh
122
+ npm run dev
123
+ ```
124
+
125
+ Open the printed URL to rotate the included models and try different lighting and resolutions. Copy the URL to share the selected settings and camera.
126
+
127
+ ## Development and reference
128
+
129
+ Run `npm test` for the automated checks. Browser tests require Chrome and run sequentially.
130
+
131
+ - [Runtime API and capture format](docs/format.md)
132
+ - [Rendering measurements](docs/measurements.md)
133
+ - [Third-party licenses and notices](LICENSES/README.md)
134
+
135
+ ## Optional: XUASTC compression
136
+
137
+ Captures encoded with XUASTC can use compressed GPU textures. For these files, load `img-3d-xuastc.js` instead of `img-3d.js`:
138
+
139
+ ```html
140
+ <script type="module" src="./img-3d-xuastc.js"></script>
141
+ <img data-img-3d src="./model-xuastc.webp" alt="Product">
142
+ ```
143
+
144
+ The XUASTC entry includes the decoder and WebAssembly in one JavaScript file. The HTML and camera API stay the same.
145
+
146
+ To encode an existing conversion, install the Basis Universal encoder and pass its executable to the compression tool:
147
+
148
+ ```sh
149
+ node tools/xuastc.mjs output compressed-output /path/to/basisu
150
+ npm run validate -- compressed-output --dense
151
+ ```
152
+
153
+ To package an XUASTC capture as WebP, use `node tools/package-image.mjs capture.i3d model-xuastc.webp --xuastc`.
154
+
155
+ ## Technical note: how the WebP file loads
156
+
157
+ An Image 3D WebP is a regular WebP image. Its image data comes first, allowing the browser to decode and display it while the rest of the file is still downloading. This follows the [WebP container specification's ordering for streaming image data](https://developers.google.com/speed/webp/docs/riff_container#extended_file_format).
158
+
159
+ The 3D capture is embedded sidecar data in an `I3D1` RIFF chunk after the image, inside the same `.webp` file. The [WebP specification allows application-specific chunks](https://developers.google.com/speed/webp/docs/riff_container#unknown_chunks), which ordinary image readers can ignore. Image 3D reads this extra data to render the interactive view. See the [Image 3D WebP package format](docs/format.md#webp-image-package) for its layout.
160
+
161
+ For programmatic shared-camera scenes and opt-in progressive loading, see [scene loading](docs/scenes.md).
162
+
163
+ ## Contact
164
+
165
+ Questions or feedback? Email [hi@needle.tools](mailto:hi@needle.tools).
166
+
167
+ [Needle](https://needle.tools) | [GitHub](https://github.com/needle-tools) | [Discord](https://discord.needle.tools) | [Forum](https://forum.needle.tools)