Add clusteringPixelSizeThreshold

[igoroctaviano]

Clustering Configuration and Progress Indicators

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. UI Toggle for Clustering - Easy-to-use switch to enable/disable clustering with conditional UI display
3. Progress Indicator - Visual feedback for bulk annotation retrieval and processing
4. Style Updates - UI improvements for clustering settings

Changes

1. Clustering Pixel Size Threshold (Initial Feature)

• Added clusteringPixelSizeThreshold to component state

  • Type: number
  • Default value: 0.001 mm (1 micrometer)
  • Added to SlideViewerState interface

• Added threshold input UI

  • InputNumber component in Annotation Groups menu
  • Allows users to set pixel size threshold in millimeters
  • Supports values from 0 to 100 mm with 0.001 precision
  • Placeholder text: "Auto (zoom-based)"
  • Help text explains threshold behavior

• Updated viewer construction

  • Passes clusteringPixelSizeThreshold to viewer via annotationOptions
  • Integrated with constructViewers utility function

• Added handleClusteringPixelSizeThresholdChange handler

  • Updates state when threshold value changes
  • Updates viewer annotation options when clustering is enabled

2. Progress Indicator for Bulk Annotations

• Added AnnotationProgress component

  • Displays progress for annotation retrieval and processing
  • Shows separate progress bars for retrieval and processing phases
  • Fixed position at bottom-right of screen
  • Auto-dismisses when processing completes
  • Listens to ANNOTATION_PROCESSING_PROGRESS and ANNOTATION_RETRIEVAL_PROGRESS events

• Integrated progress component in SlideViewer

  • Added to render method
  • Automatically displays when annotations are being retrieved/processed

3. UI Toggle for Clustering (Latest Feature)

• Added clustering toggle switch in the Annotation Groups menu

  • Located above the clustering pixel size threshold input
  • Uses Ant Design Switch component
  • Enabled by default (isClusteringEnabled: true)

• Conditional display of threshold input

  • The "Clustering Pixel Size Threshold" input is only shown when clustering is enabled
  • When clustering is disabled, the threshold UI is hidden

• State Management

  • Added isClusteringEnabled to component state (type: boolean, default: true)
  • Updated shouldComponentUpdate to include clustering state changes
  • Ensures component re-renders when clustering state changes

• Viewer Integration

  • When clustering is disabled, clusteringPixelSizeThreshold is passed as undefined to the viewer
  • When enabled, uses the current threshold value from state
  • Added handleClusteringToggle handler with error handling

4. Style Updates

• Updated styling for clustering settings
  • Improved layout and spacing in clustering menu items
  • Enhanced visual presentation of threshold input

Code Quality

• All new comments use JSDoc format (/** */)
• Fixed linting issues (explicit null/undefined checks)
• Follows existing code patterns and conventions

User Experience

• Users can configure clustering pixel size threshold for fine-grained control
• Easy toggle to enable/disable clustering without losing threshold configuration
• Visual progress feedback during annotation retrieval and processing
• When clustering is disabled, threshold input is hidden to reduce UI clutter
• Clustering is enabled by default to maintain existing behavior
• Toggle state is preserved and works correctly even when toggled before annotations are loaded

Testing

• Threshold can be set and updated successfully

• Toggle can be switched on/off successfully

• Threshold input appears/disappears based on toggle state

• Viewer correctly applies clustering settings when toggled

• Progress indicator displays during annotation operations

• No unnecessary annotation loading when toggling clustering

• Works correctly when toggled before annotations are loaded

• Bulk annotations always cluster #330 (comment)

• DMV PR: Add clusteringPixelSizeThreshold option dicom-microscopy-viewer#222

[deepsource-io]

Here's the code health analysis summary for commits fea13f6..877ec4a. View details on DeepSource ↗.

Analysis Summary

Analyzer	Status	Summary	Link
JavaScript	❌ Failure	❗ 21 occurences introduced	View Check ↗

---

💡 If you’re a repository administrator, you can configure the quality gates from the settings.

[igoroctaviano]

@fedorov I have this solution for items 1 and 2 of #330 (comment). Please let me know if its better now.

[sonarqubecloud]

Quality Gate passed

Issues
21 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[fedorov]

Now the image doesn't load at all. I deployed using the feat/cluster-threshold for both slim and dmv. Tested using the same URL as in #330 https://andrey-slim-test.web.app/studies/2.25.302737996345872783571112300080988167697/series/1.3.6.1.4.1.5962.99.1.1250863857.1162905243.1637633436401.2.0.

[igoroctaviano]

studies/2.25.302737996345872783571112300080988167697/series/1.3.6.1.4.1.5962.99.1.1250863857.1162905243.1637633436401.2.0.

@fedorov Looks like even prod it does not load: https://viewer.imaging.datacommons.cancer.gov/slim/studies/2.25.302737996345872783571112300080988167697/series/1.3.6.1.4.1.5962.99.1.1250863857.1162905243.1637633436401.2.0

[fedorov]

Then we broke the production with another regression... It was working as of Nov 21, 2025, as documented in the screenshot in #330 (comment).