anchi-toolkit 1.0.0 → 1.2.1

package/dist/.cursor/skills/threejs/references/15-specialized-loaders.md

@@ -0,0 +1,333 @@
+# Specialized Loaders
+
+Domain-specific file format loaders.
+
+## SVG Loader
+
+Load and extrude SVG paths:
+
+```javascript
+import { SVGLoader } from 'three/addons/loaders/SVGLoader.js';
+
+const loader = new SVGLoader();
+loader.load('image.svg', (data) => {
+  const paths = data.paths;
+  const group = new THREE.Group();
+
+  paths.forEach((path) => {
+    const material = new THREE.MeshBasicMaterial({
+      color: path.color,
+      side: THREE.DoubleSide,
+      depthWrite: false
+    });
+
+    const shapes = SVGLoader.createShapes(path);
+    shapes.forEach((shape) => {
+      const geometry = new THREE.ShapeGeometry(shape);
+      const mesh = new THREE.Mesh(geometry, material);
+      group.add(mesh);
+    });
+  });
+
+  // Extrude SVG
+  paths.forEach((path) => {
+    const shapes = SVGLoader.createShapes(path);
+    const geometry = new THREE.ExtrudeGeometry(shapes, {
+      depth: 10,
+      bevelEnabled: false
+    });
+    const mesh = new THREE.Mesh(geometry, material);
+    group.add(mesh);
+  });
+
+  scene.add(group);
+});
+```
+
+## Collada (.dae) Loader
+
+XML-based format from Blender, SketchUp:
+
+```javascript
+import { ColladaLoader } from 'three/addons/loaders/ColladaLoader.js';
+
+const loader = new ColladaLoader();
+loader.load('model.dae', (collada) => {
+  const model = collada.scene;
+  scene.add(model);
+
+  // Access animations
+  const animations = collada.animations;
+  const mixer = new THREE.AnimationMixer(model);
+  animations.forEach(clip => mixer.clipAction(clip).play());
+});
+```
+
+## STL Loader
+
+3D printing format:
+
+```javascript
+import { STLLoader } from 'three/addons/loaders/STLLoader.js';
+
+const loader = new STLLoader();
+loader.load('model.stl', (geometry) => {
+  const material = new THREE.MeshPhongMaterial({ color: 0xff5533 });
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+
+  // STL doesn't include normals, compute them
+  geometry.computeVertexNormals();
+});
+```
+
+## 3MF Loader
+
+Modern 3D printing format:
+
+```javascript
+import { 3MFLoader } from 'three/addons/loaders/3MFLoader.js';
+
+const loader = new 3MFLoader();
+loader.load('model.3mf', (object) => {
+  scene.add(object);
+});
+```
+
+## VRML/X3D Loader
+
+Virtual Reality Modeling Language:
+
+```javascript
+import { VRMLLoader } from 'three/addons/loaders/VRMLLoader.js';
+
+const loader = new VRMLLoader();
+loader.load('model.wrl', (object) => {
+  scene.add(object);
+});
+```
+
+## PDB Loader
+
+Protein Data Bank (chemistry/molecular):
+
+```javascript
+import { PDBLoader } from 'three/addons/loaders/PDBLoader.js';
+
+const loader = new PDBLoader();
+loader.load('molecule.pdb', (pdb) => {
+  const geometryAtoms = pdb.geometryAtoms;
+  const geometryBonds = pdb.geometryBonds;
+  const json = pdb.json;
+
+  // Render atoms as spheres
+  const material = new THREE.MeshPhongMaterial({ color: 0xffffff });
+  const atoms = new THREE.Mesh(geometryAtoms, material);
+  scene.add(atoms);
+
+  // Render bonds as cylinders
+  const bondMaterial = new THREE.MeshPhongMaterial({ color: 0xcccccc });
+  const bonds = new THREE.Mesh(geometryBonds, bondMaterial);
+  scene.add(bonds);
+});
+```
+
+## LDraw Loader
+
+LEGO models:
+
+```javascript
+import { LDrawLoader } from 'three/addons/loaders/LDrawLoader.js';
+
+const loader = new LDrawLoader();
+loader.setPath('ldraw/');
+
+loader.load('model.mpd', (group) => {
+  scene.add(group);
+
+  // Smooth LEGO bricks
+  group.traverse((child) => {
+    if (child.isMesh) {
+      child.material.flatShading = false;
+    }
+  });
+});
+```
+
+## VTK Loader
+
+Visualization Toolkit (scientific data):
+
+```javascript
+import { VTKLoader } from 'three/addons/loaders/VTKLoader.js';
+
+const loader = new VTKLoader();
+loader.load('model.vtk', (geometry) => {
+  geometry.computeVertexNormals();
+  const material = new THREE.MeshStandardMaterial();
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+});
+```
+
+## PLY Loader
+
+Polygon file format (scanned 3D data):
+
+```javascript
+import { PLYLoader } from 'three/addons/loaders/PLYLoader.js';
+
+const loader = new PLYLoader();
+loader.load('model.ply', (geometry) => {
+  geometry.computeVertexNormals();
+
+  // Check if has vertex colors
+  const material = geometry.attributes.color ?
+    new THREE.MeshStandardMaterial({ vertexColors: true }) :
+    new THREE.MeshStandardMaterial({ color: 0x888888 });
+
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+});
+```
+
+## 3DS Loader
+
+3DS Max format:
+
+```javascript
+import { TDSLoader } from 'three/addons/loaders/TDSLoader.js';
+
+const loader = new TDSLoader();
+loader.load('model.3ds', (object) => {
+  scene.add(object);
+});
+```
+
+## USDZ Loader/Exporter
+
+Apple's AR format:
+
+```javascript
+// Export to USDZ (for iOS AR)
+import { USDZExporter } from 'three/addons/exporters/USDZExporter.js';
+
+const exporter = new USDZExporter();
+const arraybuffer = await exporter.parse(scene);
+const blob = new Blob([arraybuffer], { type: 'application/octet-stream' });
+
+// Download or serve for AR Quick Look
+const link = document.createElement('a');
+link.href = URL.createObjectURL(blob);
+link.download = 'model.usdz';
+link.click();
+```
+
+## Font Loader (Text)
+
+Load fonts for 3D text:
+
+```javascript
+import { FontLoader } from 'three/addons/loaders/FontLoader.js';
+import { TextGeometry } from 'three/addons/geometries/TextGeometry.js';
+
+const fontLoader = new FontLoader();
+fontLoader.load('fonts/helvetiker_regular.typeface.json', (font) => {
+  const geometry = new TextGeometry('Hello World', {
+    font: font,
+    size: 80,
+    height: 5,
+    curveSegments: 12,
+    bevelEnabled: true,
+    bevelThickness: 10,
+    bevelSize: 8,
+    bevelSegments: 5
+  });
+
+  const material = new THREE.MeshPhongMaterial({ color: 0x00ff00 });
+  const mesh = new THREE.Mesh(geometry, material);
+  scene.add(mesh);
+});
+```
+
+## EXR Loader
+
+High dynamic range images:
+
+```javascript
+import { EXRLoader } from 'three/addons/loaders/EXRLoader.js';
+
+const loader = new EXRLoader();
+loader.load('env.exr', (texture) => {
+  texture.mapping = THREE.EquirectangularReflectionMapping;
+
+  scene.background = texture;
+  scene.environment = texture;
+});
+```
+
+## RGBE/HDR Loader
+
+HDR environment maps:
+
+```javascript
+import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
+
+const loader = new RGBELoader();
+loader.load('env.hdr', (texture) => {
+  texture.mapping = THREE.EquirectangularReflectionMapping;
+
+  scene.background = texture;
+  scene.environment = texture;
+
+  // Use with PMREM generator for better quality
+  const pmremGenerator = new THREE.PMREMGenerator(renderer);
+  const envMap = pmremGenerator.fromEquirectangular(texture).texture;
+  scene.environment = envMap;
+  texture.dispose();
+  pmremGenerator.dispose();
+});
+```
+
+## Basis/KTX2 Texture Loader
+
+GPU-optimized texture compression:
+
+```javascript
+import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
+
+const loader = new KTX2Loader();
+loader.setTranscoderPath('basis/');
+loader.detectSupport(renderer);
+
+loader.load('texture.ktx2', (texture) => {
+  material.map = texture;
+  material.needsUpdate = true;
+});
+```
+
+## Common Patterns
+
+```javascript
+// Load with progress
+loader.load(
+  'file.ext',
+  (result) => { /* success */ },
+  (xhr) => {
+    const percent = (xhr.loaded / xhr.total * 100);
+    console.log(`${percent}% loaded`);
+  },
+  (error) => { /* error */ }
+);
+
+// Center imported model
+const box = new THREE.Box3().setFromObject(model);
+const center = box.getCenter(new THREE.Vector3());
+model.position.sub(center);
+
+// Scale to fit
+const size = box.getSize(new THREE.Vector3());
+const maxDim = Math.max(size.x, size.y, size.z);
+const scale = 10 / maxDim;
+model.scale.setScalar(scale);
+```

package/dist/.cursor/skills/threejs/references/16-webgpu.md

@@ -0,0 +1,302 @@
+# WebGPU Rendering
+
+Modern GPU API for next-generation graphics.
+
+## WebGPU Renderer
+
+Next-generation rendering backend:
+
+```javascript
+import WebGPU from 'three/addons/capabilities/WebGPU.js';
+import WebGPURenderer from 'three/addons/renderers/webgpu/WebGPURenderer.js';
+
+// Check support
+if (WebGPU.isAvailable()) {
+  const renderer = new WebGPURenderer();
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  document.body.appendChild(renderer.domElement);
+
+  // Use setAnimationLoop (not requestAnimationFrame)
+  renderer.setAnimationLoop(() => {
+    renderer.render(scene, camera);
+  });
+} else {
+  const warning = WebGPU.getErrorMessage();
+  document.body.appendChild(warning);
+}
+```
+
+## Benefits of WebGPU
+
+- Better performance (lower CPU overhead)
+- Compute shaders
+- Modern GPU features
+- Unified shading language (WGSL)
+- Better multi-threading support
+- More predictable behavior
+
+## Compute Shaders
+
+GPU-accelerated computation:
+
+```javascript
+import { storageBuffer, uniform, Fn } from 'three/nodes';
+import { StorageBufferAttribute } from 'three/addons/renderers/common/StorageBufferAttribute.js';
+
+// Create storage buffer
+const particleCount = 10000;
+const positionBuffer = new StorageBufferAttribute(particleCount * 3, 3);
+
+// Fill initial positions
+for (let i = 0; i < particleCount; i++) {
+  positionBuffer.setXYZ(
+    i,
+    Math.random() * 10 - 5,
+    Math.random() * 10 - 5,
+    Math.random() * 10 - 5
+  );
+}
+
+// Create compute shader
+const computeParticles = Fn(() => {
+  const position = storageBuffer(positionBuffer);
+  const time = uniform('time', 0);
+  const index = instanceIndex;
+
+  // Update position
+  const pos = position.element(index);
+  pos.y.addAssign(sin(time.add(index)).mul(0.01));
+
+  // Wrap around
+  If(pos.y.greaterThan(5), () => {
+    pos.y.assign(-5);
+  });
+})();
+
+// Create compute node
+const computeNode = computeParticles.compute(particleCount);
+
+// Execute in render loop
+renderer.setAnimationLoop(() => {
+  renderer.compute(computeNode);
+  renderer.render(scene, camera);
+});
+```
+
+## Storage Buffers
+
+GPU-accessible memory:
+
+```javascript
+import { storage, Fn, vec3, float } from 'three/nodes';
+
+// Define storage buffer structure
+const particleData = storage(
+  new THREE.StorageBufferAttribute(count * 7, 7), // 7 floats per particle
+  'vec3', // position
+  'vec3', // velocity
+  'float' // life
+);
+
+// Access in compute shader
+const updateParticle = Fn(() => {
+  const data = particleData.element(instanceIndex);
+  const position = data.xyz;
+  const velocity = data.toVec3(3); // offset 3
+  const life = data.element(6);
+
+  // Update
+  position.addAssign(velocity.mul(deltaTime));
+  life.subAssign(deltaTime);
+})();
+```
+
+## WebGPU Node Materials
+
+Use TSL (Three Shading Language) with WebGPU:
+
+```javascript
+import { MeshStandardNodeMaterial, texture, normalMap } from 'three/nodes';
+
+const material = new MeshStandardNodeMaterial();
+
+// Node-based material definition
+material.colorNode = texture(diffuseTexture);
+material.normalNode = normalMap(normalTexture);
+material.roughnessNode = float(0.5);
+material.metalnessNode = float(0.8);
+
+// Works with both WebGL and WebGPU automatically
+```
+
+## Indirect Drawing
+
+Efficient rendering with compute-generated draw calls:
+
+```javascript
+import { IndirectStorageBufferAttribute } from 'three/addons/renderers/common/IndirectStorageBufferAttribute.js';
+
+// Create indirect buffer
+const indirectBuffer = new IndirectStorageBufferAttribute(count, 5);
+// 5 elements: count, instanceCount, first, baseInstance, (padding)
+
+// Update with compute shader
+const updateIndirect = Fn(() => {
+  const indirect = storage(indirectBuffer);
+  // Compute visibility and update instance count
+  const visible = computeVisibility();
+  If(visible, () => {
+    indirect.element(1).addAssign(1); // increment instanceCount
+  });
+})();
+
+// Render using indirect buffer
+renderer.drawIndirect(mesh, indirectBuffer);
+```
+
+## Multi-Render-Target (MRT)
+
+Render to multiple textures simultaneously:
+
+```javascript
+import { WebGPURenderTarget } from 'three/addons/renderers/webgpu/WebGPURenderTarget.js';
+
+const renderTarget = new WebGPURenderTarget(width, height, {
+  count: 3, // number of render targets
+  format: THREE.RGBAFormat
+});
+
+// Access individual textures
+const albedoTexture = renderTarget.textures[0];
+const normalTexture = renderTarget.textures[1];
+const depthTexture = renderTarget.textures[2];
+
+// Use in deferred rendering pipeline
+renderer.setRenderTarget(renderTarget);
+renderer.render(scene, camera);
+```
+
+## Async Shader Compilation
+
+Avoid frame drops:
+
+```javascript
+// Compile materials ahead of time
+await renderer.compileAsync(scene, camera);
+
+// Start rendering after compilation
+renderer.setAnimationLoop(() => {
+  renderer.render(scene, camera);
+});
+```
+
+## Performance Monitoring
+
+GPU timestamp queries:
+
+```javascript
+// Query GPU timing
+const timestampQuery = renderer.getTimestampQuery();
+
+timestampQuery.begin();
+renderer.render(scene, camera);
+timestampQuery.end();
+
+timestampQuery.getResult().then((duration) => {
+  console.log(`GPU time: ${duration}ms`);
+});
+```
+
+## WebGPU-Specific Features
+
+### Texture Compression
+
+```javascript
+// BC7 compression (higher quality)
+const texture = new THREE.CompressedTexture(
+  mipmaps,
+  width,
+  height,
+  THREE.RGBA_BPTC_Format
+);
+```
+
+### Depth Textures
+
+```javascript
+const depthTexture = new THREE.DepthTexture(width, height);
+depthTexture.type = THREE.FloatType; // 32-bit depth
+depthTexture.format = THREE.DepthFormat;
+```
+
+### Storage Textures
+
+```javascript
+import { storageTexture } from 'three/nodes';
+
+// Read-write texture in compute shader
+const writeableTexture = storageTexture(texture);
+
+const computeShader = Fn(() => {
+  const coord = vec2(instanceIndex % width, instanceIndex / width);
+  const color = vec4(1, 0, 0, 1);
+  writeableTexture.store(coord, color);
+})();
+```
+
+## Migration from WebGL
+
+Most Three.js code works with both:
+
+```javascript
+// WebGL
+const renderer = new THREE.WebGLRenderer();
+
+// WebGPU (drop-in replacement for most cases)
+const renderer = new WebGPURenderer();
+
+// Exceptions:
+// - Custom shaders: need to use Node materials or WGSL
+// - Some extensions not available
+// - Compute shaders only in WebGPU
+```
+
+## WGSL (WebGPU Shading Language)
+
+Native shader language for WebGPU:
+
+```wgsl
+@group(0) @binding(0) var<storage, read_write> positions: array<vec3f>;
+@group(0) @binding(1) var<uniform> time: f32;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) global_id: vec3u) {
+  let index = global_id.x;
+  if (index >= arrayLength(&positions)) {
+    return;
+  }
+
+  var pos = positions[index];
+  pos.y += sin(time + f32(index)) * 0.01;
+  positions[index] = pos;
+}
+```
+
+## Browser Support
+
+As of 2025:
+- ✅ Chrome 113+
+- ✅ Edge 113+
+- ✅ Safari 18+ (macOS/iOS)
+- ❌ Firefox (in development)
+
+Check support: `WebGPU.isAvailable()`
+
+## Best Practices
+
+- Use compute shaders for particle systems, physics
+- Leverage storage buffers for large datasets
+- Async compile before rendering
+- Use Node materials instead of custom GLSL
+- Test on both WebGL and WebGPU
+- Provide WebGL fallback for unsupported browsers