jedmund-svelte/prd/PRD-dominant-color-extraction.md

PRD: Dominant Color Extraction for Uploaded Images

Overview

This PRD outlines the implementation of automatic dominant color extraction for images uploaded to the media library. This feature will analyze uploaded images to extract their primary colors, enabling color-based organization, search, and visual enhancements throughout the application.

Goals

1. Automatic Color Analysis: Extract dominant colors from images during the upload process
2. Data Storage: Store color information efficiently alongside existing image metadata
3. Visual Enhancement: Use extracted colors to enhance UI/UX in galleries and image displays
4. Performance: Ensure color extraction doesn't significantly impact upload performance

Technical Approach

Color Extraction Library Options

1. node-vibrant (Recommended)

   • Pros: Lightweight, fast, good algorithm, actively maintained
   • Cons: Node.js only (server-side processing)
   • NPM: node-vibrant

2. color-thief-node

   • Pros: Simple API, battle-tested algorithm
   • Cons: Less feature-rich than vibrant
   • NPM: colorthief

3. Cloudinary Color Analysis

   • Pros: Integrated with existing upload pipeline, no extra processing
   • Cons: Requires paid plan, vendor lock-in
   • API: colors parameter in upload response

Recommended Approach: node-vibrant

import Vibrant from 'node-vibrant'

// Extract colors from uploaded image
const palette = await Vibrant.from(buffer).getPalette()
const dominantColors = {
	vibrant: palette.Vibrant?.hex,
	darkVibrant: palette.DarkVibrant?.hex,
	lightVibrant: palette.LightVibrant?.hex,
	muted: palette.Muted?.hex,
	darkMuted: palette.DarkMuted?.hex,
	lightMuted: palette.LightMuted?.hex
}

Database Schema Changes

Option 1: Add to Existing exifData JSON (Recommended)

model Media {
  // ... existing fields
  exifData  Json?  // Add color data here: { colors: { vibrant, muted, etc }, ...existingExif }
}

Option 2: Separate Colors Field

model Media {
  // ... existing fields
  dominantColors  Json?  // { vibrant, darkVibrant, lightVibrant, muted, darkMuted, lightMuted }
}

API Changes

Upload Endpoint (/api/media/upload)

Update the upload handler to extract colors:

// After successful upload to Cloudinary
if (file.type.startsWith('image/') && file.type !== 'image/svg+xml') {
	const buffer = await file.arrayBuffer()

	// Extract EXIF data (existing)
	const exifData = await extractExifData(file)

	// Extract dominant colors (new)
	const colorData = await extractDominantColors(buffer)

	// Combine data
	const metadata = {
		...exifData,
		colors: colorData
	}
}

Response Format

{
	"id": 123,
	"url": "...",
	"dominantColors": {
		"vibrant": "#4285f4",
		"darkVibrant": "#1a73e8",
		"lightVibrant": "#8ab4f8",
		"muted": "#5f6368",
		"darkMuted": "#3c4043",
		"lightMuted": "#e8eaed"
	}
}

UI/UX Considerations

1. Media Library Display

• Show color swatches on hover/focus
• Optional: Color-based filtering or sorting

2. Gallery Image Modal

• Display color palette in metadata section
• Show hex values for each color
• Copy-to-clipboard functionality for colors

3. Album/Gallery Views

• Use dominant color for background accents
• Create dynamic gradients from extracted colors
• Enhance loading states with color placeholders

4. Potential Future Features

• Color-based search ("find blue images")
• Automatic theme generation for albums
• Color harmony analysis for galleries

Implementation Plan

Phase 1: Backend Implementation (1 day)

1. Install and configure node-vibrant
2. Create color extraction utility function
3. Integrate into upload pipeline
4. Update database schema (migration)
5. Update API responses

Phase 2: Basic Frontend Display (0.5 day)

1. Update Media type definitions
2. Display colors in GalleryImageModal
3. Add color swatches to media details

Phase 3: Enhanced UI Features (1 day)

1. Implement color-based backgrounds
2. Add loading placeholders with colors
3. Create color palette component

Phase 4: Testing & Optimization (0.5 day)

1. Test with various image types
2. Optimize for performance
3. Handle edge cases (B&W images, etc.)

Success Metrics

1. Performance: Color extraction adds < 200ms to upload time
2. Accuracy: Colors accurately represent image content
3. Coverage: 95%+ of uploaded images have color data
4. User Experience: Improved visual coherence in galleries

Edge Cases & Considerations

1. Black & White Images: Should return grayscale values
2. Transparent PNGs: Handle alpha channel appropriately
3. Very Large Images: Consider downsampling for performance
4. Failed Extraction: Gracefully handle errors without blocking upload

Future Enhancements

1. Color Search: Search images by dominant color
2. Auto-Tagging: Suggest tags based on color analysis
3. Accessibility: Use colors to improve contrast warnings
4. Analytics: Track most common colors in library
5. Batch Processing: Extract colors for existing images

Dependencies

• node-vibrant: ^3.2.1
• No additional infrastructure required
• Compatible with existing Cloudinary workflow

Timeline

• Total effort: 2-3 days
• Can be implemented incrementally
• No breaking changes to existing functionality