Feature request: progress callback

[JoeStrout]

Background

Currently CloudVolume.progress is a boolean, and if True, it uses tqdm to show a progress bar in the terminal.

That's fine if you're using it from a terminal, but in some contexts (e.g. using CloudVolume in a GUI app), it's not helpful at all. And there appears to be no facility for any progress callback. The best we could do currently is to monkey-patch tqdm, which might work but is hacky at best.

Proposal

Add an optional progress_callback parameter that gets called with progress updates:

  def progress_callback(current: int, total: int, desc: str) -> None:
      """
      Called periodically during download operations.
      
      Args:
          current: Number of chunks/items processed so far
          total: Total number of chunks/items to process
          desc: Description of current operation (e.g., "Downloading")
      """
      pass

Sample usage:

  vol = CloudVolume(path, progress_callback=my_callback)
  vol.download(bbox, mip=2)  # Callback gets called during download

Implementation sketch (maybe — I haven't dug into this very deeply yet):

• In parallel_execution(), if progress_callback exists, call it instead of/alongside progress_queue_listener
• Pass callback through to worker functions
• Call progress_callback(current, total, desc) whenever progress updates occur

This gives users full control over progress display, without coupling CloudVolume to any specific UI framework.

[william-silversmith]

This is a good idea! However, to fully implement it would be pretty invasive as there are progress bars littered throughout the codebase for each sub-format and type of object... I think at least for now, hacking tqdm is probably the biggest bang for your buck even though it's ugly. I'll keep this in mind though!