# Project Virtual reference image specification

Read this before preparing, interpreting or modeling from reference images. Apply the user's brief and AGENTS_PV3.md. Reference quality guides the result; additional views reduce guesswork but do not replace construction and visual inspection.

## Views and naming

| Label | What it shows | Primary use |
|---|---|---|
| front | Looking straight at the subject's front | Width, height, front silhouette and landmarks |
| right | Looking at the subject's own right side | Depth, height, side profile and placement |
| rear | Looking straight at the back | Rear shape, openings and asymmetry |
| left | Looking at the subject's own left side | Differences from the right; never silently mirror |
| top | Looking down from above | Footprint, roof or upper surfaces, width/depth |
| bottom | Looking up from underneath | Underside construction, contacts and recesses |

Use descriptive names such as prop-front.png, prop-right.png and prop-top.png. Confirm labels visually instead of trusting filenames. A generic side image must be assigned right or left intentionally. PV3 uses meters, Y up and +Z front. The subject's right is its own right, not the viewer's right when facing it. Match the editor's named view and check an asymmetric landmark for mirroring.

## Prepare the source set

- Show the same subject, design, pose and configuration in every image. Keep wheels, doors and articulated parts in consistent positions.
- Prefer straight, orthographic views with no perspective distortion. An oblique photo is useful for shape/color interpretation but must not be treated as a true top or side orthographic measurement. Record its limitations.
- Use a plain contrasting or transparent background. Include the entire subject with a little margin. Avoid cropped tips, ground shadows mistaken for geometry, watermarks over important detail and heavy blur.
- Prefer PNG for the app's import path. Preserve the original decoded pixels and filenames; never downsample the original references to the 512-square delivery atlas size. Aim for readable detail (around 1024 pixels or more across the subject when available); this is a preparation recommendation, not a parser limit.
- Supply physical dimensions if known. Otherwise record the assumed scale. Match shared landmark heights and ground level across views. The guide's physical width/height describe the whole image including blank margins, so identical pixel dimensions do not automatically mean identical physical coverage.
- Front and right are the minimum required by the current generic silhouette Build route. Rear can constrain the volume. Top/left/bottom guides help inspection and subject-specific plans; attaching them does not mean every generic reconstruction path uses those views automatically. Calibrated cybercar Build uses its four original front/right/rear/top images.

## Interpret before building

Inventory supplied views and name missing ones. Identify major masses, openings, silhouette breaks, asymmetry, wheel/leg count, contacts and recognizable markings. Reconcile conflicting views explicitly. Never invent an unseen reference image or report an inferred surface as observed. Do not label a finished perspective render as a top/front input photograph.

Use a subject-specific native plan when a generic hull loses structural landmarks. The stone lesson separates masses, fits depth and uses the oblique top image for surface color. Decoded-pixel matching identifies a calibrated input set; it does not establish general image understanding. Recompressed PNGs with identical decoded pixels may match; resized or repainted copies may not.

## Geometry and color are separate checks

1. Establish the model's silhouette, depth, openings and part placement against each supplied view before baking. Preserve intentional separated masses and moving parts.
2. Use geometry for silhouette/deformation and texture for small static details such as painted eyes, closed mouths, grain and labels. Match the reference rather than replacing its appearance with arbitrary material colors.
3. Preserve photo-projection UVs on a temporary source. Give the delivery geometry an intentional unwrap, pack it and bake from matching source surfaces. Default to 512 × 512 with 2 px island/border padding. Preserve an existing correct unwrap during small edits; do not destroy authored textures unnecessarily.
4. Select projection axes with nonzero extent on each surface. A horizontal underside with constant Y needs X/Z mapping; sampling a constant axis can produce bands even when final UV overlap checks pass. Inspect source projection as well as target UVs.
5. Inspect a UV checker for distortion, folded/degenerate charts, orientation, texel allocation, seams and gutters. Inspect baked color separately for line sampling, stretched fragments, wrong source hits, background contamination and missing landmarks. Padding helps filtering bleed; it does not fix projection or UV stretching. Adjust detail allocation or request a larger atlas when the budget cannot represent important features.
6. Compare the finished model with every original view and a three-quarter view. Save/reopen and verify exports. Record inferred surfaces, measured counts and remaining engine/rig checks.

## Included example

In the beta project, see examples/cybercar/README.md for the four original input PNGs, finished editor screenshots and editable/final PV3 projects. Left and bottom references were not supplied for that example. Use those labels for future supplied views; do not claim they were part of this input set.
