canvas-js-3d 0.1.1 → 0.1.11
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/README.md +73 -32
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -10,6 +10,7 @@ A lightweight 3D graphics library that uses the Canvas API for wireframe renderi
|
|
|
10
10
|
- **Wireframe Rendering** - Canvas 2D-based edge rendering
|
|
11
11
|
- **Transform System** - Position, rotation, and scale
|
|
12
12
|
- **Frame Update Hook** - Per-frame logic with delta-time for framerate-independent animations
|
|
13
|
+
- **Scene Object System** - Manage multiple meshes with independent transforms
|
|
13
14
|
|
|
14
15
|
## Quick Start
|
|
15
16
|
|
|
@@ -19,55 +20,43 @@ A lightweight 3D graphics library that uses the Canvas API for wireframe renderi
|
|
|
19
20
|
npm install canvas-js-3d
|
|
20
21
|
```
|
|
21
22
|
|
|
22
|
-
###
|
|
23
|
+
### Setup (No Bundler Required)
|
|
24
|
+
|
|
25
|
+
This library works with ES6 modules and requires an import map to resolve the package without a bundler.
|
|
23
26
|
|
|
24
|
-
|
|
27
|
+
Create your HTML file:
|
|
25
28
|
|
|
26
29
|
```html
|
|
27
30
|
<!DOCTYPE html>
|
|
28
31
|
<html>
|
|
29
32
|
<head>
|
|
30
33
|
<title>canvas-js-3d Example</title>
|
|
34
|
+
<script type="importmap">
|
|
35
|
+
{
|
|
36
|
+
"imports": {
|
|
37
|
+
"canvas-js-3d": "./node_modules/canvas-js-3d/src/index.js"
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
</script>
|
|
31
41
|
</head>
|
|
32
42
|
<body>
|
|
33
|
-
<canvas id="canvas" width="
|
|
34
|
-
<script type="module" src="app.js"></script>
|
|
43
|
+
<canvas id="canvas" width="800" height="800"></canvas>
|
|
44
|
+
<script type="module" src="./app.js"></script>
|
|
35
45
|
</body>
|
|
36
46
|
</html>
|
|
37
47
|
```
|
|
38
48
|
|
|
39
|
-
|
|
40
|
-
// app.js
|
|
41
|
-
import { Engine, SceneObject, Transform, Vector3, WavefrontMeshConverter } from 'canvas-js-3d';
|
|
42
|
-
|
|
43
|
-
// Get canvas and create engine with foreground/background colors
|
|
44
|
-
const canvas = document.getElementById('canvas');
|
|
45
|
-
const engine = new Engine(canvas, 'green', 'black');
|
|
46
|
-
|
|
47
|
-
// Load an OBJ mesh from URL
|
|
48
|
-
const mesh = await WavefrontMeshConverter.fromUrl('./model.obj');
|
|
49
|
-
|
|
50
|
-
// Create a scene object with position, rotation, and scale
|
|
51
|
-
const obj = new SceneObject(
|
|
52
|
-
mesh,
|
|
53
|
-
new Transform(new Vector3(0, 0, 5), 0, 1) // position, rotation, scale
|
|
54
|
-
);
|
|
55
|
-
|
|
56
|
-
// Add to engine
|
|
57
|
-
engine.addSceneObject(obj);
|
|
58
|
-
|
|
59
|
-
// Animate: rotate the object each frame
|
|
60
|
-
engine.onUpdate = (deltaTime) => {
|
|
61
|
-
obj.transform.rotation += Math.PI * 0.5 * deltaTime;
|
|
62
|
-
};
|
|
49
|
+
**Important**: You must run a local server. The library won't work if you open the HTML file directly with `file://`. Use the included dev server:
|
|
63
50
|
|
|
64
|
-
|
|
65
|
-
|
|
51
|
+
```bash
|
|
52
|
+
npm run dev
|
|
66
53
|
```
|
|
67
54
|
|
|
68
|
-
|
|
55
|
+
Then open `http://localhost:8080` in your browser.
|
|
56
|
+
|
|
57
|
+
### Tutorial: Create a Rotating Cube
|
|
69
58
|
|
|
70
|
-
|
|
59
|
+
Create `app.js`:
|
|
71
60
|
|
|
72
61
|
```javascript
|
|
73
62
|
import { Engine, Mesh, SceneObject, Transform, Vector3 } from 'canvas-js-3d';
|
|
@@ -105,6 +94,41 @@ engine.onUpdate = (dt) => { cube.transform.rotation += dt; };
|
|
|
105
94
|
engine.start();
|
|
106
95
|
```
|
|
107
96
|
|
|
97
|
+
### Tutorial: Load and Render an OBJ
|
|
98
|
+
|
|
99
|
+
Here's an example that loads a 3D model from an OBJ file:
|
|
100
|
+
|
|
101
|
+
```javascript
|
|
102
|
+
// app.js
|
|
103
|
+
import { Engine, SceneObject, Transform, Vector3, WavefrontMeshConverter } from 'canvas-js-3d';
|
|
104
|
+
|
|
105
|
+
// Get canvas and create engine with foreground/background colors
|
|
106
|
+
const canvas = document.getElementById('canvas');
|
|
107
|
+
const engine = new Engine(canvas, 'green', 'black');
|
|
108
|
+
|
|
109
|
+
// Load an OBJ mesh from URL
|
|
110
|
+
const mesh = await WavefrontMeshConverter.fromUrl('./model.obj');
|
|
111
|
+
|
|
112
|
+
// Create a scene object with position, rotation, and scale
|
|
113
|
+
const obj = new SceneObject(
|
|
114
|
+
mesh,
|
|
115
|
+
new Transform(new Vector3(0, 0, 5), 0, 1) // position, rotation, scale
|
|
116
|
+
);
|
|
117
|
+
|
|
118
|
+
// Add to engine
|
|
119
|
+
engine.addSceneObject(obj);
|
|
120
|
+
|
|
121
|
+
// Animate: rotate the object each frame
|
|
122
|
+
engine.onUpdate = (deltaTime) => {
|
|
123
|
+
obj.transform.rotation += Math.PI * 0.5 * deltaTime;
|
|
124
|
+
};
|
|
125
|
+
|
|
126
|
+
// Start the render loop
|
|
127
|
+
engine.start();
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
Make sure `model.obj` is in the same directory as your HTML file, or adjust the path accordingly.
|
|
131
|
+
|
|
108
132
|
## Architecture
|
|
109
133
|
|
|
110
134
|
### Rendering Pipeline
|
|
@@ -220,6 +244,23 @@ const mesh = await WavefrontMeshConverter.fromFileDialog();
|
|
|
220
244
|
const mesh = WavefrontMeshConverter.fromText(objString);
|
|
221
245
|
```
|
|
222
246
|
|
|
247
|
+
## Troubleshooting
|
|
248
|
+
|
|
249
|
+
### "Failed to resolve module specifier" error
|
|
250
|
+
|
|
251
|
+
Make sure you have:
|
|
252
|
+
1. The import map in your HTML `<head>` (see Setup section above)
|
|
253
|
+
2. `type="module"` on your script tag
|
|
254
|
+
3. A local server running (not opening the file with `file://`)
|
|
255
|
+
|
|
256
|
+
### Canvas is blank
|
|
257
|
+
|
|
258
|
+
Check that:
|
|
259
|
+
1. Your canvas has width and height attributes
|
|
260
|
+
2. Objects are positioned at z > 0 (positive z is away from the camera)
|
|
261
|
+
3. The scale and rotation values are reasonable
|
|
262
|
+
4. `engine.start()` is called
|
|
263
|
+
|
|
223
264
|
## License
|
|
224
265
|
|
|
225
266
|
MIT
|