A 3D model pipeline, pushed by GPT-6-Astra
agent (cont.)
+0:35exec_commandsed -n '976,1442p' docs/portrait-guide.md
command
sed -n '976,1442p' docs/portrait-guide.md
result, 4 lines
Script completed Wall time 0.0 seconds Output: {"chunk_id":"2f5846","wall_time_seconds":0.000009681,"exit_code":0,"original_token_count":8950,"output":" unclothed (`winvroid.py bases`).\n- **A retry added:** the menu ignores clicks while the editor reloads after an export.\n\n### 25 · VRoid bodies shaped by MakeHuman, their own head kept, 2026-10-10\n\n**Why:** the head graft looked like surgery and the heads didn't sit naturally on some bodies, and\nMakeHuman's mass carried onto VRoid didn't sculpt well. VRoid's bodies only come in a narrow range and\nMakeHuman's realistic bodies don't match an anime head. The spike (`tools/cage.py`) keeps VRoid's whole\nmodel, head included, and takes only the broad shape from a MakeHuman body: MakeHuman gives the range of\nbuilds, VRoid gives the head and the surface.\n\n**How it's done** (the details are in `tools/cage.py`):\n- **The skeleton goes onto the MakeHuman body's joints:** the limb bones are turned and stretched from\n joint to joint, the spine as one piece. The head, hands and feet are scaled whole, and the head is\n placed by its chin.\n- **The wrap:** each body vertex casts a ray along its normal to the MakeHuman skin. The distance is\n smoothed over space, so only broad volumes come across.\n- **Untouched:** the head, hands and feet, and every vertex the body shares with the face mesh.\n\n**What didn't work, and why:**\n- **Shaping by hand with the spec's own controls** (bone thickness, rings, bumps) made fat or boxy\n bodies:\n - Scaling a whole bone's thickness shows as a step wherever its skin weight changes quickly (knees,\n wrists). Scaling the collarbone made a box round the shoulders.\n - Smooth rings along each limb fixed the steps, but widening a slim body's cross-sections reads as fat,\n not strong. The trapezius and deltoids are shapes over the top of the shoulder, which rings can't\n raise.\n- **Nearest points:** for a slim body inside a big one, the nearest reference point usually lies to the\n side. Cast along the normal instead, and only accept skin facing the same way: without that, a neck\n whose front is missing (the reference's grafted head) takes its back and pinches the throat.\n- **Smoothing a vector:** it cancels round a limb, because opposite sides point opposite ways. Smooth the\n distance along the normal instead.\n- **Smoothing by mesh passes:** it isn't the same distance everywhere. VRoid's chest is densely meshed\n and kept MakeHuman's pec edges as two domes. A Gaussian over real distance is the same everywhere, and\n the torso gets a wider one than the limbs (3.5 to 4.5 cm against 2 to 2.5).\n- **Stretching short bones one by one:** the 6 cm pelvis bone stretched 2.6 times made a box. The spine\n stretches as one piece instead.\n- **Moving the thighs out:** they move out from under a pelvis that only stretches, and VRoid's quick\n change of weight there folds the skin. The rig's move is smoothed over 3 cm.\n\n**Folds from pushing far:** the wrap pushes skin out 6 to 14 cm. Along the skin's own normals, every hollow\ntighter than that (under VRoid's pecs, the collarbones' notch) folds over, which showed as rings round the\npecs and a wavy crease across the collarbones. Twenty-five rounds of smoothing didn't touch them, because\nthey're folds, not fine detail. Pushing along normals averaged over 2 to 4 cm removed them, and the forms\npush the same way.\n\n**Width isn't mass (Fable's critique):** the smoothed pull gave the brute width but no mass hierarchy. It\nread as a big, soft man, with arms leaving the torso as even tubes. Its masses are now forms: deltoid caps\nwider than the arm, a trapezius rising into the neck, pecs, lats, biceps, forearms and calves. Each stands on\nthe skin where a ray from its anchor leaves the body, so its height is what it adds. Centred on a joint deep\ninside a big body, the first forms added a third of their height and changed nothing visible. The heavy man\ngets milder shoulder and upper-arm bulk, so he reads big, not only fat.\n\n**Women** (VRoid's feminine base over the five MakeHuman women):\n- **The bust:** it stays VRoid's own and is scaled whole by VRoid's bust bones (`bust`, the way its slider\n works) where the build needs more: +10% strong, +30% heavy. The wrap alone left a heavy woman with a\n slim girl's bust.\n- **The strong woman:** mild shoulder, arm and calf forms. The smoothing takes MakeHuman's muscle tone, and\n without them she read slim, not strong.\n- **Two passes:** the wrap now casts again from the skin the first pass left and pulls what is still\n missing. It follows quick changes of width (a narrow waist under wide hips) more closely.\n- **The waist \"fails\" are the measure's:** see `docs/proportions.md`.\n- **The crop top's top edge** stepped on broad backs: triangles crossing the hem were dropped. It now takes\n triangles past both hems and clamps them on, like the shorts (`tools/mobs.py`).\n\n**The archetype's widths come from armoured figures:** the heavy targets' hips (1.7 to 2.3 head heights)\nand waist (1.5 to 2.1) were measured on Unicorn Overlord figures in armour and skirts. Fitting a bare\nMakeHuman brute to them gives it saddlebags. The brute's reference is fitted without them\n(`fit=dict(..., skip=(\"hip_hd\", \"waist_hd\"))`). The shoulder top's drop is armour-derived too.\n\n### 26 · Compare side by side, and heads held in metres, 2026-10-10\n\n**Compare** (the armory's default view, replacing its lineup): up to six bodies side by side at real heights,\nposed with arms up, out or down. Two things learned building it:\n- **The bind pose isn't the T-pose:** the exported skeleton's bind pose has the arms down, while the mesh is\n T-posed. Poses are turns from the bind pose about the body's front axis, with the direction read from where\n each hand points, and room is measured on the posed skin, never on the joints.\n- **The page framed figures too high** whenever the top bar was taller than the bottom one: the frame's centre\n used the bars' height difference with its sign flipped. A three-row bar hid raised hands.\n\n**Head sizes:** the user saw the tall woman's head as small, and it was. At 1.9 m and 8.3 heads her head\nwas the slender woman's, and VRoid's own tallest adults stop at 7.9 heads. The brute was the opposite: 6 heads\nat 2.09 m is a 35 cm head. Heads tall alone can't catch either, since both passed their ranges. Each body now\nalso keeps a head height in metres and a height in the cast's span, and the fitter solves heads tall and height\ntogether, moving a body only when a range demands it (`fit.head_goal`, `docs/proportions.md`).\n\n### 27 · Bodies against real people, 2026-10-10\n\nThe user saw the heavy woman's arms and the heavy man's thighs as thin, and asked for a check before any\nchange. Ratios in head heights couldn't answer it: they hold lengths and widths, not flesh. So each body is now\ncut like a tape at a body survey's landmarks, and every girth is read among real people of its own height and\nwaist. The surveys are NHANES and the two ANSURs; `tools/anthro.py` reads them and `docs/anthro.md` has the\nsources.\n\n**What it showed:**\n- **The user was right on both:**\n - **The heavy man:** mid-thigh at the 3rd percentile under a waist at the 90th.\n - **The heavy woman:** arm at the 16th.\n- **The bigger cause was upstream:** the heavy archetype's widths were measured on armoured figures. Bare, they\n gave the heavy man shoulders 54 cm across his acromions, against 42.5 for real men of his height and waist,\n past every one of them. Legs under a torso no real body has read thin even when they aren't.\n- **Busts:** MakeHuman's women had their bust points spread past every woman of their build, pointing at the\n arms. VRoid's are hemispheres set close.\n\n**Lessons:**\n- **A survey's percentile, conditioned on the body's own height and waist, is a style-neutral yardstick.** It\n asks \"is this coherent?\", not \"is this real?\". An anime-slim woman is judged against slim women.\n- **Ranges measured on armour don't belong on bare bodies.** It's the same lesson as the brute's hips (lesson\n 24), now his shoulders too. A heavy body's build is better defined by the population: a waist at the 80th to\n 97th percentile of everyone its height.\n- **Percentiles don't scale with the body.** Real girths don't grow in proportion with height. The fitter\n works on a small body and scales it last, so it must read percentiles at the final height. Read at the\n working size, a bust spacing at the 78th percentile came out at the 96th.\n- **Read the targets' names:** MakeHuman's \"stomach-pregnant\" is a pregnancy. As the last control for a heavy\n waist, past 0.25 it made her read pregnant, not heavy. Its \"upperleg-fat\" runs down to the knee, so the knee\n needs its own upper bound, and its forearm fat thickened the wrist past everyone's.\n- **A landmark rule must survive the shapes it will see:**\n - The fold under a breast found right under the nipple, then too low on a slim one.\n - The bust point picked the inner curve of a breast pointing out, then jumped between levels.\n - Each rule was fixed against the cases that broke it: a corner past the nipple, an axis 15° out.\n- **The cage pulls back what is shaped before it:** VRoid's bust scaled before the wrap came out the same.\n A tight wrap round the bust took MakeHuman's shape, but lumpy on VRoid's mesh. Reshaping after the wrap,\n faded by VRoid's own bust weights, holds. Grown far from VRoid's narrow base, a breast reads as a balloon,\n so a heavy cage bust needs a wider base before it can reach its build's median cup.\n\n### 28 · One line, the heroic man and the sexy woman, real hands, spring bones, 2026-10-12\n\n**What the user asked:** keep only the VRoid bodies shaped by MakeHuman, add a heroic man and a sexy woman for the\ngame, expand the line, and give the women physics. Also: \"I think we're scaling hand sizes appropriately too?\"\n\n**What the check showed:** we weren't. Hands were held in face units from the study, whose young heroes have large\nfaces; with heads held in metres since v6, nothing tied a hand to its body. The fitter had shrunk the slender\nwoman's hands to its limit (13.4 cm on a 1.66 m body, the 0th percentile of women her height; their median 18) and\nthe strong woman's to 14.4 cm at 1.85 m, while the heavy man's came out at 22.4 cm (the 100th).\n\n**What changed:**\n- **The armory is one line:** VRoid's base, its head kept, over a MakeHuman reference (lesson 25). The MakeHuman\n bodies are references only, never shown; the VRoid-native and massed bodies are gone. Eight men, six women.\n- **Hands and feet** hold to the 25th to 90th and 15th to 90th percentiles of people the body's height (ANSUR II).\n- **Figures:** the heroic man and the sexy woman are the adult archetype with a figure of percentiles\n (`docs/anthro.md`): his waist slim under a big chest and arms, her waist slim between a full bust and hips.\n- **Breasts inflated, not scaled:** scaled up from VRoid's narrow base, a breast stood out as a ball glued on, with\n a crease round the rim. Pushed out along the skin's normals, fading over a wide base above and to the sides but\n only on the breast itself below, it keeps VRoid's shape, widens its base and keeps the fold.\n- **Each VRoid body is fitted itself** (thighs, and the women's cups), not trusted to inherit its reference's: the\n pull fell 1.5 to 5 cm short of the references' mid-thighs, and VRoid's breasts are smaller than a slim\n reference's.\n- **Spring bones:** VRoid's base carries its breasts' (stiffness 0.75, drag 0.05, no gravity). The viewer runs\n them as UniVRM does; the cage moves each breast bone with the skin it carries, so they swing about the reshaped\n breast.\n\n**Lessons:**\n- **A unit borrowed from a style ties a part to the wrong thing.** Hands in face units were fine while the faces\n were the study's; once heads were held to real sizes, hands drifted with the face, not the body. Tie each part\n to what it belongs to: a hand to the body's height.\n- **A landmark rule needs the shapes it will see (again):** \"the lowest midline skin\" found the crotch where\n thighs touch, near a heroic man's knees. Ask which bone the skin belongs to, not just where it is.\n- **Fixing a measure moves what was fitted to it.** With the crotch read right, the fitter stopped at the limbs'\n floor, and the heavy woman's thighs came out thinner than the user had approved. When a fix changes a reading,\n compare the bodies the user has seen, measured the new way, before and after.\n- **Don't scale a body to match a number its parts don't share:** scaled whole to its reference's height (VRoid's\n taller feet stood it 2 to 4 cm over), every girth shrank 2% with it.\n- **In one shell line, `pkill -f PATTERN` matches the line itself** when the pattern is in it, and kills the job\n it was meant to start. Stop processes in a call of their own.\n- **A cache key must hash everything the output depends on.** A cage body's key named its reference but didn't\n hash it, so a refitted reference left the body as it was. Its key now holds the reference's spec too.\n- **An outside eye sees the archetype, not the numbers** (Fable): the first heroic man passed every percentile\n and still read as the strong man stretched, his V only from the waist, and taller than the brute. The heavy\n woman's belly passed too, and read pregnant: MakeHuman's torso depth and pregnancy target put it high. A\n woman's waist now grows low (a soft lower belly, then the hips, then the depth).\n\n### 29 · Heads: VRoid's sample faces on our bases, fitted by code, 2026-10-13\n\n**What the user asked:** start on heads (Aldric is retired as a study; the neck waits on the head work).\n\n**What was built:** `tools/heads.py` puts a VRoid sample's face on our base (`docs/vroid.md`), sculpts it in the\nfile and fits it to a face archetype's ratios; `tools/cage.py` then builds the body on it and sizes the head to\nits reference's. Each of the 14 armory bodies has its own head.\n\n**Lessons:**\n- **Check a template before building on it:** all 26 faces share the skin's triangles and texture layout exactly,\n but the eye parts are each sample's own geometry. That decided the method: move the shared part vertex for\n vertex, carry the rest whole.\n- **Know where a mesh ends:** VRoid's face mesh is only the head's front; the back of the skull is in the body\n mesh. Taking a sample's whole front set its skull against the base's back, and the hair base couldn't sit on\n both. Taking only the face, faded out before the skull, kept every join and the cap as they were.\n- **Lighting is geometry too:** with the base's ears kept but the sample's normals taken, the ears lit as if turned\n and looked ghostly. Normals follow the positions they belong to.\n- **A fitter must not undo the character:** asked to narrow a face, it narrowed the strong man's jaw away and grew\n the old man's eyes to make up for smaller irises. Fit with controls that don't carry the character (lower-face\n length, cheeks, eye size), and leave the jaw, brow and nose to the design.\n- **Ratios from one group don't fit another:** the heavy face ratios come from the study's heavy men; held to them\n the heavy woman's face came out pinched. The old faces take the adult ratios, not the study's young-eyed\n townsfolk.\n- **The numbers pass and the faces can still miss** (Fable): a long adult lower face read as a gaunt spade on the\n strong pair, the brute's jaw as a block, a winged liner as make-up, star glints as a child. Strength is jaw\n width; age needs modelling, not lines alone; and much of the variety must come from the shape, since the painted\n renderer recolours the eyes.\n\n### 30 · Faces as VRoid built them, 2026-10-13\n\n**What the user said:** v9's faces looked good from some angles and too sharp from others; the average man's face\nlooked wide from the front; the sexy woman's face didn't fit her body.\n\n**What it was:** the fitter. To meet face ratios measured on Unicorn Overlord's paintings, it lengthened lower\nfaces (the sexy woman's by 17%) and enlarged eyes (the average man's by 20%, shortening his face). The paintings are\nmostly seen from the front; from the side the stretched chins jutted.\n\n**What changed:** faces are VRoid's as built, chosen per body by look, or blends of two samples (one template, so a\nblend stays coherent from every angle). Light sculpting only. The ratios are reported against the study, not held.\n\n**Lessons:**\n- **Numbers from 2D art don't transfer to 3D by force.** A painting fixes one view; a 3D face must hold at all of\n them. Use 2D ratios as a reference to report against, and judge 3D faces turning.\n- **A face made by a face tool stays coherent; one made by moving points on its skin doesn't.** VRoid's sliders\n were built to keep an anime face right at every angle. Our sculpt moved landmarks with a smooth field, which is\n fine for small touches and breaks for large ones.\n- **Look at the source before the result:** rendering the samples as VRoid made them beside our fitted versions,\n at 0°, 30°, 60° and 90°, showed at once that the fault was ours.\n- **The set has a ceiling:** all 26 samples are young. A mature or sultry face isn't in it at any blend; that needs\n VRoid's own editor.\n\n### 31 · Hair that rests on the body, 2026-10-13\n\n**What you saw:** some of the hair went inside the bodies. You asked whether collision there was ours or the game\nengine's.\n\n**Whose it is:** ours. A VRM's hair collides only with spheres the model carries, on its bones; every engine that\nplays VRM runs those spheres and nothing else, never the skin. v11's hair brought its sample's spheres, sized for\nVRoid's slim sample bodies, with none over the back or bust. Replayed in code (`tools/hair_check.py`), the slender\nwoman's hair sank up to 6 cm into her upper back and shoulders when she twisted; the heavy man's nape hair stood\n4 cm inside his neck, even standing still.\n\n**What changed (`tools/collide.py`):** each body gets spheres fitted to its own skin wherever its hair can reach,\n2 cm proud of it, and its hair is draped over them at rest, so it starts where it lies.\n\n**Lessons:**\n- **Measure the joints and the mesh both.** Spring collision tests only a bone's tail. A bone held off the body\n still left its lock in it three ways: the body bulges between two joints (a 10 cm bone over the slope from neck to\n shoulder dipped 3 cm in); a lock is thick round its bone (a median 2.3 cm); and a bone needn't run down its lock\n (the heavy man's nape tufts hang below bones that point back).\n- **A transplant must keep what physics reads, not only what the mesh reads.** Taking only the bones the hair's\n mesh is weighted to dropped each lock's weightless end bone, the one that says where its last bone points. A\n one-bone lock then swung about a tail pointing up off the scalp, and its collisions tested a point in the air.\n- **Order that matters goes in a list, never a dict's keys.** A face blend's first sample gives its eyes, but the\n body fit's cache stores specs with sorted keys: whenever a body came from the cache, the heavy woman, old man and\n youth took their eyes from the other sample. Rebuilding the same commit twice and comparing the files caught it.\n- **Drape by letting go, not by turning stiffly.** Turned rigidly with their parents, long locks lifted off the\n upper back splayed out like a tent. Each bone keeps its own way unless the body is in it, so the hair falls along\n the back.\n\n### 32 · Faces shaded from a simple head shape, 2026-10-30\n\n**What you asked:** you bought DillonGoo's Yin and Yang anime rigs (personal-use licence: study only, nothing of\ntheirs ships). Take their lessons for our faces one step at a time, each shown in the armory at 0°, 35°, 60° and 90°.\n\n**What was built:** `face_normals` in `tools/vroid_portrait.py`, on by default (`face_normals=1.0` in NEUTRAL). The\nface, brows, lines, mouth and skull are shaded from normals that point away from a short vertical line inside the\nhead (pulled halfway to its middle), not from the mesh; the neck fades back to its own normals over 3 cm under the\nchin; then 5 rounds of smoothing. It runs when a character is drawn, so the armory's painted renderer, the pixel\npath and the GLB all get it.\n\n**Lessons:**\n- **The blotches were the mesh, not the light.** A VRoid face's normals carry every small bump of the nose, cheek and\n jaw; a cel threshold turns each into a patch that jumps as the head turns. A simple shape behind the face gives one\n clean shadow edge at every angle.\n- **Place the shape for our faces and our light, not the source's.** At the rig's spot (13% of the head's depth in\n front of its middle) a VRoid face, flatter than Yin's, shaded half its front under the armory's key. At the middle\n the front stays lit and only the far jaw and the neck shade.\n- **Not everything wants it.** On hair the same trick flattened the strands into one plastic sheen in the painted\n renderer, so hair keeps its own normals (`hair_normals=0.0`).\n- **Check what a cache key covers before editing a file in it.** `tools/cage.py` keys bodies on this file's source,\n so every edit here rebuilds bodies (two in about two minutes); they came out byte-identical, as they should.\n\n### 33 · Hand-placed shadows: under the nose, the chin's on the neck, 2026-10-30\n\n**What was built:** `shade_marks` in `tools/vroid_portrait.py` (after `face_normals`, sizes in `SHADE_MARKS`, in\neye-to-chin spans). A small patch under the nose tip and a band on the neck under the jaw line turn their normals\ndown, so the key from above leaves them in shade at every angle and the cel threshold draws a clean edge, the way the\nrigs' shadow cards and painted shade mask do.\n\n**Lessons:**\n- **Small and few.** At the first sizes the nose shadow read as a smudge, almost a moustache on the youth; small\n (6% of the span tall) it reads as a nose.\n- **Not every drawn convention survives 3D.** A lower-lip shade is house style in the pixel portraits, but in the\n painted renderer it read as a goatee or a second mouth at every size tried. It stays supported and off.\n- **The chin's shadow is the one that sells it:** a band following the jaw line, 45% of the span deep, gives the\n classic V under the chin at the front and holds as the head turns.\n\n### 34 · Shadow cards instead of tilted skin, 2026-10-30\n\n**What you saw:** the chin's shadow from lesson 33 looked like a scar, not a shadow.\n\n**Why:** it was the neck's skin turned away from the light in a soft patch. Its edge followed the neck mesh's\ntriangles (a zig-zag with notches) and ended where the neck's own bumpy normals took over. The nose patch did the\nsame and turned VRoid's painted nose line into a \"T\", like a stitch.\n\n**What was built (`shadow_cards`, replacing `shade_marks`):** the shadows are small pieces of geometry with designed\noutlines, as on the Yin and Yang rigs: a crescent on the neck under the jaw and a half-moon under the nose tip.\n- They lie just off the skin and borrow its weights, so they ride and bend with it.\n- They take a new role, \"shadow\": skin that only ever darkens into its shade tone, in the painted renderer, the\n export and the pixel path.\n- `face_normals` gains the rig's second skeleton, a cylinder round the neck's axis, so the neck itself shades\n smoothly around the card.\n\n**Lessons:**\n- **A cel edge drawn by the mesh is only as smooth as the mesh.** Where the shape of a shadow matters, give it its\n own geometry.\n- **Follow the real edge, not a guess at it.** A parabola for the jaw line left the card's top ragged where it met\n the face; the jaw's lowest edge, measured round the neck's axis and smoothed, hides it.\n- **A card must agree with the shade around it.** Fixed at one tone it showed a darker V inside the neck's own\n half-shade. Letting it only darken (never lighten) merges it where the neck is already in shade.\n- **Take the neck from the skeleton, not from a slice of skin.** In the armory's T-pose the slender woman's neck is\n short: 5 cm under her chin is already shoulders and arms, so a ring cut there put her neck's centre at the front\n of her throat. Half her chin card failed and the rest came out shallow. Her visible \"shadow\" was mostly the neck's\n own shading, so she and the youth looked unlike each other. The line from the neck bone to the head bone (it leans\n as the neck does) fixed it.\n- **Hold a light constant to see what a shape really is.** Rendering the neck fully lit, so only the cards shaded,\n showed at once that her card was nearly missing, and that the light was not to blame.\n- **A chin shadow is the upper neck, not the whole of it:** deepest about a quarter of the eye-to-chin span under\n the chin, ends tapering to points before the jaw's angle, and a soft shade tone rather than the darkest one.\n\n### 35 · The chin's shadow cast in screen space, 2026-10-30\n\n**What you said:** at angles the chin card still looked wrong; we might need research.\n\n**What the research said:** anime pipelines either paint neck shadows into the texture (Genshin), edit normals and\nshadow thresholds (Guilty Gear Xrd), or cast them in screen space (\"depth offset\" shadows: Anime Shading Plus,\nStylized NextGen). They avoid ordinary shadow maps on faces. A painted or card shadow is fixed to the neck, while a\nreal chin shadow comes from the jaw's outline and changes as the head turns.\n\n**What was built:** the painted renderer draws its info pass (roles, ids, depth) first. For body skin, the colour\npass walks from each pixel toward the key light across that pass: [redacted: secret] the face (jaw, chin) or hair stands in front of\nthe ray, the pixel drops into the shade band. The chin card is off (`CHIN_CARD`); the nose card stays, since a face\ncan't shadow itself this way.\n\n**Lessons:**\n- **A shadow's shape belongs to its caster.** Thrown from the jaw's own outline, the chin's shadow is right at\n every angle with no shape to design.\n- **Unbind what you are about to draw into.** The first version rendered one tile and then black: the info textures\n were still bound for sampling when the next frame drew into them (a WebGL feedback loop).\n\n### 36 · A skin range, people and fantasy, 2026-10-30\n\n**What you asked:** more range for the models, starting with skin, including fantasy tones (dark elves and the\nlike). The pixel renderer is abandoned; the armory's painted renderer is the target.\n\n**What was built:**\n- `cast.SKINS` gains 12 people tones (porcelain to ebony) and 7 fantasy tones (two dark elf, ashen, two orc, sea,\n infernal).\n- `export_glb.skin_ramp` gives each tone its own lit, shade and deep-shade colours.\n- The armory page has a skin picker that tries any tone on the bodies shown (`?skin=<tone>` for sheets).\n\n**Lessons:**\n- **One tint over a light skin can't make a deep one.** Multiplying the light ramp darkened every tone the same way,\n and the stage's blue shade turned brown skin grey. A ramp per tone, with shade hue nudged warm on people (cool on\n fantasy blues and greens) and the stage grade taken at 30% on skin, keeps deep tones rich.\n- **Space the range by eye, not by name.** The older seven bunched at the light end (pale, light, fair look alike)\n and stopped at a mid brown.\n\n### 37 · Shut eyes shut (from main's 4aa16f2), 2026-10-31\n\n- **A blended face may not shut its eyes.** The youth's lash lines come from another sample than his lid skin, and\n VRoid's close shapes stopped short on him: a strip of iris, then white, then socket showed in joy and the wink.\n `hide_closed_irises` closes a shut eye 30% further, hides its iris and highlight (per eye, so the wink's open eye\n keeps them), and the shut eye's white is dropped.\n- **A closed lid is the model's own open lash, moved** (the rule: lesson 38). VRoid's close shapes move the lid edge further than the\n lash's top, so a closed line came out about 1.3 times the open lash on the youth (a slab beside his thin stroke).\n `keep_lash_weight` moves each UV column of the upper line rigidly with its lid edge, so it keeps the open weight,\n taper and colour. `lid_gap` measures per model whether the lids meet (the edge reaches the painted lower line):\n if so nothing more (closing past 1 folded the woman's lash fan into strays); if not, the lid closes over the whole\n lower line. A shut eye's lower line is dropped, and the lash fan moves with the edge rather than folding.\n- **A big opening needs a dark inside.** VRoid's mouth map read as teeth/tongue/dark looks right on small mouths but\n stretches into a pink blob on a shout; the composite darkens the upper half of a tall opening.\n\n### 38 · One lash per character (a rule), 2026-10-31\n\n**One lash size per character: open and closed lids share it. A closed lid is that lash moved, never a stack of\nlines or a generic close.**\n\n- **How:** `keep_lash_weight` moves each UV column of a closing eye's upper line rigidly with its lid edge, so the\n closed (or lidded) eye carries the open lash's weight, taper and colour; VRoid's own close stretched it (about 1.3\n times on the youth). `lid_gap` measures per model whether the lids meet: if they do, nothing more; if they stop\n short, the lid closes over the lower line, and a shut eye's lower line is dropped, so the lid is one stroke. The\n lash fan (FaceEyelash) moves with the edge rather than folding past shut.\n- **Where the size is set:** today it is implicit in the VRoid sample that gives the eyes (the first in a head's\n blend, `cast.HEADS`). A designed size goes in the character's shape as `lash` (NEUTRAL default 1, the sample's\n own; per character in its cast `shape`). `lash_size` applies it to the open lash, and every closed lid is moved\n from that open lash, so closed lids follow it automatically; there is no closed-eye lash to set.\n- **VRoid's lash highlights:** the pale specks VRoid paints inside its lash lines are filled at export\n (`export_glb.fill_line_specks`), in open and closed lashes alike.\n- **A shut lid is one solid stroke.** A shut eye's upper line is its own primitive (`lid_fill`), drawn with\n `export_glb.fill_lid`: the lash's main stroke solid from its top ink to its bottom ink, its pale streaks and\n hollows inked, a crease line or loose wisp above it cleared. On an open eye those read as shine and a crease; over\n a closed lid they split it (the brute's hollow lash read as an empty almond, the average's streak as two lines).\n The open eye is drawn as VRoid painted it.\n- **Check it before an armory republish:**\n - `python3 tools/lash_check.py [names]` (meshes; after `tools/cage.py`, under 10 s a body): open lash against\n every lid the recipes close 30% or more, across the lash's middle columns. Flags a weight past 15%, and a shut\n lid that falls into two lines across a pale gap in 2 or more of its 9 columns.\n - `python3 tools/lash_shots.py SHOTS [bodies]` (rendered shots): the same in px on the frontal tile; a body whose\n lash is mostly under hair is \"not measurable\", which is not a pass.\n - 15%: half the 1.3 times the owner rejected, and above either measure's noise.\n\n### 39 · Expressions, after the Yin and Yang rigs (the pass before the benchmark), 2026-10-30\n\nWritten on master before the expressions benchmark. Its code was replaced by the combined track (B's brows and\nrecipes, A's mouth and wink, shut eyes from lessons 37 and 38); the benchmark is in `~/Projects/lowmarch-bench`.\nThe lessons below still hold.\n\n**What you asked:** compare the rigs' expressions (their selling point) with ours, then iterate on ours and show\nfrontal images of each.\n\n**What the comparison showed:** see the trials folder, `expressions-vs-yin-yang.png`.\n- The rigs pose expressions with macro controls (Action constraints) and draw closed mouths with Line Art.\n- Ours use VRoid's 57 shapes. Joy, wink and the vowels already read.\n- Open mouths were a flat dark blob.\n- Brows hid under the bangs, so angry and sad didn't read.\n- There was no one-sided mouth.\n\n**What was built (the painted renderer and `tools/vrm.py`):**\n- **The mouth from VRoid's own texture, mapped to an anime palette:** maroon cavity, rose tongue, white teeth. The\n rim and a closed mouth's sliver are inked, and face pixels round the mouth get an ink line.\n- **Brows through the bangs:** a brow-only pass shows a brow where hair stands just in front of it (within 6 cm).\n- **VRoid's painted lip line inked** inside the template's lip window.\n- **One-sided shapes:** `Fcl_MTH_Up@L` applies a shape to one half with a soft middle. The smug is one corner up and\n one brow raised.\n\n**Lessons:**\n- **Use the parts you already have.** VRoid's mouth texture had teeth and tongue all along; a flat colour threw them\n away.\n- **Map texture to style, don't show it raw.** The raw texture read washed-out pink. A three-colour palette by\n brightness reads as an anime mouth.\n- **A painted lip line can't carry a frown.** VRoid's is faint (about 0.7 of the skin) and a few texels wide; angry\n and sad stay weak whatever we ink. They need a drawn line, as the rigs' Line Art does: next.\n- **Brows over hair is the anime convention, not the rigs'.** Yin keeps her bangs above her brows instead.\n- **A blended face may not shut its eyes.** The youth's lash lines come from another sample than his lid skin, and\n VRoid's close shapes stopped short on him: a strip of iris, then white, then socket showed in joy and the wink.\n `hide_closed_irises` closes a shut eye 30% further, hides its iris and highlight (per eye, so the wink's open eye\n keeps them), and the shut eye's white is dropped. The woman's eyes, which shut already, are unchanged.\n\n### 40 · Mouths on every face (the 14-body check), 2026-10-31\n\nThe open mouth (lessons 37, 39) was tuned on two bodies. On all 14 armory bodies it broke four ways, each because a\nfixed number stood in for something that differs per face.\n\n- **A recipe past VRoid's 1 goes past what the face holds.** Shout is `Fcl_MTH_A:1.5`; on long jaws (average, brute,\n old, heavy) the lower teeth and the mouth's floor came out under the chin. `hold_mouth` measures it on the face:\n `mouth_room` is how far the mouth's inside stays above the face skin's lower outline (2 mm columns, front and 30\n degrees either way), and the recipe's `Fcl_MTH_*` weights scale down together until it is 2 mm (`MOUTH_ROOM`).\n Scales for shout: 0.66 to 1.0 (average 0.66, old 0.66, brute 0.74; slender 0.90, youth 0.96). The outline is\n sampled along the face's triangle edges: its vertices alone leave columns with no outline point.\n- **Measure a texture before thresholding it.** Every VRoid mouth map has the same layout (teeth top left, tongue top\n right, the inside below) but not the same paint: the sexy woman's is darker throughout, so fixed thresholds read\n her whole mouth as the dark inside. `export_glb.even_mouth` measures each map's inside, tongue light and teeth\n white in their parts and repaints it in the colours the renderer's split was tuned on. Teeth are told by their\n least channel: a tongue's highlight is bright but pink, and on brightness it read as a white tooth.\n- **A slit is all teeth.** VRoid's teeth fill a barely parted mouth (the heroic man's angry, several sads), which read\n as a white pill. The composite shows teeth only where the opening is 8 to 11 mm tall, measured in the face's own\n metres (`uPpm`), not in pixels.\n- **Some samples have fangs in their teeth.** Sample V's upper teeth carry two fangs in the mesh itself (no shape\n key applies them), so faces blended from V (arm_m_old) show them in an open mouth. `fangs` in the shape (1, the\n face's own teeth) is the switch: 0 adds VRoid's `Fcl_HA_Short`, which removes them and shortens the other teeth a\n little.\n- **Still weak:** angry on the slender, strong, sexy and old women is a closed line that thins to a hairline in its\n middle, where the shape presses the painted lip line; widening its texture taps by how squeezed the texture is\n on screen was tried and dropped (no thicker, specks on the heroic man's rim). It needs a drawn line (lesson 39).\n"}exec_commandsed -n '201,300p' docs/portrait-guide.md && cat tools/session/frame.py (+1 more)
command
sed -n '201,300p' docs/portrait-guide.md && cat tools/session/frame.py ls -la review/out ~/out ~/.local/share/lowmarch && sed -n '1,220p' tools/shots/arm_shoot.py && cat tools/session/smoke_spec.json
result, 4 lines
Script completed Wall time 0.1 seconds Output: {"chunk_id":"26e69c","wall_time_seconds":0.00000403,"exit_code":0,"original_token_count":2660,"output":"- **Mouth:** `curve` is the default. It traces the painted lip line in 3D and draws it as a tapered\n 1-px line (offline: `draw_curve_mouth`; live: a GL line, always one pixel wide at render\n resolution). Under a collar's front opening, keep the throat skin.\n- **Cloth in the viewer:** the cape and tails export as grids (`grid`); the browser runs Verlet with\n stretch and bend constraints, a pinned top row, and capsule colliders measured from the body\n (`export_glb.scene_info`). Gold trim on cloth is drawn as lines that follow the particles.\n- **Tails collide with hips and legs only.** Hanging sleeves in the collision set hold them out.\n\n### 09 · Painted renderer and battle animation, 2026-10-08\n\nDirection change (user): keep the pixel renderer, and add a renderer aiming at Unicorn Overlord's\nhand-painted look. Unicorn Overlord has no 3D models: Vanillaware paints 2D parts and puppets them.\nSo its art is a design study only, and the look comes from our 3D through a painted shader.\n\n- **Painted renderer** (viewer, `PAINT_FS`/`PAINT_COMP`): palette ramps blended softly\n (smoothstep ±0.09 around each band), a key light from the upper left, cool shadows (rosy for\n skin), warm lights, a fresnel rim, metal as a sky/ground reflection plus a highlight streak, a hair\n sheen, object-space brush grain (per material: skin 0.02, hair 0.04, cloth 0.10, ground 0.16),\n coloured outlines (a 2.2 px outer silhouette, interior lines at depth breaks, each a darker\n shade of the colour it borders), and crease darkening from depth.\n- **One rigged character** (`export_glb.export_skinned`): the reference-pose mesh, VRoid skeleton\n with our bone scales, inverse binds, and per-vertex weights for every piece. Clips are\n authored in `tools/clips.py` as a few key poses, finished with `tools/rig.py` (two-bone leg IK,\n `aim` for the sword, `rotate_world`). Poses accept 4×4 adjustments (`poses.move`) for root motion.\n- **Garment weights come from the exact skin they grew from** (`fitting.blend_weights` through\n subdivision). Copying from the nearest skin let one boot take the other leg's bones, and the\n boots stretched into sheets when the legs split.\n- **Export a channel for every bone the clip moves away from the reference pose,** even if it\n then holds still: a held fist has no variation, but without a channel it reverts to the open\n reference hand.\n- three.js shader includes must start a line: `void main() {\\n#include <...>`.\n- Cloth on an animated body: hide the skinned cape and read its pinned row with\n `getVertexPosition` each frame; colliders follow bones by name; the simulated copy is a plain mesh\n in world space.\n\n### 10 · Painted renderer tuned to the study, and the costume kit, 2026-10-08\n\nThe Unicorn Overlord study (24 official images, measured) gave shader rules and a costume\nlanguage. The art itself was used for study only; nothing of it is in the repo.\n\n- **Painted shader** (`PAINT_FS`):\n - **Ramps.** Each role carries a kind and one base colour (`scene_info` → `paint`, from the\n cast's `paint` dict). The shader builds the ramp: shadows rotate toward violet (cool hues) or\n magenta (warm hues, leather), and lights rotate toward yellow with less saturation.\n Terminators are ±0.03, and the light band starts at `lit` 0.91: at 0.82, everything facing\n the camera landed in the highlight.\n - **Skin** uses the measured ramp (`#f8e1d5` / `#c6a89b` / `#73524f`) with no grain.\n - **Hair** has four bands and a spec band shaped by the strand texture. Keep the texture's\n influence low (0.12), or VRoid's baked streaks turn into noise.\n - **Steel** uses hard bands on the reflection's y. A surface facing the camera (r.y ≈ 0) must\n land on the plate's own grey, not a dark band. Jitter the thresholds with noise stretched\n along the bands, or they break into blobs.\n - **Stage grade:** ambient, key colour and back rim, set per view.\n- **Painted line art** (`PAINT_COMP`): the ink is the local hue at saturation 0.2–0.45 and value\n 0.19. The silhouette is about 0.42% of the figure's height on screen. Interior lines are 55%\n of that, and only at depth breaks between pieces.\n- **Costume kit** (`outfit.py`):\n - `limb_lames`: bands around a limb, cast out of the bone axis. Use at least one row per 15 mm\n along the limb: with sparse rows the calf bulged through between them.\n - `dome` and `fan` (`joint_guard`): couters and poleyns with wings.\n - `pipe`: rolled plate edges, which define plate instead of gold.\n - `panel`: the tabard.\n - `mantle`: the hooded scarf.\n - `shield`: the round shield with a chevron device.\n - The new `lord` builds in the study's layering order: doublet, plate, belts, tabard, scarf.\n The first costume stays as `lord_tunic`.\n- **Cloth must start outside what it covers.** The drape only pushes outward along the nearest\n face, so a scarf that starts inside the breastplate stays there. Push it out with level rays\n from the neck axis.\n - Keep overhanging pieces (spaulders) out of that collision set. A ray that passes under one\n lands on the arm and pulls the cloth into the gap.\n - The scarf is short at the sides, so the spaulders stand over its edges.\n- **Spaulder spread about 108°.** At 132° the lames' front ends wrapped onto the chest and cut\n through the scarf.\n- **Per-cloth colliders** (`export_glb.CLOTH`): panels hanging from the belt meet the legs only.\n The hip capsule's round end pushed the back panel out behind.\n- **Contacts are inelastic** (the viewer's `Cloth.step`): 80% of a push-out is added to the\n previous position too. Otherwise a stepping thigh flings the tabard.\n- New pixel roles: `signature` (the cast's coat bands) and `doublet` (cream, `Q R S T`).\n- **Follow-up after review (user):**\n - **Body proportions.** New shape keys in `bone_pose`: `shoulders` (clavicle length), `arms`\n and `legs` (limb thickness), `torso` (waist to chest), `leg_len` (the hips lift by the leg's\n growth, so the feet stay down) and `hands`. Aldric is now about 7.5 heads (from 6.8), with\n shoulders 1.28.\n - **Bone scales vs. pieces that use a bone's frame.** Pieces that take directions from a bone's\n world matrix (the sword in the hand) must normalise it once the bone carries a scale.\n - **An under-layer next to skin must not be skin-toned.** The cream doublet read as bare arms,\n so the doublet is dark charcoal-navy; borders and devices use a separate cool-white\n `heraldry` role.\n - **Belts cast with the body skin in the set wrap the hanging forearms** in the reference pose,\n and stick out sideways once the arms move. Cast belts onto torso layers only.\n - **Body skin is culled under a costume, so every joint needs an overlap.** The wrist showed a\n gap between the sleeve hem and the glove. Gauntlet cuffs overlap both.\n\n### Milestone · Aldric v9 frozen, 2026-10-08\n\nThe user froze Aldric here as the reference character and asked to put on record how far the\nwork has come. In two days, the same character went from:\n\n1. a 96 px GBA-style portrait;\n\"\"\"Shoot the first-session frame (docs/handbook.md): review/frame/index.html, headless, one PNG per option in the spec.\n\n python3 tools/session/frame.py SPEC.json OUT_DIR writes OUT_DIR/<label>.png and OUT_DIR/frame_info.json\n python3 tools/session/frame.py --info FIGURE prints the figure's height and landmarks, for placing blocks\n\nThe figure comes from the built armory site (review/out/armory/site/<figure>.glb.json). Nothing is rebuilt, so a new\noption costs a few seconds. CHROMIUM picks the browser (default /snap/bin/chromium); the page loads three.js from a CDN.\n\"\"\"\nimport base64\nimport json\nimport os\nimport re\nimport shutil\nimport socket\nimport subprocess\nimport sys\nimport tempfile\nimport time\n\nROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))\nSITE = os.environ.get(\"LOWMARCH_FRAME_SITE\", os.path.join(ROOT, \"review\", \"out\", \"armory\", \"site\"))\nPAGE = os.path.join(ROOT, \"review\", \"frame\", \"index.html\")\nCHROMIUM = os.environ.get(\"CHROMIUM\", \"/snap/bin/chromium\")\n\n\ndef shoot(spec):\n figure = spec[\"figure\"]\n src = os.path.join(SITE, f\"{figure}.glb.json\")\n if not os.path.exists(src):\n sys.exit(f\"no {src}: build the armory first (handbook, How to run)\")\n # snap Chromium can't read outside home, and the site must hold page, spec and figure together\n work = tempfile.mkdtemp(prefix=\"lowmarch-frame-\", dir=os.path.expanduser(\"~/.cache\"))\n try:\n shutil.copy(PAGE, os.path.join(work, \"index.html\"))\n os.symlink(src, os.path.join(work, f\"{figure}.glb.json\"))\n json.dump(spec, open(os.path.join(work, \"spec.json\"), \"w\"))\n s = socket.socket()\n s.bind((\"127.0.0.1\", 0))\n port = s.getsockname()[1]\n s.close()\n server = subprocess.Popen([sys.executable, \"-m\", \"http.server\", str(port), \"--bind\", \"127.0.0.1\", \"--directory\", work],\n stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)\n try:\n time.sleep(0.4)\n r = subprocess.run([CHROMIUM, \"--headless=new\", \"--use-angle=swiftshader\", \"--enable-unsafe-swiftshader\",\n \"--ignore-gpu-blocklist\", \"--window-size=1280,900\", \"--virtual-time-budget=120000\",\n \"--dump-dom\", f\"http://127.0.0.1:{port}/index.html?spec=spec.json\"],\n capture_output=True, text=True, timeout=300)\n finally:\n server.terminate()\n finally:\n shutil.rmtree(work, ignore_errors=True)\n m = re.search(r'id=\"out\"[^>]*>(\\{.*?\\})</textarea>', r.stdout, re.S)\n if not m:\n sys.exit(\"the frame page gave no result:\\n\" + r.stderr[-1500:])\n return json.loads(m.group(1).replace(\""\", '\"').replace(\"&\", \"&\"))\n\n\ndef main():\n if len(sys.argv) == 3 and sys.argv[1] == \"--info\":\n res = shoot({\"figure\": sys.argv[2]})\n print(json.dumps({k: res[k] for k in (\"height\", \"box\", \"landmarks\")}, indent=1))\n return\n if len(sys.argv) != 3:\n sys.exit(__doc__)\n t0 = time.time()\n spec = json.load(open(sys.argv[1]))\n res = shoot(spec)\n os.makedirs(sys.argv[2], exist_ok=True)\n for label, data in res[\"shots\"].items():\n open(os.path.join(sys.argv[2], f\"{label}.png\"), \"wb\").write(base64.b64decode(data.split(\",\", 1)[1]))\n json.dump({k: res[k] for k in (\"height\", \"box\", \"landmarks\")}, open(os.path.join(sys.argv[2], \"frame_info.json\"), \"w\"), indent=1)\n print(f\"{len(res['shots'])} image(s) in {sys.argv[2]}, {time.time() - t0:.0f}s, figure {res['height']} m\")\n\n\nif __name__ == \"__main__\":\n main()\n"}{"chunk_id":"a3ed42","wall_time_seconds":0.00000356,"exit_code":2,"original_token_count":231,"output":"ls: cannot access 'review/out': No such file or directory\n~/.local/share/lowmarch:\ntotal 52\ndrwxr-xr-x 13 runner runner 4096 Oct 29 22:09 .\ndrwx------ 3 runner runner 4096 Nov 15 03:13 ..\ndrwxr-xr-x 5 runner runner 4096 Oct 10 12:26 anthro\ndrwxr-xr-x 4 runner runner 4096 Oct 9 08:05 blender-base-meshes\ndrwxr-xr-x 4 runner runner 4096 Oct 8 15:55 makehuman\ndrwxr-xr-x 4 runner runner 4096 Oct 9 08:10 quaternius\ndrwxr-xr-x 5 runner runner 4096 Oct 8 12:08 refs\ndrwxr-xr-x 10 runner runner 4096 Oct 8 01:30 refs3d\ndrwxr-xr-x 6 runner runner 4096 Oct 9 19:20 study\ndrwxr-xr-x 3 runner runner 4096 Oct 9 08:04 tools\ndrwx------ 9 runner runner 4096 Nov 8 04:48 trials\ndrwxr-xr-x 16 runner runner 4096 Oct 12 17:04 vroid\ndrwxr-xr-x 3 runner runner 4096 Oct 9 11:35 winvroid\n\n~/out:\ntotal 8\ndrwx------ 2 runner runner 4096 Nov 15 03:12 .\ndrwx------ 6 runner runner 4096 Nov 15 03:12 ..\n"}