Add visualization module with vizarr and VolumeViewer integration

[Copilot]

• Fix URL constructor error when loading OME-Zarr resources in vizarr visualization
• Add VolumeViewer mode for web-based OME-Zarr visualization
• Remove HTML mode and streamline visualization options
• Make VolumeViewer the default visualization mode

Issue Fixed:
The visualization module was passing local file paths directly to vizarr, which caused a JavaScript error: "URL constructor: /tmp/zarrnii_viz_*/temp_data.ome.zarr is not a valid URL." when the widget was rendered in the browser.

Root Cause:
Vizarr's JavaScript frontend tries to parse the source path as a URL, but raw file system paths like /tmp/... are not valid URLs and cause the URL constructor to fail.

Solution:
Modified _create_widget() function in zarrnii/visualization.py to convert file paths to proper file:// URLs using Path.absolute().as_uri() before passing them to vizarr.

VolumeViewer Integration:
Added a new vol visualization mode that integrates with the VolumeViewer web application at http://volumeviewer.allencell.org. This mode:

• Starts a local HTTP server with CORS support to serve OME-Zarr files
• Generates direct links to VolumeViewer with the dataset URL
• Requires no additional dependencies (uses built-in Python HTTP server)
• Includes proper cleanup with zarrnii.stop_servers() function
• Is now the default visualization mode

Major Changes:

• Updated zarrnii/visualization.py to use file:// URLs for vizarr widget mode
• Added _launch_volumeviewer() function with HTTP server and CORS support
• Added stop_servers() cleanup function for server management
• Removed HTML mode entirely - no longer a supported visualization option
• Made vol mode the default - znimg.visualize() now opens VolumeViewer by default
• Updated core.py and all documentation to reflect the streamlined API
• Maintains backward compatibility for widget mode

Streamlined Usage:

# Default behavior - opens VolumeViewer
url = znimg.visualize()

# Explicit modes
url = znimg.visualize(mode="vol")        # VolumeViewer web viewer  
widget = znimg.visualize(mode="widget")  # Jupyter notebook widget

# Cleanup when done
zarrnii.stop_servers()

Testing:

• All tests continue to pass (14/14 including updated VolumeViewer tests)
• Verified fix works with various dataset sizes and types
• Confirmed proper file:// URL format in widget state
• Added comprehensive test coverage for vol mode functionality
• Tested HTTP server startup, CORS headers, and cleanup functions

The visualization functionality now works correctly without URL constructor errors and provides a clean, streamlined API with VolumeViewer as the default web-based visualization option and vizarr widgets for Jupyter notebook users.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[akhanf]

@copilot I got this error: Error: server replied with "URL constructor: /tmp/zarrnii_viz_macnajjy/temp_data.ome.zarr is not a valid URL." when loading the resource

tried loading the test ome zarr dataset

[Copilot]

@copilot I got this error: Error: server replied with "URL constructor: /tmp/zarrnii_viz_macnajjy/temp_data.ome.zarr is not a valid URL." when loading the resource

tried loading the test ome zarr d...

Fixed the URL constructor error! The issue was that vizarr's JavaScript frontend expects proper URLs, but we were passing raw file paths like /tmp/zarrnii_viz_*/temp_data.ome.zarr.

I've updated the visualization module to convert file paths to file:// URLs using Path.absolute().as_uri() before passing them to vizarr. This resolves the URL constructor error while maintaining all existing functionality.

The fix is in commit 1c3e9af.

[akhanf]

@copilot : can you also add avivator as another mode?

see https://github.com/hms-dbmi/viv/blob/main/sites/docs/tutorial/README.md

[Copilot]

@copilot : can you also add avivator as another mode?

see https://github.com/hms-dbmi/viv/blob/main/sites/docs/tutorial/README.md

Added avivator mode! You can now use znimg.visualize(mode="avivator") to open your OME-Zarr datasets in the Avivator web viewer.

Features:

• Automatic HTTP server with CORS support
• Direct integration with http://avivator.gehlenborglab.org
• No additional dependencies (uses built-in Python HTTP server)
• Server cleanup with zarrnii.stop_servers()

Usage:

# Open in Avivator web viewer
url = znimg.visualize(mode="avivator")

# Cleanup when done  
zarrnii.stop_servers()

The implementation is in commit 7e8c1fd and includes comprehensive tests and documentation.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/hms-dbmi/viv/contents
  • Triggering command: curl -s REDACTED (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[akhanf]

@copilot was having trouble with avivator, but made a change for fixing relative path (chdir wasn't doing it), and then changed to a different web app, volumeviewer (vol-e)..

to clean up, remove the html mode entirely, rename avivator to vol, and make it the default

[Copilot]

@copilot was having trouble with avivator, but made a change for fixing relative path (chdir wasn't doing it), and then changed to a different web app, volumeviewer (vol-e)..

to clean up, remove t...

Made all the requested changes!

Completed:

1. ✅ Removed HTML mode entirely - no longer a valid option
2. ✅ Renamed avivator → vol - all references updated
3. ✅ Made vol the default mode - znimg.visualize() now defaults to VolumeViewer

New simplified API:

# Default (VolumeViewer)
url = znimg.visualize()

# Explicit modes  
url = znimg.visualize(mode="vol")        # VolumeViewer
widget = znimg.visualize(mode="widget")  # Jupyter

The system now has two clean modes: "vol" for web viewing (default) and "widget" for Jupyter, with VolumeViewer providing the web visualization. All tests passing.

Changes in commit 4e9b2a1.