feat: pretty tree view (#29)

* wip

* cleaner code

* feat: add prefetching for plate hierarchy and rich representation for ZarrGroup

* fix: update OME-zarr icons for consistency in tree representation

* fix: add LabelsGroup to exports in __all__ for consistency

* fix: update tree icons for improved representation of Zarr nodes

* typos

Author: tlambert03

docs/index.md

@@ -278,7 +278,7 @@ write.v05.Bf2RawBuilder(...)
 ### CLI validation
 
 The CLI command provides a quick way to validate any zarr store as an OME-Zarr
-store.  Here, "store" here refers to any URI (local path, http(s) url, or s3 url.
+store.  Here, "store" refers to any URI (local path, http(s) url, or s3 url.
 
 !!!important
     Requires `fsspec`. install with `pip install yaozarrs[io]`
@@ -301,9 +301,44 @@ store.  Here, "store" here refers to any URI (local path, http(s) url, or s3 url
   Type: Image
 ```
 
+### CLI tree view
+
+Visualize the hierarchy of any OME-Zarr store with `yaozarrs tree`:
+
+=== "with uvx"
+
+    ```sh
+    uvx "yaozarrs[io]" tree https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.5/idr0062A/6001240_labels.zarr
+    ```
+
+=== "from installed package"
+
+    ```sh
+    yaozarrs tree https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.5/idr0062A/6001240_labels.zarr
+    ```
+
+```
+🖼️ 6001240_labels.zarr
+├── zarr.json  <- v05.Image
+├── 📦 0 (uint16, (2, 236, 275, 271))
+├── 📦 1 (uint16, (2, 236, 137, 135))
+├── 📦 2 (uint16, (2, 236, 68, 67))
+└── 🏷️ labels
+    ├── zarr.json  <- v05.LabelsGroup
+    └── 🖼️ 0
+        ├── zarr.json  <- v05.LabelImage
+        ├── 📦 0 (int8, (1, 236, 275, 271))
+        ├── 📦 1 (int8, (1, 236, 137, 135))
+        ├── 📦 2 (int8, (1, 236, 68, 67))
+        └── 📦 3 (int8, (1, 236, 34, 33))
+```
+
+Use `--depth` / `-d` to limit traversal depth, and `--max-per-level` / `-n` to
+cap the number of children shown at each level.
+
 ### Loading OME-Zarr Stores
 
-[`yaozarrs.open_group`][] teturns a small wrapper around a zarr group with
+[`yaozarrs.open_group`][] returns a small wrapper around a zarr group with
 minimal functionality: [`yaozarrs.ZarrGroup`][].  Requires the [`yaozarrs[io]`
 extra](./installation.md#structural-validation) to support remote URIs.  This
 class is used behind the scenes for structural validation, but can also be used
@@ -324,6 +359,13 @@ child = group["0"]  # (2)!
 2. Access arrays and sub-groups using standard dictionary-like syntax. Returns
    [`ZarrArray`][yaozarrs._zarr.ZarrArray] or [`ZarrGroup`][yaozarrs._zarr.ZarrGroup]
 
+You can also get a tree view of the hierarchy programmatically with
+[`ZarrGroup.tree()`][yaozarrs._zarr.ZarrGroup.tree]:
+
+```python
+print(group.tree(depth=2))
+```
+
 #### Access array data
 
 This package does *not* depend on `zarr` or `tensorstore`, even for validating
@@ -363,7 +405,7 @@ Zarr itself is a *specification* with multiple implementations:  There are many
 ways to read and write Zarr stores (e.g. `zarr-python`, `tensorstore`,
 `acquire-zarr`, `zarrs`, etc..) and **yaozarrs makes no assumptions about which
 implementation you may want to use**.  Similarly, OME NGFF is a *metadata
-sepcification*, defining what JSON documents and hierarchy structure must look
+specification*, defining what JSON documents and hierarchy structure must look
 like.
 
 1. At its core, **yaozarrs provides pydantic models for OME-Zarr metadata

docs/ome_zarr_guide.md

@@ -3,7 +3,7 @@ icon: material/book-open-variant
 title: Guide to OME-Zarr
 ---
 
-# Yaozzars Guide to OME-Zarr
+# Yaozarrs Guide to OME-Zarr
 
 <script type="module" src="/javascripts/ome_explorer.js"></script>
 
@@ -56,7 +56,7 @@ title: Guide to OME-Zarr
     spec takes precedence!
 
 OME-Zarr is a file format specification used by the bioimaging community for
-storing multi-dimensional data. It is a "meta-specication", based on the
+storing multi-dimensional data. It is a "meta-specification", based on the
 pre-existing Zarr format, which is designed for the storage of chunked,
 compressed, N-dimensional arrays. OME-Zarr **extends** Zarr by adding metadata
 conventions specific to bioimaging, making it easier to store and share complex

src/yaozarrs/_cli.py

@@ -62,6 +62,33 @@ def validate_command(args: argparse.Namespace) -> int:
         return 2
 
 
+def tree_command(args: argparse.Namespace) -> int:
+    """Execute the tree subcommand.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed command-line arguments
+
+    Returns
+    -------
+    int
+        Exit code (0 for success, 2 for errors)
+    """
+    from yaozarrs._tree import print_tree
+
+    try:
+        group = open_group(args.path)
+        print_tree(group, depth=args.depth, max_per_level=args.max_per_level)
+        return 0
+    except ImportError as e:  # pragma: no cover
+        print(f"ImportError: {e}", file=sys.stderr)
+        return 2
+    except Exception as e:
+        print(f"✗ Error: {e}", file=sys.stderr)
+        return 2
+
+
 def main(argv: list[str] | None = None) -> int:
     """Main entry point for the CLI.
 
@@ -98,6 +125,32 @@ def main(argv: list[str] | None = None) -> int:
     )
     validate_parser.set_defaults(func=validate_command)
 
+    # Tree subcommand
+    tree_parser = subparsers.add_parser(
+        "tree",
+        help="Display the hierarchy of an OME-Zarr store as a tree",
+    )
+    tree_parser.add_argument(
+        "path",
+        help="Path or URI to the OME-Zarr store",
+    )
+    tree_parser.add_argument(
+        "-d",
+        "--depth",
+        type=int,
+        default=None,
+        help="Maximum depth to traverse (default: unlimited)",
+    )
+    tree_parser.add_argument(
+        "-n",
+        "--max-per-level",
+        type=int,
+        default=None,
+        dest="max_per_level",
+        help="Maximum children to show per level (default: unlimited)",
+    )
+    tree_parser.set_defaults(func=tree_command)
+
     # Parse arguments
     args = parser.parse_args(argv)