Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
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
16 changes: 10 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

**ArCode Persona** is an independent avatar creation platform in the ArCode ecosystem. It is designed to let each person build a customizable digital persona while keeping identity data portable and under the user's control.

> Current status: interactive prototype and engineering foundation. The current character is procedural placeholder geometry, not a production-quality rigged avatar.
> Current status: interactive prototype with a weighted procedural humanoid blockout and procedural facial morph targets. Production sculpted topology, authored assets and animation-quality deformation remain in progress.

## Product direction

Expand Down Expand Up @@ -47,7 +47,9 @@ npm run preview
| `test/` | Unit tests for the configuration contract |
| `docs/TECHNICAL_ARCHITECTURE.md` | System boundaries and rendering architecture |
| `docs/MOROCCAN_WARDROBE_CATALOG.md` | Moroccan clothing research and design direction |
| `docs/AVATAR_ASSET_PIPELINE.md` | Production 3D asset authoring and validation pipeline |\n| `tools/blender/export_skinned_asset.py` | Blender GLB exporter with provenance manifest |\n| `tools/validate-avatar-glb.mjs` | GLB rig/morph/animation profile validator |
| `docs/AVATAR_ASSET_PIPELINE.md` | Production 3D asset authoring and validation pipeline |
| `tools/blender/export_skinned_asset.py` | Blender GLB exporter with provenance manifest |
| `tools/validate-avatar-glb.mjs` | GLB rig/morph/animation profile validator |
| `docs/PRIVACY_AND_SECURITY.md` | Data handling and future server security principles |
| `docs/QUALITY_GATES.md` | CI and release acceptance criteria |
| `docs/ROADMAP_EXECUTION.md` | Phased execution plan |
Expand All @@ -67,7 +69,8 @@ npm run preview
- Semantic application of supported design properties to matching GLB morph targets and conventionally named skeleton bones.
- Automatic local browser persistence with no account or server storage.
- Restore saved looks after reloading the studio.
- Responsive Arabic RTL interface.\n- Blender export helper and GLB production-profile validation for skinned avatars and garments.
- Responsive Arabic RTL interface.
- Blender export helper and GLB production-profile validation for skinned avatars and garments.

## Important limitations

Expand All @@ -85,9 +88,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
### Human anatomy, rig and color engine

- `src/human-proportions.js`: shared proportion solver and anatomical landmarks for shoulder, elbow, wrist, pelvis, knee, ankle and foot placement.
- `src/human-rig.js`: standardized humanoid bone hierarchy (hips, spine, chest, neck, head, clavicles, arms, hands, fingers, legs, feet and toes) for future animation and skin binding.
- `src/human-anatomy.js`: lofted torso surface with smoother ribcage-to-waist-to-pelvis transitions, plus articulated limb blockout.
- `src/human-rig.js`: standardized humanoid bone hierarchy aligned to body landmarks, including spine, neck, head, clavicles, arms, fingers, legs and feet.
- `src/face-morphs.js`: procedural head and nose surfaces with named relative morph targets and normalized JSON v2 controls.
- `src/human-anatomy.js`: lofted torso and articulated limbs, hands and feet; when passed the humanoid rig, every generated body part receives normalized two-bone skin weights and is bound as a `SkinnedMesh`.
- `src/color-system.js`: Moroccan-inspired palettes and physically based skin/fabric material presets.
- The face preview now has more deliberate jaw, cheek, ear and nose sub-shapes; all remain stylized procedural geometry.

The bone hierarchy is currently animation-ready metadata, not yet a weighted SkinnedMesh. The preview anatomy remains a blockout; realistic anatomical topology, fingers, muscle definition and deformation require a dedicated production base mesh and skin weights.
The procedural body is now weighted to the humanoid skeleton, and the head/nose use real Three.js morph-target deltas. The result remains a stylized blockout: production anatomical topology, sculpted muscle definition, deformation QA, calibrated facial shapes and finished garment assets still require dedicated art production.
16 changes: 6 additions & 10 deletions app.js
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import { validateGlbArrayBuffer, MAX_GLB_BYTES } from './src/avatar-asset.js';
import { buildBoneRemap } from './src/garment-rig.js';
import { buildHumanAnatomy } from './src/human-anatomy.js';
import { buildHumanRig } from './src/human-rig.js';
import { createFaceSurface, createNoseSurface } from './src/face-morphs.js';
import { applyColorPalette, createSkinMaterial, createFabricMaterial } from './src/color-system.js';

const wrap=document.getElementById('canvasWrap');
Expand Down Expand Up @@ -66,8 +67,8 @@ function build(){
const torso=new THREE.Group();model.add(torso);model.scale.set(1,body.height,1);
// Geometry generators consume normalized design values directly; avoid double-scaling the anatomy.
torso.scale.set(1,1,1);
buildHumanAnatomy(torso, body, skin);
const humanoidRig=buildHumanRig(body);torso.add(humanoidRig.root);model.userData.humanoidRig=humanoidRig;
const humanoidRig=buildHumanRig(body);torso.add(humanoidRig.root);
buildHumanAnatomy(torso, body, skin, humanoidRig);model.userData.humanoidRig=humanoidRig;
const robeHeight=(state.outfit==='modern'?1.13:1.48)*wardrobe.robeLength;
if(state.outfit==='modern'){
cylinder(torso,.49*fitScale,.63*fitScale,robeHeight,0,-.42,0,clothMaterial);
Expand All @@ -93,11 +94,9 @@ function build(){
sphere(torso,side*.59,-.92*wardrobe.sleeveLength,.015,.14,.15,.14,skin);
sphere(torso,side*.59,-1.12*wardrobe.sleeveLength,.015,.17,.17,.22,clothMaterial);
}
cylinder(model,.17,.18,.28*body.neckLength,0,.52,0,skin);
const head=new THREE.Group();head.position.set(0,1.12+(body.neckLength-1)*.14,0);head.scale.set(body.headScale,body.headScale,body.headScale);model.add(head);
const shapeFactor={oval:[1,1],round:[1.08,.94],square:[1.04,.98],heart:[1,.98],long:[.94,1.08]}[face.shape];
const head=new THREE.Group();head.scale.set(body.headScale,body.headScale,body.headScale);humanoidRig.bones.Head.add(head);
const jawFactor={oval:1,round:1.08,square:1.14,heart:.86,long:.94}[face.shape];
sphere(head,0,0,0,.58*face.width*shapeFactor[0],.72*face.height*shapeFactor[1],.49,skin,56);
head.add(createFaceSurface(face,skin));
sphere(head,0,-.25,.055,.43*face.jawWidth*jawFactor,.34*face.height,.43,skin,48);
sphere(head,0,-.46,.12,.22*face.chinWidth,.16,.25,skin,32);
// Subtle mandibular and cheek transitions make face silhouettes respond coherently to the selected shape.
Expand Down Expand Up @@ -125,10 +124,7 @@ function build(){
sphere(head,eyeX,.035,.488,.015,.019,.009,dark,16);
}
// Nasal bridge, dorsum, tip and alar wings are independently scaled but share one centerline.
sphere(head,0,.015,.435,.042*face.noseWidth,.115*face.noseLength,.052*face.noseBridgeHeight,skin,28);
sphere(head,0,-.095,.485,.052*face.noseWidth,.105*face.noseLength,.065*face.noseBridgeHeight,skin,28);
sphere(head,0,-.17,.525,.068*face.noseWidth,.052*face.noseTip,.065,skin,24);
for(const side of [-1,1])sphere(head,side*.047*face.noseWidth,-.17,.505,.032*face.noseWidth,.026,.035,skin,18);
head.add(createNoseSurface(face,skin));
faceParts.mouth=curve(head,[[-.14,-.29,.43],[0,-.34,.47],[.14,-.29,.43]],mat('#6b302d'),.018);
if(state.expression==='neutral'){faceParts.mouth.scale.y=.45}
if(state.expression==='surprised'){faceParts.mouth.scale.set(.55,1.8,1)}
Expand Down
2 changes: 1 addition & 1 deletion docs/QUALITY_GATES.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,4 @@

## Current limitations

The existing geometric model is not a rigged production avatar. Full skeletal animation, facial blendshapes, cloth simulation, authentic garment geometry, automated visual regression, and browser-level E2E tests remain planned work.
The built-in procedural blockout now binds its generated body parts to a stable humanoid skeleton with normalized two-bone weights, and the procedural face/nose surfaces expose runtime morph targets. This is an engineering foundation, not a production-quality sculpted base mesh: production topology, animation deformation QA, authored facial shapes, cloth simulation, authentic garment geometry, automated visual regression, and browser-level E2E tests remain planned work.
7 changes: 5 additions & 2 deletions docs/ROADMAP_EXECUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,11 @@
- [x] Define versioned body, face, hair, and clothing proportion properties in JSON.
- [x] Connect procedural geometry and compatible imported GLB morph/bone targets to design properties.
- [ ] Approve stylized visual direction and character proportions.
- [ ] Create production base mesh and rig.
- [x] Implement a procedural skinned humanoid blockout with normalized two-bone weights and a stable rig contract.
- [ ] Create and approve a production-quality sculpted base mesh and animation-ready production rig.
- [x] Expose imported GLB facial morph targets through runtime sliders.
- [x] Add runtime facial expression presets for imported blendshape names.
- [x] Add procedural face and nose morph targets for width, height, jaw, cheeks, chin, nose bridge, nose length and tip.
- [ ] Build visual blendshape authoring and calibration tools.
- [ ] Replace placeholder garments with researched modular Moroccan assets.
- [x] Play and select animation clips embedded in imported GLB files.
Expand All @@ -25,7 +27,8 @@
## Phase 1A — Production asset pipeline
- [x] Add a Blender export helper with mandatory provenance metadata.
- [x] Add a GLB profile validator for skinned avatars and garments.
- [ ] Produce and license the base human mesh, rig, and facial shape keys.
- [x] Implement an initial procedural weighted rig and runtime facial shape keys.
- [ ] Produce, license and visually QA a production human mesh, rig and authored facial shape keys.
- [ ] Produce modular djellaba, caftan, and takchita assets against the pinned rig.
- [ ] Complete garment deformation and clipping QA on the base animation set.

Expand Down
138 changes: 138 additions & 0 deletions src/face-morphs.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
/**
* Procedural facial surface and nose with real relative morph-target deltas.
* Morph values are normalized to [-1, 1] around the neutral JSON v2 design.
*/
import * as THREE from 'three';

const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
function addMorphTargets(geometry, definitions) {
const base = geometry.getAttribute('position');
geometry.morphTargetsRelative = true;
geometry.morphAttributes.position = [];
geometry.morphAttributes.normal = [];
const baseNormals = geometry.getAttribute('normal');
for (const [name, deltaForVertex] of Object.entries(definitions)) {
const delta = new Float32Array(base.count * 3);
const vertex = new THREE.Vector3();
for (let i = 0; i < base.count; i++) {
vertex.fromBufferAttribute(base, i);
const change = deltaForVertex(vertex, i);
delta[i * 3] = change.x;
delta[i * 3 + 1] = change.y;
delta[i * 3 + 2] = change.z;
}
const attribute = new THREE.Float32BufferAttribute(delta, 3);
attribute.name = name;
geometry.morphAttributes.position.push(attribute);

const deformedPositions = new Float32Array(base.array.length);
for (let i = 0; i < base.count; i++) {
deformedPositions[i * 3] = base.getX(i) + delta[i * 3];
deformedPositions[i * 3 + 1] = base.getY(i) + delta[i * 3 + 1];
deformedPositions[i * 3 + 2] = base.getZ(i) + delta[i * 3 + 2];
}
const deformed = geometry.clone();
deformed.morphAttributes = {};
deformed.setAttribute('position', new THREE.Float32BufferAttribute(deformedPositions, 3));
deformed.computeVertexNormals();
const changedNormals = deformed.getAttribute('normal');
const normalDelta = new Float32Array(baseNormals.count * 3);
for (let i = 0; i < baseNormals.count; i++) {
normalDelta[i * 3] = changedNormals.getX(i) - baseNormals.getX(i);
normalDelta[i * 3 + 1] = changedNormals.getY(i) - baseNormals.getY(i);
normalDelta[i * 3 + 2] = changedNormals.getZ(i) - baseNormals.getZ(i);
}
const normalAttribute = new THREE.Float32BufferAttribute(normalDelta, 3);
normalAttribute.name = name;
geometry.morphAttributes.normal.push(normalAttribute);
deformed.dispose();
}
geometry.computeBoundingBox();
geometry.computeBoundingSphere();
return geometry;
}

function faceMask(y, center, width) {
const distance = Math.abs(y - center) / width;
return Math.exp(-distance * distance * 2.2);
}

export function createFaceSurface(face = {}, material) {
const geometry = new THREE.SphereGeometry(1, 56, 40);
const position = geometry.getAttribute('position');
const base = new Float32Array(position.array.length);
for (let i = 0; i < position.count; i++) {
base[i * 3] = position.getX(i) * .58;
base[i * 3 + 1] = position.getY(i) * .72;
base[i * 3 + 2] = position.getZ(i) * .49;
}
position.array.set(base);
position.needsUpdate = true;
geometry.computeVertexNormals();
addMorphTargets(geometry, {
faceWidth: v => new THREE.Vector3(v.x * .38, 0, 0),
faceHeight: v => new THREE.Vector3(0, v.y * .34, 0),
jawWidth: v => new THREE.Vector3(v.x * .52 * faceMask(v.y, -.42, .42), 0, 0),
cheekboneWidth: v => new THREE.Vector3(v.x * .34 * faceMask(v.y, -.06, .22), 0, 0),
chinWidth: v => new THREE.Vector3(v.x * .46 * faceMask(v.y, -.72, .2), 0, 0),
shapeRound: v => new THREE.Vector3(v.x * .13 * faceMask(v.y, -.18, .55), -Math.abs(v.y) * .025, 0),
shapeSquare: v => new THREE.Vector3(v.x * .12 * faceMask(v.y, -.48, .32), 0, 0),
shapeHeart: v => new THREE.Vector3(v.x * .12 * (faceMask(v.y, .08, .3) - faceMask(v.y, -.55, .3)), 0, 0),
shapeLong: v => new THREE.Vector3(0, v.y * .16, 0)
});
const mesh = new THREE.Mesh(geometry, material);
mesh.name = 'ProceduralFaceSurface';
mesh.updateMorphTargets();
const dictionary = mesh.morphTargetDictionary;
const values = {
faceWidth: (face.width ?? 1) - 1,
faceHeight: (face.height ?? 1) - 1,
jawWidth: (face.jawWidth ?? 1) - 1,
cheekboneWidth: (face.cheekboneWidth ?? 1) - 1,
chinWidth: (face.chinWidth ?? 1) - 1,
shapeRound: face.shape === 'round' ? 1 : 0,
shapeSquare: face.shape === 'square' ? 1 : 0,
shapeHeart: face.shape === 'heart' ? 1 : 0,
shapeLong: face.shape === 'long' ? 1 : 0
};
for (const [name, value] of Object.entries(values)) {
const index = dictionary[name];
if (index !== undefined) mesh.morphTargetInfluences[index] = clamp(value, -1, 1);
}
mesh.castShadow = true;
mesh.receiveShadow = true;
return mesh;
}

export function createNoseSurface(face = {}, material) {
const geometry = new THREE.SphereGeometry(1, 32, 24);
const position = geometry.getAttribute('position');
for (let i = 0; i < position.count; i++) {
position.setXYZ(i, position.getX(i) * .072, position.getY(i) * .17, position.getZ(i) * .07);
}
position.needsUpdate = true;
geometry.computeVertexNormals();
addMorphTargets(geometry, {
noseWidth: v => new THREE.Vector3(v.x * .48, 0, 0),
noseLength: v => new THREE.Vector3(0, v.y * .38, 0),
noseBridgeHeight: v => new THREE.Vector3(0, 0, v.z * .34 * faceMask(v.y, .35, .7)),
noseTip: v => new THREE.Vector3(v.x * .12 * faceMask(v.y, -.65, .3), 0, v.z * .2 * faceMask(v.y, -.65, .3))
});
const mesh = new THREE.Mesh(geometry, material);
mesh.name = 'ProceduralNose';
mesh.position.set(0, -.075, .49);
mesh.updateMorphTargets();
const values = {
noseWidth: (face.noseWidth ?? 1) - 1,
noseLength: (face.noseLength ?? 1) - 1,
noseBridgeHeight: (face.noseBridgeHeight ?? 1) - 1,
noseTip: (face.noseTip ?? 1) - 1
};
for (const [name, value] of Object.entries(values)) {
const index = mesh.morphTargetDictionary[name];
if (index !== undefined) mesh.morphTargetInfluences[index] = clamp(value, -1, 1);
}
mesh.castShadow = true;
mesh.receiveShadow = true;
return mesh;
}
Loading
Loading