modularize upload.py

py_backend/app/main.py

@@ -30,6 +30,11 @@ from app.routers.images import router as images_router
 from app.routers.prompts import router as prompts_router
 from app.routers.admin import router as admin_router
 from app.routers.schemas import router as schemas_router
+# New modular image routers
+from app.routers.images_listing import router as images_listing_router
+from app.routers.images_metadata import router as images_metadata_router
+from app.routers.images_files import router as images_files_router
+from app.routers.images_upload import router as images_upload_router
 
 app = FastAPI(
     title="PromptAid Vision",
@@ -95,14 +100,20 @@ app.add_middleware(
 # --------------------------------------------------------------------
 # API Routers
 # --------------------------------------------------------------------
-app.include_router(caption.router,     prefix="/api",            tags=["captions"])
-app.include_router(metadata.router,    prefix="/api",            tags=["metadata"])
-app.include_router(models.router,      prefix="/api",            tags=["models"])
-app.include_router(upload.router,      prefix="/api/images",     tags=["images"])
-app.include_router(images_router,      prefix="/api/contribute", tags=["contribute"])
-app.include_router(prompts_router,     prefix="/api/prompts",    tags=["prompts"])
-app.include_router(admin_router,       prefix="/api/admin",      tags=["admin"])
-app.include_router(schemas_router,     prefix="/api",            tags=["schemas"])
+app.include_router(caption.router,              prefix="/api",            tags=["captions"])
+app.include_router(metadata.router,             prefix="/api",            tags=["metadata"])
+app.include_router(models.router,               prefix="/api",            tags=["models"])
+# Legacy upload router (to be deprecated)
+app.include_router(upload.router,               prefix="/api/images",     tags=["images-legacy"])
+# New modular image routers
+app.include_router(images_listing_router,       prefix="/api/images",     tags=["images-listing"])
+app.include_router(images_metadata_router,      prefix="/api/images",     tags=["images-metadata"])
+app.include_router(images_files_router,         prefix="/api/images",     tags=["images-files"])
+app.include_router(images_upload_router,       prefix="/api/images",     tags=["images-upload"])
+app.include_router(images_router,              prefix="/api/contribute", tags=["contribute"])
+app.include_router(prompts_router,             prefix="/api/prompts",    tags=["prompts"])
+app.include_router(admin_router,               prefix="/api/admin",     tags=["admin"])
+app.include_router(schemas_router,             prefix="/api",            tags=["schemas"])
 
 # Handle /api/images and /api/prompts without trailing slash (avoid 307)
 @app.get("/api/images", include_in_schema=False)

py_backend/app/routers/images_files.py

@@ -0,0 +1,196 @@
+"""
+Image File Operations Router
+Handles file serving, copying, and preprocessing operations
+"""
+from fastapi import APIRouter, Depends, HTTPException, Response, UploadFile, Form
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+from typing import List, Optional
+import logging
+import io
+import os
+import time
+import mimetypes
+
+from .. import crud, schemas, database, storage
+from ..config import settings
+from ..services.image_preprocessor import ImagePreprocessor
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+def get_db():
+    db = database.SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+class CopyImageRequest(BaseModel):
+    source_image_id: str
+    source: str
+    event_type: str
+    countries: str = ""
+    epsg: str = ""
+    image_type: str = "crisis_map"
+    # Drone-specific fields (optional)
+    center_lon: Optional[float] = None
+    center_lat: Optional[float] = None
+    amsl_m: Optional[float] = None
+    agl_m: Optional[float] = None
+    heading_deg: Optional[float] = None
+    yaw_deg: Optional[float] = None
+    pitch_deg: Optional[float] = None
+    roll_deg: Optional[float] = None
+    rtk_fix: Optional[bool] = None
+    std_h_m: Optional[float] = None
+    std_v_m: Optional[float] = None
+
+@router.get("/{image_id}/file")
+async def get_image_file(image_id: str, db: Session = Depends(get_db)):
+    """Serve the actual image file"""
+    logger.debug(f"Serving image file for image_id: {image_id}")
+    
+    img = crud.get_image(db, image_id)
+    if not img:
+        logger.warning(f"Image not found: {image_id}")
+        raise HTTPException(404, "Image not found")
+    
+    logger.debug(f"Found image: {img.image_id}, file_key: {img.file_key}")
+    
+    try:
+        if hasattr(storage, 's3') and settings.STORAGE_PROVIDER != "local":
+            logger.debug(f"Using S3 storage - serving file content directly")
+            try:
+                response = storage.s3.get_object(Bucket=settings.S3_BUCKET, Key=img.file_key)
+                content = response['Body'].read()
+                logger.debug(f"Read {len(content)} bytes from S3")
+            except Exception as e:
+                logger.error(f"Failed to get S3 object: {e}")
+                raise HTTPException(500, f"Failed to retrieve image from storage: {e}")
+        else:
+            logger.debug(f"Using local storage")
+            file_path = os.path.join(settings.STORAGE_DIR, img.file_key)
+            logger.debug(f"Reading from: {file_path}")
+            logger.debug(f"File exists: {os.path.exists(file_path)}")
+            
+            if not os.path.exists(file_path):
+                logger.error(f"File not found at: {file_path}")
+                raise FileNotFoundError(f"Image file not found: {file_path}")
+            
+            with open(file_path, 'rb') as f:
+                content = f.read()
+            
+            logger.debug(f"Read {len(content)} bytes from file")
+        
+        content_type, _ = mimetypes.guess_type(img.file_key)
+        if not content_type:
+            content_type = 'application/octet-stream'
+        
+        logger.debug(f"Serving image with content-type: {content_type}, size: {len(content)} bytes")
+        return Response(content=content, media_type=content_type)
+    except Exception as e:
+        logger.error(f"Error serving image: {e}")
+        import traceback
+        logger.debug(f"Full traceback: {traceback.format_exc()}")
+        raise HTTPException(500, f"Failed to serve image file: {e}")
+
+@router.post("/copy", response_model=schemas.ImageOut)
+async def copy_image_for_contribution(
+    request: CopyImageRequest,
+    db: Session = Depends(get_db)
+):
+    """Copy an existing image for contribution purposes, creating a new image_id"""
+    logger.info(f"Copying image {request.source_image_id} for contribution")
+    
+    source_img = crud.get_image(db, request.source_image_id)
+    if not source_img:
+        logger.warning(f"Source image not found: {request.source_image_id}")
+        raise HTTPException(404, "Source image not found")
+    
+    try:
+        # Get image content from storage
+        if hasattr(storage, 's3') and settings.STORAGE_PROVIDER != "local":
+            response = storage.s3.get_object(
+                Bucket=settings.S3_BUCKET,
+                Key=source_img.file_key,
+            )
+            image_content = response["Body"].read()
+        else:
+            file_path = os.path.join(settings.STORAGE_DIR, source_img.file_key)
+            with open(file_path, 'rb') as f:
+                image_content = f.read()
+        
+        # Create new file with unique name
+        new_filename = f"contribution_{request.source_image_id}_{int(time.time())}.jpg"
+        new_key = storage.upload_fileobj(io.BytesIO(image_content), new_filename)
+        
+        # Parse countries
+        countries_list = [c.strip() for c in request.countries.split(',') if c.strip()] if request.countries else []
+        
+        # Create new image record
+        new_img = crud.create_image(
+            db, 
+            request.source, 
+            request.event_type, 
+            new_key, 
+            source_img.sha256,
+            countries_list, 
+            request.epsg, 
+            request.image_type,
+            request.center_lon, request.center_lat, request.amsl_m, request.agl_m,
+            request.heading_deg, request.yaw_deg, request.pitch_deg, request.roll_deg,
+            request.rtk_fix, request.std_h_m, request.std_v_m
+        )
+        
+        # Generate URL
+        try:
+            url = storage.get_object_url(new_key)
+        except Exception as e:
+            url = f"/api/images/{new_img.image_id}/file"
+        
+        # Convert to response format
+        from ..utils.image_utils import convert_image_to_dict
+        img_dict = convert_image_to_dict(new_img, url)
+        result = schemas.ImageOut(**img_dict)
+        
+        logger.info(f"Successfully copied image {request.source_image_id} -> {new_img.image_id}")
+        return result
+        
+    except Exception as e:
+        logger.error(f"Failed to copy image: {str(e)}")
+        raise HTTPException(500, f"Failed to copy image: {str(e)}")
+
+@router.post("/preprocess")
+async def preprocess_image(
+    file: UploadFile = Form(...),
+    db: Session = Depends(get_db)
+):
+    """Preprocess an image file (convert format, optimize, etc.)"""
+    logger.info(f"Preprocessing image: {file.filename}")
+    
+    try:
+        content = await file.read()
+        
+        # Preprocess the image
+        processed_content, processed_filename, mime_type = ImagePreprocessor.preprocess_image(
+            content, 
+            file.filename,
+            target_format='PNG',
+            quality=95
+        )
+        
+        logger.info(f"Image preprocessed: {file.filename} -> {processed_filename}")
+        
+        return {
+            "original_filename": file.filename,
+            "processed_filename": processed_filename,
+            "original_size": len(content),
+            "processed_size": len(processed_content),
+            "mime_type": mime_type,
+            "preprocessing_applied": processed_filename != file.filename
+        }
+        
+    except Exception as e:
+        logger.error(f"Image preprocessing failed: {str(e)}")
+        raise HTTPException(500, f"Image preprocessing failed: {str(e)}")

py_backend/app/routers/images_listing.py

@@ -0,0 +1,129 @@
+"""
+Image Listing Router
+Handles listing, pagination, and filtering of images
+"""
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.orm import Session
+from typing import List, Optional
+import logging
+
+from .. import crud, schemas, database
+from ..utils.image_utils import convert_image_to_dict
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+def get_db():
+    db = database.SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+@router.get("/", response_model=List[schemas.ImageOut])
+def list_images(db: Session = Depends(get_db)):
+    """Get all images with their caption data"""
+    logger.debug("Listing all images")
+    images = crud.get_images(db)
+    result = []
+    for img in images:
+        img_dict = convert_image_to_dict(img, f"/api/images/{img.image_id}/file")
+        result.append(schemas.ImageOut(**img_dict))
+    
+    logger.info(f"Returned {len(result)} images")
+    return result
+
+@router.get("/grouped", response_model=List[schemas.ImageOut])
+def list_images_grouped(
+    page: int = Query(1, ge=1),
+    limit: int = Query(10, ge=1, le=100),
+    search: str = Query(None),
+    source: str = Query(None),
+    event_type: str = Query(None),
+    region: str = Query(None),
+    country: str = Query(None),
+    image_type: str = Query(None),
+    db: Session = Depends(get_db)
+):
+    """Get paginated and filtered images"""
+    logger.debug(f"Listing grouped images - page: {page}, limit: {limit}")
+    
+    # Build filter parameters
+    filters = {}
+    if search:
+        filters['search'] = search
+    if source:
+        filters['source'] = source
+    if event_type:
+        filters['event_type'] = event_type
+    if region:
+        filters['region'] = region
+    if country:
+        filters['country'] = country
+    if image_type:
+        filters['image_type'] = image_type
+    
+    logger.debug(f"Applied filters: {filters}")
+    
+    # Get paginated results
+    images = crud.get_images_paginated(
+        db, 
+        page=page, 
+        limit=limit, 
+        **filters
+    )
+    
+    result = []
+    for img in images:
+        img_dict = convert_image_to_dict(img, f"/api/images/{img.image_id}/file")
+        result.append(schemas.ImageOut(**img_dict))
+    
+    logger.info(f"Returned {len(result)} images for page {page}")
+    return result
+
+@router.get("/grouped/count")
+def get_images_grouped_count(
+    search: str = Query(None),
+    source: str = Query(None),
+    event_type: str = Query(None),
+    region: str = Query(None),
+    country: str = Query(None),
+    image_type: str = Query(None),
+    db: Session = Depends(get_db)
+):
+    """Get total count of images matching filters"""
+    logger.debug("Getting images count")
+    
+    # Build filter parameters
+    filters = {}
+    if search:
+        filters['search'] = search
+    if source:
+        filters['source'] = source
+    if event_type:
+        filters['event_type'] = event_type
+    if region:
+        filters['region'] = region
+    if country:
+        filters['country'] = country
+    if image_type:
+        filters['image_type'] = image_type
+    
+    count = crud.get_images_count(db, **filters)
+    logger.info(f"Total images count: {count}")
+    return {"count": count}
+
+@router.get("/{image_id}", response_model=schemas.ImageOut)
+def get_image(image_id: str, db: Session = Depends(get_db)):
+    """Get a specific image by ID"""
+    logger.debug(f"Getting image: {image_id}")
+    
+    img = crud.get_image(db, image_id)
+    if not img:
+        logger.warning(f"Image not found: {image_id}")
+        from fastapi import HTTPException
+        raise HTTPException(404, "Image not found")
+    
+    img_dict = convert_image_to_dict(img, f"/api/images/{img.image_id}/file")
+    logger.info(f"Returned image: {image_id}")
+    return schemas.ImageOut(**img_dict)

py_backend/app/routers/images_metadata.py

@@ -0,0 +1,150 @@
+"""
+Image Metadata Router
+Handles metadata updates and image deletion
+"""
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+import logging
+import datetime
+
+from .. import crud, schemas, database, storage
+from ..utils.image_utils import convert_image_to_dict
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+def get_db():
+    db = database.SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+@router.put("/{image_id}")
+def update_image_metadata(
+    image_id: str,
+    metadata: schemas.ImageMetadataUpdate,
+    db: Session = Depends(get_db)
+):
+    """Update image metadata (source, type, epsg, image_type, countries)"""
+    logger.debug(f"Updating metadata for image {image_id}")
+    logger.debug(f"Metadata received: {metadata}")
+    
+    img = crud.get_image(db, image_id)
+    if not img:
+        logger.warning(f"Image {image_id} not found in database")
+        raise HTTPException(404, "Image not found")
+    
+    logger.debug(f"Found image {image_id} in database")
+    
+    try:
+        # Update basic fields
+        if metadata.source is not None:
+            img.source = metadata.source
+        if metadata.event_type is not None:
+            img.event_type = metadata.event_type
+        if metadata.epsg is not None:
+            img.epsg = metadata.epsg
+        if metadata.image_type is not None:
+            img.image_type = metadata.image_type
+        
+        # Handle starred field - update the first caption's starred status
+        if metadata.starred is not None:
+            if img.captions:
+                # Update the first caption's starred status
+                img.captions[0].starred = metadata.starred
+            else:
+                # If no captions exist, create a minimal caption with starred status
+                from .. import models
+                caption = models.Captions(
+                    title="",
+                    starred=metadata.starred,
+                    created_at=datetime.datetime.utcnow()
+                )
+                db.add(caption)
+                img.captions.append(caption)
+        
+        # Update drone-specific fields
+        if metadata.center_lon is not None:
+            img.center_lon = metadata.center_lon
+        if metadata.center_lat is not None:
+            img.center_lat = metadata.center_lat
+        if metadata.amsl_m is not None:
+            img.amsl_m = metadata.amsl_m
+        if metadata.agl_m is not None:
+            img.agl_m = metadata.agl_m
+        if metadata.heading_deg is not None:
+            img.heading_deg = metadata.heading_deg
+        if metadata.yaw_deg is not None:
+            img.yaw_deg = metadata.yaw_deg
+        if metadata.pitch_deg is not None:
+            img.pitch_deg = metadata.pitch_deg
+        if metadata.roll_deg is not None:
+            img.roll_deg = metadata.roll_deg
+        if metadata.rtk_fix is not None:
+            img.rtk_fix = metadata.rtk_fix
+        if metadata.std_h_m is not None:
+            img.std_h_m = metadata.std_h_m
+        if metadata.std_v_m is not None:
+            img.std_v_m = metadata.std_v_m
+        
+        # Update countries
+        if metadata.countries is not None:
+            logger.debug(f"Updating countries to: {metadata.countries}")
+            img.countries.clear()
+            for country_code in metadata.countries:
+                country = crud.get_country(db, country_code)
+                if country:
+                    img.countries.append(country)
+                    logger.debug(f"Added country: {country_code}")
+        
+        db.commit()
+        db.refresh(img)
+        logger.info(f"Metadata update successful for image {image_id}")
+        
+        # Generate image URL
+        try:
+            url = storage.get_object_url(img.file_key)
+        except Exception:
+            url = f"/api/images/{img.image_id}/file"
+        
+        img_dict = convert_image_to_dict(img, url)
+        return schemas.ImageOut(**img_dict)
+        
+    except Exception as e:
+        db.rollback()
+        logger.error(f"Metadata update failed for image {image_id}: {str(e)}")
+        raise HTTPException(500, f"Failed to update image metadata: {str(e)}")
+
+@router.delete("/{image_id}")
+def delete_image(image_id: str, db: Session = Depends(get_db), content_management: bool = False):
+    """Delete an image and its associated caption data
+    
+    Args:
+        image_id: The ID of the image to delete
+        content_management: If True, this is a content management delete (from map details)
+    """
+    logger.info(f"Deleting image {image_id} (content_management={content_management})")
+    
+    img = crud.get_image(db, image_id)
+    if not img:
+        logger.warning(f"Image {image_id} not found")
+        raise HTTPException(404, "Image not found")
+    
+    try:
+        # Delete associated captions first
+        for caption in img.captions:
+            db.delete(caption)
+            logger.debug(f"Deleted caption {caption.caption_id}")
+        
+        # Delete the image
+        db.delete(img)
+        db.commit()
+        
+        logger.info(f"Successfully deleted image {image_id}")
+        return {"message": "Image deleted successfully", "image_id": image_id}
+        
+    except Exception as e:
+        db.rollback()
+        logger.error(f"Failed to delete image {image_id}: {str(e)}")
+        raise HTTPException(500, f"Failed to delete image: {str(e)}")

py_backend/app/routers/images_upload.py

@@ -0,0 +1,135 @@
+"""
+Simplified Upload Router
+Handles only the core upload endpoints, delegating to service layer
+"""
+from fastapi import APIRouter, UploadFile, Form, Depends, HTTPException
+from sqlalchemy.orm import Session
+from typing import List, Optional
+import logging
+
+from .. import schemas, database
+from ..services.upload_service import UploadService
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+def get_db():
+    db = database.SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+@router.post("/", response_model=schemas.ImageOut)
+async def upload_image(
+    source: Optional[str] = Form(default=None),
+    event_type: str = Form(default="OTHER"),
+    countries: str = Form(default=""),
+    epsg: str = Form(default=""),
+    image_type: str = Form(default="crisis_map"),
+    file: UploadFile = Form(...),
+    title: str = Form(default=""),
+    model_name: Optional[str] = Form(default=None),
+    # Drone-specific fields (optional)
+    center_lon: Optional[float] = Form(default=None),
+    center_lat: Optional[float] = Form(default=None),
+    amsl_m: Optional[float] = Form(default=None),
+    agl_m: Optional[float] = Form(default=None),
+    heading_deg: Optional[float] = Form(default=None),
+    yaw_deg: Optional[float] = Form(default=None),
+    pitch_deg: Optional[float] = Form(default=None),
+    roll_deg: Optional[float] = Form(default=None),
+    rtk_fix: Optional[bool] = Form(default=None),
+    std_h_m: Optional[float] = Form(default=None),
+    std_v_m: Optional[float] = Form(default=None),
+    db: Session = Depends(get_db)
+):
+    """Upload a single image"""
+    logger.info(f"Single image upload request: {file.filename}")
+    
+    try:
+        result = await UploadService.process_single_upload(
+            file=file,
+            source=source,
+            event_type=event_type,
+            countries=countries,
+            epsg=epsg,
+            image_type=image_type,
+            title=title,
+            model_name=model_name,
+            center_lon=center_lon,
+            center_lat=center_lat,
+            amsl_m=amsl_m,
+            agl_m=agl_m,
+            heading_deg=heading_deg,
+            yaw_deg=yaw_deg,
+            pitch_deg=pitch_deg,
+            roll_deg=roll_deg,
+            rtk_fix=rtk_fix,
+            std_h_m=std_h_m,
+            std_v_m=std_v_m,
+            db=db
+        )
+        
+        return result['image']
+        
+    except Exception as e:
+        logger.error(f"Single upload failed: {str(e)}")
+        raise HTTPException(500, f"Upload failed: {str(e)}")
+
+@router.post("/multi", response_model=dict)
+async def upload_multiple_images(
+    files: List[UploadFile] = Form(...),
+    source: Optional[str] = Form(default=None),
+    event_type: str = Form(default="OTHER"),
+    countries: str = Form(default=""),
+    epsg: str = Form(default=""),
+    image_type: str = Form(default="crisis_map"),
+    title: str = Form(default=""),
+    model_name: Optional[str] = Form(default=None),
+    # Drone-specific fields (optional)
+    center_lon: Optional[float] = Form(default=None),
+    center_lat: Optional[float] = Form(default=None),
+    amsl_m: Optional[float] = Form(default=None),
+    agl_m: Optional[float] = Form(default=None),
+    heading_deg: Optional[float] = Form(default=None),
+    yaw_deg: Optional[float] = Form(default=None),
+    pitch_deg: Optional[float] = Form(default=None),
+    roll_deg: Optional[float] = Form(default=None),
+    rtk_fix: Optional[bool] = Form(default=None),
+    std_h_m: Optional[float] = Form(default=None),
+    std_v_m: Optional[float] = Form(default=None),
+    db: Session = Depends(get_db)
+):
+    """Upload multiple images"""
+    logger.info(f"Multi image upload request: {len(files)} files")
+    
+    try:
+        result = await UploadService.process_multi_upload(
+            files=files,
+            source=source,
+            event_type=event_type,
+            countries=countries,
+            epsg=epsg,
+            image_type=image_type,
+            title=title,
+            model_name=model_name,
+            center_lon=center_lon,
+            center_lat=center_lat,
+            amsl_m=amsl_m,
+            agl_m=agl_m,
+            heading_deg=heading_deg,
+            yaw_deg=yaw_deg,
+            pitch_deg=pitch_deg,
+            roll_deg=roll_deg,
+            rtk_fix=rtk_fix,
+            std_h_m=std_h_m,
+            std_v_m=std_v_m,
+            db=db
+        )
+        
+        return result
+        
+    except Exception as e:
+        logger.error(f"Multi upload failed: {str(e)}")
+        raise HTTPException(500, f"Multi upload failed: {str(e)}")

py_backend/app/services/upload_service.py

@@ -0,0 +1,293 @@
+"""
+Upload Service
+Handles the core business logic for image uploads and processing
+"""
+import logging
+import io
+from typing import Optional, Dict, Any, Tuple
+from fastapi import UploadFile
+from sqlalchemy.orm import Session
+
+from .. import crud, schemas, storage
+from ..services.image_preprocessor import ImagePreprocessor
+from ..services.thumbnail_service import ImageProcessingService
+from ..services.vlm_service import vlm_manager
+from ..utils.image_utils import convert_image_to_dict
+
+logger = logging.getLogger(__name__)
+
+class UploadService:
+    """Service for handling image upload operations"""
+    
+    @staticmethod
+    async def process_single_upload(
+        file: UploadFile,
+        source: Optional[str],
+        event_type: str,
+        countries: str,
+        epsg: str,
+        image_type: str,
+        title: str,
+        model_name: Optional[str],
+        # Drone-specific fields
+        center_lon: Optional[float] = None,
+        center_lat: Optional[float] = None,
+        amsl_m: Optional[float] = None,
+        agl_m: Optional[float] = None,
+        heading_deg: Optional[float] = None,
+        yaw_deg: Optional[float] = None,
+        pitch_deg: Optional[float] = None,
+        roll_deg: Optional[float] = None,
+        rtk_fix: Optional[bool] = None,
+        std_h_m: Optional[float] = None,
+        std_v_m: Optional[float] = None,
+        db: Session = None
+    ) -> Dict[str, Any]:
+        """Process a single image upload"""
+        logger.info(f"Processing single upload: {file.filename}")
+        
+        # Parse and validate input
+        countries_list = [c.strip() for c in countries.split(',') if c.strip()] if countries else []
+        
+        # Set defaults based on image type
+        if image_type == "drone_image":
+            if not event_type or event_type.strip() == "":
+                event_type = "OTHER"
+            if not epsg or epsg.strip() == "":
+                epsg = "OTHER"
+        else:
+            if not source or source.strip() == "":
+                source = "OTHER"
+            if not event_type or event_type.strip() == "":
+                event_type = "OTHER"
+            if not epsg or epsg.strip() == "":
+                epsg = "OTHER"
+            
+            # Clear drone fields for non-drone images
+            center_lon = center_lat = amsl_m = agl_m = None
+            heading_deg = yaw_deg = pitch_deg = roll_deg = None
+            rtk_fix = std_h_m = std_v_m = None
+        
+        if not image_type or image_type.strip() == "":
+            image_type = "crisis_map"
+        
+        # Read file content
+        content = await file.read()
+        
+        # Preprocess image
+        preprocessing_info = await UploadService._preprocess_image(content, file.filename)
+        
+        # Upload to storage
+        key, sha = await UploadService._upload_to_storage(
+            preprocessing_info['processed_content'],
+            preprocessing_info['processed_filename'],
+            preprocessing_info['mime_type']
+        )
+        
+        # Generate thumbnails and detail versions
+        thumbnail_result, detail_result = await UploadService._generate_image_versions(
+            preprocessing_info['processed_content'],
+            preprocessing_info['processed_filename']
+        )
+        
+        # Create database record
+        img = crud.create_image(
+            db, source, event_type, key, sha, countries_list, epsg, image_type,
+            center_lon, center_lat, amsl_m, agl_m,
+            heading_deg, yaw_deg, pitch_deg, roll_deg,
+            rtk_fix, std_h_m, std_v_m,
+            thumbnail_key=thumbnail_result[0] if thumbnail_result else None,
+            detail_key=detail_result[0] if detail_result else None
+        )
+        
+        # Generate caption if requested
+        if title or model_name:
+            await UploadService._generate_caption(
+                img, preprocessing_info['processed_content'], title, model_name, db
+            )
+        
+        # Generate response
+        url = storage.get_object_url(key)
+        img_dict = convert_image_to_dict(img, url)
+        img_dict['preprocessing_info'] = preprocessing_info
+        
+        logger.info(f"Successfully processed upload: {img.image_id}")
+        return {
+            'image': schemas.ImageOut(**img_dict),
+            'preprocessing_info': preprocessing_info
+        }
+    
+    @staticmethod
+    async def process_multi_upload(
+        files: list[UploadFile],
+        source: Optional[str],
+        event_type: str,
+        countries: str,
+        epsg: str,
+        image_type: str,
+        title: str,
+        model_name: Optional[str],
+        # Drone-specific fields
+        center_lon: Optional[float] = None,
+        center_lat: Optional[float] = None,
+        amsl_m: Optional[float] = None,
+        agl_m: Optional[float] = None,
+        heading_deg: Optional[float] = None,
+        yaw_deg: Optional[float] = None,
+        pitch_deg: Optional[float] = None,
+        roll_deg: Optional[float] = None,
+        rtk_fix: Optional[bool] = None,
+        std_h_m: Optional[float] = None,
+        std_v_m: Optional[float] = None,
+        db: Session = None
+    ) -> Dict[str, Any]:
+        """Process multiple image uploads"""
+        logger.info(f"Processing multi upload: {len(files)} files")
+        
+        results = []
+        for file in files:
+            try:
+                result = await UploadService.process_single_upload(
+                    file, source, event_type, countries, epsg, image_type,
+                    title, model_name, center_lon, center_lat, amsl_m, agl_m,
+                    heading_deg, yaw_deg, pitch_deg, roll_deg,
+                    rtk_fix, std_h_m, std_v_m, db
+                )
+                results.append(result)
+            except Exception as e:
+                logger.error(f"Failed to process file {file.filename}: {str(e)}")
+                results.append({
+                    'error': str(e),
+                    'filename': file.filename
+                })
+        
+        logger.info(f"Multi upload completed: {len(results)} results")
+        return {
+            'results': results,
+            'total_files': len(files),
+            'successful': len([r for r in results if 'error' not in r])
+        }
+    
+    @staticmethod
+    async def _preprocess_image(content: bytes, filename: str) -> Dict[str, Any]:
+        """Preprocess an image file"""
+        logger.debug(f"Preprocessing image: {filename}")
+        
+        try:
+            processed_content, processed_filename, mime_type = ImagePreprocessor.preprocess_image(
+                content, 
+                filename,
+                target_format='PNG',
+                quality=95
+            )
+            
+            preprocessing_info = {
+                "original_filename": filename,
+                "processed_filename": processed_filename,
+                "original_mime_type": ImagePreprocessor.detect_mime_type(content, filename),
+                "processed_mime_type": mime_type,
+                "processed_content": processed_content,
+                "was_preprocessed": processed_filename != filename
+            }
+            
+            if processed_filename != filename:
+                logger.info(f"Image preprocessed: {filename} -> {processed_filename}")
+            
+            return preprocessing_info
+            
+        except Exception as e:
+            logger.error(f"Image preprocessing failed: {str(e)}")
+            # Fall back to original content
+            return {
+                "original_filename": filename,
+                "processed_filename": filename,
+                "original_mime_type": "unknown",
+                "processed_mime_type": "image/png",
+                "processed_content": content,
+                "was_preprocessed": False,
+                "error": str(e)
+            }
+    
+    @staticmethod
+    async def _upload_to_storage(content: bytes, filename: str, mime_type: str) -> Tuple[str, str]:
+        """Upload content to storage and return key and SHA256"""
+        logger.debug(f"Uploading to storage: {filename}")
+        
+        key = storage.upload_fileobj(
+            io.BytesIO(content), 
+            filename, 
+            content_type=mime_type
+        )
+        
+        sha = crud.hash_bytes(content)
+        logger.debug(f"Uploaded to key: {key}, SHA: {sha}")
+        
+        return key, sha
+    
+    @staticmethod
+    async def _generate_image_versions(content: bytes, filename: str) -> Tuple[Optional[Tuple], Optional[Tuple]]:
+        """Generate thumbnail and detail versions of the image"""
+        logger.debug(f"Generating image versions: {filename}")
+        
+        try:
+            thumbnail_result = ImageProcessingService.create_and_upload_thumbnail(
+                content, filename
+            )
+            
+            detail_result = ImageProcessingService.create_and_upload_detail(
+                content, filename
+            )
+            
+            if thumbnail_result:
+                logger.info(f"Thumbnail generated: {thumbnail_result[0]}")
+            if detail_result:
+                logger.info(f"Detail version generated: {detail_result[0]}")
+            
+            return thumbnail_result, detail_result
+            
+        except Exception as e:
+            logger.error(f"Image version generation failed: {str(e)}")
+            return None, None
+    
+    @staticmethod
+    async def _generate_caption(img, image_content: bytes, title: str, model_name: Optional[str], db: Session):
+        """Generate caption for the uploaded image"""
+        if not title and not model_name:
+            return
+        
+        logger.debug(f"Generating caption for image {img.image_id}")
+        
+        try:
+            # Get active prompt for image type
+            prompt_obj = crud.get_active_prompt_by_image_type(db, img.image_type)
+            if not prompt_obj:
+                logger.warning(f"No active prompt found for image type: {img.image_type}")
+                return
+            
+            # Generate caption using VLM service
+            result = await vlm_manager.generate_caption(
+                image_content=image_content,
+                prompt=prompt_obj.label,
+                metadata_instructions=prompt_obj.metadata_instructions or "",
+                model_name=model_name,
+                db_session=db
+            )
+            
+            # Create caption record
+            crud.create_caption(
+                db=db,
+                image_id=img.image_id,
+                title=title or result.get("title", ""),
+                prompt=prompt_obj.p_code,
+                model_code=result.get("model", model_name or "STUB_MODEL"),
+                raw_json=result.get("raw_response", {}),
+                text=result.get("text", ""),
+                metadata=result.get("metadata", {}),
+                image_count=1
+            )
+            
+            logger.info(f"Caption generated for image {img.image_id}")
+            
+        except Exception as e:
+            logger.error(f"Caption generation failed: {str(e)}")
+            # Continue without caption if generation fails

py_backend/app/utils/__init__.py

@@ -0,0 +1 @@
+# Utils package

py_backend/app/utils/image_utils.py

@@ -0,0 +1,109 @@
+"""
+Shared utilities for image operations
+"""
+import logging
+from typing import Dict, Any
+from sqlalchemy.orm import Session
+from .. import crud, storage
+
+logger = logging.getLogger(__name__)
+
+def convert_image_to_dict(img, image_url: str) -> Dict[str, Any]:
+    """Helper function to convert SQLAlchemy image model to dict for Pydantic"""
+    countries_list = []
+    if hasattr(img, 'countries') and img.countries is not None:
+        try:
+            countries_list = [{"c_code": c.c_code, "label": c.label, "r_code": c.r_code} for c in img.countries]
+        except Exception as e:
+            logger.warning(f"Error processing countries for image {img.image_id}: {e}")
+            countries_list = []
+    
+    captions_list = []
+    if hasattr(img, 'captions') and img.captions is not None:
+        try:
+            captions_list = [
+                {
+                    "caption_id": c.caption_id,
+                    "title": c.title,
+                    "text": c.text,
+                    "starred": c.starred,
+                    "generated": c.generated,
+                    "model": c.model,
+                    "created_at": c.created_at,
+                    "updated_at": c.updated_at
+                } for c in img.captions
+            ]
+        except Exception as e:
+            logger.warning(f"Error processing captions for image {img.image_id}: {e}")
+            captions_list = []
+    
+    # Get starred status and other caption fields from first caption for backward compatibility
+    starred = False
+    title = None
+    text = None
+    generated = False
+    model = None
+    created_at = None
+    updated_at = None
+    
+    if captions_list:
+        first_caption = captions_list[0]
+        starred = first_caption.get("starred", False)
+        title = first_caption.get("title", "")
+        text = first_caption.get("text", "")
+        generated = first_caption.get("generated", False)
+        model = first_caption.get("model", "")
+        created_at = first_caption.get("created_at")
+        updated_at = first_caption.get("updated_at")
+    
+    # Generate URLs for thumbnail and detail versions
+    thumbnail_url = None
+    detail_url = None
+    
+    if hasattr(img, 'thumbnail_key') and img.thumbnail_key:
+        try:
+            thumbnail_url = storage.get_object_url(img.thumbnail_key)
+        except Exception as e:
+            logger.warning(f"Error generating thumbnail URL for image {img.image_id}: {e}")
+    
+    if hasattr(img, 'detail_key') and img.detail_key:
+        try:
+            detail_url = storage.get_object_url(img.detail_key)
+        except Exception as e:
+            logger.warning(f"Error generating detail URL for image {img.image_id}: {e}")
+    
+    img_dict = {
+        "image_id": img.image_id,
+        "file_key": img.file_key,
+        "sha256": img.sha256,
+        "source": img.source,
+        "event_type": img.event_type,
+        "epsg": img.epsg,
+        "image_type": img.image_type,
+        "countries": countries_list,
+        "captions": captions_list,
+        "starred": starred,
+        "title": title,
+        "text": text,
+        "generated": generated,
+        "model": model,
+        "created_at": created_at,
+        "updated_at": updated_at,
+        "url": image_url,
+        "thumbnail_url": thumbnail_url,
+        "detail_url": detail_url,
+        # Drone-specific fields
+        "center_lon": getattr(img, 'center_lon', None),
+        "center_lat": getattr(img, 'center_lat', None),
+        "amsl_m": getattr(img, 'amsl_m', None),
+        "agl_m": getattr(img, 'agl_m', None),
+        "heading_deg": getattr(img, 'heading_deg', None),
+        "yaw_deg": getattr(img, 'yaw_deg', None),
+        "pitch_deg": getattr(img, 'pitch_deg', None),
+        "roll_deg": getattr(img, 'roll_deg', None),
+        "rtk_fix": getattr(img, 'rtk_fix', None),
+        "std_h_m": getattr(img, 'std_h_m', None),
+        "std_v_m": getattr(img, 'std_v_m', None),
+    }
+    
+    return img_dict