Add structured JSON analysis functionality: implement new API endpoints for detailed fashion analysis and enhance documentation

JSON_API_DOCUMENTATION.md

@@ -0,0 +1,368 @@
+# JSON API Documentation
+
+This document describes the JSON-structured API endpoints for the Vestiq Fashion Analysis System.
+
+## Overview
+
+The Vestiq API now provides structured JSON responses for fashion analysis, making it easy to integrate with other applications and process results programmatically.
+
+## Base URL
+
+```
+http://localhost:7861
+```
+
+## Authentication
+
+No authentication required for current version.
+
+## Content Types
+
+- **Request**: `multipart/form-data` (for image uploads)
+- **Response**: `application/json`
+
+## API Endpoints
+
+### 1. Health Check
+
+**GET** `/health`
+
+Check the health status of the API and models.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "models": "loaded", 
+  "device": "cpu"
+}
+```
+
+### 2. Detailed JSON Analysis
+
+**POST** `/analyze-json`
+
+Analyze an uploaded image and return comprehensive structured JSON response.
+
+**Request:**
+- Method: `POST`
+- Content-Type: `multipart/form-data`
+- Body: Form data with `file` field containing the image
+
+**Response:**
+```json
+{
+  "structured_analysis": {
+    "upper_garment": {
+      "type": "Floral midi dress",
+      "color": "Navy blue base with white and pink floral print",
+      "material": "Lightweight cotton or cotton blend",
+      "features": "Short sleeves, round neckline, fitted bodice with A-line skirt"
+    },
+    "lower_garment": {
+      "type": "Not applicable - dress serves as complete outfit",
+      "color": "N/A",
+      "material": "N/A",
+      "features": "N/A"
+    },
+    "footwear": {
+      "type": "White leather sneakers",
+      "color": "Clean white with minimal accent details",
+      "material": "Leather upper with rubber sole",
+      "features": "Lace-up closure, low-profile design"
+    },
+    "outfit_summary": {
+      "aesthetic": "Casual chic",
+      "style_notes": "Floral pattern with modern styling",
+      "occasion_suitability": "Versatile for multiple occasions",
+      "color_harmony": "Cool-toned palette with neutral accents",
+      "overall_assessment": "This outfit demonstrates perfect balance between feminine charm and casual comfort..."
+    },
+    "confidence_score": 0.847,
+    "detected_items": [
+      {
+        "category": "dress",
+        "confidence": 0.892,
+        "bbox": [45.2, 78.1, 234.7, 456.3]
+      },
+      {
+        "category": "shoes",
+        "confidence": 0.756,
+        "bbox": [89.4, 423.8, 187.2, 478.9]
+      }
+    ]
+  },
+  "raw_analysis": "UPPER GARMENT:\nType: Floral midi dress\n...",
+  "processing_time": 2.347,
+  "model_info": {
+    "detection_model": "yainage90/fashion-object-detection",
+    "feature_model": "yainage90/fashion-image-feature-extractor",
+    "device": "cpu"
+  }
+}
+```
+
+### 3. Object Detection Only
+
+**POST** `/detect-objects`
+
+Detect fashion objects in an image and return detection results.
+
+**Request:**
+- Method: `POST`
+- Content-Type: `multipart/form-data`
+- Body: Form data with `file` field containing the image
+
+**Response:**
+```json
+{
+  "detected_items": [
+    {
+      "category": "top",
+      "confidence": 0.892,
+      "bbox": [45.2, 78.1, 234.7, 298.5]
+    },
+    {
+      "category": "bottom", 
+      "confidence": 0.756,
+      "bbox": [52.1, 285.3, 227.8, 423.9]
+    },
+    {
+      "category": "shoes",
+      "confidence": 0.634,
+      "bbox": [89.4, 423.8, 187.2, 478.9]
+    }
+  ]
+}
+```
+
+### 4. Feature Extraction Only
+
+**POST** `/extract-features`
+
+Extract fashion features from an image.
+
+**Request:**
+- Method: `POST`
+- Content-Type: `multipart/form-data`
+- Body: Form data with `file` field containing the image
+
+**Response:**
+```json
+{
+  "feature_vector": [0.123, -0.456, 0.789, ...],
+  "feature_dimension": 128,
+  "processing_time": 1.234,
+  "model_used": "yainage90/fashion-image-feature-extractor"
+}
+```
+
+### 5. Legacy Text Analysis
+
+**POST** `/analyze-image`
+
+Legacy endpoint returning text-based analysis.
+
+**Response:**
+```json
+{
+  "analysis": "Detailed text-based fashion analysis..."
+}
+```
+
+**POST** `/analyze-structured`
+
+Legacy endpoint returning structured text analysis.
+
+**Response:**
+```json
+{
+  "analysis": "UPPER GARMENT:\nType: ...\n\nLOWER GARMENT:\n..."
+}
+```
+
+## Data Models
+
+### GarmentDetails
+```json
+{
+  "type": "string",        // Garment type (e.g., "Floral midi dress")
+  "color": "string",       // Color description with analysis
+  "material": "string",    // Material type or inference
+  "features": "string"     // Detailed features description
+}
+```
+
+### OutfitSummary
+```json
+{
+  "aesthetic": "string",           // Overall aesthetic style
+  "style_notes": "string",         // Pattern and design notes
+  "occasion_suitability": "string", // Suitable occasions
+  "color_harmony": "string",       // Color analysis
+  "overall_assessment": "string"   // Comprehensive summary
+}
+```
+
+### StructuredAnalysisResponse
+```json
+{
+  "upper_garment": "GarmentDetails",
+  "lower_garment": "GarmentDetails", 
+  "footwear": "GarmentDetails",
+  "outfit_summary": "OutfitSummary",
+  "confidence_score": "float",      // 0.0 to 1.0
+  "detected_items": "array"         // Array of detection results
+}
+```
+
+### DetectedItem
+```json
+{
+  "category": "string",    // Fashion category (top, bottom, shoes, etc.)
+  "confidence": "float",   // Detection confidence (0.0 to 1.0)
+  "bbox": "array"         // Bounding box [x1, y1, x2, y2]
+}
+```
+
+## Fashion Categories
+
+The system recognizes these fashion categories:
+- `top` - Shirts, blouses, t-shirts
+- `bottom` - Pants, jeans, skirts
+- `dress` - Dresses of all types
+- `outer` - Jackets, blazers, coats
+- `shoes` - All types of footwear
+- `bag` - Bags and purses
+- `hat` - Hats and headwear
+
+## Error Responses
+
+All endpoints return error responses in this format:
+
+```json
+{
+  "detail": "Error message describing what went wrong"
+}
+```
+
+Common HTTP status codes:
+- `400` - Bad Request (invalid input)
+- `422` - Unprocessable Entity (validation error)
+- `500` - Internal Server Error (processing failed)
+
+## Usage Examples
+
+### cURL Examples
+
+```bash
+# Health check
+curl -X GET "http://localhost:7861/health"
+
+# Analyze image with JSON response
+curl -X POST "http://localhost:7861/analyze-json" \
+     -F "file=@your_image.jpg"
+
+# Detect objects only
+curl -X POST "http://localhost:7861/detect-objects" \
+     -F "file=@your_image.jpg"
+
+# Extract features only
+curl -X POST "http://localhost:7861/extract-features" \
+     -F "file=@your_image.jpg"
+```
+
+### Python Examples
+
+```python
+import requests
+
+# Analyze image with structured JSON
+with open('fashion_image.jpg', 'rb') as f:
+    response = requests.post(
+        'http://localhost:7861/analyze-json',
+        files={'file': f}
+    )
+    result = response.json()
+    
+    # Access structured data
+    upper_garment = result['structured_analysis']['upper_garment']
+    confidence = result['structured_analysis']['confidence_score']
+    processing_time = result['processing_time']
+
+# Object detection only
+with open('fashion_image.jpg', 'rb') as f:
+    response = requests.post(
+        'http://localhost:7861/detect-objects',
+        files={'file': f}
+    )
+    detections = response.json()['detected_items']
+    
+    for item in detections:
+        print(f"Found {item['category']} with {item['confidence']:.3f} confidence")
+```
+
+### JavaScript Examples
+
+```javascript
+// Analyze image with fetch API
+const formData = new FormData();
+formData.append('file', fileInput.files[0]);
+
+fetch('/analyze-json', {
+    method: 'POST',
+    body: formData
+})
+.then(response => response.json())
+.then(data => {
+    console.log('Analysis result:', data.structured_analysis);
+    console.log('Processing time:', data.processing_time);
+});
+
+// Object detection
+fetch('/detect-objects', {
+    method: 'POST', 
+    body: formData
+})
+.then(response => response.json())
+.then(data => {
+    data.detected_items.forEach(item => {
+        console.log(`${item.category}: ${item.confidence}`);
+    });
+});
+```
+
+## Performance Notes
+
+- **Processing Time**: Typical analysis takes 1-5 seconds depending on image size and hardware
+- **Image Formats**: Supports JPEG, PNG, WebP, and other common formats
+- **Image Size**: Optimal size is 224x224 to 512x512 pixels
+- **Batch Processing**: Currently single image per request
+- **Rate Limiting**: No rate limiting implemented in current version
+
+## Integration Tips
+
+1. **Error Handling**: Always check HTTP status codes and handle errors gracefully
+2. **Image Preprocessing**: Resize large images before upload for better performance
+3. **Confidence Thresholds**: Filter detection results by confidence score (>0.5 recommended)
+4. **Caching**: Consider caching results for identical images
+5. **Async Processing**: Use async/await patterns for better user experience
+
+## DeepFashion2 Integration
+
+When the DeepFashion2 dataset is available, additional endpoints become active:
+
+- `/deepfashion2/status` - Check dataset availability
+- `/deepfashion2/statistics` - Get dataset statistics
+- `/deepfashion2/evaluate` - Run model evaluation
+- `/deepfashion2/train` - Start model training
+
+See [DEEPFASHION2_INTEGRATION.md](DEEPFASHION2_INTEGRATION.md) for details.
+
+## Support
+
+For issues or questions:
+1. Check the server logs for detailed error messages
+2. Verify image format and size requirements
+3. Test with the `/health` endpoint to ensure models are loaded
+4. Review this documentation for correct API usage

fast.py

@@ -1,7 +1,7 @@
 from fastapi import FastAPI, HTTPException, UploadFile, File
 from fastapi.responses import JSONResponse, HTMLResponse, PlainTextResponse
 from pydantic import BaseModel
-from typing import List, Optional
+from typing import List, Optional, Dict, Any
 import json
 from PIL import Image
 import io
@@ -465,6 +465,114 @@ class HuggingFaceFashionAnalyzer:
 
         return " ".join(summary_sentences)
 
+    def parse_structured_analysis(self, detection_results, basic_description):
+        """Parse detection results and description into structured JSON format"""
+
+        # Process detection results
+        detected_items = detection_results.get('detected_items', [])
+
+        # Categorize detected items
+        upper_items = []
+        lower_items = []
+        footwear_items = []
+
+        for item in detected_items:
+            category = item['category'].lower()
+            if category in ['top', 'shirt', 'blouse', 'outer', 'jacket', 'blazer', 'dress']:
+                upper_items.append(item)
+            elif category in ['bottom', 'pants', 'jeans', 'skirt']:
+                lower_items.append(item)
+            elif category in ['shoes']:
+                footwear_items.append(item)
+
+        # Extract upper garment details
+        if upper_items or 'dress' in basic_description.lower():
+            if upper_items:
+                garment_type = upper_items[0]['category'].title()
+            else:
+                garment_type = self.extract_garment_type(basic_description)
+
+            upper_garment = {
+                "type": garment_type,
+                "color": self.extract_colors(basic_description),
+                "material": self.extract_material(basic_description),
+                "features": self.extract_comprehensive_features(basic_description, garment_type)
+            }
+        else:
+            upper_garment = {
+                "type": "Not clearly visible",
+                "color": "Unable to determine",
+                "material": "Unable to determine",
+                "features": "Unable to determine"
+            }
+
+        # Extract lower garment details
+        if 'dress' in basic_description.lower() and not lower_items:
+            lower_garment = {
+                "type": "Not applicable - dress serves as complete outfit",
+                "color": "N/A",
+                "material": "N/A",
+                "features": "N/A"
+            }
+        elif lower_items:
+            garment_type = lower_items[0]['category'].title()
+            lower_garment = {
+                "type": garment_type,
+                "color": self.extract_colors(basic_description),
+                "material": self.extract_material(basic_description),
+                "features": self.extract_comprehensive_features(basic_description, garment_type)
+            }
+        else:
+            lower_garment = {
+                "type": "Not clearly visible",
+                "color": "Unable to determine",
+                "material": "Unable to determine",
+                "features": "Unable to determine"
+            }
+
+        # Extract footwear details
+        if footwear_items:
+            footwear_type = footwear_items[0]['category'].title()
+            footwear = {
+                "type": footwear_type,
+                "color": self.extract_colors(basic_description),
+                "material": self.extract_material(basic_description),
+                "features": self.extract_comprehensive_features(basic_description, footwear_type)
+            }
+        else:
+            footwear = {
+                "type": "Not clearly visible",
+                "color": "Unable to determine",
+                "material": "Unable to determine",
+                "features": "Unable to determine"
+            }
+
+        # Create outfit summary
+        outfit_summary_text = self.create_comprehensive_outfit_summary(detected_items, basic_description)
+
+        # Parse outfit summary into components
+        outfit_summary = {
+            "aesthetic": self.extract_style(basic_description),
+            "style_notes": self.extract_pattern(basic_description),
+            "occasion_suitability": "Versatile for multiple occasions",
+            "color_harmony": self.extract_colors(basic_description),
+            "overall_assessment": outfit_summary_text
+        }
+
+        # Calculate confidence score
+        confidence_scores = [item['confidence'] for item in detected_items if item['confidence'] > 0.3]
+        confidence_score = sum(confidence_scores) / len(confidence_scores) if confidence_scores else 0.5
+
+        # Create structured response
+        return StructuredAnalysisResponse(
+            upper_garment=GarmentDetails(**upper_garment),
+            lower_garment=GarmentDetails(**lower_garment),
+            footwear=GarmentDetails(**footwear),
+            outfit_summary=OutfitSummary(**outfit_summary),
+            confidence_score=round(confidence_score, 3),
+            detected_items=detected_items
+        )
+
     def detect_fashion_objects(self, image):
         """Detect fashion objects using yainage90 fashion detection model"""
         if self.detection_model is None or self.detection_processor is None:
@@ -1612,9 +1720,36 @@ if DEEPFASHION2_AVAILABLE:
         DEEPFASHION2_AVAILABLE = False
 
 # Request/Response models
+class GarmentDetails(BaseModel):
+    type: str
+    color: str
+    material: str
+    features: str
+
+class OutfitSummary(BaseModel):
+    aesthetic: str
+    style_notes: str
+    occasion_suitability: str
+    color_harmony: str
+    overall_assessment: str
+
+class StructuredAnalysisResponse(BaseModel):
+    upper_garment: GarmentDetails
+    lower_garment: GarmentDetails
+    footwear: GarmentDetails
+    outfit_summary: OutfitSummary
+    confidence_score: float
+    detected_items: List[Dict[str, Any]] = []
+
 class AnalysisResponse(BaseModel):
     analysis: str
 
+class DetailedAnalysisResponse(BaseModel):
+    structured_analysis: StructuredAnalysisResponse
+    raw_analysis: str
+    processing_time: float
+    model_info: Dict[str, str]
+
 # API Endpoints
 @app.get("/", response_class=HTMLResponse)
 async def root():
@@ -1639,6 +1774,7 @@ async def root():
             <br>
             <button onclick="analyzeImage()" style="padding: 10px 20px; margin: 10px;">Analyze Fashion (Detailed)</button>
             <button onclick="analyzeStructured()" style="padding: 10px 20px; margin: 10px;">Analyze Fashion (Structured)</button>
+            <button onclick="analyzeJSON()" style="padding: 10px 20px; margin: 10px; background-color: #28a745; color: white;">Analyze Fashion (JSON)</button>
             <button onclick="checkDeepFashion2Status()" style="padding: 10px 20px; margin: 10px; background-color: #6f42c1; color: white;">DeepFashion2 Status</button>
             <br>
             <a href="/refined-prompt" target="_blank" style="color: #007bff; text-decoration: none;">View Refined Prompt Format</a>
@@ -1706,6 +1842,45 @@ async def root():
             }
         }
 
+        async function analyzeJSON() {
+            const input = document.getElementById('imageInput');
+            const file = input.files[0];
+
+            if (!file) {
+                alert('Please select an image file');
+                return;
+            }
+
+            const formData = new FormData();
+            formData.append('file', file);
+
+            document.getElementById('analysisText').textContent = 'Analyzing with JSON format... Please wait...';
+            document.getElementById('result').style.display = 'block';
+
+            try {
+                const response = await fetch('/analyze-json', {
+                    method: 'POST',
+                    body: formData
+                });
+
+                const result = await response.json();
+
+                // Format JSON output nicely
+                let jsonOutput = 'JSON FASHION ANALYSIS RESULT:\\n\\n';
+                jsonOutput += 'STRUCTURED ANALYSIS:\\n';
+                jsonOutput += JSON.stringify(result.structured_analysis, null, 2);
+                jsonOutput += '\\n\\nPROCESSING INFO:\\n';
+                jsonOutput += `Processing Time: ${result.processing_time.toFixed(3)} seconds\\n`;
+                jsonOutput += `Device: ${result.model_info.device}\\n`;
+                jsonOutput += `Detection Model: ${result.model_info.detection_model}\\n`;
+                jsonOutput += `Feature Model: ${result.model_info.feature_model}\\n`;
+
+                document.getElementById('analysisText').textContent = jsonOutput;
+            } catch (error) {
+                document.getElementById('analysisText').textContent = 'Error: ' + error.message;
+            }
+        }
+
         async function checkDeepFashion2Status() {
             document.getElementById('analysisText').textContent = 'Checking DeepFashion2 status...';
             document.getElementById('result').style.display = 'block';
@@ -1811,6 +1986,82 @@ async def analyze_structured(file: UploadFile = File(...)):
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Error analyzing image: {str(e)}")
 
+@app.post("/analyze-json", response_model=DetailedAnalysisResponse)
+async def analyze_json(file: UploadFile = File(...)):
+    """Analyze uploaded image and return structured JSON response"""
+    try:
+        start_time = time.time()
+
+        # Read image bytes
+        image_bytes = await file.read()
+
+        # Process image
+        image = analyzer.process_image_from_bytes(image_bytes)
+
+        # Get fashion object detection results
+        detection_results = analyzer.detect_fashion_objects(image)
+
+        # Get basic image description
+        basic_description = analyzer.get_basic_description(image)
+
+        # Extract structured information
+        structured_analysis = analyzer.parse_structured_analysis(detection_results, basic_description)
+
+        # Get raw analysis for comparison
+        raw_analysis = analyzer.analyze_clothing_structured_format(image_bytes)
+
+        processing_time = time.time() - start_time
+
+        return DetailedAnalysisResponse(
+            structured_analysis=structured_analysis,
+            raw_analysis=raw_analysis,
+            processing_time=processing_time,
+            model_info={
+                "detection_model": analyzer.detection_ckpt if analyzer.detection_model else "Not available",
+                "feature_model": analyzer.encoder_ckpt if analyzer.feature_encoder else "Not available",
+                "device": analyzer.device
+            }
+        )
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error analyzing image: {str(e)}")
+
+@app.post("/detect-objects", response_model=Dict[str, Any])
+async def detect_objects(file: UploadFile = File(...)):
+    """Detect fashion objects and return JSON structure"""
+    try:
+        # Read image bytes
+        image_bytes = await file.read()
+
+        # Process image
+        image = analyzer.process_image_from_bytes(image_bytes)
+
+        # Get fashion object detection results
+        detection_results = analyzer.detect_fashion_objects(image)
+
+        return detection_results
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error detecting objects: {str(e)}")
+
+@app.post("/extract-features", response_model=Dict[str, Any])
+async def extract_features(file: UploadFile = File(...)):
+    """Extract fashion features and return JSON structure"""
+    try:
+        # Read image bytes
+        image_bytes = await file.read()
+
+        # Process image
+        image = analyzer.process_image_from_bytes(image_bytes)
+
+        # Extract fashion features
+        feature_results = analyzer.extract_fashion_features(image)
+
+        return feature_results
+
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Error extracting features: {str(e)}")
+
 @app.get("/refined-prompt", response_class=PlainTextResponse)
 async def get_refined_prompt():
     """Get the refined prompt for clothing analysis"""