Upload folder using huggingface_hub

web_demo/app.py

@@ -10,10 +10,12 @@ import csv
 import io
 import json
 import os
+import re
 import sys
 import uuid
+from datetime import datetime
 from pathlib import Path
-from typing import Dict, Any
+from typing import Dict, Any, Tuple
 
 import cv2
 import numpy as np
@@ -43,6 +45,19 @@ def _allowed_file(filename: str) -> bool:
     return Path(filename).suffix.lower() in ALLOWED_EXTENSIONS
 
 
+def _slugify(name: str) -> str:
+    slug = re.sub(r"[^a-zA-Z0-9]+", "-", name or "").strip("-").lower()
+    return slug or "anon"
+
+
+def _make_base_name(kol_name: str) -> Tuple[str, str]:
+    """Return (base_name, run_id). base_name = '{slug}_{timestamp}_{shortid}'."""
+    run_id = uuid.uuid4().hex[:8]
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    base_name = f"{_slugify(kol_name)}_{timestamp}_{run_id}"
+    return base_name, run_id
+
+
 class _NumpyEncoder(json.JSONEncoder):
     """Handle numpy types that aren't natively JSON serializable."""
     def default(self, obj):
@@ -86,7 +101,13 @@ def _save_json(path: Path, data: Dict[str, Any]) -> None:
 
 @app.route("/")
 def index():
-    return render_template("index.html", default_sample_url=DEFAULT_SAMPLE_URL)
+    return render_template("index.html", default_sample_url=DEFAULT_SAMPLE_URL, dev_mode=False)
+
+
+@app.route("/dev")
+@app.route("/debug")
+def index_dev():
+    return render_template("index.html", default_sample_url=DEFAULT_SAMPLE_URL, dev_mode=True)
 
 
 @app.route("/results/<path:filename>")
@@ -117,9 +138,9 @@ def api_measure():
     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}"
+    base_name, run_id = _make_base_name(kol_name)
+    suffix = Path(secure_filename(file.filename)).suffix.lower() or ".jpg"
+    upload_name = f"{base_name}{suffix}"
     upload_path = UPLOAD_DIR / upload_name
     upload_path.parent.mkdir(parents=True, exist_ok=True)
     file.save(upload_path)
@@ -136,6 +157,8 @@ def api_measure():
             kol_name=kol_name,
             upload_path=upload_path,
             upload_name=upload_name,
+            base_name=base_name,
+            run_id=run_id,
         )
 
     return _run_measurement(
@@ -146,6 +169,8 @@ def api_measure():
         kol_name=kol_name,
         upload_path=upload_path,
         upload_name=upload_name,
+        base_name=base_name,
+        run_id=run_id,
     )
 
 
@@ -164,12 +189,16 @@ def api_measure_default():
     if image is None:
         return jsonify({"success": False, "error": "Failed to load default sample image"}), 500
 
+    base_name, run_id = _make_base_name(kol_name or "sample")
+
     if mode == "multi":
         return _run_multi_measurement(
             image=image,
             input_image_url=DEFAULT_SAMPLE_URL,
             ring_model=ring_model,
             kol_name=kol_name,
+            base_name=base_name,
+            run_id=run_id,
         )
 
     return _run_measurement(
@@ -178,6 +207,8 @@ def api_measure_default():
         input_image_url=DEFAULT_SAMPLE_URL,
         ring_model=ring_model,
         kol_name=kol_name,
+        base_name=base_name,
+        run_id=run_id,
     )
 
 
@@ -189,10 +220,13 @@ def _run_measurement(
     kol_name: str = "",
     upload_path: Path = None,
     upload_name: str = "",
+    base_name: str = "",
+    run_id: str = "",
 ):
-    run_id = uuid.uuid4().hex[:12]
+    if not base_name:
+        base_name, run_id = _make_base_name(kol_name)
 
-    result_png_name = f"{run_id}__result.png"
+    result_png_name = f"{base_name}_result.png"
     result_png_path = RESULTS_DIR / result_png_name
 
     result = measure_finger(
@@ -217,7 +251,7 @@ def _run_measurement(
 
     result = _numpy_safe(result)
 
-    result_json_name = f"{run_id}__result.json"
+    result_json_name = f"{base_name}_result.json"
     result_json_path = RESULTS_DIR / result_json_name
     _save_json(result_json_path, result)
 
@@ -266,11 +300,14 @@ def _run_multi_measurement(
     kol_name: str = "",
     upload_path: Path = None,
     upload_name: str = "",
+    base_name: str = "",
+    run_id: str = "",
 ):
     """Run multi-finger measurement pipeline."""
-    run_id = uuid.uuid4().hex[:12]
+    if not base_name:
+        base_name, run_id = _make_base_name(kol_name)
 
-    result_png_name = f"{run_id}__result.png"
+    result_png_name = f"{base_name}_result.png"
     result_png_path = RESULTS_DIR / result_png_name
 
     result = measure_multi_finger(
@@ -307,7 +344,7 @@ def _run_multi_measurement(
     if ai_reason:
         result["ai_explanation"] = ai_reason
 
-    result_json_name = f"{run_id}__result.json"
+    result_json_name = f"{base_name}_result.json"
     result_json_path = RESULTS_DIR / result_json_name
     _save_json(result_json_path, result)
 

web_demo/static/app.js

@@ -15,13 +15,13 @@ const fingerBreakdown = document.getElementById("fingerBreakdown");
 const defaultSampleUrl = window.DEFAULT_SAMPLE_URL || "";
 const failReasonMessageMap = {
   card_not_detected:
-    "Credit card not detected. Place a full card flat beside your hand.",
+    "Credit card not detected. Place the card beside your hand on a plain, white background (e.g. a sheet of paper), and turn on your phone's flash.",
   card_not_parallel:
     "Card is not parallel to the camera. Keep your phone directly above and parallel to the card.",
   card_near_edge:
     "Card appears cropped. Place the entire card within the photo frame.",
   hand_not_detected:
-    "Hand not detected. Include your full palm in frame and keep fingers fully visible.",
+    "Hand not detected. Place your hand flat on a plain, white background (e.g. a sheet of paper), and spread your fingers naturally.",
   finger_isolation_failed:
     "Could not isolate the selected finger. Keep one target finger extended and separated.",
   finger_not_fully_visible:
@@ -66,23 +66,24 @@ const formatFailReasonStatus = (failReason) => {
   }
 
   if (failReason.startsWith("quality_score_low_")) {
-    return `Low edge quality detected. Turn on flash and retake. (${failReason})`;
+    return "Low edge quality detected. Turn on flash and retake.";
   }
 
   if (failReason.startsWith("consistency_low_")) {
-    return `Edge detection was inconsistent. Keep phone parallel to table and retry. (${failReason})`;
+    return "Edge detection was inconsistent. Keep phone parallel to table and retry.";
   }
 
   const friendlyMessage = failReasonMessageMap[failReason];
   if (friendlyMessage) {
-    return `${friendlyMessage} (${failReason})`;
+    return friendlyMessage;
   }
 
-  return `Measurement failed: ${failReason}`;
+  return "Measurement failed. Please retake the photo and try again.";
 };
 
-const setStatus = (text) => {
+const setStatus = (text, { error = false } = {}) => {
   statusText.textContent = text;
+  statusText.classList.toggle("error", error);
 };
 
 const showImage = (imgEl, frameEl, url) => {
@@ -103,16 +104,18 @@ const RING_MODEL_LABELS = { gen: "Gen1/Gen2", air: "Air" };
 const kolNameInput = document.getElementById("kolNameInput");
 
 const buildMeasureSettings = () => {
-  const fingerSelect = form.querySelector('select[name="finger_index"]');
+  const fingerSelect = form.querySelector('[name="finger_index"]');
   const aiToggle = document.getElementById("aiExplainToggle");
-  const mode = modeSelect ? modeSelect.value : "single";
+  const mode = modeSelect ? modeSelect.value : "multi";
   const ringModel = ringModelSelect ? ringModelSelect.value : "gen";
+  // Hidden inputs (non-dev mode) have no `checked` property — treat as on.
+  const aiOn = aiToggle ? (aiToggle.type === "checkbox" ? aiToggle.checked : true) : false;
   return {
     finger_index: fingerSelect ? fingerSelect.value : "index",
     edge_method: "sobel",
     mode: mode,
     ring_model: ringModel,
-    ai_explain: aiToggle && aiToggle.checked ? "1" : "0",
+    ai_explain: aiOn ? "1" : "0",
     kol_name: kolNameInput ? kolNameInput.value.trim() : "",
   };
 };
@@ -205,7 +208,7 @@ const renderSingleResult = (result) => {
     </div>`;
 
   const diamMm = result.finger_outer_diameter_cm ? (result.finger_outer_diameter_cm * 10).toFixed(1) : "—";
-  const fingerSelect = form.querySelector('select[name="finger_index"]');
+  const fingerSelect = form.querySelector('[name="finger_index"]');
   const fingerName = fingerSelect ? fingerSelect.value : "finger";
   const capitalName = fingerName.charAt(0).toUpperCase() + fingerName.slice(1);
   let html = `<div class="finger-cards">
@@ -252,7 +255,7 @@ const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
 
     if (!response.ok) {
       const error = await response.json();
-      setStatus(error.error || "Measurement failed");
+      setStatus(error.error || "Measurement failed", { error: true });
       return;
     }
 
@@ -273,10 +276,10 @@ const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
       setStatus("Measurement complete. Results updated.");
     } else {
       const failReason = data?.result?.fail_reason;
-      setStatus(formatFailReasonStatus(failReason));
+      setStatus(formatFailReasonStatus(failReason), { error: true });
     }
   } catch (error) {
-    setStatus("Network error. Please retry.");
+    setStatus("Network error. Please retry.", { error: true });
   }
 };
 
@@ -310,7 +313,7 @@ form.addEventListener("submit", async (event) => {
 
   const settings = buildMeasureSettings();
   if (!settings.kol_name) {
-    setStatus("Please enter your Name / ID before measuring.");
+    setStatus("Please enter your Name / ID before measuring.", { error: true });
     kolNameInput.focus();
     return;
   }

web_demo/static/styles.css

@@ -133,6 +133,26 @@ body {
   color: var(--ink-soft);
 }
 
+.capture-tips {
+  margin: 14px 0 0;
+  padding: 12px 16px 12px 30px;
+  list-style: disc;
+  background: rgba(191, 58, 43, 0.06);
+  border-left: 3px solid rgba(191, 58, 43, 0.55);
+  border-radius: 8px;
+  font-size: 0.85rem;
+  color: var(--ink-soft);
+  line-height: 1.5;
+}
+
+.capture-tips li + li {
+  margin-top: 4px;
+}
+
+.capture-tips strong {
+  color: var(--ink);
+}
+
 .controls {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
@@ -183,6 +203,11 @@ select,
   color: var(--ink-soft);
 }
 
+.status.error {
+  color: #c0271b;
+  font-weight: 600;
+}
+
 .content {
   position: relative;
   z-index: 1;

web_demo/templates/index.html

@@ -26,6 +26,13 @@
           <span class="file-hint">JPG / PNG supported · 1080p or higher recommended</span>
         </label>
 
+        <ul class="capture-tips">
+          <li><strong>Turn on your phone's flash</strong> — even in daylight, it sharpens the finger edges.</li>
+          <li>Place a card flat next to your hand on a <strong>plain white background</strong> (a sheet of paper works great).</li>
+          <li>Hold the phone <strong>directly above</strong> your hand, keeping it parallel to the table.</li>
+          <li><strong>Spread your fingers</strong> naturally and keep your whole hand inside the frame.</li>
+        </ul>
+
         <div class="controls">
           <label>
             <span>Name / ID</span>
@@ -38,6 +45,7 @@
               <option value="air">Air</option>
             </select>
           </label>
+          {% if dev_mode %}
           <label>
             <span>Mode</span>
             <select name="mode" id="modeSelect">
@@ -62,6 +70,11 @@
               <span class="toggle-hint">Uses OpenAI tokens</span>
             </div>
           </label>
+          {% else %}
+          <input type="hidden" name="mode" id="modeSelect" value="multi" />
+          <input type="hidden" name="finger_index" value="index" />
+          <input type="hidden" id="aiExplainToggle" value="on" />
+          {% endif %}
         </div>
 
         <button class="primary" type="submit">Start Measurement</button>
@@ -102,6 +115,7 @@
         </div>
       </div>
 
+      {% if dev_mode %}
       <div class="panel">
         <div class="panel-head">
           <h2>JSON Output</h2>
@@ -109,6 +123,10 @@
         </div>
         <pre id="jsonOutput">{}</pre>
       </div>
+      {% else %}
+      <pre id="jsonOutput" hidden>{}</pre>
+      <a id="jsonLink" hidden href="#"></a>
+      {% endif %}
     </section>
   </main>