nimbusimage

Python API for NimbusImage (app) — programmatic access to scientific imaging datasets, annotations, workers, and analysis.

Installation

pip install nimbusimage

For Docker worker development (includes large_image for writing TIFF files):

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 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.

Required scopes. The simplest option is a full-access key (leave the scope list empty), which works for everything including polling job status. If you instead create a scoped key, it must include core.user_auth — without it, job.wait() / job.refresh() fail with a confusing 401 Unauthorized even though you own the job. Add jobs.rest.list_job as well so job logs can be read. Recommended scoped-key set: core.data.read, core.data.write, core.data.own, core.user_info.read, core.user_auth, jobs.rest.list_job.

Set environment variables for persistent access:

# Add to ~/.zshrc or ~/.bashrc

# For nimbusimage.com:
export NI_API_URL="https://app.nimbusimage.com/girder/api/v1"
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:

import nimbusimage as ni

client = ni.connect()

Or pass credentials explicitly:

client = ni.connect("http://localhost:8080/api/v1", api_key="your-api-key")

Quick start

import nimbusimage as ni

client = ni.connect()

# Build a dataset from image files (dry-run first to check the plan)
ds = client.create_dataset("My Experiment")
ds.upload("path/to/images/")
plan = ds.configure(dry_run=True)
if plan.is_valid:
    ds.configure()   # also creates the collection + view, so ds.open() works

# 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.create_dataset(name) -> Dataset
    client.dataset(id) -> Dataset
        ds.upload()      # add image files to the dataset folder
        ds.configure()   # turn those files into one multi-dimensional image
        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 docs.nimbusimage.com for general documentation and the API reference for detailed API docs.

Agent integration: Claude Code and Codex

NimbusImage includes a shared set of Agent Skills that teach Claude Code and Codex how to use this API. After installing the plugin, ask either agent to connect to a NimbusImage server, inspect datasets, retrieve images, manage annotations, run workers, or export results.

Claude Code

# Add the NimbusImage marketplace (one-time)
claude plugin marketplace add arjunrajlaboratory/NimbusImage

# Install the plugin
claude plugin install nimbusimage@NimbusImage

For development from a local clone, load the plugin for one session:

claude --plugin-dir /path/to/NimbusImage/plugins/nimbusimage

Codex

# Add the NimbusImage marketplace (one-time)
codex plugin marketplace add arjunrajlaboratory/NimbusImage

# Install the plugin
codex plugin add nimbusimage@NimbusImage

When working inside a clone of this repository, Codex can also discover the synchronized repository-local skills under .agents/skills/ without installing the plugin.

Available skills

The skills use progressive disclosure, so each agent loads detailed instructions and API references only when needed. See the plugin documentation for repository-local Codex aliases and skill-development instructions.

Development

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.