Square Image Cropping Use Case

Created: Mån 7 Jul 2025 11:19:00 CEST

Overview

This document outlines the use case for implementing square image cropping functionality within the Plings image capture and upload system. When users take photos using the camera or select images from their device, the system should provide an option to crop images to square format for standardized display across the interface.

Business Justification

Visual Consistency

  • Unified Grid Layouts: Square images create clean, consistent grid layouts in object galleries and dashboards
  • Professional Appearance: Standardized image dimensions improve the overall visual polish of the application
  • Mobile Optimization: Square images work better on mobile interfaces where screen space is limited

User Experience Benefits

  • Simplified Composition: Users can focus on the most important part of their object when cropping
  • Better Thumbnails: Square cropped images create more effective thumbnails and preview cards
  • Social Media Integration: Square format is optimal for social media sharing and external integrations

Technical Advantages

  • Consistent Loading: All images load with predictable dimensions, improving page performance
  • Simplified Responsive Design: Square images are easier to handle across different screen sizes
  • Reduced Bandwidth: Cropped images are smaller in file size, reducing storage and transfer costs

Current State Analysis

Existing Image Capture System

Camera Integration (CameraCapture.tsx):

  • ✅ Live camera preview with photo capture
  • ✅ Photo review and retake functionality
  • ✅ Canvas-based image capture from video stream
  • ✅ JPEG compression with 0.9 quality
  • ❌ No cropping functionality during capture

Image Upload System (ImageUploadSection.tsx):

  • ✅ Multiple image upload via drag-drop, file picker, and camera
  • ✅ Real-time image preview with thumbnail grid
  • ✅ Image reordering and removal capabilities
  • ✅ Main image designation
  • ❌ No post-upload cropping options

Image Processing Pipeline:

  • ✅ Direct upload to Supabase Storage (object-images bucket)
  • ✅ Automatic thumbnail generation via CDN transformations
  • ✅ Background upload with progress tracking
  • ❌ No client-side image manipulation before upload

User Stories

Primary User Story

As a user taking photos of objects, I want the option to crop my images to square format so that they display consistently in grids and thumbnails throughout the application.

Secondary User Stories

Mobile Camera User:

  • As a mobile user capturing objects with my camera, I want a live square preview overlay so I can compose my shot for optimal square cropping
  • As a user reviewing a captured photo, I want to adjust the square crop area before confirming the image

Desktop Upload User:

  • As a user uploading existing photos from my computer, I want to crop rectangular images to square format during the upload process
  • As a user with multiple images, I want to batch apply square cropping to all images in my upload queue

Gallery Management User:

  • As a user viewing my object gallery, I want all images to display in a consistent square format for better visual organization
  • As a user sharing objects, I want square-cropped thumbnails that look professional in external contexts

Detailed Scenarios

Scenario 1: Camera Capture with Live Square Preview

Context: User is capturing a photo using the camera interface

Flow:

  1. User opens camera capture modal
  2. Camera preview shows with optional square overlay guide
  3. User positions object within the square guide
  4. User captures photo
  5. Photo review screen shows the captured image with adjustable square crop
  6. User can:
    • Accept the default square crop
    • Drag to reposition the crop area
    • Pinch/zoom to resize the crop area
    • Disable square crop to keep original dimensions
  7. User confirms the final image

Expected Outcome: High-quality square image optimally composed for the object

Scenario 2: File Upload with Batch Cropping

Context: User is uploading multiple existing photos from their device

Flow:

  1. User selects multiple images via file picker or drag-drop
  2. Images appear in upload preview grid
  3. System detects non-square images and shows crop indicators
  4. User clicks “Crop to Square” batch action
  5. Crop modal opens showing all images with suggested square crops
  6. User can:
    • Accept all suggested crops
    • Individually adjust crop areas for specific images
    • Skip cropping for selected images
  7. User applies crops and continues with upload

Expected Outcome: Consistent square images uploaded to the system

Scenario 3: Post-Upload Cropping

Context: User wants to modify existing images to square format

Flow:

  1. User views object with rectangular images
  2. User clicks “Edit Images” or similar action
  3. Image management interface shows current images
  4. User selects “Crop to Square” for specific images
  5. Crop interface allows adjustment of square crop area
  6. User saves changes
  7. System generates new square version while preserving original

Expected Outcome: Updated object images in square format with originals preserved

Technical Requirements

Camera Integration Enhancement

Live Preview Overlay:

  • Optional square crop guide overlay on camera viewfinder
  • Adjustable opacity (default 30% opacity white border)
  • Toggle on/off based on user preference
  • Maintains aspect ratio across different device screen sizes

Post-Capture Cropping:

  • Canvas-based crop editor with touch/mouse interaction
  • Drag to reposition crop area within image bounds
  • Pinch-to-zoom or scroll wheel for crop area resizing
  • Visual feedback with dimmed areas outside crop region

Image Processing Pipeline

Client-Side Crop Processing:

  • HTML5 Canvas API for crop operations before upload
  • Maintain original image quality during crop operations
  • Generate square output at multiple resolutions (thumbnail, display, full)
  • Preserve EXIF data where possible

Batch Processing Support:

  • Queue-based processing for multiple images
  • Progress indicators during batch crop operations
  • Rollback capability if crop operation fails

Storage and Versioning

Dual Image Storage:

  • Original uploaded image preserved in Supabase Storage
  • Cropped square version stored as separate file
  • Metadata linking original to cropped versions
  • Option to regenerate crops if needed

CDN Integration:

  • Leverage Supabase CDN transform API for on-demand square crops
  • Cache cropped versions for performance
  • Fallback to client-side cropping if CDN unavailable

User Interface Specifications

Camera Capture Interface

Square Preview Mode:

┌─────────────────────────────┐
│  📷 Camera Capture          │
├─────────────────────────────┤
│  ┌─────┬─────────────┬─────┐ │
│  │     │             │     │ │
│  │     │   ┌─────┐   │     │ │
│  │     │   │     │   │     │ │
│  │     │   │  📦 │   │     │ │
│  │     │   │     │   │     │ │
│  │     │   └─────┘   │     │ │
│  │     │             │     │ │
│  └─────┴─────────────┴─────┘ │
├─────────────────────────────┤
│  [□ Square Guide]  [📷 Capture] │
└─────────────────────────────┘

Crop Adjustment Interface:

┌─────────────────────────────┐
│  ✂️ Crop to Square          │
├─────────────────────────────┤
│    ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓     │
│    ▓▓┌─────────────┐▓▓     │
│    ▓▓│             │▓▓     │
│    ▓▓│    📷       │▓▓     │
│    ▓▓│   Image     │▓▓     │
│    ▓▓│             │▓▓     │
│    ▓▓└─────────────┘▓▓     │
│    ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓     │
├─────────────────────────────┤
│  [⚪ Original] [✂️ Crop] [✅ Done] │
└─────────────────────────────┘

Batch Cropping Interface

Multi-Image Crop Editor:

┌─────────────────────────────────────┐
│  ✂️ Crop Images to Square (3/5)     │
├─────────────────────────────────────┤
│  ┌───────┐ ┌───────┐ ┌───────┐     │
│  │ ✂️ 📷 │ │ ✅ 📷 │ │ ⏭️ 📷 │     │
│  │ Image1│ │ Image2│ │ Image3│     │
│  │ [Edit]│ │ [Done]│ │ [Skip]│     │
│  └───────┘ └───────┘ └───────┘     │
│                                     │
│  Current: Adjusting Image 1         │
│  [Large crop editor for current]    │
├─────────────────────────────────────┤
│  [⏪ Previous] [Apply All] [Next ⏩] │
└─────────────────────────────────────┘

Integration Points

Camera Capture Component Enhancement

Modified CameraCapture.tsx:

  • Add square preview overlay toggle
  • Implement post-capture crop interface
  • Integrate crop functionality with existing photo review
  • Maintain backward compatibility with existing uncropped workflow

Image Upload Section Integration

Enhanced ImageUploadSection.tsx:

  • Add batch crop functionality to upload preview
  • Show crop indicators on non-square images
  • Integrate crop controls with existing image management
  • Preserve existing drag-drop and reordering capabilities

Backend Integration

Image Processing Pipeline:

  • Register both original and cropped versions in object_images table
  • Maintain relationships between original and cropped images
  • Support for regenerating crops with different parameters
  • Metadata tracking for crop parameters and operations

Implementation Phases

Phase 1: Basic Square Cropping (MVP)

  • Post-capture crop interface for camera
  • Single image crop functionality for uploads
  • Basic square crop with center positioning
  • Integration with existing upload pipeline

Phase 2: Enhanced Crop Controls

  • Adjustable crop area with drag and resize
  • Live preview overlay for camera
  • Batch cropping for multiple images
  • Crop parameter persistence

Phase 3: Advanced Features

  • Multiple crop aspect ratios (1:1, 4:3, 16:9)
  • Smart crop suggestions using AI
  • Crop presets for different object types
  • Advanced crop tools (rotate, straighten)

Success Metrics

User Adoption

  • Crop Usage Rate: % of users who enable square cropping
  • Camera Guide Usage: % of camera captures using square overlay
  • Batch Crop Adoption: % of multi-image uploads using batch crop

Image Quality

  • Composition Improvement: User satisfaction with cropped vs uncropped images
  • Consistency Score: Visual consistency of object galleries
  • File Size Reduction: Average file size reduction from cropping

Technical Performance

  • Crop Processing Time: Average time to process square crop
  • Upload Success Rate: Upload success rate with crop processing
  • Storage Efficiency: Storage space saved through smaller cropped images

Risks and Mitigation

Data Loss Risk

  • Risk: Users accidentally crop important parts of images
  • Mitigation: Always preserve original images, allow re-cropping

Performance Impact

  • Risk: Client-side image processing slows down uploads
  • Mitigation: Background processing, progress indicators, optional feature

User Experience Complexity

  • Risk: Adding crop functionality makes interface too complex
  • Mitigation: Smart defaults, optional advanced controls, clear UI patterns

Future Enhancements

AI-Powered Cropping

  • Automatic object detection for optimal crop suggestions
  • Smart composition analysis for best square crop
  • Batch intelligent cropping based on object type

Social Media Integration

  • Platform-specific crop presets (Instagram, Facebook, Twitter)
  • Automatic crop optimization for sharing
  • Multiple format generation from single crop

Advanced Editing Tools

  • Rotation and straightening tools
  • Brightness/contrast adjustment
  • Background removal for product photography

This use case document serves as the foundation for implementing square image cropping functionality within the Plings image capture system. It should be referenced alongside the technical requirements document for complete implementation guidance.