# THIS YOU — Dynamic Visual Feature Map & Product Identity Fidelity

## Goal

Replace static, garment-type-specific fidelity checks with a **generic visual decomposition system** that can inspect any fashion product and automatically determine which visible details make that exact product recognizable.

The system must work for:

- jackets;
- coats;
- shirts;
- trousers;
- dresses;
- skirts;
- knitwear;
- shoes;
- bags;
- eyewear;
- hats;
- jewellery;
- other accessories.

The key principle is:

> Do not ask only “what should normally be checked for this garment type?”  
> Ask “what visible features in these exact reference images make this exact product identifiable?”

This system sits on top of the existing Product Visual Lock architecture.

---

# 1. Problem to solve

The current system can store broad fields such as:

```json
[
  "front_closure",
  "collar",
  "pocket_configuration",
  "overall_length",
  "silhouette",
  "primary_color"
]
```

This is not detailed enough.

Example failure:

The reference jacket has:

- exactly 5 visible black front buttons;
- evenly spaced vertically;
- centered on the front placket;
- zipper concealed;
- exactly 2 diagonal flap pockets;
- 1 black button on each pocket.

A generated HERO may contain:

- only 4 buttons;
- exposed zipper;
- different pocket shape.

A broad check like:

```json
"front_closure": "pass"
```

can incorrectly pass the garment even though it is visibly a different product.

Therefore the system must derive **dynamic, product-specific visual features** from the exact product images.

---

# 2. New pipeline

Required pipeline:

```text
EXACT PRODUCT IMAGE(S)
        ↓
VISUAL DECOMPOSITION
        ↓
FEATURE MAP
        ↓
IDENTITY SIGNATURE
        ↓
DYNAMIC FIDELITY CHECKLIST
        ↓
HERO GENERATION
        ↓
IMAGE-TO-IMAGE + FEATURE CHECK
        ↓
PASS / TARGETED CORRECTION / HUMAN REVIEW
```

---

# 3. Source of truth

The exact product reference image is the primary visual source of truth.

Use:

```text
real product reference image(s)
+
structured visual feature extraction
+
optional retailer text
```

Do not derive product identity only from:

- product title;
- product description;
- URL;
- category;
- brand;
- cached text;
- generic knowledge of that garment type.

---

# 4. Visual decomposition

For every visually significant element in the product reference, extract the feature into a structured representation.

Do not hardcode only fashion-specific attributes.

Use a generic set of visual primitives.

## Core primitive types

```text
COUNT
POSITION
SIZE
SHAPE
COLOR
MATERIAL
TEXTURE
ORIENTATION
ANGLE
SPACING
PROPORTION
SYMMETRY
LENGTH
WIDTH
VISIBLE / HIDDEN
RELATION TO OTHER FEATURES
PATTERN
EDGE / HEM SHAPE
LAYERING
HARDWARE
GRAPHIC / LOGO PLACEMENT
```

These primitives can represent almost any visible garment or accessory detail.

---

# 5. Example — buttons

Instead of:

```json
{
  "buttons": true
}
```

extract:

```json
{
  "feature_id": "front_buttons",
  "feature_type": "button_group",
  "count": 5,
  "color": "black",
  "placement": "center_front",
  "orientation": "vertical",
  "spacing": "even",
  "visibility": "fully_visible",
  "relative_scale": "medium",
  "priority": "identity_critical"
}
```

---

# 6. Example — pockets

Instead of:

```json
{
  "pockets": 2
}
```

extract:

```json
{
  "feature_id": "front_pockets",
  "feature_type": "pocket_group",
  "count": 2,
  "symmetry": "left_right_symmetric",
  "placement": "lower_front",
  "shape": "compact_flap",
  "orientation": "diagonal_upward_toward_center",
  "closure": {
    "type": "button",
    "count_per_pocket": 1,
    "color": "black"
  },
  "patch_body_visible": false,
  "priority": "identity_critical"
}
```

---

# 7. Example — collar

```json
{
  "feature_id": "collar",
  "feature_type": "collar",
  "shape": "wide_pointed",
  "color": "black",
  "texture": "ribbed_corduroy",
  "width": "wide_relative_to_neck",
  "orientation": "flat_spread",
  "priority": "identity_critical"
}
```

---

# 8. Example — sneaker

A sneaker feature map could include:

```json
[
  {
    "feature_id": "base_upper",
    "material": "open_mesh",
    "color": "white"
  },
  {
    "feature_id": "overlay_system",
    "material": "synthetic",
    "color": "metallic_silver",
    "placement": "toe_eyestay_side_heel"
  },
  {
    "feature_id": "side_stripes",
    "count": 4,
    "color": "dark_burgundy",
    "placement": "both_sides",
    "shape": "asics_cage_geometry"
  },
  {
    "feature_id": "midsole",
    "color": "natural_white",
    "shape": "sculpted_retro_runner"
  },
  {
    "feature_id": "outsole_blocks",
    "color": "black",
    "placement": "forefoot_and_heel"
  }
]
```

---

# 9. Dynamic feature extraction

The system must inspect each exact product reference and automatically identify relevant features.

Do not rely only on a fixed schema like:

```text
collar
buttons
pockets
```

The extractor must also detect product-specific features such as:

- drawstrings;
- buckles;
- pleats;
- panels;
- vents;
- slits;
- straps;
- cut-outs;
- embroidery;
- contrast stitching;
- piping;
- patch placement;
- zipper orientation;
- sole segmentation;
- heel blocks;
- eyestay shape;
- logo placement;
- graphic scale;
- asymmetric construction;
- fastening count;
- layered panels;
- seam geometry.

---

# 10. Product Identity Signature

After decomposition, generate a concise list of the most recognition-critical features.

Example:

```json
{
  "identity_signature": [
    "wide ribbed black pointed collar",
    "exactly 5 centered black front buttons",
    "concealed zipper",
    "2 diagonal lower flap pockets",
    "1 black button on each pocket",
    "straight padded mid-thigh body",
    "raglan shoulders"
  ]
}
```

The identity signature should contain only features that materially distinguish this exact product.

---

# 11. Feature importance levels

Every extracted feature receives a priority:

```text
identity_critical
important
secondary
approximate
```

Map to fidelity behavior:

```text
identity_critical → MUST_MATCH
important         → SHOULD_MATCH
secondary         → SHOULD_MATCH when visible
approximate       → MAY_APPROXIMATE
```

---

# 12. Dynamic fidelity checklist

Do not use one universal fixed list for every product.

Generate the checklist automatically from the feature map.

Example for the jacket:

```json
[
  "front_button_count",
  "front_button_color",
  "front_button_spacing",
  "front_button_position",
  "zipper_visibility",
  "collar_shape",
  "collar_texture",
  "pocket_count",
  "pocket_shape",
  "pocket_angle",
  "pocket_button_count",
  "overall_length",
  "body_proportion",
  "sleeve_shape",
  "primary_color"
]
```

Example for a dress:

```json
[
  "strap_count",
  "strap_width",
  "neckline_shape",
  "waist_seam_position",
  "skirt_volume",
  "slit_count",
  "slit_position",
  "hem_length",
  "print_scale",
  "print_distribution"
]
```

Example for a bag:

```json
[
  "handle_count",
  "handle_length",
  "closure_type",
  "hardware_color",
  "front_pocket_count",
  "logo_position",
  "body_shape",
  "base_width"
]
```

---

# 13. Comparison mode

Every feature should declare how it must be compared.

Supported comparison modes:

```text
exact
categorical
relative
approximate
presence_absence
count
spatial
color_similarity
shape_similarity
```

Example:

```json
{
  "feature_id": "front_button_count",
  "expected": 5,
  "comparison": "exact",
  "priority": "must_match"
}
```

Example:

```json
{
  "feature_id": "pocket_angle",
  "expected": "diagonal_upward_toward_center",
  "comparison": "categorical",
  "priority": "must_match"
}
```

Example:

```json
{
  "feature_id": "fabric_wrinkle_pattern",
  "comparison": "approximate",
  "priority": "may_approximate"
}
```

---

# 14. Exact-count rule

When the reference clearly exposes a countable feature, exact count must be checked.

Examples:

```text
buttons
pockets
straps
buckles
zippers
vents
slits
pleats
eyelets
stripes
panels
logos
patches
```

If reference:

```text
5 buttons
```

and HERO:

```text
4 buttons
```

result:

```json
{
  "front_button_count": "fail"
}
```

This must be a critical failure if the feature is identity-critical.

---

# 15. Visibility rule

Use:

```text
pass
fail
not_visible
```

Definitions remain:

### PASS

Feature is visible enough and matches.

### FAIL

Feature is visible enough and clearly mismatches.

### NOT_VISIBLE

Pose, crop, layering, lighting or occlusion prevents reliable assessment.

Do not:

- guess hidden features;
- mark invisible features as pass;
- mark invisible features as fail.

---

# 16. Missing reference is different from NOT_VISIBLE

Important distinction:

```text
NOT_VISIBLE
```

means:

> reference exists, but HERO does not expose the feature.

This is different from:

```text
insufficient_visual_reference
```

which means:

> there is no usable product reference image.

Do not mix these states.

---

# 17. Feature evidence

Every feature should record where it was observed.

Example:

```json
{
  "feature_id": "front_button_count",
  "reference_evidence": [
    {
      "reference_type": "front",
      "asset_id": "product-assets/231/front.jpg"
    }
  ]
}
```

This improves traceability.

---

# 18. Multi-image reconciliation

When multiple official references exist:

```text
front
detail
side
back
on_model
```

extract features from all available views.

Do not overwrite one view with another.

Use view-specific evidence.

Example:

```json
{
  "feature_id": "rear_patch_pocket",
  "visible_in_reference_views": [
    "back"
  ]
}
```

---

# 19. Unknown / ambiguous features

If a feature cannot be confidently determined from the reference:

```json
{
  "confidence": 0.54,
  "status": "ambiguous"
}
```

Do not convert ambiguity into a hard constraint.

Recommended threshold:

```text
>= 0.85 → may become MUST_MATCH
0.65–0.84 → SHOULD_MATCH / human review
< 0.65 → do not lock as hard feature
```

Thresholds should remain configurable.

---

# 20. Visual feature schema

Recommended new structure:

```json
{
  "visual_feature_map": [
    {
      "feature_id": "front_buttons",
      "feature_type": "button_group",
      "attributes": {
        "count": 5,
        "color": "black",
        "position": "center_front",
        "orientation": "vertical",
        "spacing": "even"
      },
      "comparison": {
        "count": "exact",
        "color": "color_similarity",
        "position": "spatial",
        "spacing": "relative"
      },
      "priority": "identity_critical",
      "confidence": 0.99,
      "reference_evidence": [
        "front"
      ]
    }
  ]
}
```

---

# 21. Keep visual_spec

Do not remove the current human-readable `visual_spec`.

Keep both:

```text
visual_spec
+
visual_feature_map
```

Roles:

### visual_spec

Human-readable description and generation guidance.

### visual_feature_map

Machine-checkable visual structure.

---

# 22. HERO generation

HERO generation must receive:

```text
reader reference images
+
exact product reference images
+
visual_spec
+
identity_signature
+
visual_feature_map
```

The generation prompt should explicitly mention all `identity_critical` features.

Example:

```text
EXACT PRODUCT IDENTITY REQUIREMENTS:

- exactly 5 visible black center-front buttons
- zipper concealed
- two diagonal flap pockets
- one black button per pocket
- wide ribbed collar
```

---

# 23. Do not overload generation prompt

Do not dump every minor feature into the generation prompt.

Use:

```text
identity_critical
+
highest-value important features
```

Keep lower-priority features primarily for post-generation checking.

This avoids overly complex generation prompts.

---

# 24. Post-HERO checking

After generation, run two independent checks.

## A. Structured Feature Check

Compare every assessable feature in the feature map.

Example:

```json
{
  "front_button_count": "fail",
  "zipper_visibility": "pass",
  "pocket_count": "pass"
}
```

## B. Holistic Product Similarity Check

Ask:

> Does the visible garment still look like the same specific product overall?

Return:

```json
{
  "holistic_product_identity": "pass|fail|uncertain",
  "holistic_similarity_score": 0.0
}
```

The holistic check catches mismatches not covered by individual fields.

---

# 25. Holistic similarity is not enough alone

Do not replace structured checks with one similarity score.

Bad:

```json
{
  "similarity": 0.91
}
```

Correct:

```text
structured feature checks
+
holistic similarity
```

Both are required.

---

# 26. Critical failure logic

Regeneration/correction trigger:

```pseudo
if any visible identity_critical feature == fail:
    correction_required = true
```

Examples:

```text
wrong button count
wrong pocket count
wrong collar shape
wrong closure type
wrong primary color
wrong logo geometry
wrong silhouette
wrong length category
```

---

# 27. Product score

Product score should be based only on assessable visible features.

Do not penalize:

```text
not_visible
```

Recommended weighted score:

```pseudo
identity_critical weight = 3
important weight = 2
secondary weight = 1
approximate weight = 0.5
```

Example:

```text
visible passes / visible weighted checks
```

---

# 28. Correction payload

Targeted correction should receive exact failures.

Bad:

```text
Fix the jacket.
```

Correct:

```json
{
  "failed_features": [
    {
      "feature_id": "front_button_count",
      "expected": 5,
      "observed": 4,
      "priority": "identity_critical"
    },
    {
      "feature_id": "zipper_visibility",
      "expected": "hidden",
      "observed": "visible",
      "priority": "identity_critical"
    }
  ]
}
```

This makes the correction model much more precise.

---

# 29. Correction image inputs

Correction must also receive:

```text
CURRENT HERO IMAGE
+
EXACT PRODUCT REFERENCE IMAGE(S)
+
FAILED FEATURE DATA
```

Do not correct from text only.

---

# 30. New recommended Product Visual Lock result

Example:

```json
{
  "product_id": 231,
  "reference_status": "ready",

  "visual_spec": {
    "...": "existing human-readable structure"
  },

  "identity_signature": [
    "wide ribbed black collar",
    "exactly 5 centered black buttons",
    "concealed zipper",
    "two diagonal flap pockets",
    "one button on each pocket"
  ],

  "visual_feature_map": [
    {
      "feature_id": "front_button_count",
      "feature_type": "countable_detail",
      "expected": 5,
      "comparison": "exact",
      "priority": "identity_critical",
      "confidence": 0.99
    },
    {
      "feature_id": "zipper_visibility",
      "feature_type": "visibility",
      "expected": "hidden",
      "comparison": "categorical",
      "priority": "identity_critical",
      "confidence": 0.99
    },
    {
      "feature_id": "pocket_angle",
      "feature_type": "orientation",
      "expected": "diagonal_upward_toward_center",
      "comparison": "categorical",
      "priority": "identity_critical",
      "confidence": 0.99
    }
  ]
}
```

---

# 31. Dynamic checker result

Example:

```json
{
  "product_id": 231,

  "feature_checks": [
    {
      "feature_id": "front_button_count",
      "status": "fail",
      "expected": 5,
      "observed": 4
    },
    {
      "feature_id": "zipper_visibility",
      "status": "pass",
      "expected": "hidden",
      "observed": "hidden"
    },
    {
      "feature_id": "rear_construction",
      "status": "not_visible"
    }
  ],

  "holistic_product_identity": "fail",
  "holistic_similarity_score": 0.82,

  "critical_failures": [
    "front_button_count"
  ]
}
```

---

# 32. Admin human-review UI

Show the generated identity signature:

```text
PRODUCT IDENTITY

✓ 5 front buttons
✓ concealed zipper
✓ wide ribbed collar
✓ 2 diagonal flap pockets
✓ 1 button per pocket
```

Allow human to:

```text
approve
edit
promote to MUST_MATCH
downgrade
remove incorrect feature
```

---

# 33. Visual comparison debug UI

For human review, show:

```text
REFERENCE IMAGE | HERO CROP
```

and below:

```text
front_button_count
expected: 5
observed: 4
FAIL
```

This makes mistakes immediately understandable.

---

# 34. HERO garment cropping

Before fidelity analysis, automatically crop visible product regions from HERO.

Example:

```text
HERO
↓
detect person
↓
segment outerwear
↓
crop jacket
↓
compare jacket crop to reference jacket
```

Repeat for:

```text
shirt
trousers
shoes
bag
accessory
```

This helps the checker focus on the product instead of the full scene.

---

# 35. Occlusion awareness

Layering matters.

Example:

```text
shirt chest pocket hidden under jacket
```

Result:

```text
not_visible
```

Do not require the HERO to expose every product feature.

The user-facing image can remain natural.

---

# 36. Product coverage score

Separately track how much of the product is visually assessable.

Example:

```json
{
  "fidelity_score": 0.98,
  "coverage_score": 0.62
}
```

Meaning:

```text
visible details match very well,
but only 62% of identity features were assessable.
```

This is better than incorrectly reducing fidelity because of layering.

---

# 37. Two different scores

Recommended:

```text
fidelity_score
coverage_score
```

Do not combine them into one misleading number.

---

# 38. Existing manual review remains

`human_review_required` should remain true for production.

AI checks reduce errors but do not eliminate manual review.

Especially review:

- unusual closures;
- logo details;
- very similar colorways;
- asymmetric construction;
- fine embroidery;
- products whose identity depends on small details.

---

# 39. Acceptance criteria

## Visual Lock

- [ ] Exact product imagery was actually inspected.
- [ ] System automatically extracts dynamic visible features.
- [ ] Countable features include exact counts when clearly visible.
- [ ] Positions, orientation, shape and spacing are extracted where meaningful.
- [ ] Identity signature is produced.
- [ ] Feature priority is assigned.
- [ ] Confidence is recorded.
- [ ] Ambiguous features are not promoted to hard constraints.
- [ ] `visual_spec` remains available.
- [ ] `visual_feature_map` is added.

## HERO generation

- [ ] Product images are actual image inputs.
- [ ] Identity-critical features are included in generation constraints.
- [ ] Reader photos control identity, not garment design.
- [ ] Product references control garment construction.

## Fidelity check

- [ ] Check list is dynamically generated from the product feature map.
- [ ] Exact-count features are validated exactly.
- [ ] `pass | fail | not_visible` is used per feature.
- [ ] NOT_VISIBLE does not lower fidelity score.
- [ ] Product crop is compared against product reference imagery.
- [ ] Structured checks are performed.
- [ ] Holistic product identity check is also performed.
- [ ] Visible identity-critical failure triggers correction.
- [ ] Fidelity score and coverage score are separate.

## Correction

- [ ] Correction receives exact failed feature IDs.
- [ ] Expected and observed values are provided where possible.
- [ ] Current HERO and exact product reference images are attached.
- [ ] Unrelated passed features/products must remain unchanged.

---

# 40. Example — Weekday jacket regression test

Reference product:

```text
Weekday Oversized Padded Nylon Jacket
Black
```

Required extracted identity features:

```text
wide pointed ribbed black collar
exactly 5 black center-front buttons
buttons vertically spaced
concealed zipper
exactly 2 lower diagonal flap pockets
1 black button on each pocket
straight padded body
mid-thigh length
raglan shoulder construction
```

Regression test HERO:

```text
4 front buttons
```

Expected result:

```json
{
  "front_button_count": "fail",
  "critical_failures": [
    "front_button_count"
  ],
  "correction_required": true
}
```

The system must never return full PASS for this image.

---

# Final architecture principle

The system must not attempt to hardcode every possible fashion detail.

Instead:

```text
REFERENCE IMAGE
    ↓
DISCOVER VISIBLE FEATURES
    ↓
STRUCTURE THEM INTO GENERIC VISUAL PRIMITIVES
    ↓
IDENTIFY WHICH FEATURES DEFINE PRODUCT IDENTITY
    ↓
GENERATE PRODUCT-SPECIFIC CHECKS
```

This makes the fidelity system reusable for products and design details that were never anticipated by the developers.

Final rule:

> **The product itself defines what must be checked. The schema provides the language for describing it.**