@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 +21 -0
- package/LICENSES/README.md +19 -0
- package/LICENSES/mesh-effects-MIT.txt +21 -0
- package/LICENSES/three-MIT.txt +21 -0
- package/README.md +166 -2
- package/dist/img-3d-xuastc.js +825 -0
- package/dist/img-3d.js +574 -0
- package/package.json +66 -4
- package/src/runtime.d.ts +64 -0
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
|
-
#
|
|
1
|
+
# Image 3D
|
|
2
2
|
|
|
3
|
-
|
|
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)
|