Building a mapped reference library for 3D modeling

Models now get built and judged against a library of reference pictures. It has 11 subjects and 235 pictures, a small Python tool to fill and search it, and a line in the model pipeline that says a brief has to cite the pictures it’s built against. Nothing in the game changed, so there’s nothing to show.

Why did I need a reference library?

The hands of the playable races took many judged rounds. Each round, the builder and the judge were working from whatever they remembered a hand looks like. I asked for a step that pulls reference photos for whatever I’m building, and then for something better: a library I keep adding to, with the same kind of map I use elsewhere so an agent doesn’t have to search the whole thing.

How can an agent find a picture without opening the folders?

The library lives in the art workspace, outside the repository. It has one folder per subject, and a subject is what a model gets judged on: hands, heads, necks, feet, cat heads, hound heads, corvid heads. It isn’t a whole creature.

refs/INDEX.md                    one line per subject
refs/<subject>/MAP.md            one line per picture
refs/<subject>/<id>-<slug>.jpg   the picture, long side 1024 px or less

An agent reads the index, then one subject’s map, then only the pictures it needs or a contact sheet of them. It never lists a folder. A map line has 11 columns: id, file, kind, what it shows, view, licence, author, source, when it was fetched, what used it, and a model file if one is kept. The tool writes both files, nobody edits them by hand. Ids are never reused. Each map ends with a “last id” line, so a picture I remove leaves its number empty and an old citation can’t end up pointing at a different picture.

The tool is tools/refs.py. find returns the map lines, across every subject, that contain all the words you give it. sheet makes a labelled contact sheet. used records which model or judged round used a picture. check makes sure every picture has a map line and every line has a picture, and that every licence is one I keep.

Where do the pictures come from?

add takes a Wikimedia Commons title, an Openverse id, a Sketchfab model page, a plain URL or a file. For the first three it fills in the source, licence and author itself. Every picture is resized to 1024 pixels on its long side and saved as a jpg.

The licence rule is a regular expression. Public domain and CC0 come first, then CC BY and CC BY-SA with the author written down, and Pexels and Unsplash by name. Non-commercial, no-derivatives, all rights reserved, anything behind a login or with a watermark is refused. Commons answers HTTP 429 to a burst of requests, so the download waits and tries again.

I seeded the first subjects from Commons, and it was nearly all statues and busts. I said so: “the heads refs are all statues, include 3d assets, and photos of real people whenever possible as well”. So the rule is now the same for every subject. Photos of real people or animals are the majority, 3D assets (low-poly game models above all) come next, and casts, statues and drawings are the minority. Each picture has a kind column and check prints each subject’s mix. Commons turned out to be poor for photos of real people, so the tool also searches Openverse, and it searches Sketchfab for models. For a Sketchfab model the creator’s preview is the picture and the model’s page is the source. I only keep the model file itself if it’s CC0.

The seven anatomy subjects ended up with 149 pictures: 90 photos, 34 3D assets, 20 casts and 5 drawings.

What changed in the model pipeline?

Step 1 now also says what a model is built against. A brief written after 14 October has a ## References section with one line per cited picture, its id and the feature it’s for, like hands-020: the fist from the front, knuckles as blocks. refs.py cited lists them and fails on an id the library doesn’t have or a brief that cites nothing. A subject with fewer than about ten pictures, or no photo of the view the model is seen in, gets filled first. If a judge round fails twice on the same feature, references for it get fetched before the third round, and the builder and the judge both compare against them.

I didn’t make pipeline.py check the citation. A brief belongs to a family of models, not one model, so the code couldn’t tell an old member’s brief from a new one without dating it by git, and that fails for a brief that isn’t committed yet. The library is also outside the repository, so step 1 would fail on any machine without it. refs.py cited is the check, and the judge’s checklist asks for it.

What’s the style bible?

I also asked for a style bible, something to check the feel, textures and paints of props and armor against. It’s four more subjects, 86 pictures of games with the look I want, plus a written summary of what Blobber takes from them and what it doesn’t. A prop, armor or weapon brief cites two or more of them and says what to take from each. These are copyrighted screenshots, so their licence is a special value, STUDY-ONLY, which check accepts only in subjects whose name starts with style_. They’re for looking at. They never get copied into a model, a texture, the repository or a page. That’s also why this post has no pictures.

Also done

• A test, ref_library, runs the tool’s 21 self-checks and then the real library’s check. It skips the second where the library isn’t on the machine.