Add clusteringPixelSizeThreshold option

[igoroctaviano]

Clustering Configuration, Progress Tracking, and Performance Improvements

Summary

This PR introduces several enhancements to annotation clustering and processing:

1. Clustering Pixel Size Threshold - Configurable threshold for enabling/disabling clustering based on pixel size
2. Support for Disabling Clustering - Ability to disable clustering by setting threshold to undefined
3. Progress Tracking - Events and infrastructure for tracking annotation retrieval and processing progress
4. Performance Improvements - Optimized layer switching and reduced unnecessary data loading
5. Dependency Updates - Updated OpenLayers version

Changes

1. Clustering Pixel Size Threshold (Initial Feature)

• Added clusteringPixelSizeThreshold to annotation options

  • Configurable pixel size threshold in millimeters
  • When current pixel size ≤ threshold, clustering is disabled (high resolution mode)
  • Defaults to undefined which falls back to zoom-based detection

• Enhanced isHighResolution function in addAnnotationGroups

  • Uses pixel size threshold when available
  • Falls back to zoom-based detection when threshold is undefined
  • Calculates current pixel size based on pyramid level and resolution

• Added setAnnotationOptions method

  • Allows updating clustering configuration at runtime
  • Updates layer visibility based on new clustering settings
  • Supports both threshold-based and zoom-based clustering detection

2. Progress Tracking Infrastructure

• Added progress events

  • ANNOTATION_PROCESSING_PROGRESS - Tracks annotation processing progress
  • ANNOTATION_RETRIEVAL_PROGRESS - Tracks annotation retrieval progress
  • Events published to both container and window for reliable delivery

• Enhanced annotation processing

  • Added progress callbacks to async processing
  • Progress events include: annotationGroupUID, processed, total, percentage
  • Progress updates during chunked processing

• Added utility modules

  • annotationProcessingQueue.js - Queue management for annotation processing tasks
  • asyncProcessor.js - Chunked processing utilities with progress tracking
  • performanceMonitor.js - Performance monitoring utilities

• Web worker enhancements

  • annotationCoordinateTransformTask.js - Coordinate transformation in web workers
  • annotationStatisticsTask.js - Statistics computation in web workers
  • Improved data loader worker integration

3. Support for Disabling Clustering (Latest Feature)

• Enhanced setAnnotationOptions method

  • When clusteringPixelSizeThreshold is undefined, always shows high-resolution layer
  • Only updates layer visibility if annotation group is currently visible
  • Prevents triggering unnecessary data loads when toggling clustering settings
  • Added defensive checks for _annotationOptions object

• Fixed isHighResolution function in addAnnotationGroups

  • When clusteringPixelSizeThreshold is undefined, returns true (always use high-res layer)
  • Previously returned undefined which caused incorrect layer selection
  • Ensures correct behavior when clustering is disabled before annotations are loaded

• Optimized layer visibility management

  • Only updates layer visibility if annotation group is currently visible
  • If annotation group is not visible, only updates configuration
  • Existing moveend handler applies correct layer when group becomes visible
  • Only updates visibility if it's actually changing
  • Prevents unnecessary annotation retrieval when toggling clustering

4. Dependency Updates

• Updated OpenLayers version
  • Package.json and yarn.lock updated
  • Ensures compatibility with latest OpenLayers features

5. Code Quality

• Updated comments to JSDoc format
  • All new comments use /** */ format
  • Improved code documentation

Behavior Changes

When Clustering is Disabled (clusteringPixelSizeThreshold === undefined)

• Always uses high-resolution layer (no clustering)
• Layer visibility is only updated if annotation group is visible
• Configuration is preserved for when annotations are loaded later

When Clustering is Enabled

• Uses pixel size threshold to determine high-res vs clustered layer
• Falls back to zoom-based detection if threshold not set
• Maintains existing behavior

Performance Improvements

• Prevents unnecessary annotation loading when toggling clustering
• Only processes layer visibility changes when annotation groups are visible
• Reduces redundant loader triggers
• Chunked processing with progress tracking improves responsiveness
• Web worker integration for heavy computations

Code Quality

• All new comments use JSDoc format (/** */)
• Follows existing code patterns and conventions
• Maintains backward compatibility

Testing

• Clustering pixel size threshold can be configured and updated

• Clustering can be disabled by setting threshold to undefined

• High-resolution layer is always used when clustering is disabled

• Progress events are emitted during annotation operations

• No unnecessary annotation loading when toggling clustering

• Works correctly when clustering is disabled before annotations are loaded

• Layer switching works correctly when annotations become visible

• Bulk annotations always cluster slim#330 (comment)