nimbusimage 0.1.0__tar.gz

nimbusimage-0.1.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: nimbusimage
+Version: 0.1.0
+Summary: Python API for NimbusImage
+Author-email: Arjun Raj <arjunrajlab@gmail.com>
+License: Apache-2.0
+Project-URL: Homepage, https://nimbusimage.com
+Project-URL: Repository, https://github.com/arjunrajlaboratory/NimbusImage
+Project-URL: Documentation, https://docs.nimbusimage.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: girder-client
+Requires-Dist: numpy
+Requires-Dist: pydantic>=2.0
+Requires-Dist: shapely
+Requires-Dist: scikit-image
+Provides-Extra: worker
+Requires-Dist: large-image; extra == "worker"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+
+# nimbusimage
+
+Python API for [NimbusImage](https://nimbusimage.com) — programmatic access to scientific imaging datasets, annotations, workers, and analysis.
+
+## Installation
+
+```bash
+pip install nimbusimage
+```
+
+For Docker worker development (includes `large_image` for writing TIFF files):
+
+```bash
+pip install nimbusimage[worker]
+```
+
+## Authentication
+
+The recommended setup uses a **Girder API key**, which is persistent and doesn't expire.
+
+**How to get an API key:**
+
+- **nimbusimage.com (hosted):** Email **[support@cytopixel.com](mailto:support@cytopixel.com)** with your account email address to request an API key.
+- **Local/self-hosted server:** In the Girder admin UI, go to **Users** > select the user > **Edit User** > **API Keys** > create a new key and copy the key string.
+
+Set environment variables for persistent access:
+
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+
+# For nimbusimage.com:
+export NI_API_URL="https://nimbusimage.com/girder"
+export NI_API_KEY="your-api-key-here"
+
+# For a local server:
+export NI_API_URL="http://localhost:8080/api/v1"
+export NI_API_KEY="your-api-key-here"
+```
+
+Then connect with no arguments:
+
+```python
+import nimbusimage as ni
+
+client = ni.connect()
+```
+
+Or pass credentials explicitly:
+
+```python
+client = ni.connect("http://localhost:8080/api/v1", api_key="your-api-key")
+```
+
+## Quick start
+
+```python
+import nimbusimage as ni
+
+client = ni.connect()
+
+# List datasets
+for d in client.list_datasets():
+    print(f"{d['name']} (ID: {d['_id']})")
+
+# Open a dataset
+ds = client.dataset(name="My Experiment")
+print(f"{ds.name}: {ds.channels}, {ds.num_z} z-slices, {ds.shape}")
+
+# Fetch an image
+img = ds.images.get(channel=0, z=0)  # numpy array
+
+# Get a composite RGB image
+rgb = ds.images.get_composite(dtype="uint8")
+
+# List annotations
+polygons = ds.annotations.list(shape="polygon")
+
+# Run a worker
+job = ds.annotations.compute(
+    image="annotations/random_squares:latest",
+    channel=0, tags=["detected"],
+    worker_interface={"Number of squares": 10, "Square size": 15},
+)
+job.wait()
+
+# Export data
+ds.export.to_csv(property_paths=[["prop_id", "Area"]], path="results.csv")
+
+# Open in browser
+ds.open(z=3)
+```
+
+## API overview
+
+The package follows an accessor pattern:
+
+```
+ni.connect() -> NimbusClient
+    client.dataset(id) -> Dataset
+        ds.images        # fetch frames, composites, z-stacks
+        ds.annotations   # create, list, filter, delete annotations
+        ds.connections   # parent-child annotation links
+        ds.properties    # computed measurements
+        ds.collections   # display configuration (layers, tools)
+        ds.export        # JSON and CSV export
+        ds.history       # undo/redo
+        ds.sharing       # access control
+    client.list_datasets()
+    client.list_workers()
+    client.list_projects()
+```
+
+See the [full documentation](docs/) for detailed API reference and examples.
+
+## Claude Code integration
+
+NimbusImage includes skills for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that teach Claude how to use this API. After installing, you can ask Claude things like "connect to my NimbusImage server and list datasets" and it will write correct code.
+
+### Install the skills
+
+**Option A — Marketplace install (recommended):**
+
+```bash
+# Add the NimbusImage marketplace (one-time)
+claude plugin marketplace add arjunrajlaboratory/NimbusImage
+
+# Install the nimbusimage plugin
+claude plugin install nimbusimage@arjunrajlaboratory/NimbusImage
+```
+
+**Option B — For this session only:**
+
+```bash
+claude --plugin-dir /path/to/NimbusImage/plugins/nimbusimage
+```
+
+**Option C — Permanent (project-scoped):**
+
+Add to your project's `.claude/settings.local.json`:
+
+```json
+{
+  "plugins": ["/path/to/NimbusImage/plugins/nimbusimage"]
+}
+```
+
+### Available skills
+
+
+| Command                    | What it covers                                     |
+| -------------------------- | -------------------------------------------------- |
+| `/nimbusimage`             | Connection, dataset discovery, metadata, projects  |
+| `/nimbusimage:annotations` | Annotation CRUD, geometry helpers, bulk operations |
+| `/nimbusimage:images`      | Frame retrieval, composites, z-stacks, crops       |
+| `/nimbusimage:workers`     | Docker worker discovery, execution, job tracking   |
+| `/nimbusimage:analyze`     | Properties, export, connections, sharing           |
+
+
+The skills use progressive disclosure — Claude loads only what it needs for the current task.
+
+## Development
+
+```bash
+cd nimbusimage
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run unit tests (no backend required)
+pytest tests/ --ignore=tests/integration -v
+
+# Run integration tests (requires docker compose up)
+pytest tests/integration/ -v -m integration
+```
+
+## License
+
+See the project root for license information.

nimbusimage-0.1.0/README.md

@@ -0,0 +1,177 @@
+# nimbusimage
+
+Python API for [NimbusImage](https://nimbusimage.com) — programmatic access to scientific imaging datasets, annotations, workers, and analysis.
+
+## Installation
+
+```bash
+pip install nimbusimage
+```
+
+For Docker worker development (includes `large_image` for writing TIFF files):
+
+```bash
+pip install nimbusimage[worker]
+```
+
+## Authentication
+
+The recommended setup uses a **Girder API key**, which is persistent and doesn't expire.
+
+**How to get an API key:**
+
+- **nimbusimage.com (hosted):** Email **[support@cytopixel.com](mailto:support@cytopixel.com)** with your account email address to request an API key.
+- **Local/self-hosted server:** In the Girder admin UI, go to **Users** > select the user > **Edit User** > **API Keys** > create a new key and copy the key string.
+
+Set environment variables for persistent access:
+
+```bash
+# Add to ~/.zshrc or ~/.bashrc
+
+# For nimbusimage.com:
+export NI_API_URL="https://nimbusimage.com/girder"
+export NI_API_KEY="your-api-key-here"
+
+# For a local server:
+export NI_API_URL="http://localhost:8080/api/v1"
+export NI_API_KEY="your-api-key-here"
+```
+
+Then connect with no arguments:
+
+```python
+import nimbusimage as ni
+
+client = ni.connect()
+```
+
+Or pass credentials explicitly:
+
+```python
+client = ni.connect("http://localhost:8080/api/v1", api_key="your-api-key")
+```
+
+## Quick start
+
+```python
+import nimbusimage as ni
+
+client = ni.connect()
+
+# List datasets
+for d in client.list_datasets():
+    print(f"{d['name']} (ID: {d['_id']})")
+
+# Open a dataset
+ds = client.dataset(name="My Experiment")
+print(f"{ds.name}: {ds.channels}, {ds.num_z} z-slices, {ds.shape}")
+
+# Fetch an image
+img = ds.images.get(channel=0, z=0)  # numpy array
+
+# Get a composite RGB image
+rgb = ds.images.get_composite(dtype="uint8")
+
+# List annotations
+polygons = ds.annotations.list(shape="polygon")
+
+# Run a worker
+job = ds.annotations.compute(
+    image="annotations/random_squares:latest",
+    channel=0, tags=["detected"],
+    worker_interface={"Number of squares": 10, "Square size": 15},
+)
+job.wait()
+
+# Export data
+ds.export.to_csv(property_paths=[["prop_id", "Area"]], path="results.csv")
+
+# Open in browser
+ds.open(z=3)
+```
+
+## API overview
+
+The package follows an accessor pattern:
+
+```
+ni.connect() -> NimbusClient
+    client.dataset(id) -> Dataset
+        ds.images        # fetch frames, composites, z-stacks
+        ds.annotations   # create, list, filter, delete annotations
+        ds.connections   # parent-child annotation links
+        ds.properties    # computed measurements
+        ds.collections   # display configuration (layers, tools)
+        ds.export        # JSON and CSV export
+        ds.history       # undo/redo
+        ds.sharing       # access control
+    client.list_datasets()
+    client.list_workers()
+    client.list_projects()
+```
+
+See the [full documentation](docs/) for detailed API reference and examples.
+
+## Claude Code integration
+
+NimbusImage includes skills for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) that teach Claude how to use this API. After installing, you can ask Claude things like "connect to my NimbusImage server and list datasets" and it will write correct code.
+
+### Install the skills
+
+**Option A — Marketplace install (recommended):**
+
+```bash
+# Add the NimbusImage marketplace (one-time)
+claude plugin marketplace add arjunrajlaboratory/NimbusImage
+
+# Install the nimbusimage plugin
+claude plugin install nimbusimage@arjunrajlaboratory/NimbusImage
+```
+
+**Option B — For this session only:**
+
+```bash
+claude --plugin-dir /path/to/NimbusImage/plugins/nimbusimage
+```
+
+**Option C — Permanent (project-scoped):**
+
+Add to your project's `.claude/settings.local.json`:
+
+```json
+{
+  "plugins": ["/path/to/NimbusImage/plugins/nimbusimage"]
+}
+```
+
+### Available skills
+
+
+| Command                    | What it covers                                     |
+| -------------------------- | -------------------------------------------------- |
+| `/nimbusimage`             | Connection, dataset discovery, metadata, projects  |
+| `/nimbusimage:annotations` | Annotation CRUD, geometry helpers, bulk operations |
+| `/nimbusimage:images`      | Frame retrieval, composites, z-stacks, crops       |
+| `/nimbusimage:workers`     | Docker worker discovery, execution, job tracking   |
+| `/nimbusimage:analyze`     | Properties, export, connections, sharing           |
+
+
+The skills use progressive disclosure — Claude loads only what it needs for the current task.
+
+## Development
+
+```bash
+cd nimbusimage
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run unit tests (no backend required)
+pytest tests/ --ignore=tests/integration -v
+
+# Run integration tests (requires docker compose up)
+pytest tests/integration/ -v -m integration
+```
+
+## License
+
+See the project root for license information.

nimbusimage-0.1.0/nimbusimage/__init__.py

@@ -0,0 +1,107 @@
+"""NimbusImage Python API.
+
+Usage:
+    import nimbusimage as ni
+
+    client = ni.connect(api_url, token=...)
+    ds = client.dataset(dataset_id)
+    img = ds.images.get(channel=0)
+    anns = ds.annotations.list(shape='polygon')
+"""
+
+from nimbusimage.client import NimbusClient
+from nimbusimage.collections import Collection
+from nimbusimage.coordinates import attach_geometry_methods
+from nimbusimage.dataset import Dataset
+from nimbusimage.jobs import Job
+from nimbusimage.filters import (
+    filter_by_tags,
+    filter_by_location,
+    group_by_location,
+)
+from nimbusimage.models import (
+    Annotation,
+    Connection,
+    FrameInfo,
+    Location,
+    PixelSize,
+    Property,
+)
+from nimbusimage.worker import WorkerContext
+
+# Attach geometry methods (polygon, point, get_mask, etc.) to Annotation
+attach_geometry_methods()
+
+
+def connect(
+    api_url: str | None = None,
+    token: str | None = None,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+) -> NimbusClient:
+    """Connect to a NimbusImage server.
+
+    Args:
+        api_url: Girder API URL. Or set NI_API_URL env var.
+        token: Auth token. Or set NI_TOKEN env var.
+        api_key: Girder API key. Or set NI_API_KEY env var.
+            API keys are persistent and don't expire (unlike
+            session tokens). Recommended for automation.
+        username: Username for interactive auth.
+        password: Password for interactive auth.
+
+    Returns:
+        Authenticated NimbusClient.
+    """
+    return NimbusClient(
+        api_url=api_url, token=token, api_key=api_key,
+        username=username, password=password,
+    )
+
+
+def worker_context(
+    dataset_id: str | None = None,
+    api_url: str | None = None,
+    token: str | None = None,
+    params: dict | None = None,
+) -> WorkerContext:
+    """Create a worker context for Docker worker scripts.
+
+    Args:
+        dataset_id: The dataset folder ID.
+        api_url: Girder API URL.
+        token: Auth token.
+        params: Worker parameters dict (from the job).
+
+    Returns:
+        WorkerContext with parsed parameters and dataset access.
+    """
+    return WorkerContext(
+        dataset_id=dataset_id, api_url=api_url,
+        token=token, params=params,
+    )
+
+
+__all__ = [
+    # Connection
+    "connect",
+    "worker_context",
+    # Classes
+    "NimbusClient",
+    "Collection",
+    "Dataset",
+    "Job",
+    "WorkerContext",
+    # Data models
+    "Annotation",
+    "Connection",
+    "Property",
+    "Location",
+    "PixelSize",
+    "FrameInfo",
+    # Filters
+    "filter_by_tags",
+    "filter_by_location",
+    "group_by_location",
+]

nimbusimage-0.1.0/nimbusimage/_access.py

@@ -0,0 +1,20 @@
+"""Shared access level constants and helpers."""
+
+ACCESS_MAP = {"read": 0, "write": 1, "admin": 2, "remove": -1}
+
+
+def resolve_access(access: str) -> int:
+    """Convert a human-readable access level to its integer code.
+
+    Args:
+        access: One of 'read', 'write', 'admin', 'remove'.
+
+    Raises:
+        ValueError: If the access level is not recognized.
+    """
+    if access not in ACCESS_MAP:
+        raise ValueError(
+            f"Invalid access level '{access}'. "
+            f"Must be one of: {', '.join(ACCESS_MAP.keys())}"
+        )
+    return ACCESS_MAP[access]

nimbusimage-0.1.0/nimbusimage/_girder.py

@@ -0,0 +1,77 @@
+"""Internal wrapper around girder_client.GirderClient.
+
+This module is an implementation detail. Users should never import from it.
+All HTTP communication goes through this wrapper so that endpoint paths
+and error handling are centralized.
+"""
+
+from __future__ import annotations
+
+import os
+
+import girder_client
+
+
+def create_client(
+    api_url: str | None = None,
+    token: str | None = None,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+) -> girder_client.GirderClient:
+    """Create and authenticate a GirderClient.
+
+    Connection modes (tried in order):
+    1. Explicit token
+    2. Explicit API key
+    3. Username + password
+    4. NI_API_KEY environment variable
+    5. NI_TOKEN environment variable
+
+    Args:
+        api_url: Girder API URL (e.g., 'http://localhost:8080/api/v1').
+        token: Pre-existing authentication token.
+        api_key: Girder API key (persistent, doesn't expire).
+        username: Username for interactive auth.
+        password: Password for interactive auth.
+
+    Returns:
+        Authenticated GirderClient instance.
+
+    Raises:
+        ValueError: If no valid authentication method is provided.
+    """
+    if api_url is None:
+        api_url = os.environ.get("NI_API_URL")
+    if api_url is None:
+        raise ValueError(
+            "api_url must be provided or set NI_API_URL "
+            "environment variable"
+        )
+
+    gc = girder_client.GirderClient(apiUrl=api_url)
+
+    if token is not None:
+        gc.setToken(token)
+    elif api_key is not None:
+        gc.authenticate(apiKey=api_key)
+    elif username is not None or password is not None:
+        if username is None or password is None:
+            raise ValueError(
+                "Both username and password must be provided"
+            )
+        gc.authenticate(username=username, password=password)
+    else:
+        env_api_key = os.environ.get("NI_API_KEY")
+        env_token = os.environ.get("NI_TOKEN")
+        if env_api_key is not None:
+            gc.authenticate(apiKey=env_api_key)
+        elif env_token is not None:
+            gc.setToken(env_token)
+        else:
+            raise ValueError(
+                "Provide token=, api_key=, username=/password=, "
+                "or set NI_API_KEY/NI_TOKEN environment variable"
+            )
+
+    return gc