Upload folder using huggingface_hub

README.md

@@ -21,7 +21,7 @@ Local computer-vision CLI tool that measures **finger outer diameter** from a si
 - Detects hand/finger with MediaPipe.
 - Measures finger width in the ring-wearing zone.
 - **Regression calibration** corrects systematic over-measurement (MAE: 0.158 → 0.060 cm).
-- **Ring size recommendation** maps calibrated diameter to China standard sizes 6–13 (best match + 2-size range).
+- **Ring size recommendation** maps calibrated diameter to sizes 6–13 (best match + 2-size range). Supports multiple ring models: **Gen1/Gen2** and **Air**, each with its own size chart.
 - **Multi-finger mode** measures index, middle, and ring fingers in one pass; consensus aggregation maximizes the chance at least one finger fits.
 - **Optional AI explanation** (OpenAI) generates a human-readable rationale for the recommendation (size selection is always deterministic).
 - Supports dual edge modes:
@@ -72,6 +72,9 @@ python measure_finger.py --input input/test_image.jpg --output output/result.jso
 
 # Multi-finger (recommended) — measures index, middle, ring in one pass
 python measure_finger.py --input input/test_image.jpg --output output/result.json --mode multi
+
+# Specify ring model (gen or air)
+python measure_finger.py --input input/test_image.jpg --output output/result.json --mode multi --ring-model air
 ```
 
 ### Common options
@@ -105,6 +108,7 @@ python measure_finger.py --input image.jpg --output output/result.json \
 | `--debug` | flag | false | Save intermediate debug images |
 | `--finger-index` | auto, index, middle, ring, pinky | index | Which finger to measure (single mode) |
 | `--mode` | single, multi | single | Single finger or all 3 fingers |
+| `--ring-model` | gen, air | gen | Ring model for size lookup (Gen1/Gen2 or Air) |
 | `--confidence-threshold` | float | 0.7 | Minimum confidence threshold |
 | `--edge-method` | auto, contour, sobel, compare | auto | Edge detection method |
 | `--sobel-threshold` | float | 15.0 | Minimum gradient magnitude |
@@ -133,14 +137,15 @@ python measure_finger.py --input image.jpg --output output/result.json \
     "best_match_inner_mm": 18.6,
     "range_min": 8,
     "range_max": 9,
-    "diameter_mm": 17.80
+    "diameter_mm": 17.80,
+    "ring_model": "gen"
   }
 }
 ```
 
 Notes:
 - `raw_diameter_cm` is the pre-calibration measurement (present when calibration is applied).
-- `ring_size` maps calibrated diameter to China standard sizes 6–13 (nearest match + 2-size recommended range).
+- `ring_size` maps calibrated diameter to sizes 6–13 for the selected ring model (nearest match + 2-size recommended range). `ring_model` indicates which chart was used (`gen` or `air`).
 - `edge_method_used` and `method_comparison` are optional (present when relevant).
 - Result image path is auto-derived: `output/result.json` → `output/result.png`.
 

measure_finger.py

@@ -31,7 +31,7 @@ from src.confidence import (
     compute_overall_confidence,
 )
 from src.debug_observer import draw_comprehensive_edge_overlay
-from src.ring_size import recommend_ring_size, aggregate_ring_sizes
+from src.ring_size import recommend_ring_size, aggregate_ring_sizes, VALID_RING_MODELS, DEFAULT_RING_MODEL
 from src.image_quality import (
     check_card_in_frame,
     check_finger_landmarks_visible,
@@ -146,6 +146,15 @@ Examples:
         help="Measurement mode: single (one finger) or multi (index+middle+ring at once) (default: single)",
     )
 
+    # Ring model
+    parser.add_argument(
+        "--ring-model",
+        type=str,
+        choices=VALID_RING_MODELS,
+        default=DEFAULT_RING_MODEL,
+        help=f"Ring model for size recommendation (default: {DEFAULT_RING_MODEL})",
+    )
+
     # Calibration
     parser.add_argument(
         "--no-calibration",
@@ -273,6 +282,7 @@ def measure_finger(
     sobel_kernel_size: int = 3,
     use_subpixel: bool = True,
     skip_card_detection: bool = False,
+    ring_model: str = DEFAULT_RING_MODEL,
 ) -> Dict[str, Any]:
     """
     Main measurement pipeline.
@@ -720,7 +730,7 @@ def measure_finger(
             width_data["raw_width_cm"] = raw_cm
 
             # Add ring size for overlay
-            rec = recommend_ring_size(cal_cm)
+            rec = recommend_ring_size(cal_cm, ring_model=ring_model)
             if rec:
                 width_data["ring_size_rec"] = rec
 
@@ -974,6 +984,7 @@ def measure_multi_finger(
     use_subpixel: bool = True,
     skip_card_detection: bool = False,
     no_calibration: bool = False,
+    ring_model: str = DEFAULT_RING_MODEL,
 ) -> Dict[str, Any]:
     """Measure index, middle, and ring fingers from a single image.
 
@@ -1084,7 +1095,7 @@ def measure_multi_finger(
         # Ring size per finger
         diam = result.get("finger_outer_diameter_cm")
         if diam is not None:
-            rec = recommend_ring_size(diam)
+            rec = recommend_ring_size(diam, ring_model=ring_model)
             if rec:
                 result["ring_size"] = rec
 
@@ -1255,6 +1266,7 @@ def main() -> int:
             use_subpixel=not args.no_subpixel,
             skip_card_detection=args.skip_card_detection,
             no_calibration=args.no_calibration,
+            ring_model=args.ring_model,
         )
 
         save_output(result, args.output)
@@ -1289,6 +1301,7 @@ def main() -> int:
         sobel_kernel_size=args.sobel_kernel_size,
         use_subpixel=not args.no_subpixel,
         skip_card_detection=args.skip_card_detection,
+        ring_model=args.ring_model,
     )
 
     # Apply calibration (post-processing)
@@ -1304,7 +1317,7 @@ def main() -> int:
     # Ring size recommendation (from calibrated diameter)
     diameter = result.get("finger_outer_diameter_cm")
     if diameter is not None:
-        rec = recommend_ring_size(diameter)
+        rec = recommend_ring_size(diameter, ring_model=args.ring_model)
         if rec:
             result["ring_size"] = rec
 

src/ai_recommendation.py

@@ -8,16 +8,22 @@ import os
 import logging
 from typing import Dict, Optional
 
-from src.ring_size import RING_SIZE_CHART
+from src.ring_size import RING_MODELS, DEFAULT_RING_MODEL
 
 logger = logging.getLogger(__name__)
 
-_SIZE_TABLE_TEXT = "\n".join(
-    f"  Size {size}: inner diameter {diameter_mm:.1f} mm"
-    for size, diameter_mm in sorted(RING_SIZE_CHART.items())
-)
+_MODEL_LABELS = {"gen": "Gen1/Gen2", "air": "Air"}
 
-_SYSTEM_PROMPT = """You are a sizing explanation assistant for Femometer Smart Ring.
+
+def _build_size_table_text(ring_model: str = DEFAULT_RING_MODEL) -> str:
+    chart = RING_MODELS.get(ring_model, RING_MODELS[DEFAULT_RING_MODEL])
+    return "\n".join(
+        f"  Size {size}: inner diameter {diameter_mm:.1f} mm"
+        for size, diameter_mm in sorted(chart.items())
+    )
+
+
+_SYSTEM_PROMPT_TEMPLATE = """You are a sizing explanation assistant for Femometer Smart Ring ({model_label}).
 
 You are given measured finger widths and a pre-computed ring size recommendation.
 Your ONLY job is to explain WHY the recommended size is a good fit, in 1-2 concise sentences.
@@ -30,11 +36,11 @@ Guidelines:
 - Priority context: index finger fit is slightly preferred over middle, then ring
 - Keep it concise and actionable
 
-Ring Size Chart (China Standard):
+Ring Size Chart ({model_label}):
 {size_table}
 
 Respond in plain text (1-2 sentences). Do NOT use JSON or markdown.
-""".format(size_table=_SIZE_TABLE_TEXT)
+"""
 
 
 def ai_explain_recommendation(
@@ -42,6 +48,7 @@ def ai_explain_recommendation(
     recommended_size: int,
     range_min: int,
     range_max: int,
+    ring_model: str = DEFAULT_RING_MODEL,
 ) -> Optional[str]:
     """Call OpenAI to explain an already-computed ring size recommendation.
 
@@ -51,6 +58,7 @@ def ai_explain_recommendation(
         recommended_size: The deterministic best-match size from ring_size.py.
         range_min: Lower bound of recommended size range.
         range_max: Upper bound of recommended size range.
+        ring_model: Which ring model chart to reference.
 
     Returns:
         A plain-text explanation string, or None if the API call fails.
@@ -60,6 +68,12 @@ def ai_explain_recommendation(
         logger.warning("OPENAI_API_KEY not set, skipping AI explanation")
         return None
 
+    model_label = _MODEL_LABELS.get(ring_model, ring_model)
+    system_prompt = _SYSTEM_PROMPT_TEMPLATE.format(
+        model_label=model_label,
+        size_table=_build_size_table_text(ring_model),
+    )
+
     # Build user message with measurements and pre-computed recommendation
     lines = ["Measured finger outer diameters:"]
     for finger, width in finger_widths.items():
@@ -68,7 +82,7 @@ def ai_explain_recommendation(
         else:
             lines.append(f"  {finger.capitalize()}: measurement failed")
     lines.append("")
-    lines.append(f"Recommended size: {recommended_size} (range {range_min}–{range_max})")
+    lines.append(f"Recommended size: {recommended_size} (range {range_min}\u2013{range_max})")
     lines.append("")
     lines.append("Explain why this size is a good fit.")
     user_msg = "\n".join(lines)
@@ -80,7 +94,7 @@ def ai_explain_recommendation(
         response = client.chat.completions.create(
             model="gpt-5.4",
             messages=[
-                {"role": "system", "content": _SYSTEM_PROMPT},
+                {"role": "system", "content": system_prompt},
                 {"role": "user", "content": user_msg},
             ],
             temperature=0.3,

src/ring_size.py

@@ -1,24 +1,44 @@
 """Ring size recommendation from calibrated finger width."""
 
-from typing import Dict, List, Optional, Tuple
-
-# China standard ring size chart: size → inner diameter (mm)
-RING_SIZE_CHART = {
-    6: 16.9,
-    7: 17.7,
-    8: 18.6,
-    9: 19.4,
-    10: 20.3,
-    11: 21.1,
-    12: 21.9,
-    13: 22.7,
+from typing import Dict, List, Literal, Optional, Tuple
+
+# Ring model definitions: model name → {size: inner_diameter_mm}
+RING_MODELS: Dict[str, Dict[int, float]] = {
+    "gen": {
+        6: 16.9,
+        7: 17.7,
+        8: 18.6,
+        9: 19.4,
+        10: 20.3,
+        11: 21.1,
+        12: 21.9,
+        13: 22.7,
+    },
+    "air": {
+        6: 16.6,
+        7: 17.4,
+        8: 18.2,
+        9: 19.0,
+        10: 19.9,
+        11: 20.7,
+        12: 21.5,
+        13: 22.3,
+    },
 }
 
-# Sorted sizes for lookup
-_SORTED_SIZES = sorted(RING_SIZE_CHART.items(), key=lambda x: x[1])
+VALID_RING_MODELS = list(RING_MODELS.keys())
+DEFAULT_RING_MODEL = "gen"
 
+# Backwards-compatible alias
+RING_SIZE_CHART = RING_MODELS[DEFAULT_RING_MODEL]
 
-def recommend_ring_size(diameter_cm: float) -> Optional[Dict]:
+
+def _get_sorted_sizes(ring_model: str) -> List[Tuple[int, float]]:
+    chart = RING_MODELS.get(ring_model, RING_MODELS[DEFAULT_RING_MODEL])
+    return sorted(chart.items(), key=lambda x: x[1])
+
+
+def recommend_ring_size(diameter_cm: float, ring_model: str = DEFAULT_RING_MODEL) -> Optional[Dict]:
     """Recommend ring size from calibrated finger outer diameter.
 
     Returns dict with:
@@ -26,6 +46,7 @@ def recommend_ring_size(diameter_cm: float) -> Optional[Dict]:
         - best_match_inner_mm: inner diameter of best match
         - range_min / range_max: recommended 2-size range
         - diameter_mm: input converted to mm
+        - ring_model: which model chart was used
     Returns None if diameter is out of reasonable range.
     """
     diameter_mm = diameter_cm * 10.0
@@ -33,12 +54,14 @@ def recommend_ring_size(diameter_cm: float) -> Optional[Dict]:
     if diameter_mm < 14.0 or diameter_mm > 26.0:
         return None
 
+    sorted_sizes = _get_sorted_sizes(ring_model)
+
     # Find nearest size
-    best_size, best_inner = min(_SORTED_SIZES, key=lambda x: abs(x[1] - diameter_mm))
+    best_size, best_inner = min(sorted_sizes, key=lambda x: abs(x[1] - diameter_mm))
 
     # Find second nearest size
     second_size, second_inner = min(
-        (s for s in _SORTED_SIZES if s[0] != best_size),
+        (s for s in sorted_sizes if s[0] != best_size),
         key=lambda x: abs(x[1] - diameter_mm),
     )
 
@@ -51,6 +74,7 @@ def recommend_ring_size(diameter_cm: float) -> Optional[Dict]:
         "range_min": range_min,
         "range_max": range_max,
         "diameter_mm": round(diameter_mm, 2),
+        "ring_model": ring_model,
     }
 
 

web_demo/app.py

@@ -21,7 +21,7 @@ ROOT_DIR = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(ROOT_DIR))
 
 from measure_finger import measure_finger, measure_multi_finger, apply_calibration
-from src.ring_size import recommend_ring_size
+from src.ring_size import recommend_ring_size, RING_MODELS, VALID_RING_MODELS, DEFAULT_RING_MODEL
 from src.ai_recommendation import ai_explain_recommendation
 
 APP_ROOT = Path(__file__).resolve().parent
@@ -109,6 +109,9 @@ def api_measure():
 
     finger_index = request.form.get("finger_index", "index")
     mode = request.form.get("mode", "single")
+    ring_model = request.form.get("ring_model", DEFAULT_RING_MODEL)
+    if ring_model not in VALID_RING_MODELS:
+        ring_model = DEFAULT_RING_MODEL
     run_id = uuid.uuid4().hex[:12]
     safe_name = secure_filename(file.filename)
     upload_name = f"{run_id}__{safe_name}"
@@ -124,12 +127,14 @@ def api_measure():
         return _run_multi_measurement(
             image=image,
             input_image_url=f"/uploads/{upload_name}",
+            ring_model=ring_model,
         )
 
     return _run_measurement(
         image=image,
         finger_index=finger_index,
         input_image_url=f"/uploads/{upload_name}",
+        ring_model=ring_model,
     )
 
 
@@ -137,6 +142,9 @@ def api_measure():
 def api_measure_default():
     finger_index = request.form.get("finger_index", "index")
     mode = request.form.get("mode", "single")
+    ring_model = request.form.get("ring_model", DEFAULT_RING_MODEL)
+    if ring_model not in VALID_RING_MODELS:
+        ring_model = DEFAULT_RING_MODEL
     if not DEFAULT_SAMPLE_PATH.exists():
         return jsonify({"success": False, "error": "Default sample image not found"}), 500
 
@@ -148,12 +156,14 @@ def api_measure_default():
         return _run_multi_measurement(
             image=image,
             input_image_url=DEFAULT_SAMPLE_URL,
+            ring_model=ring_model,
         )
 
     return _run_measurement(
         image=image,
         finger_index=finger_index,
         input_image_url=DEFAULT_SAMPLE_URL,
+        ring_model=ring_model,
     )
 
 
@@ -161,6 +171,7 @@ def _run_measurement(
     image,
     finger_index: str,
     input_image_url: str,
+    ring_model: str = DEFAULT_RING_MODEL,
 ):
     run_id = uuid.uuid4().hex[:12]
 
@@ -173,6 +184,7 @@ def _run_measurement(
         edge_method=DEMO_EDGE_METHOD,
         result_png_path=str(result_png_path),
         save_debug=False,
+        ring_model=ring_model,
     )
 
     # Apply calibration
@@ -182,7 +194,7 @@ def _run_measurement(
         calibrated = round(apply_calibration(raw_diameter), 4)
         result["finger_outer_diameter_cm"] = calibrated
         result["calibration_applied"] = True
-        rec = recommend_ring_size(calibrated)
+        rec = recommend_ring_size(calibrated, ring_model=ring_model)
         if rec:
             result["ring_size"] = rec
 
@@ -206,6 +218,7 @@ def _run_measurement(
 def _run_multi_measurement(
     image,
     input_image_url: str,
+    ring_model: str = DEFAULT_RING_MODEL,
 ):
     """Run multi-finger measurement pipeline."""
     run_id = uuid.uuid4().hex[:12]
@@ -219,6 +232,7 @@ def _run_multi_measurement(
         result_png_path=str(result_png_path),
         save_debug=False,
         no_calibration=False,
+        ring_model=ring_model,
     )
 
     result = _numpy_safe(result)
@@ -241,6 +255,7 @@ def _run_multi_measurement(
             recommended_size=result["overall_best_size"],
             range_min=result["overall_range_min"],
             range_max=result["overall_range_max"],
+            ring_model=ring_model,
         )
     if ai_reason:
         result["ai_explanation"] = ai_reason

web_demo/static/app.js

@@ -92,26 +92,35 @@ const showImage = (imgEl, frameEl, url) => {
   frameEl.querySelector(".placeholder").style.display = "none";
 };
 
+const ringModelSelect = document.getElementById("ringModelSelect");
+
+const RING_SIZE_TABLES = {
+  gen: {6: 16.9, 7: 17.7, 8: 18.6, 9: 19.4, 10: 20.3, 11: 21.1, 12: 21.9, 13: 22.7},
+  air: {6: 16.6, 7: 17.4, 8: 18.2, 9: 19.0, 10: 19.9, 11: 20.7, 12: 21.5, 13: 22.3},
+};
+const RING_MODEL_LABELS = { gen: "Gen1/Gen2", air: "Air" };
+
 const buildMeasureSettings = () => {
   const fingerSelect = form.querySelector('select[name="finger_index"]');
   const aiToggle = document.getElementById("aiExplainToggle");
   const mode = modeSelect ? modeSelect.value : "single";
+  const ringModel = ringModelSelect ? ringModelSelect.value : "gen";
   return {
     finger_index: fingerSelect ? fingerSelect.value : "index",
     edge_method: "sobel",
     mode: mode,
+    ring_model: ringModel,
     ai_explain: aiToggle && aiToggle.checked ? "1" : "0",
   };
 };
 
 const renderMultiResult = (result) => {
   if (!result || !result.per_finger) {
-    multiResultPanel.style.display = "none";
+    overallSize.innerHTML = `<div class="size-hero"><span class="size-label">Measurement Failed</span></div>`;
+    fingerBreakdown.innerHTML = "";
     return;
   }
 
-  multiResultPanel.style.display = "";
-
   const aiExplanation = result.ai_explanation;
 
   // Always show deterministic recommendation as hero
@@ -156,22 +165,20 @@ const renderMultiResult = (result) => {
   html += "</div>";
   html += `<div class="finger-count">${result.fingers_succeeded}/${result.fingers_measured} fingers measured</div>`;
 
-  // Size reference table
+  // Size reference table (dynamic based on selected ring model)
+  const ringModel = ringModelSelect ? ringModelSelect.value : "gen";
+  const sizeTable = RING_SIZE_TABLES[ringModel] || RING_SIZE_TABLES.gen;
+  const modelLabel = RING_MODEL_LABELS[ringModel] || ringModel;
+  let tableRows = "";
+  for (const [size, mm] of Object.entries(sizeTable)) {
+    tableRows += `<tr><td>${size}</td><td>${mm.toFixed(1)}</td></tr>`;
+  }
   html += `
     <div class="size-ref-table">
-      <h3 class="size-ref-title">Size Reference</h3>
+      <h3 class="size-ref-title">Size Reference (${modelLabel})</h3>
       <table>
         <thead><tr><th>Size</th><th>Inner ⌀ (mm)</th></tr></thead>
-        <tbody>
-          <tr><td>6</td><td>16.9</td></tr>
-          <tr><td>7</td><td>17.7</td></tr>
-          <tr><td>8</td><td>18.6</td></tr>
-          <tr><td>9</td><td>19.4</td></tr>
-          <tr><td>10</td><td>20.3</td></tr>
-          <tr><td>11</td><td>21.1</td></tr>
-          <tr><td>12</td><td>21.9</td></tr>
-          <tr><td>13</td><td>22.7</td></tr>
-        </tbody>
+        <tbody>${tableRows}</tbody>
       </table>
     </div>`;
 
@@ -181,7 +188,8 @@ const renderMultiResult = (result) => {
 const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
   setStatus("Measuring… Please wait.");
   jsonOutput.textContent = '{\n  "status": "processing"\n}';
-  multiResultPanel.style.display = "none";
+  overallSize.innerHTML = `<div class="size-hero"><span class="size-label">Measuring…</span></div>`;
+  fingerBreakdown.innerHTML = "";
 
   try {
     const response = await fetch(endpoint, {
@@ -250,6 +258,7 @@ form.addEventListener("submit", async (event) => {
   formData.append("finger_index", settings.finger_index);
   formData.append("edge_method", settings.edge_method);
   formData.append("mode", settings.mode);
+  formData.append("ring_model", settings.ring_model);
   formData.append("ai_explain", settings.ai_explain);
 
   const file = imageInput.files[0];

web_demo/templates/index.html

@@ -44,6 +44,13 @@
               <option value="auto">Auto</option>
             </select>
           </label>
+          <label>
+            <span>Ring Model</span>
+            <select name="ring_model" id="ringModelSelect">
+              <option value="gen" selected>Gen1/Gen2</option>
+              <option value="air">Air</option>
+            </select>
+          </label>
           <label>
             <span>Edge Method</span>
             <select name="edge_method" disabled aria-disabled="true">
@@ -85,10 +92,14 @@
     </section>
 
     <section class="result">
-      <div class="panel" id="multiResultPanel" style="display:none;">
+      <div class="panel" id="multiResultPanel">
         <h2>Ring Size Recommendation</h2>
         <div id="multiResult" class="multi-result">
-          <div class="overall-size" id="overallSize"></div>
+          <div class="overall-size" id="overallSize">
+            <div class="size-hero">
+              <span class="size-label">Waiting for measurement</span>
+            </div>
+          </div>
           <div class="finger-breakdown" id="fingerBreakdown"></div>
         </div>
       </div>
@@ -100,19 +111,6 @@
         </div>
         <pre id="jsonOutput">{}</pre>
       </div>
-
-      <div class="panel tips">
-        <h2>📸 Photo Tips</h2>
-        <ul>
-          <li>✅ Place credit card flat next to your hand</li>
-          <li>✅ Shoot from directly above (bird's-eye view)</li>
-          <li>✅ Turn on flash for even lighting</li>
-          <li>✅ Keep all fingers and card fully within frame</li>
-          <li>✅ Spread index, middle, and ring fingers apart</li>
-          <li>✅ Use a plain, light-colored background</li>
-          <li>✅ Hold phone steady — avoid blur</li>
-        </ul>
-      </div>
     </section>
   </main>