Use Case: Sub-Container Overview Images (UC-306)

Last Updated: Mån 7 Jul 2025 11:18:53 CEST

Overview

Sub-Container Overview Images provide automatically generated visual previews showing the spatial layout of contained objects within containers. This feature helps users quickly understand what’s inside containers before opening them, improving navigation efficiency and spatial awareness within the Plings system.

Business Value

Primary Benefits

  • Faster Navigation: Users can preview container contents without entering the container
  • Improved Spatial Awareness: Visual representation of object layout within containers
  • Enhanced Discovery: Users can identify objects visually even if they don’t remember exact names
  • Reduced Interaction Cost: Fewer clicks and navigation steps to find objects
  • Better Organization: Visual feedback helps users maintain better spatial organization

User Problems Solved

  1. “What’s in this box?” - Users can see container contents at a glance
  2. “Where did I put my keys?” - Visual previews help locate objects faster
  3. “Is there space in this drawer?” - Overview shows spatial density and available space
  4. “How are things arranged?” - Shows relative positioning of contained objects

Detailed Use Cases

UC-306.1: Container Preview in Spatial Hierarchy

Actor: User browsing spatial hierarchy Goal: Preview container contents before entering

Flow:

  1. User views spatial hierarchy with containers shown as cards
  2. System displays overview image on each container card
  3. Overview image shows miniaturized layout of contained objects
  4. User can identify target objects without entering container
  5. User clicks to enter only when target object is confirmed present

Expected Outcome: 30% reduction in unnecessary container navigation

UC-306.2: Hover Preview for Detailed View

Actor: User examining container options Goal: Get detailed preview without committing to navigation

Flow:

  1. User hovers over container card in hierarchy view
  2. System displays enlarged overview image with object labels
  3. User sees detailed spatial layout with object identifications
  4. User can make informed decision about entering container
  5. Hover away to continue browsing or click to enter

Expected Outcome: Improved user confidence in navigation decisions

UC-306.3: Search Result Context

Actor: User viewing search results Goal: Understand spatial context of found objects

Flow:

  1. User searches for specific object type (e.g., “screwdrivers”)
  2. Search results show objects with their container overview images
  3. User sees how each object is positioned within its container
  4. User can choose the most accessible or conveniently located object
  5. Navigate directly to preferred container location

Expected Outcome: More informed object selection from search results

UC-306.4: Organization Assessment

Actor: User organizing workspace Goal: Assess container organization and density

Flow:

  1. User reviews multiple containers for organization quality
  2. Overview images reveal overpacked, empty, or well-organized containers
  3. User identifies containers needing reorganization
  4. User can plan reorganization activities based on visual evidence
  5. Track organization improvements over time

Expected Outcome: Better workspace organization and maintenance

Integration with Existing Systems

Spatial Relationships System

  • Container Detection: Leverages spatialChildren relationships to identify containers
  • Layout Calculation: Uses spatial predicates (CURRENT_IN, CURRENT_ON, CURRENT_LEFT_OF, etc.) for positioning
  • Hierarchy Navigation: Integrates with existing spatialHierarchy breadcrumb system
  • Parent-Child Relationships: Respects existing containment rules and permissions

Image Management System

  • Single Source of Truth: Generated overview images stored in object-images Supabase bucket
  • CDN Transformations: Leverage existing Supabase image transformation pipeline
  • Caching Strategy: Generated images cached and regenerated when container contents change
  • Storage Path: object-images/overview/{container_id}/layout-{version}.png

Existing UI Components

  • HierarchicalSpatialCard: Enhanced to display overview images
  • SpatialHierarchyView: Shows overview images on container cards
  • ObjectDetailsModal: Includes overview image for containers in details view
  • LocationSelector: Uses overview images to help users choose locations

Technical Architecture

Overview Image Generation

# Backend endpoint for generating container overview images
@app.route('/api/generate-overview/<container_id>', methods=['POST'])
async def generate_container_overview(container_id: str):
    """Generate spatial layout overview for container"""
    
    # 1. Query spatial relationships
    contained_objects = await get_spatial_children(container_id)
    spatial_layout = await calculate_spatial_positions(contained_objects)
    
    # 2. Generate layout image
    overview_image = await render_spatial_layout(
        layout=spatial_layout,
        style=OverviewStyle.MINIATURE,
        size=(400, 300)
    )
    
    # 3. Store in Supabase Storage
    image_url = await store_overview_image(container_id, overview_image)
    
    # 4. Update container metadata
    await update_container_overview_url(container_id, image_url)
    
    return {"overview_url": image_url, "generated_at": datetime.now()}

Layout Calculation Algorithm

class SpatialLayoutRenderer:
    def calculate_positions(self, objects: List[ObjectInstance]) -> LayoutGrid:
        """Calculate 2D positions from spatial predicates"""
        
        grid = LayoutGrid(width=400, height=300)
        
        # 1. Identify anchor objects (those without positioning relationships)
        anchors = [obj for obj in objects if not obj.positional_relationships]
        
        # 2. Place anchors in grid
        for i, anchor in enumerate(anchors):
            grid.place_object(anchor, auto_position=True)
        
        # 3. Place positioned objects relative to anchors
        positioned_objects = [obj for obj in objects if obj.positional_relationships]
        
        for obj in positioned_objects:
            for rel in obj.positional_relationships:
                if rel.relationshipType in ['CURRENT_LEFT_OF', 'NORMAL_LEFT_OF']:
                    grid.place_left_of(obj, rel.relatedObject)
                elif rel.relationshipType in ['CURRENT_RIGHT_OF', 'NORMAL_RIGHT_OF']:
                    grid.place_right_of(obj, rel.relatedObject)
                elif rel.relationshipType in ['CURRENT_ABOVE', 'NORMAL_ABOVE']:
                    grid.place_above(obj, rel.relatedObject)
                elif rel.relationshipType in ['CURRENT_UNDER', 'NORMAL_UNDER']:
                    grid.place_below(obj, rel.relatedObject)
        
        return grid

Frontend Integration

Container Card Enhancement

// Enhanced HierarchicalSpatialCard with overview image
interface ContainerCardProps extends HierarchicalSpatialCardProps {
  showOverviewImage?: boolean;
  overviewImageStyle?: 'thumbnail' | 'detailed' | 'hover';
}

const ContainerOverviewImage: React.FC<{
  containerId: string;
  overviewUrl?: string;
  style: 'thumbnail' | 'detailed';
}> = ({ containerId, overviewUrl, style }) => {
  const { transformedUrl, loading } = useTransformedImage(overviewUrl, {
    width: style === 'thumbnail' ? 168 : 320,
    height: style === 'thumbnail' ? 112 : 240,
    resize: 'contain',
    quality: 90
  });

  const [isHovering, setIsHovering] = useState(false);

  if (loading) {
    return <OverviewImageSkeleton />;
  }

  return (
    <div 
      className="overview-image-container"
      onMouseEnter={() => setIsHovering(true)}
      onMouseLeave={() => setIsHovering(false)}
    >
      <img src={transformedUrl} alt="Container overview" />
      
      {isHovering && style === 'thumbnail' && (
        <HoverPreview containerId={containerId} />
      )}
    </div>
  );
};

GraphQL Schema Extensions

extend type ObjectInstance {
  # Container overview image URL
  overviewImageUrl: String
  
  # Overview image metadata
  overviewImageVersion: Int
  overviewImageGeneratedAt: DateTime
  
  # Spatial layout data for overview generation
  spatialLayoutData: SpatialLayoutData
}

type SpatialLayoutData {
  containerBounds: BoundingBox
  objectPositions: [ObjectPosition!]!
  lastUpdated: DateTime
}

type ObjectPosition {
  object: ObjectInstance!
  x: Float!
  y: Float!
  width: Float!
  height: Float!
  zIndex: Int!
}

# Mutations for overview image management
extend type Mutation {
  generateContainerOverview(containerId: ID!): ContainerOverview!
  refreshContainerOverview(containerId: ID!, force: Boolean): ContainerOverview!
}

type ContainerOverview {
  containerId: ID!
  overviewImageUrl: String!
  version: Int!
  generatedAt: DateTime!
  objectCount: Int!
}

Automatic Generation Triggers

When to Generate Overview Images

  1. Container Content Changes:
    • Object added to container
    • Object removed from container
    • Object moved within container
    • Spatial relationships modified
  2. Scheduled Generation:
    • Daily refresh for active containers
    • Weekly refresh for inactive containers
    • On-demand generation for first-time access
  3. Manual Triggers:
    • User requests refresh
    • Admin maintenance operations
    • API-triggered regeneration

Generation Strategy

// Hook for managing overview image generation
const useContainerOverview = (containerId: string) => {
  const [generateOverview] = useMutation(GENERATE_CONTAINER_OVERVIEW);
  const [refreshOverview] = useMutation(REFRESH_CONTAINER_OVERVIEW);
  
  const regenerateIfStale = async () => {
    const container = await getContainer(containerId);
    const lastModified = container.lastContentModified;
    const overviewGenerated = container.overviewImageGeneratedAt;
    
    // Regenerate if overview is older than last content modification
    if (!overviewGenerated || lastModified > overviewGenerated) {
      await generateOverview({ variables: { containerId } });
    }
  };
  
  return {
    regenerateIfStale,
    forceRegenerate: () => refreshOverview({ 
      variables: { containerId, force: true } 
    })
  };
};

User Experience Flows

Flow 1: First-Time Container View

  1. User opens spatial hierarchy
  2. System detects containers without overview images
  3. Background generation begins for visible containers
  4. Placeholder shown while generating
  5. Overview image appears when ready
  6. User can immediately understand container contents

Flow 2: Container Content Changes

  1. User moves object into container
  2. System optimistically updates UI
  3. Background task queues overview regeneration
  4. New overview image generated within 30 seconds
  5. UI updates with fresh overview image
  6. User sees updated container visualization

Flow 3: Hover for Detail

  1. User hovers over container with thumbnail overview
  2. Enlarged preview appears with object labels
  3. User can identify specific objects of interest
  4. Decision made whether to enter container
  5. Hover away or click to proceed

Visual Design Specifications

Overview Image Styles

Thumbnail Style (168×112px)

  • Purpose: Quick preview on container cards
  • Content: Simplified object shapes with color coding
  • Details: Object count badge, density indicator
  • Style: Minimalist, high contrast

Detailed Style (320×240px)

  • Purpose: Hover previews and modal displays
  • Content: Object shapes with names/labels
  • Details: Spatial relationship indicators, grid overlay
  • Style: Detailed but not cluttered

Interactive Style (Full size)

  • Purpose: Overview editing and organization
  • Content: Draggable object representations
  • Details: Drag targets, relationship lines, measurements
  • Style: Work-focused with interaction affordances

Color and Visual Coding

  • Object Types: Color-coded by class (tools=blue, documents=green, etc.)
  • Status Indicators: Border styles for object status
  • Density Visualization: Background shading for space utilization
  • Relationship Lines: Subtle indicators for spatial predicates

Performance Considerations

Image Generation Performance

  • Generation Time: Target <5 seconds for typical containers
  • Background Processing: Queue non-urgent generations
  • Caching: Cache generated images with versioning
  • CDN Delivery: Leverage Supabase CDN for fast delivery

Storage Optimization

  • Image Compression: Optimize for web delivery (WebP format)
  • Size Variants: Generate multiple sizes for different use cases
  • Cleanup: Remove outdated overview images automatically
  • Storage Limits: Monitor and manage storage usage

Frontend Performance

  • Lazy Loading: Load overview images as containers come into view
  • Progressive Enhancement: Show placeholder while loading
  • Memory Management: Unload off-screen overview images
  • Caching: Browser cache overview images aggressively

Accessibility Features

Visual Accessibility

  • Alt Text: Descriptive alt text for overview images
  • High Contrast: High contrast mode support
  • Text Alternatives: Text-based container content lists
  • Screen Reader: Screen reader compatible descriptions

Interaction Accessibility

  • Keyboard Navigation: Full keyboard navigation support
  • Focus Indicators: Clear focus indicators for interactive elements
  • Voice Commands: Voice-activated overview requests
  • Touch Accessibility: Touch-friendly interaction targets

Security and Privacy

Access Control

  • Organization Boundaries: Overview images respect organization permissions
  • Privacy Settings: Honor private container settings
  • User Permissions: Check user access before generating overviews
  • Audit Trail: Log overview generation and access

Data Security

  • Secure Storage: Overview images stored securely in Supabase
  • Encryption: Image data encrypted at rest and in transit
  • Access Tokens: Time-limited access tokens for image URLs
  • GDPR Compliance: Support data deletion and privacy requests

Success Metrics

User Experience Metrics

  • Navigation Efficiency: Reduce container entry attempts by 30%
  • Discovery Time: Decrease object finding time by 25%
  • User Satisfaction: Improve spatial navigation satisfaction scores
  • Error Reduction: Reduce “object not found” incidents

Technical Metrics

  • Generation Performance: <5 second average generation time
  • Cache Hit Rate: >90% cache hit rate for overview images
  • Storage Efficiency: <50MB average storage per 1000 containers
  • Availability: 99.5% overview image availability

Business Metrics

  • User Engagement: Increase spatial dashboard usage
  • Feature Adoption: >80% of users use overview images
  • Support Reduction: Reduce spatial navigation support tickets
  • Organization Efficiency: Improve workspace organization scores

Implementation Phases

Phase 1: Core Overview Generation (Weeks 1-3)

  • Backend overview image generation pipeline
  • Basic spatial layout calculation algorithm
  • Integration with existing image storage system
  • Container card enhancement with thumbnail overview

Phase 2: Advanced Visualization (Weeks 4-6)

  • Detailed overview styles with labels
  • Hover preview functionality
  • Automatic generation triggers
  • Performance optimization and caching

Phase 3: Interactive Features (Weeks 7-9)

  • Interactive overview editing
  • Real-time layout updates
  • Advanced spatial relationship visualization
  • Mobile-optimized overview display

Phase 4: Intelligence and Analytics (Weeks 10-12)

  • Smart overview generation (focus on important objects)
  • Organization assessment features
  • Usage analytics and optimization
  • Advanced accessibility features

Integration Testing

Test Scenarios

  1. Container with Mixed Object Types: Verify layout with various object classes
  2. Empty Container: Handle containers with no objects gracefully
  3. Overpacked Container: Manage containers with many objects
  4. Deep Nesting: Test containers within containers
  5. Permission Boundaries: Respect organization and privacy settings

Performance Testing

  1. Large Container Load: Test with containers having 100+ objects
  2. Concurrent Generation: Multiple overview generations simultaneously
  3. Cache Performance: Verify cache hit rates and invalidation
  4. Mobile Performance: Test on low-powered mobile devices
  5. Network Conditions: Test under various network conditions

Documentation and Training

User Documentation

  • Feature introduction and benefits
  • How to interpret overview images
  • Customization options
  • Troubleshooting common issues

Developer Documentation

  • Overview generation API reference
  • Spatial layout algorithm documentation
  • Frontend integration guide
  • Performance optimization guide

Admin Documentation

  • Overview image management
  • Performance monitoring
  • Storage management
  • Security configuration

Future Enhancements

Short-term (Next 6 months)

  • 3D Overview Images: Perspective views for deep containers
  • Object Labels: Toggle-able object names on overview
  • Density Heatmaps: Visual indicators of container utilization
  • Smart Cropping: Focus on areas with most objects

Medium-term (6-12 months)

  • Interactive Editing: Drag objects within overview to reorganize
  • AR Integration: Overlay overview on real container view
  • Machine Learning: Intelligent layout suggestions
  • Collaboration: Multi-user overview editing

Long-term (12+ months)

  • Video Overviews: Time-lapse of container organization changes
  • Voice Descriptions: Audio descriptions of container contents
  • Physical Integration: Sync with smart container sensors
  • Advanced Analytics: Predictive organization recommendations

This use case document provides a comprehensive foundation for implementing sub-container overview images within the existing Plings spatial relationships system, ensuring seamless integration with current functionality while delivering significant user experience improvements.