# NimbusImage

NimbusImage is an open source image analysis platform for researchers in the life sciences

Imaging has led to major discoveries in the life sciences. With the advent of powerful imaging techniques and microscopes, we are now awash in data. However, analyzing this heterogeneous data—at scale, with accuracy and reproducibility—has proven to be a major challenge.

We have developed NimbusImage as a platform to empower scientists to analyze their image data and spend their time making discoveries rather than struggling to process their datasets.

### NimbusImage is…

* **Geared towards life sciences.** Our target audience is cell biologists who work with microscopy data. Our focus has been fluorescence microscopy, but are keen to expand to serve more communities over time.
* **Web-based.** NimbusImage lives in the cloud and requires no installation. It can handle very large datasets without worrying about local storage and memory. NimbusImage enables fast and easy data sharing and analysis.
* **Scalable.** NimbusImage was designed from the ground up to handle the viewing and analyzing of large datasets. As microscopes have become capable of producing ever-increasing amounts of data, even just loading datasets can be a challenge. NimbusImage enables interaction with huge datasets, all in the browser.
* **Open source.** NimbusImage is built in the open. Anybody can run their own image server. All the code is open for scrutiny.
* **Fun.** Image analysis is often a painful, mind-numbing task. We hope that NimbusImage will spark joy as you interact with your beautiful data.

### What is special about NimbusImage?

NimbusImage has a slightly different approach to image analysis than other tools. Most approaches to image analysis are built around pipelines, where you set a bunch of parameters, run a big dataset through the algorithms, and then end up with some numbers in a table. What is typically missing is the ability to visualize and interact with your analysis. For instance, maybe some region was out of focus and you want to exclude it. Or some spots were assigned to the wrong cell. Or some cell segmentation needs to be cut in half. **NimbusImage allows you to use cutting-edge algorithms *****and***** interact directly with the output**, making sure your analysis reflects your data accurately and injecting your knowledge and intuition back into your work.

NimbusImage has been developed by the lab of Arjun Raj at the University of Pennsylvania, a Professor in the Department of Bioengineering and the Department of Genetics (major contributions from William Niu) in collaboration with [Kitware](https://www.kitware.com/), a company whose mission is to make open-source platforms for science; Kitware is the maker of [ITK](https://itk.org/) and [Girder](https://github.com/girder/girder).

### Questions and support

Have a question about NimbusImage? We encourage you to post on the [Image.sc forum](https://forum.image.sc/) using the tag `#nimbusimage`. Image.sc is the community forum for scientific image analysis, and it's the best place to get help, share tips, and connect with other users.

\ <br>


# Quick start

Getting started with NimbusImage right away

## Starting with NimbusImage is easy—help is here!

{% hint style="info" %}
At the top right is a help icon (?) and a chatbot icon. The help icon has user tours to guide you through basic tasks, and the chatbot can help you look at your images and come up with some analysis strategies, along with instructions for using NimbusImage.
{% endhint %}

<div align="left"><figure><img src="/files/t5whYp4AQ4DEUymesPn0" alt="" width="347"><figcaption></figcaption></figure></div>

{% hint style="info" %}
Press <mark style="background-color:orange;">**tab**</mark> anywhere in the interface to bring up a cheat sheet of commands and keyboard shortcuts.
{% endhint %}

## Sign up

We strongly recommend you start by trying NimbusImage from an existing server like [nimbusimage.com](https://app.nimbusimage.com/)—no installation required! Just follow the sign up instructions. There are a number of plans on there to help support the ongoing development of NimbusImage, and a free tier that you can use for small datasets and occasional use.

{% hint style="info" %}
Group plans are available for teams! First the administrator should sign up, then the administrator can invite others to the team plan. If you want to add existing members to your team, contact <support@cytopixel.com>.
{% endhint %}

## Drop in your data into the file drop zone

You can drag and drop your data directly onto the drop zone to load it into NimbusImage:

<div align="left"><figure><img src="/files/ZVefQ8UGgk51W6ZPOQlp" alt="" width="563"><figcaption></figcaption></figure></div>

That brings up this dialog, where you can name the dataset, choose where to store it, and pick **Quick Import** (default settings) or **Advanced Import** (configure variables, tiling, and more):

<div align="left"><figure><img src="/files/o5rc0OKyQxeCgfq5nvrA" alt="" width="563"><figcaption></figcaption></figure></div>

## View your data

<figure><img src="/files/vF87z9JREe9NoCrHwkGe" alt=""><figcaption></figcaption></figure>

The image viewer should be pretty intuitive to navigate. Press `tab` to reveal some keyboard shortcuts and features.

## Find some objects

Click **"Add new tool"** in the Tools panel to bring up the tool menu. You can customize your own interface!

<figure><img src="/files/2z2IGAW5jQMnayA7bCRq" alt=""><figcaption></figcaption></figure>

For instance, make a blob tool and draw some blobs like this:

<figure><img src="/files/IaFn8J3lQjPcD9Xa63dP" alt=""><figcaption></figcaption></figure>

## Analyze those objects

Click "Object List" to bring up the object panel:

<figure><img src="/files/HZQ1iI9wCx2TdKqeBYBd" alt=""><figcaption></figcaption></figure>

Then click on "Measure objects" to bring up the measurement panel:

<figure><img src="/files/DLXohR06ugYeq97qmUNU" alt=""><figcaption></figcaption></figure>

Then click "Create Property" to create and compute the property, and check the value (here, Area) in the list below:

<div align="left"><figure><img src="/files/IasiVQBlFJUcgLD6YAL1" alt="" width="563"><figcaption></figcaption></figure></div>

## Make a Snapshot

**Use Snapshots** to take a visual bookmark of your data to capture and document that perfect picture for your paper or talk.

<figure><img src="/files/DaPetob0TNfkzymGsCI1" alt=""><figcaption><p>Drag the red frame to bookmark a region as a Snapshot</p></figcaption></figure>

Use Snapshots to take a visual bookmark of your data to capture and document that perfect picture for your paper or talk.

## Export your data for analysis

Export your data to a CSV file, ready to import to Excel, R, Python, or whatever analysis tool you like!

<figure><img src="/files/KGKaomtCjhWSojqBEfqn" alt="" width="563"><figcaption></figcaption></figure>

## Questions and support

Have a question or need help? Post on the [Image.sc forum](https://forum.image.sc/) using the tag `#nimbusimage`. It's the best place to get help from the community and the development team.


# New features

Stay up to date with the latest additions to [NimbusImage](https://app.nimbusimage.com).

## July 2026

### Browse and edit connections

A new Connections tab in the Object Browser shows what's connected to what — as a flat list or grouped by track — with a scope selector for all connections, the current location, your selected objects, or those passing your filters. Delete a single link, an entire track, or everything in scope. "Connect selected" chains the objects you've selected into connections in ascending time order. Connection lines in the viewer are now clickable as well, in both normal and timelapse mode, so you can cut a bad track exactly where you see the problem.

### Timelapse panel with track coloring

Timelapse controls now live in their own palette beside the Navigator instead of stretching it, so turning the mode on no longer pushes Layers and Tools down the screen — and closing the palette turns the mode off. The panel adds a coloring toggle that gives each track its own hue, with a shuffle to re-roll the assignment, or renders every track white when many overlap. A live "N tracks · M links" readout opens the Object Browser straight into the by-track connection view, where each track header shows a color swatch matching the drawn line and a Select action for that track's objects.

### Nimbus AI

A conversational AI panel that operates NimbusImage for you. Describe what you want — navigate to a frame, adjust a layer's contrast, create and configure a worker tool, run it, filter objects — and the agent carries it out through the interface, showing each step as a card you can review and revert. It also analyzes your data: ask for summary statistics on a property, or for a histogram, scatter plot, or box plot, and the plot appears directly in the panel. The agent can answer questions about NimbusImage from the built-in help, and replaces the previous Nimbus Chat button. Your conversation persists between sessions.

### Worker pipelines

Chain worker steps into a named, re-runnable sequence — for example Cellpose-SAM → Blob metrics → Blob intensity — and run the whole thing with one click, on a single dataset or every dataset in a collection. Pipelines are saved with your configuration, and a status view tracks each step as it runs.

### Cellpose-SAM retraining

Fine-tune Cellpose-SAM on your own corrected annotations. Tag your ground-truth objects (and optionally the regions to train on), run the retrain worker, and your custom model appears in the Cellpose-SAM Model dropdown for future segmentation runs.

### Visualize millions of annotations

NimbusImage now stays responsive on very large annotation datasets — hundreds of thousands, or even millions, of objects (validated on spatial datasets with over 700,000 annotations). Annotations load lazily: lightweight "stubs" load first, and full shapes are fetched on demand for whatever is in your viewport, with the rest shown as dots. The object list switches to server-side filtering, sorting, and pagination for large datasets so it stays fast. This happens automatically, and power users can tune the behavior under **Settings → "Advanced settings for large numbers of annotations."** See [Working with large annotation datasets](/documentation/analyzing-image-data-with-objects-connections-and-properties/large-annotation-datasets).

### Line scan intensity profiles

Draw a line across your image and see a live plot of raw pixel intensity along it, with one trace per channel — without creating any stored annotations. Choose freehand mode (drag) or segment mode (two clicks), and optionally restrict the plot to a single channel. Useful for inspecting signal profiles, comparing channels, and locating edges and peaks.

### Segment similar objects (experimental)

Mark a few example objects and automatically find similar ones across the current view. Pick examples with a SAM click, a SAM box, or a freehand circle, then propagate them using SAM-embedding similarity, an in-browser random-forest classifier, or a chained "SAM → Classifier" mode. Putative matches appear as outlines that you can accept in bulk. This tool is experimental and currently requires Google Chrome with WebGPU.

**Folder upload** — Upload an entire folder at once. Drag a folder onto the upload area (nested subfolders included) or click "Upload a folder" to pick one; all of its files are collected into the dataset.

**AI-suggested tools** — When you open a freshly created, empty collection, NimbusImage can suggest a starting set of analysis tools based on your image and its channel names (for example, Cellpose-SAM for nuclei or Piscis for spots). Accept the ones you want with a click.

**Improved 3D annotation rendering** — Segmentations in the 3D viewer now render as smooth, shaded surfaces lofted across Z-slices, points appear as spheres, and an opacity slider lets you see the volume data through the surfaces.

**Faster AI segmentation** — Segment Anything (SAM) model loading and image encoding are noticeably faster.

**Consistent workspace design** — The refreshed dataset-view design language now extends across the rest of the app.

**Searchable tool picker** — The tool selection dialog now has a search field that filters by name, description, or category, with tools grouped into "Drawing & interaction tools" and "Automated analysis."

**Storage usage and quota** — Your profile menu shows how much storage you've used against your quota, with a warning as you approach the limit. Operations that fail because of a full quota now say so, instead of appearing to stall.

**More annotation rendering controls** — On large datasets you can now set a minimum number of visible annotations in view, choose whether zooming in reveals more objects or holds a constant density, and reset all rendering settings to their defaults.

**Saved rendering and object-list settings** — Annotation rendering tuning, the property columns shown in the object list, and property filters are now saved with your dataset configuration instead of being lost on reload.

**Filter count badge** — The Filters button shows how many filters are currently active, so hidden objects are never a mystery.

**Unrolled frame labels** — Each cell in an unrolled grid is labeled (e.g. `XY 3`, `Z 2 · Time 7`), and clicking a label rolls the grid back up at that frame.

**Faster large-dataset interactions** — Visibility updates on datasets with hundreds of thousands of objects are substantially faster, the object list switches to server-side pagination sooner, and the minimap no longer re-renders on every frame while scrubbing sliders.

**Cellpose-SAM model update** — Cellpose-SAM now defaults to the newer cpsam\_v2 checkpoint, which produces fewer spurious masks in low-contrast regions. The original model remains selectable for reproducibility.

**Faster worker startup** — Analysis workers start noticeably faster, and opening a worker's settings no longer waits on model loading.

**Refined progress bars** — Progress bars have a lighter, restyled look and sit above the bottom-left button cluster instead of covering the Tools panel.

**AI agent waits for jobs** — When the AI panel starts a worker or a property computation, it now waits for the job to finish and continues the workflow with the result, instead of stalling or repeatedly re-checking.

#### Bug fixes

* Fixed a race condition that could cause the Segment Anything model to fail to initialize.
* Fixed JSON import failing when the file contained connections.
* Fixed filters from one dataset carrying over when you opened another.
* Fixed clicking an object in the image not highlighting its row in the object list on large datasets.
* Fixed the AI panel reporting a successful save when the change had actually been rejected.
* Fixed clicking an object in the Object Browser panning to the wrong tile when a dimension was unrolled.
* Fixed most connection lines going undrawn on large, lazily loaded datasets until you zoomed in.
* Fixed track colors that could render near-black or near-white, or that were nearly indistinguishable between neighboring tracks.

## June 2026

### 3D volume visualization

View your dataset as an interactive 3D volume, rendered directly in your browser. Toggle between the 2D and 3D views from the top app bar. Each channel is volume-rendered using its existing color and contrast, with a choice of Composite or Maximum Intensity Projection (MIP) blend modes. Polygon segmentations appear as 3D objects colored by tag or by a computed property, and you can map either Z or Time to the depth axis — turning a time lapse into a volume where moving objects trace out continuous paths ("worldlines"). Orientation aids include an XYZ gizmo and an optional scaled bounding box with tick labels. Large images are automatically downsampled to stay within memory and GPU limits.

**More robust Python API** — The `nimbusimage` Python package now retries transient server errors, offers a stable cursor for iterating annotations safely while deleting them, validates conflicting compute arguments, and reports clearer permission errors when a job's session has expired.

#### Bug fixes

* Fixed polygon and line annotation outlines not rendering on all Z-slices.
* Fixed downloaded snapshots using an incorrect scale bar size.
* Fixed snapshot ZIP downloads nesting files inside extra folders.
* Fixed stale snapshot selections persisting after the underlying data changed.
* Fixed a duplicate filename when downloading an image together with its annotations.
* Fixed segmentation runs failing to upload when a worker produced an empty or split outline — one bad shape no longer fails the entire batch.
* Fixed the StarDist worker crashing on startup.
* Fixed the line scan worker crashing on single-channel datasets when "All channels" was selected.

## May 2026

**"Mine only" dataset filter** — Filter the Recent Datasets list on the home page to show only datasets you own.

**Fine slider adjustment** — Hold Shift while dragging the XY, Z, or Time slider to scrub through values more precisely.

**Single-file bulk export** — Bulk JSON export now downloads all datasets together as one ZIP archive, requiring just a single save dialog.

**Collection navigator for import** — A streamlined navigator makes it easier to find and select a compatible collection when adding a dataset to an existing one.

**Move files in the file manager** — The Move action opens a location chooser again, letting you reorganize files and folders.

**Improved viewer responsiveness** — Reduced rendering overhead on the image canvas for smoother interactions.

**Modular dataset workspace** — The dataset view has been refreshed into a modular workspace: your image fills the screen as the focus, while the Navigator, Layers, Tools, and other panels become floating, translucent palettes you can toggle and rearrange. Worker tools now open in a dialog that keeps the image visible behind it.

**Stay logged in across reloads** — Reloading the page no longer returns you to the login screen; your session now persists reliably.

#### Bug fixes

* Fixed memory leaks when switching between datasets.
* Fixed checkboxes that could not be selected in some tool configuration panels.
* Fixed drag-and-drop uploads not working on the dataset drop zone.
* Fixed worker progress bar text being clipped.
* Fixed live notifications (such as job progress updates) stopping after a short period of inactivity.
* Fixed a crash when opening the log for a job that had no arguments.

## April 2026

### Publish projects to Zenodo

Archive an entire project—image files, annotations, and metadata—directly to Zenodo for a permanent, citable DOI, helping you meet data-sharing and archiving requirements. Configure a Zenodo API token, upload your project as a draft, review it on Zenodo, then publish to mint a DOI. You can upload new versions later while keeping a single citable identifier.

### Refreshed interface

NimbusImage has a refreshed look built on a new dark theme with layered surfaces and updated typography, along with a new light theme.

**Full-screen file browser** — Expand the Browse panel to fill the page, hiding the upload and recents panels so you can navigate large folder structures more easily. Your preference is remembered.

**Copy link button** — Copy a shareable link to a dataset or other resource with a single click.

#### Bug fixes

* Fixed a server error that could occur when importing certain datasets.
* Fixed recent datasets not refreshing on the home page after changes.
* Fixed multi-file uploads misreading filenames that don't use a separator between variables.

## March 2026

### Few-shot segmentation with SAM

Use a few example annotations to automatically find and segment similar objects across your image. Two model options are available: SAM1 (ViT-H) for higher quality results and SAM2 (Base+) for faster processing.

### Python API for programmatic access

Access NimbusImage from Python with the new `nimbusimage` package. Connect to a dataset and work with its images, annotations, connections, properties, and exports in code—useful for scripting custom analysis and automating workflows.

**TSV export support** — Export your annotation data as tab-separated values (TSV) in addition to CSV. A format toggle in the export dialog lets you switch between CSV and TSV. TSV is recommended when property names contain commas, and the dialog will warn you when this is the case.

**Increased batch dataset limit** — Automated annotation workers can now be applied to up to 50 datasets in a collection at once, up from 10.

**Side panels push content** — The object list, snapshots, and settings panels now push the image viewport to the side instead of overlaying it, so you can see your image and panel contents at the same time. Panels also stay open when interacting with the image.

**Bulk CSV export** — Export annotations for every dataset in a collection as CSV files in one step, alongside the existing bulk JSON export.

**Faster annotation rendering** — Performance improvements to annotation drawing, store operations, and drag-select make working with many objects more responsive.

**CondensateNet model versions** — Choose between CondensateNet model versions (including a new default) from a dropdown when running the condensate segmentation worker.

#### Bug fixes

* Fixed CSV export where selecting individual properties to export would check or uncheck all properties at once.
* Fixed comma handling in property names: property auto-naming now uses spaces instead of commas between tags, and property names containing commas are properly quoted in CSV exports.
* Fixed layer and annotation renaming showing "\[object Event]" instead of the typed name.
* Fixed worker tool settings being lost when closing and reopening the tool panel.
* Fixed the collection name label overlapping the input text on the dataset info page.
* Fixed tooltips on dataset info collection buttons rendering as a narrow vertical stripe.
* Fixed upload progress bar stuck at "0 B / 0 B".
* Fixed login form not appearing on the home page.
* Fixed an occasional race condition that could cause annotation data to load incorrectly.

## February 2026

### Circle and ellipse annotation tools

Draw circular and elliptical regions on your images. The circle tool inscribes a circle within your drag area, while the ellipse tool fills the full bounding box. Both are measured like other polygon-based objects.

### Combine annotations tool

Merge two polygon annotations into one by clicking them in sequence. Works with overlapping or nearby polygons, with a configurable tolerance for how close shapes need to be. Connections from the merged annotation are automatically preserved.

### Batch annotation computation

Apply automated annotation computations across all datasets in a collection at once. A progress bar tracks each dataset, and you can cancel the batch at any time.

### Project sharing

Share entire projects with other users and control their access level. When you share a project, permissions automatically propagate to all datasets, collections, and views within it. Making a project public also makes all its contents publicly accessible.

**Sharing status indicators** — See at a glance who has access to your datasets and configurations, with color-coded badges showing read, write, and admin access levels.

**SAM model options** — Choose between SAM1 (ViT-B), SAM2 Base+, and SAM2 Large for AI-assisted segmentation, giving you more control over speed vs. quality.

**MP4 movie export** — Export snapshot movies as MP4 in addition to WebM, with broader browser compatibility including Safari.

**Bulk collection export** — Export annotations for every dataset in a collection as individual JSON files with a single click.

**Upload dialog help** — An info button in the upload dialog explains what datasets, batch mode, and collections are.

**Dataset statistics** — The dataset info page now shows counts for annotations, connections, properties, and property values.

**Upload configuration redesign** — The multi-file dataset configuration view now uses a visual badge and slot layout, making it easier to see and assign variables to dimensions like XY, Z, Time, and Channel.

**Filename variable highlighting** — When uploading multi-file datasets, an interactive preview highlights which parts of your filenames correspond to which dimensions, with color-coded segments and a legend.

**Improved annotation defaults** — Annotations now maintain a consistent size regardless of zoom level and use a smaller, less obtrusive marker size by default.

**Large dataset exports** — CSV and JSON exports now handle large datasets (tens of thousands of annotations) without browser memory issues.

**CondensateNet large image support** — The CondensateNet segmentation worker can now process large images by automatically tiling them, stitching objects across tile boundaries.

#### Bug fixes

* Fixed CondensateNet segmentation failing on images with non-standard dimensions.

## January 2026

### Projects

Group your datasets and collections into projects for publications. Add metadata like authors, license, DOI, and keywords to prepare your data for sharing and citation.

### Batch dataset upload

Upload multiple files at once, creating one dataset per file within a collection. Supports both quick and advanced import modes, with shared dimension configuration across all datasets.

### Public dataset sharing

Make any dataset publicly accessible via a link — no account required to view.

### Redesigned sharing dialog

Manage who has access to your datasets in real time. See current users, change permission levels, add or remove access, and toggle public visibility from one unified dialog.

### Redesigned tool selection

The tool creation dialog now groups tools by category with color-coded sections, descriptions for each tool, and a featured tools section at the top.

### Deconwolf deconvolution

Deconvolve 3D fluorescence microscopy Z-stacks using the Richardson-Lucy algorithm. Supports GPU acceleration for faster processing, with automatic CPU fallback. Optical parameters can be auto-extracted from ND2 metadata, and large images are automatically tiled to fit in memory.

**Piscis PyTorch update** — The Piscis spot detection workers have been updated to the official v1.0.0 release with a PyTorch backend. The default detection threshold is now 0.5 (previously 1.0) for improved sensitivity.

**Dimension slider step arrows** — Use up/down arrow buttons next to XY, Z, and Time sliders to step through values one at a time.

#### Bug fixes

* Fixed login requiring a double click.

## December 2025

### CondensateNet automated condensate segmentation

Automatically detect and segment biomolecular condensates in fluorescence microscopy images using the CondensateNet deep learning model.

**Improved upload dialog** — The upload dialog now includes a name picker and location picker, with duplicate name checking.

**Text or number labels** — Toggle between showing descriptive text labels (e.g., "Well A1") or numeric labels in the viewer settings.

**Smarter folder defaults** — When adding a dataset to an existing collection, the file browser now defaults to the dataset's current folder instead of your private folder.

## November 2025

### Refreshed home page

The home page now has a single unified upload button, a tabbed interface for recent and sample datasets, updated guided tours, and improved dark mode support.

#### Bug fixes

* Fixed the unroll checkbox disappearing when selected.


# Vignettes

Here are a few examples of common use cases for NimbusImage to give you a sense of how to use it.

## Uploading and navigating datasets

{% embed url="<https://www.loom.com/share/5ee1665068194cf4aa136aeade16ee63?sid=01b98d6a-8f84-43b7-828d-bc8a2acd78d6>" %}

## Circling cells using manual tools

{% embed url="<https://www.loom.com/share/eeeb01efcf084be1b1e6eb3717886291?sid=6843c035-cafd-47d5-8179-96bcbbca7832>" %}

## Finding nuclei automatically using cellpose

{% embed url="<https://www.loom.com/share/f6bbba2dc579469c90217f38c843dc95?sid=7ca76e71-f6c3-42ca-b573-d0f30952a9c1>" %}

## Quantify fluorescence intensity

{% embed url="<https://www.loom.com/share/dce3dd0da05746628ac13d640e1b5dcd?sid=b3df3fec-d98f-4403-afb4-f06d893ecb99>" %}

## Segment Anything Model (SAM) for quickly picking out objects

{% embed url="<https://www.loom.com/share/b308324229c04ec0ac8f0d4dc4d18fb1?sid=4e397936-a77a-44d9-85d9-73f38c6ed2db>" %}

## Finding spots automatically using Piscis

{% embed url="<https://www.loom.com/share/49d795f30a3844ef908c3aaddf858098?sid=b223ff71-676d-43ed-86b8-dcc2e0e5285b>" %}

## Counting the number of spots per cell

{% embed url="<https://www.loom.com/share/c8c55bcedbc942b7be3bd1ae816bdefa?sid=a26123e5-5c13-462a-ac44-a4520d0428e6>" %}

## Fixing and interacting with your data

{% embed url="<https://www.loom.com/share/5cda2fadb8da400f90a7f8651cee3512?sid=ed4331c5-37f3-4a2b-8382-c05c3b5ef7f6>" %}


# Installation

How to install NimbusImage

If you really want to install NimbusImage yourself, you can :). Before getting into the details of installation, it's important to understand the structure of NimbusImage. The front end and back end are two completely independent components. The web application lives on the front end, while all your data and analyses reside in the back end. You can mix and match almost any front end with any back end. For example, you could use nimbusimage.com for the front end and run the back end on your local laptop or vice versa. We here provide instructions for installing both, but again, the easiest option is to simply use the online version.

A good halfway point (if you must) is to use the front end provided by nimbusimage.com along with your own back end. That way, your data lives on your own computer, in case that is important to you.

## Installing the back end

The back end is a data management system called [Girder](https://girder.readthedocs.io/en/latest/), which is developed by Kitware. You can install it fairly easily using Docker. Keep in mind that Docker on Mac is really slow for various reasons, so we strongly recommend using Linux. Also, some workers that require GPUs, like cellpose for cell segmentation, need a Linux system with a GPU.

To install the backend, first you need to install Docker.

**Linux:**

1. **I**nstall using the apt-repository. Follow [these instructions](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository). Then follow these [post-install instructions](https://docs.docker.com/engine/install/linux-postinstall/).
2. If you want to use GPU workers, you will need to [install CUDA](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html). Make sure your GPU driver is installed (probably need 535 or higher).
3. Then install the Nvidia [Docker toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).
4. Wasn't that easy? I hate Linux. Also, you will probably have to restart your computer at least once by now.

**Mac:**

1. Install using the [Docker app](https://docs.docker.com/desktop/install/mac-install/).

**Now install the backend using Docker:**

* Pull the NimbusImage repository:

```sh
git clone https://github.com/arjunrajlaboratory/NimbusImage.git
cd NimbusImage/
```

* Start docker images for the backend:

```sh
docker compose build
docker compose up -d
```

You should now be able to see the backend at [http://localhost:8080](https://localhost:8080). You can login with login "admin" and password "password". **We strongly recommend changing those defaults ASAP!**

## Installing the workers

Go to a **new directory** (NOT the `NimbusImage` directory) and run the following:

```sh
git clone https://github.com/arjunrajlab/ImageAnalysisProject
cd ImageAnalysisProject/
chmod +x build_machine_learning_workers.sh
chmod +x build_workers.sh
./build_machine_learning_workers.sh
./build_workers.sh
```

The machine learning workers will run on CPU on Linux if a GPU is not available, although will run much more slowly.

## Installing the front end

To install the frontend, you need to:

1. Install [node.js](https://nodejs.org/en/download/package-manager/current).
2. Install [pnpm](https://pnpm.io/installation):

   ```sh
   npm i -g pnpm
   ```
3. Pull the repository (if you haven't already done so for the backend):

   ```sh
   git clone https://github.com/arjunrajlaboratory/NimbusImage.git
   cd NimbusImage/
   ```
4. Install node modules:

   ```sh
   pnpm install
   ```
5. Compile C++ code to wasm:

   ```sh
   pnpm emscripten-build
   ```
6. If you are on Linux, you may need to run:

   ```sh
   cat /proc/sys/fs/inotify/max_user_watches
   sudo sysctl fs.inotify.max_user_watches=1000000
   sudo sysctl -p
   ```
7. Copy in the models for Segment Anything (optional):

   ```sh
   mkdir -p public/onnx-models/sam/vit_b
   cd public/onnx-models/sam/vit_b
   wget "https://huggingface.co/rajlab/sam_vit_b/resolve/main/decoder.onnx" -O decoder.onnx
   wget "https://huggingface.co/rajlab/sam_vit_b/resolve/main/encoder.onnx" -O encoder.onnx
   cd ../../../.. # Go back to the NimbusImage root directory
   ```
8. Now start up the server:
   1. If you want to run the development build:

      ```sh
      pnpm run dev
      ```

      You should see output indicating the server is running, likely on `http://localhost:5173`.
   2. If you want to run for production:

      ```sh
      pnpm build
      pnpm run serve
      ```

      You should see output indicating the server is running, likely on `http://localhost:4173`.
9. Go to the relevant localhost URL (`http://localhost:5173` for dev, `http://localhost:4173` for prod) and you should see the website!

## Sign in (if you are running your own server)

IMPORTANT: By default, an admin user will be created with the login `admin` and the password `password`. You can use these credentials to initially log into the system.

1. Navigate to your running NimbusImage frontend (e.g., `http://localhost:5173`).
2. **In the "Girder domain" field, enter the domain associated with your backend.** If running locally, this will be `http://localhost:8080`.
3. **Enter the username (`admin`) and password (`password`).**
4. **For security, it is critical to add a new admin user in Girder and then remove the original `admin` user.** To do this, go to `http://localhost:8080`, sign into Girder using the default credentials, then go to the `Users` tab on the left to manage users.

<figure><img src="/files/NFlrqrP5wz5jrWIsimIo" alt="" width="365"><figcaption><p>Make sure to set the Girder domain to your backend server, e.g., http://localhost:8080</p></figcaption></figure>


# Citations

NimbusImage depends on countless contributions from scientists and engineers around the world. If you use NimbusImage, we recommend you cite the NimbusImage paper as well as the relevant papers for the underlying tools to recognize these efforts.

## NimbusImage

If you use NimbusImage, please cite:

Niu, Z., Bruyère, T., Manthey, D., Li, J., O'Farrell, A., & Raj, A. (2026). [NimbusImage: a cloud-computing platform for image analysis.](https://doi.org/10.1038/s41592-025-02942-6) *Nature Methods, 23*(1), 6-8. PMID: 41266644.

## How to acknowledge NimbusImage and related software

We recommend including text along the following lines in your papers:

> We analyzed our image datasets using the NimbusImage platform (1), which is available here:\
> <https://github.com/arjunrajlaboratory/NimbusImage/>\
> and hosted here:
>
> <https://www.nimbusimage.com/>
>
> We used the Cellpose and Cellpose retrain tools (2-5) to detect cells and the Piscis and Piscis retrain tools (6) to detect mRNA spots. We connected each mRNA spot to the nearest cell using the "Connect to nearest tool" as described in the NimbusImage documentation.

## Citations

### Cellpose

Cellpose works like magic for cell segmentation and is the product of extensive research and development by Carsen Stringer. They have a series of three papers on the topic, and we generally recommending citing all three. The first one describes the Cellpose algorithm, the second introduces retraining, and the third introduces image restoration and new, highly accurate models. The fourth paper is a preprint for Cellpose-SAM, which combines Cellpose with the Segment Anything Model (SAM) to enable versatile cell segmentation.

Here is the GitHub repository:\
<https://github.com/MouseLand/cellpose>

Here are the papers:\
\
1\. Stringer, C., Wang, T., Michaelos, M., & Pachitariu, M. (2021). [Cellpose: a generalist algorithm for cellular segmentation.](https://www.nature.com/articles/s41592-020-01018-x) *Nature methods, 18*(1), 100-106.\
\
2\. Pachitariu, M. & Stringer, C. (2022). [Cellpose 2.0: how to train your own model.](https://www.nature.com/articles/s41592-022-01663-4) *Nature methods*, 1-8.\
\
3\. Stringer, C. & Pachitariu, M. (2025). [Cellpose3: one-click image restoration for improved segmentation.](https://www.nature.com/articles/s41592-025-02595-5) *Nature Methods*.\
\
4\. Pachitariu, M., Rariden, M., & Stringer, C. (2025). [Cellpose-SAM: superhuman generalization for cellular segmentation.](https://doi.org/10.1101/2025.04.28.651001) *bioRxiv* 2025.04.28.651001.

### StarDist

StarDist is a powerful tool for cell and nuclei detection that uses star-convex polygons to accurately segment objects in microscopy images. It is particularly effective for nuclear segmentation and can work in both 2D and 3D.

Here is the GitHub repository:\
<https://github.com/stardist/stardist>

Here are the papers:

1\. Schmidt, U., Weigert, M., Broaddus, C., & Myers, G. (2018). [Cell Detection with Star-Convex Polygons.](https://doi.org/10.1007/978-3-030-00934-2_30) *Medical Image Computing and Computer Assisted Intervention (MICCAI)*, 265-273.

2\. Weigert, M., Schmidt, U., Haase, R., Sugawara, K., & Myers, G. (2020). [Star-convex Polyhedra for 3D Object Detection and Segmentation in Microscopy.](https://doi.org/10.1109/WACV45572.2020.9093435) *The IEEE Winter Conference on Applications of Computer Vision (WACV)*.

3\. Weigert, M., & Schmidt, U. (2022). [Nuclei Instance Segmentation and Classification in Histopathology Images with Stardist.](https://doi.org/10.1109/ISBIC56247.2022.9854534) *The IEEE International Symposium on Biomedical Imaging Challenges (ISBIC)*.

### Segment Anything Model (SAM)

The Segment Anything Model (SAM) is a revolutionary promptable segmentation tool developed by Meta Research that can segment almost any object in an image based on simple prompts like points or boxes. NimbusImage incorporates SAM to enable rapid semi-automated segmentation with minimal user input.

Here is the GitHub repository:\
<https://github.com/facebookresearch/segment-anything>

Here is the paper:

Kirillov, A., Mintun, E., Ravi, N., Mao, H., Rolland, C., Gustafson, L., Xiao, T., Whitehead, S., Berg, A.C., Lo, W\.Y., Dollár, P., & Girshick, R. (2023). [Segment Anything.](https://arxiv.org/abs/2304.02643) *arXiv:2304.02643*.

### Piscis

Piscis is a specialized deep learning algorithm developed by Will Niu while in the Raj Lab. It is designed specifically for detecting diffraction-limited spots in fluorescence microscopy images, such as single RNA molecules in FISH experiments. It uses a novel loss function, the SmoothF1 loss, that directly penalizes false positives and false negatives while remaining differentiable for deep learning training.

Here is the GitHub repository:\
<https://github.com/zjniu/Piscis>

Here is the paper:

Niu, Z., O'Farrell, A., Li, J., Reffsin, S., Jain, N., Dardani, I., Goyal, Y., & Raj, A. (2025). [Piscis: A loss estimator of the F1 score enables accurate spot detection in fluorescence microscopy images via deep learning.](https://doi.org/10.1016/j.cels.2025.101448) *Cell Systems, 16*(11), 101448. PMID: 41265398.

### CondensateNet

CondensateNet is a deep learning model developed by the Raj Lab for segmenting biomolecular condensates in brightfield microscopy images. It uses a Feature Pyramid Network (FPN) architecture with an EfficientNet encoder to detect and segment condensates.

Here is the GitHub repository: <https://github.com/arjunrajlaboratory/condensatenet>

Raj Lab. (2024). CondensateNet: Deep Learning for Biomolecular Condensate Segmentation. GitHub. <https://github.com/arjunrajlaboratory/condensatenet>

### Deconwolf

Deconwolf is an open-source 3D deconvolution engine that uses the Richardson-Lucy algorithm with a theoretically generated Born-Wolf point spread function (PSF) to sharpen fluorescence microscopy images. NimbusImage uses deconwolf to provide GPU-accelerated deconvolution of Z-stacks directly within the platform.

Here is the GitHub repository: <https://github.com/elgw/deconwolf>

Here is the paper:

Wernersson, E., Gelali, E., Girelli, G., et al. (2024). [Deconwolf enables high-performance deconvolution of widefield fluorescence microscopy images.](https://doi.org/10.1038/s41592-024-02294-7) *Nature Methods, 21*, 1245–1256.

## Packages

### Girder

Girder is a free and open source web-based data management platform developed by Kitware. It provides a flexible framework for storing, managing, and sharing various types of data, including large scientific and medical images.

Here is the GitHub repository:\
<https://github.com/girder/girder>

### Large Image

Large Image is a collection of Python modules developed and maintained by the Data & Analytics group at Kitware for processing large geospatial and medical images. It provides capabilities for tile serving, support for a wide variety of image formats, and efficient methods for accessing regions of large images.

Here is the GitHub repository:\
<https://github.com/girder/large_image>

### GeoJS

GeoJS is a JavaScript library for visualizing geospatial data in a browser, developed by Kitware and OpenGeoscience. It aims to bridge the gap between GIS, scientific visualization, and information visualization, providing high-performance visualization and interactive data exploration of scientific and geospatial location-aware datasets.

Here is the GitHub repository:\
<https://github.com/OpenGeoscience/geojs>

### VTK.js

VTK.js is an open-source JavaScript library for scientific visualization in the browser, developed by Kitware. NimbusImage uses VTK.js to power its interactive 3D volume visualization, rendering multi-channel volumes and 3D segmentations directly in the browser.

Here is the GitHub repository:\
<https://github.com/Kitware/vtk-js>

### DeepTile

DeepTile is a large image tiling and stitching library developed by the Arjun Raj Laboratory. It provides a standardized workflow for splitting large images into tiles of a specified size, processing tiles using regular Python functions, and stitching the processed tiles. DeepTile is especially useful for scaling Python functions and deep learning algorithms to arbitrarily large input image sizes.

Here is the GitHub repository:\
<https://github.com/arjunrajlaboratory/DeepTile>


# Images, datasets, and collections

Imaging data in NimbusImage is organized into *datasets,* *collections*, and *projects.*

<div align="left"><figure><img src="/files/po3p9nJBvRjAhTUwSNCe" alt=""><figcaption></figcaption></figure></div>

## Datasets

A *dataset* is the set of images that you want to visualize and analyze at once. Examples could include:

1. A simple image.
2. A very large image.
3. A Nikon .nd2 file containing a Z-stack for 3 fluorescence channels.
4. A Nikon .nd2 file containing 15 positions of Z-stacks for 3 fluorescence channels.
5. Large images in 4 channels from a 12 well plate stored across multiple TIFF files.
6. Time lapse image data across a set of files.

A dataset can be from a single file (such as a multidimensional .nd2 file) or could be spread across multiple files. The dataset will also store all objects and snapshots that you make as you analyze your data. To learn more about file formats, see [File formats](https://github.com/arjunrajlaboratory/NimbusImageGitBook/blob/main/documentation/documentation/file-formats.md).

{% hint style="info" %}
Datasets are stored on the server as a folder that contains (often multiple) files.
{% endhint %}

## Collections

A *collection* is a set of datasets that you want to group together for visualization and analysis. For instance, if you collected data from, say, a number of experimental conditions over multiple days, then you may want to group those datasets for each experimental condition into a collection.

The advantage of organizing datasets into a collection is that the user interface is common across all datasets in the collection. Let's say you set up just the right set of contrast settings, colors, and tools for one dataset and now you want to use those same settings for another dataset. In a collection, those settings will apply across *all* datasets, simplifying that process.

In order to form a collection, the datasets must be *compatible* in the sense that the datasets have a similar structure. For instance, if one dataset is a time lapse with 2 fluorescence channels and the other is a Z-stack with 3 channels, then they will not be compatible. However, they don't have to have the exact same size. For instance, say you took 15 timepoints for your time lapse recording in condition 1, but 20 timepoints for condition 2. Those are still compatible as a collection.

{% hint style="info" %}
**Every dataset belongs to a collection.** If you never use collections, that is totally fine, but just be aware that somewhere in there, there is a collection that contains your dataset.
{% endhint %}

{% hint style="info" %}
**A dataset can belong to multiple collections.** Each collection can provide a different view of the same dataset, because it could have different visualization settings and annotation tools. *However, note that objects are associated with the dataset itself and not the collection.*
{% endhint %}

## Projects

A *project* is a way to group datasets and collections together for coordinated management and sharing. Projects are particularly useful for organizing data associated with a publication or a complete study.

Key features of projects:

* Group multiple datasets and collections into a single organizational unit
* Add publication metadata including title, description, license, keywords, authors, and DOI
* Publish an entire project—image files, annotations, and metadata—directly to [Zenodo](/documentation/images-datasets-and-collections/publishing-to-zenodo) for permanent archiving with a citable DOI
* Track project status (draft, exporting, exported)

Projects exist as organizational containers that reference your datasets and collections—the underlying data stays where it is, but projects give you a unified way to manage and eventually share a complete body of work.

When you're ready to archive and share a project, see [Publishing to Zenodo](/documentation/images-datasets-and-collections/publishing-to-zenodo).

## Uploading a dataset

There are two ways to upload a dataset.

**Quick Import:** Just drop in your data on the home page and NimbusImage will automatically parse your data, pick some default options, and bring you to the viewer! Note that behind the scenes, NimbusImage makes a collection for your dataset.

**Advanced Import:** For more control over how your image files are parsed into datasets and organized into collections, use Advanced Upload.

### Uploading multiple files at once

NimbusImage supports batch uploading, which allows you to upload multiple files at once and create a collection containing one dataset per file. This is useful when you have many separate image files that you want to organize together.

* **Quick Import:** Drop multiple files at once, and each file will become its own dataset, all organized into a single collection with default settings.
* **Advanced Import:** Upload multiple files and configure them as a batch. You set the dimension configuration (variables, compositing, etc.) once on the first dataset, and NimbusImage applies those same settings to all subsequent datasets in the batch. This saves time when you have many files with the same structure.

First, upload files, name the dataset, and choose the location for the dataset files to be stored.

**Variable assignment:** The next step in advanced upload is variable assignment: when you have a Z-stack and stage positions and timepoints, each of those is a variable that NimbusImage will let you navigate. Some files, such as .nd2 files or TIFF files with sufficient specification, contain a lot of metadata and the variable assignment is already done. However, it is quite common for data to be stored across multiple files, with the variable encoded in the filename. For instance:

```
GFP_s001_t001.tif
GFP_s001_t002.tif
...
RFP_s003_t010.tif
```

In the above, there could be two channel variables (GFP, RFP), 3 stage positions, and 10 timepoints. **NimbusImage will automatically attempt to read these filename variables and assign them.** In the above, it will assign the variable with "s" to XY position and "t" to time and GFP/RFP to channel. Moreover, sometimes the .tif file itself will have multiple images in it. In that case, that series of images can also be assigned to a variable. **NimbusImage will let you change the variable assignment**, giving you complete flexibility over how all these variables are parsed.

**Compositing:** Sometimes, you want stage position to be a variable you can flip through, like different wells in an image. By default, those will be parsed as different XY positions that can be scrolled through as a variable. However, sometimes you might have images that tile a large field of view, or perhaps you want to visualize all the wells next to each other. In that case, check "Composite", which will put all the data into a single large image using the metadata about the location of the different stage positions.

**Transcoding into optimized TIFF:** In order to facilitate the ability to navigate large images with high performance, it is important to have a well-optimized file format. We have found that many microscopy formats are unfortunately very inefficient. Hence, we give the option to transcode all the data into a single, well-optimized TIFF file. This transcoding takes some compute time, but results in much better performance in most scenarios, hence it is enabled by default. Some formats, like .nd2, are well optimized from the outset, and so transcoding is not enabled by default for those files.

**Assigning to a collection:** In the next screen, you can decide how you want to organize your dataset into a collection. The default is to create a new collection. However, you can also choose to add it to an existing collection or make a new collection derived from an existing collection. The latter option makes a copy of an existing collection and puts your file in this copied collection. That is useful if you want to, say, copy over existing viewer settings, but you want to organize this dataset separately.


# File formats

Files you can import to NimbusImage.

NimbusImage can read most file formats "out of the box", so mostly you will not have to worry about it. Here, we describe a few considerations for some common formats here. Also, **please do let us know if you are having trouble importing your data.** We have tried to make it as easy and compatible as possible, but there are a quasi-infinite number of formats, so we are sure there are many cases we have not yet encountered.

## Nikon (.nd2)

Nikon .nd2 files work essentially out of the box. You can just import them, and the variable assignment should work, and you generally will not need to enable "Transcode to optimized TIFF". If you have a large tiled image, it would be best to stitch the image in Nikon Elements first, if possible. If, however, that is not an option because the file is too large, you can enable "Composite stage positions" and "Transcode to optimized TIFF" and that should be able to do the stitching for you (although that has not been as extensively tested on our end).

## Zeiss (.czi)

Zeiss .czi files work out of the box as well. The only difference is that we have found that performance is better when these files are transcoded inot a TIFF, so by default "Transcode to optimized TIFF" is enabled.

## Leica (.lif)

Leica .lif files are somewhat more complex, because they are more like containers that can contain multiple image sets. For instance, a .lif file could contain a time lapse, a set of Z-stacks, and a few individual multi-channel images. NimbusImage does not currently import multiple datasets at once. Hence, **for .lif files, we select the largest image set and import that one.** We recommend breaking up your .lif file accordingly so that the outcome is predictable. If enough users ask for the feature, we may enable the ability to choose amongst the image sets or allow for multiple imports.

## TIFF and OME-TIFF

Ah yes, TIFF… So TIFF can be imported, and if the variables are set within the TIFF, they will be read.

{% hint style="info" %}
By default, "Transcode into optimized TIFF" is enabled because, in our experience, most TIFF files are not well optimized. Certainly, if you have multiple TIFF files, we would strongly recommend transcoding them. Only disable this option if you know for sure that the TIFF is optimized (for an example, see below).
{% endhint %}

Most TIFFs work fine, but there is an issue with OME-TIFFs that are spread across multiple files. An OME-TIFF can sometimes have a single file that points to multiple files in a series. This sort of file is not yet supported out of the box, in that you cannot upload all the files and import them directly. However, you can convert this into a single tiff file pretty easily and then import it. Do the following:

```
pip install large_image # installs the large_image package
large_image_converter first_file_in_series.ome.tiff outputfile.tiff
```

This will generate `outputfile.tiff` that then can be directly imported into NimbusImage. **In this case, you do NOT need to transcode into an optimized TIFF**, because `large_image_converter` has already done that for you.

## TIFFs from IncuCyte

The IncuCyte outputs files in a VERY annoying way. They can be directly read into NimbusImage, and it will do its best to handle the naming conventions, but it can be irritating because if you have multi-channel images, it exports them all with the *exact same file names*. Ugh. Anyway, we wrote a little script you can use to clean up the IncuCyte TIFFs and rename them:

<https://github.com/arjunrajlaboratory/process_incucyte_tiff_data>

{% hint style="info" %}
Follow the directory structure very carefully. Also, if you just have a single channel, you still have to have a "phase" subdirectory in which all your files will live.
{% endhint %}


# Managing files

## Overview

NimbusImage provides a powerful file management system that helps you organize your datasets, collections, and other files. The interface is designed to be intuitive while giving you full control over your data organization.

<figure><img src="/files/SzAdMZeU6VFCsu2Usqh7" alt=""><figcaption></figcaption></figure>

## The landing screen

When you first log in, you'll see the main landing screen with several key sections:

1. **Upload dataset** - Options to add new data to NimbusImage
2. **Recent datasets** - Shows your recently accessed datasets
3. **File navigator** - Browse your folders and files
4. **Action buttons** - Create folders, upload files, and more

{% hint style="info" %}
The file navigator shows your current location. Any datasets you upload will be placed in this current location unless specified otherwise.
{% endhint %}

## Uploading datasets

NimbusImage provides a unified "Create Dataset" dialog that offers both quick and advanced upload options. Before uploading, you'll need to specify where to store your dataset (Private, Public, or Team folder).

### Quick Upload

The Quick Upload option lets you:

* Simply drag and drop files directly
* Use default options for processing
* Go straight to the image viewer
* Have a collection automatically created with the same name

This is perfect for getting started quickly with minimal configuration.

### Advanced Upload

If you need more control over how your data is organized and processed, use Advanced Upload to:

* Customize variable assignments
* Configure tiling and compositing options
* Specify collection placement
* Adjust transcoding settings

<figure><img src="/files/Zv4pBzQNj5rlTxs9pKyz" alt=""><figcaption><p>The Advanced Import screen, where you can review the selected files, name the dataset, choose a location, and add more files or a whole folder before importing</p></figcaption></figure>

### Uploading a folder

You can upload an entire folder at once instead of selecting files individually:

* **Drag and drop a folder** onto the upload area. Every file inside is collected, including files in nested subfolders.
* **Click "Upload a folder"** (or "Select a folder instead") to open a folder picker.

All of the folder's files are flattened into the dataset — the subfolder structure itself isn't preserved — which matches how NimbusImage builds a multi-file dataset. Files are added in natural, numeric-aware name order, so image sequences like `frame1`, `frame2`, … `frame10` are ordered correctly.

## File organization

### Storage locations

NimbusImage provides specific locations for storing your datasets and files:

* **Private folder**: Only accessible to you
* **Public folder**: Accessible to everyone using the system
* **Team folder**: (NimbusImage.com specific) Shared only with members of your team

<div align="left"><figure><img src="/files/x8f1qw7IW60e1aPIsB3Q" alt="" width="260"><figcaption><p>Private and public folders</p></figcaption></figure></div>

{% hint style="info" %}
By default, Quick Upload will place your dataset in your Private folder. This ensures your data remains private until you choose to share it.
{% endhint %}

### Creating folders

To organize your datasets, you can create folders within these storage locations:

1. Navigate to where you want to create the folder
2. Click the "NEW FOLDER" button in the top right
3. Name your folder and click "Create"

## File operations

### Basic file actions

You can perform several operations on your files and datasets:

<div align="left"><figure><img src="/files/jCGk3gDJC67DgeJTBjIj" alt="" width="335"><figcaption><p>Actions on files and datasets</p></figcaption></figure></div>

* **Move**: Relocate files to a different folder
* **Delete**: Remove files or datasets
* **Rename**: Change the name of a file or dataset
* **Browse**: For datasets, view the internal files (use with caution)

### Working with multiple files

<figure><img src="/files/qAOiixwdl9ydQdi2QUjA" alt=""><figcaption></figcaption></figure>

To operate on multiple files at once:

1. Select the checkboxes next to the files
2. Click "ACTIONS"
3. Choose the operation you want to perform

### Individual file options

Each file or dataset has its own options menu (three dots) with specific actions:

* For regular files: Download, Move, Delete, etc.
* For datasets: Browse internal files (caution: these files are system files that generally should not be modified)

{% hint style="warning" %}
Dataset folders contain system files that NimbusImage uses to render and analyze your data. It's best not to directly modify these files unless you know exactly what you're doing.
{% endhint %}

## Sharing datasets and collections

NimbusImage provides flexible sharing options that allow you to share datasets and collections with specific users or make them publicly accessible to anyone.

### How to share with specific users

To share a dataset or collection with specific users:

1. Click the sharing icon next to the dataset or collection you want to share
2. Enter the email address of the recipient's NimbusImage account
3. Choose the access level (Read or Edit)
4. Click to confirm sharing

The sharing dialog shows a real-time table of all users who currently have access, their permission levels, and allows you to modify or remove access as needed.

### Access levels

When sharing, you can grant two types of access:

* **Read access**: The recipient can view the dataset and any annotations, but cannot make changes
* **Edit access**: The recipient can view and modify annotations and analysis

{% hint style="info" %}
Dataset owners always retain full access and cannot be removed from the access list.
{% endhint %}

### Making a dataset public

You can make a dataset publicly accessible so that **anyone with the link can view it, even without a NimbusImage account**. This is useful for sharing data with collaborators who don't have accounts, for publications, or for sharing with the broader community.

To make a dataset public:

1. **Open the dataset** in the viewer
2. **Click the Share button** (the `<` icon next to the dataset name) to open the Share Dataset dialog

<div align="left"><figure><img src="/files/aQf5OTSMjxzezVkvJEfh" alt="" width="350"><figcaption><p>The Share button next to the dataset name</p></figcaption></figure></div>

3. **Check the "Make Public" checkbox** — labeled "Make Public (read-only access for everyone)"

<div align="left"><figure><img src="/files/S4w6rtGtKHGtZqhhlXjV" alt="" width="500"><figcaption><p>The Share Dataset dialog with the Make Public option</p></figcaption></figure></div>

4. **Copy the URL** from your browser's address bar — this is the shareable link

To share the dataset, simply send this URL to anyone. When they open it, they will be able to view the dataset directly in the NimbusImage viewer without needing to log in or create an account.

{% hint style="info" %}
The shareable link is the same URL you see when viewing the dataset (the datasetView route). There is no separate "share link" to generate — just copy the URL from your browser and send it.
{% endhint %}

#### What public viewers can see and do

Public viewers have **read-only access** to the dataset. They can:

* View the image data, navigate through Z-stacks, positions, and channels
* See any existing annotations (objects, connections, and properties)
* View snapshots

Public viewers **cannot** modify annotations, run analysis tools, or change any settings. Only users you have explicitly granted Edit access can make changes.

{% hint style="warning" %}
Making a dataset public means anyone with the link can view it. You can revoke public access at any time by unchecking "Make Public" in the sharing dialog.
{% endhint %}

### Important considerations

{% hint style="warning" %}
To share a dataset, you must also share its parent collection so the recipient can view it properly. Without sharing the parent collection, the recipient won't be able to access the shared dataset.
{% endhint %}

### What happens when you share

Once you share a dataset or collection:

* The shared content automatically appears in the recipient's file navigator
* Any collaborative changes remain visible across all authorized users
* You can revoke access at any time through the sharing settings
* For public datasets, anyone with the link can view the data immediately

{% hint style="info" %}
Sharing is a powerful way to collaborate on analysis while maintaining control over who can access and modify your data.
{% endhint %}

## Team collaboration (NimbusImage.com only)

If you're using NimbusImage.com and are part of a team, you can access team-specific storage:

1. Navigate to the top level (globe icon)
2. Click the "Collections" icon
3. Select your team name
4. Upload or create datasets in this location to share only with team members

<div align="left"><figure><img src="/files/9Cadm1AOaqmexN1rY8PQ" alt="" width="282"><figcaption><p>Selected items actions menu</p></figcaption></figure></div>

<div align="left"><figure><img src="/files/jCGk3gDJC67DgeJTBjIj" alt="" width="128"><figcaption><p>File action menu</p></figcaption></figure></div>

{% hint style="info" %}
Team folders provide a convenient way to collaborate on datasets while keeping them separate from your personal files and fully public content.
{% endhint %}

## Best practices for file management

* **Use meaningful names** for your datasets and collections
* **Create folders** to organize related datasets
* **Keep the file structure simple** to make navigation easier
* **Use private folders** for work in progress
* **Move to team folders** when ready to collaborate

By effectively using NimbusImage's file management system, you can keep your datasets organized and easily accessible for analysis and collaboration.


# Publishing to Zenodo

Archive an entire project—image files, annotations, and metadata—to Zenodo with a permanent DOI to satisfy data sharing and archiving requirements.

[Zenodo](https://zenodo.org/) is a free, open repository operated by CERN for archiving research data and minting permanent [DOIs](https://en.wikipedia.org/wiki/Digital_object_identifier). NimbusImage can upload an entire [project](/documentation/images-datasets-and-collections#projects)—the original image files, all of your annotations, and the project metadata—directly to Zenodo. This gives you a single, citable, permanently archived record of your imaging data so that you can comply with the data sharing and archiving policies required by journals and funding agencies.

Because NimbusImage uploads everything (raw images plus the analysis you layered on top), the Zenodo record is a complete, reproducible snapshot of your work rather than just a folder of files.

{% hint style="info" %}
Publishing to Zenodo is a **project-level** feature. Before you can publish, you'll need to gather your datasets and collections into a project and fill in its publication metadata. See [Projects](/documentation/images-datasets-and-collections#projects).
{% endhint %}

## What gets uploaded

When you upload a project, NimbusImage assembles a Zenodo deposition containing:

* **The original image files** for every dataset, in their original format (OME-TIFF, `.nd2`, etc.)
* **Annotation data** for each dataset, exported as JSON (the same format produced by [Importing and exporting objects and properties](/documentation/analyzing-image-data-with-objects-connections-and-properties/importing-and-exporting-objects-and-properties))
* **Collection configurations**, so the viewer and analysis setup can be reconstructed
* **A manifest** describing the structure and metadata of the whole project

## Step 1: Create a Zenodo API token

NimbusImage uploads on your behalf using a personal access token from your Zenodo account.

1. Log in to [Zenodo](https://zenodo.org/) (or [Zenodo Sandbox](https://sandbox.zenodo.org/) if you are testing—see the hint below).
2. Go to **Applications** in your account settings, and under **Personal access tokens** click **+ New Token**.
3. Give the token a name (for example, *NimbusImage*).
4. Grant the scopes `deposit:write`, `deposit:actions`, and `user:email` (or simply select **all**).
5. Click **Create**, then copy the token. **Zenodo only shows the token once**, so save a copy somewhere safe.

## Step 2: Configure the token in NimbusImage

1. Open your project and find the **Zenodo Publication** card on the project page.
2. Click **Configure Zenodo Token**.
3. Paste your token into the dialog and click **Save**. You can change or remove the token at any time from the same card.

Your token is stored encrypted on the NimbusImage server—it is never exposed in the browser.

{% hint style="info" %}
**Testing first?** Enable **Use Zenodo Sandbox** in the token dialog to practice the full workflow against [sandbox.zenodo.org](https://sandbox.zenodo.org/). The sandbox issues test-only DOIs and its data may be wiped periodically, so it's the safe place to rehearse before publishing for real. Note that the sandbox uses a separate account and a separate token from production Zenodo.
{% endhint %}

## Step 3: Upload the project

Once a token is configured, the **Zenodo Publication** card shows a green confirmation and an **Upload to Zenodo** button.

<figure><img src="/files/JtGXNjoxWG826gjvxXZ8" alt="The Zenodo Publication card showing a configured token, a Change Token button, and the Upload to Zenodo button"><figcaption></figcaption></figure>

1. Make sure your project's publication metadata is filled in—**title, description, license, keywords, and authors**. NimbusImage maps these fields onto the Zenodo record.
2. On the **Zenodo Publication** card, click **Upload to Zenodo**.
3. A progress bar tracks the upload. Large projects can take several minutes; you can navigate away and come back, and the upload will continue in the background.

When the upload finishes, your project has a **draft** deposition on Zenodo. The card shows a link to open and review the draft on Zenodo's website.

{% hint style="info" %}
Zenodo limits a single record to **50 GB** and **100 files**. If your project is larger, you can request a quota increase (up to 200 GB) directly from Zenodo.
{% endhint %}

## Step 4: Review and publish

1. Click the link on the card to open the draft on Zenodo and confirm everything looks correct.
2. Back in NimbusImage, click **Publish (Mint DOI)** and confirm.

{% hint style="warning" %}
**Publishing is irreversible.** It mints a permanent DOI, and the published record can no longer be deleted—you can only add new versions. Review the draft carefully before publishing.
{% endhint %}

Once published, the card displays the project's DOI. This is the identifier you cite in your paper and report to your funding agency.

If you uploaded a draft but decide not to publish it, click **Discard Draft** to remove it.

## Updating a published project

If your data or analysis changes after publishing, you don't start over. Open the project and click **Upload New Version**. NimbusImage uploads the current state of the project as a new version of the existing Zenodo record. Each version gets its own version-specific DOI, while a single *concept DOI* continues to point at the latest version—so citations remain valid as your work evolves.


# Viewing your image dataset

Once your images are loaded into NimbusImage, you can interact with it through the viewer. The viewer allows for easy navigation and flexible visualization.

**Key features include:**

* **Easy to use navigation and contrast settings**
* **"Unrolling" of variables** to show montages
* **Overview "minimap".** Drag around the square to navigate; shift-click-drag to directly go to a location.

  <figure><img src="/files/UXIyzora4GvC1XaKajyE" alt="" width="156"><figcaption></figcaption></figure>
* **Dynamic scale bar.** Click the scale bar to adjust pixel sizes and other settings.
* **Zoom in and out of large images.** Scroll wheel zooms, just like Google Maps.
* **Flexible layer settings.** See below for more information about layers.

## Layers

Understanding layers can help unlock more flexibility in how you visualize your data. Generally, layers are most commonly thought of as mapping to channels, but in NimbusImage, they are capable of more. For instance, you can make multiple layers that draw from the same channel, but show different times in different colors, which can be very helpful for time lapse analysis.

<figure><img src="/files/kvBR6BLA7oAdBA1Ha6H6" alt=""><figcaption><p>Current time in green, next time in red so that you can see the shift</p></figcaption></figure>

### Layer grouping

Another useful feature is layer grouping, which allows you to put together multiple layers into a single grouped layer. For instance, if you have a couple fluorescence channels that you always want to show together, you can group them.

To create a group, click **"Make layer group…"** at the top of the Layers panel, check the layers you want to combine, and click **Create group**:

<figure><img src="/files/SU8CryUwHCn4boLIOrrO" alt=""><figcaption></figcaption></figure>

You can group any number of layers together, and ungroup them later from the group's menu.

## Label display options

NimbusImage allows you to customize how labels are displayed in your image viewer. You can toggle between:

* **Text labels**: Display descriptive labels such as "Well A1", "Position 3", etc.
* **Numeric identifiers**: Display simple numeric IDs for a cleaner view

This toggle helps you choose between more informative labels and a less cluttered display depending on your needs.

## Custom channel color preferences

You can set default channel color preferences in your user profile. These custom color settings:

* Automatically apply to new datasets you create or upload
* Can be overridden on a per-dataset basis if you want different colors for a specific dataset
* Help maintain consistency across your analyses

This feature is especially useful if you work with the same types of channels regularly and want them to always appear in your preferred colors.

## 3D visualization

In addition to the standard 2D viewer, NimbusImage can render your dataset as an interactive 3D volume directly in your browser. This is useful for exploring Z-stacks and for viewing time lapses as volumes. Toggle between the 2D and 3D views using the control in the top app bar.

<figure><img src="/files/xYK6q0Fden8ds8xSf6Xz" alt=""><figcaption><p>A time lapse rendered in 3D with Time mapped to the depth axis: each green streak is a nucleus tracing its path (a "worldline") over time. The scaled bounding box and 3D controls run along the edges.</p></figcaption></figure>

### Volume rendering

Each layer is volume-rendered using the same color and contrast settings you use in the 2D viewer. Two blend modes are available:

* **Composite**: Blends all channels together, so overlapping structures appear semi-transparent.
* **Maximum Intensity Projection (MIP)**: Shows the brightest value along each viewing ray, which is useful for emphasizing bright puncta or fibers.

The volume respects anisotropic voxel spacing (the physical Z-step relative to the XY pixel size), so structures keep their true proportions.

{% hint style="info" %}
Very large images are automatically downsampled to stay within your browser's memory and GPU limits. This affects only the 3D preview, not your underlying data.
{% endhint %}

### Choosing the depth axis: Z or Time

You can map either **Z** or **Time** to the depth axis of the volume:

* Use **Z** to view a conventional Z-stack as a volume.
* Use **Time** to stack the frames of a time lapse into a volume, so that moving objects trace out continuous paths ("worldlines") through the third axis. A small dialog lets you set the spacing between time points.

### Segmentations in 3D

Polygon annotations are rendered as 3D objects within the volume, colored either by tag or by a computed property, and they honor your current annotation filters. Rendering options include:

* **Lofted surfaces**: When enabled (the default), the outlines of the same object on adjacent slices are joined into smooth, shaded surfaces, so a segmented cell reads as a continuous 3D shape rather than a stack of slabs. A configurable overlap threshold controls how much two outlines must overlap to be joined.
* **Points and lines**: Point annotations appear as small spheres, and line annotations as vertical ribbons.
* **Opacity**: An opacity slider adjusts how transparent the segmentations are, so you can see the underlying volume data through them.

### Orientation aids

* An **XYZ gizmo** in the corner shows the current orientation.
* An optional **bounding box** draws a scaled cage around the volume with tick labels in physical units, making it easier to judge sizes and distances.

## Line scan intensity profiles

The line scan tool lets you draw a line across your image and immediately see a plot of raw pixel intensity along that line, without creating any stored annotations. This is handy for inspecting signal profiles, comparing channels, checking for colocalization, or locating edges and peaks.

<figure><img src="/files/UqYYS3MniV2lc6Z4J9iV" alt=""><figcaption><p>A freehand line scan across several cells, with the live intensity profile for each channel shown at the bottom right</p></figcaption></figure>

### How to use

1. **Add a line scan tool** from the tool menu. Two variants are available:
   * **Freehand**: Drag to draw a freeform line; the scan completes when you release the mouse.
   * **Segment**: Click once to start and once to end a straight line segment.
2. **Draw across the feature** you want to examine. A panel appears at the bottom right of the viewer showing the intensity profile.
3. The profile updates live as you draw, with one colored trace per channel (matching each layer's color) and a legend. Hover over the plot to read the intensity at a given position.
4. **Close the panel** to dismiss and reset the scan.

### Options

* **Channel selection**: When creating the tool, you can optionally pick a single channel to plot. The panel can then toggle between showing all visible channels and just the selected one.

### Technical details

Intensities are read as raw, unstyled pixel values from the image tiles (not the contrast-adjusted display values) and sampled along the line. The plotted values therefore reflect the true underlying data, making them suitable for quantitative comparison.


# Analyzing image data with objects, connections, and properties

## Overview

Analysis in NimbusImage is a little bit different than in other tools. The key concepts are ***Objects***, ***Connections***, and ***Properties***. Throughout, the key organizational system is ***tagging***, allowing flexible organization and more intuitive analysis patterns.

**Objects** are essentially annotations of items of interest within your dataset. Examples are:

1. Point objects representing spots of a particular RNA in the cytoplasm.
2. "Blob" objects representing the outline of a cell.
3. Line objects representing the basement membrane.

**Connections** between objects allow you to build relationships between objects. For instance, each RNA could be connected to a cell, meaning that that RNA is within that cell. Or a nucleolus object could be connected to a nucleus, or to a nearby paraspeckle. Connections allow you to document and analyze specific relationships, and interact with those relationships visually to get the analysis you want.

**Properties** are measurements you want to make on objects and connections for the final analysis of your data. For instance, average fluorescence intensity within the nucleus. Or distance from the speckle to the nuclear periphery. Or the length of a filament. Or the number of spots in the cytoplasm.

{% hint style="info" %}
**Tags are critical for organizing your analysis.** Objects should all have tags, which allow you to label, say, cells vs. nuclei, or spots for GAPDH mRNA or EEF2 mRNA. It helps you know what things represent.
{% endhint %}

Learn more about these concepts in the following sections:

* [Tools for making objects](/documentation/analyzing-image-data-with-objects-connections-and-properties/tools-for-making-objects)
* [Tools for connecting objects](/documentation/analyzing-image-data-with-objects-connections-and-properties/tools-for-connecting-objects)
* [Measuring object properties](/documentation/analyzing-image-data-with-objects-connections-and-properties/measuring-object-properties)

NimbusImage is designed for scaling, so these tools will work for many thousands of objects.

## Example flows

***The typical workflow in NimbusImage is to find objects in your images, either manually or using several automated tools and quantify properties of those objects.*** Throughout, NimbusImage is designed to allow you to interact with your objects. You can manually add cells, remove incorrectly segmented nuclei, connect extra spots to a cell that got missed, and run your analysis on this corrected data. It is this flexibility that allows you to easily get numbers that accurately reflect your data.

Here's a couple examples of a workflow to make these concepts more concrete.

### Measure cell areas:

1. Circle a bunch of cells, tag them with <kbd><mark style="background-color:orange;">fibroblast<mark style="background-color:orange;"></kbd>.
2. Create a "metrics" property and compute it.
3. List the areas for each.

### Count dots in each cell

1. Circle cells ( <kbd><mark style="background-color:orange;">fibroblast<mark style="background-color:orange;"></kbd>) and click on dots ( <kbd><mark style="background-color:orange;">UBC mRNA<mark style="background-color:orange;"></kbd>)
   1. More likely, you will use automated tools in NimbusImage to find cells and dots.
2. Use a "Connect to nearest" tool to automatically connect each dot to a cell.
3. Create a property to count the number of UBC mRNA spots connected to fibroblasts.
4. List the point count for each cell.

### Track cells over time

1. Find cells ( <kbd><mark style="background-color:orange;">HEK<mark style="background-color:orange;"></kbd>). NimbusImage has many automated tools for time lapse analysis specifically.
2. Use a "Connect timelapse" tool to automatically connect cells over time.
3. Use "Time lapse mode" to review and correct tracks.
4. Create a property to store all the tree information.
5. Export the tree information in a CSV for downstream analysis in Python/R.


# Tools for making objects

The way to create and edit objects is through the use of **tools**. Tools are defined by the user and are customized (via tags) to flexible organization of the results without a lot of clicking. There are two general categories of tools, manual and automated.

<figure><img src="/files/2z2IGAW5jQMnayA7bCRq" alt=""><figcaption><p>The "Add new tool" dialog, where tools are organized by category (manual object tools, Segment Anything, connections, line scans, and more)</p></figcaption></figure>

**Manual tools.** Manual tools are often based on a primitive type, like a point, line, or blob, and is customized with tags and other features. For instance, you might make a tool for circling cells in your image. You would choose a manual blob creation tool, name it "Nucleus" and add the tag \[nucleus]. You could also add a hotkey. That tool gets added to your interface and you can use it to circle cells at any time.

**Automated tools.** NimbusImage has been designed to allow the use of automated algorithms for finding things like cells and points in your images, often using the latest deep learning methods. For instance, you can set up an automated tool to use Cellpose to find cells within your images. These tools often have specific parameters that you can use to obtain optimal results.

## AI-suggested tools

When you open a freshly created collection that doesn't have any tools yet, NimbusImage can suggest a starting set of tools for you. It looks at your image and its channel names and proposes relevant tools — for example, Cellpose-SAM for nuclei, a manual blob tool for cells, or Piscis for spots — in a floating panel. Review the suggestions and click to add the ones you want. You can always add, remove, or reconfigure tools yourself afterward.

<figure><img src="/files/dYXvzwW5onUfSuRx0DiC" alt=""><figcaption><p>The "Suggested tools" panel proposes tools based on your image — here, H&#x26;E Deconvolution and a Blob tool for a histology slide</p></figcaption></figure>

## Manual blob/point/line/rectangle tools

Manual blob/point/line/rectangle tools are the most basic tools in NimbusImage. Set it up by clicking on "Add New Tool" and choosing "Manual Blob", "Manual Point", "Manual Line", or "Manual Rectangle". Set the tag, and then you can use it to create objects in your image. You can use the same tag for multiple tools. For instance, you can use an automated cell finding tool and then add more cells using the manual tool, and they will be all treated the same for downstream analysis.

## Segment-Anything semi-automated object finding, AKA "God Mode"

Segment-Anything is a new method for finding objects in images. It is a semi-automated tool that allows you to find objects in your images by either clicking on them or drawing a bounding box around them. To use it, click on "Add New Tool" and choose "ViT-B" under "Segment Anything Model".

{% hint style="info" %}
If you use Segment Anything Model (SAM) in your research, please cite the [relevant papers](/citations#segment-anything-model-sam).
{% endhint %}

Options include:

* **Simplification**: The simplification parameter controls how much the segmentation is smoothed out. Smoother annotations are faster to run computations on and navigate.
* **Turbo mode**: The turbo mode allows you to rapidly segment without having to manually "accept" each segment.

Segment Anything works by first encoding the image to enable it to find the objects. This will take a few seconds to compute when you move to a new area. Every time you move the image, you will need to re-encode the image; if you want to avoid this, click the "lock" icon at the bottom left of the image to prevent the image from moving around.

Once encoded, just move your mouse over the image and it will outline what the object would be if you were to shift-click. Shift-click to make the object! Sometimes, it will give you better results if you define a box around the object you want to find. Just shift-click and drag to make a box, and it will segment that region.

{% hint style="info" %}
Segment Anything "sees" what you see in the image. Adjust the contrast and zoom to make objects visible and of a size that is around 5-15% of the size of the image for best results.
{% endhint %}

## Segment similar objects (experimental)

The "Segment similar objects" tool lets you mark a few example objects and then automatically find and segment other, similar objects across the current view. It's designed for cases where objects share a consistent appearance but would be tedious to click one by one.

{% hint style="warning" %}
This tool is **experimental** and currently requires **Google Chrome with WebGPU** support. It operates on the current viewport only.
{% endhint %}

<figure><img src="/files/NK93CB1E9yImTdCWDn0B" alt=""><figcaption><p>The Segment similar objects panel, with controls for how examples are selected and how matches are found</p></figcaption></figure>

### How to use

1. **Add the "Segment similar objects" tool** from the tool menu. A control panel appears at the bottom right of the viewer.
2. **Choose how to select examples** under **Select by**:
   * **Click (SAM)**: Shift-click an example object and Segment Anything outlines it.
   * **Box (SAM)**: Shift-drag a box around an example object.
   * **Circle**: Circle an example object by hand.
3. **Choose how to find matches** under **Find with**:
   * **SAM**: Scores candidate regions by how similar they are to your examples in the Segment Anything model's feature space.
   * **Classifier**: Trains a lightweight random-forest classifier, in your browser, on the example objects.
   * **SAM→Classifier**: Runs SAM first, then trains the classifier on everything SAM found, combining both approaches.
4. **Mark a few examples.** Shift-click (or shift-drag/circle) the objects you want to match; shift-right-click marks background to exclude. The panel tracks how many examples and putative objects you currently have.
5. **Review the putative results.** Matches appear as outlines across the current view.
6. **Accept** to commit the results in bulk. Accepted objects are deduplicated against any annotations that already exist.

{% hint style="info" %}
Because both propagation methods draw on the same set of examples, you can mix and match how you select examples with how they're applied — for instance, select with SAM clicks but propagate with the classifier.
{% endhint %}

Plain dragging pans the image as usual; hold Shift to select, matching the behavior of the Segment Anything tool.

## Edit objects

You can edit objects by using the Annotation Edits -> Blob edit tool. With that tool, you can just drag on your object and it will "slice" it into a new object. Whatever line you draw will define a new outline for that segment of the object. That allows you to both remove and add areas to the objects without having to use separate brush and eraser tools.

## Automated object finding and connection

We have a number of automated tools for finding and connecting objects (cells, spots, etc.) that take advantage of the latest deep learning methods.

### Cellpose-SAM for versatile cell segmentation

Cellpose-SAM combines the power of Cellpose with the Segment Anything Model (SAM) to offer a versatile approach to cell segmentation. It simplifies the input process by allowing users to specify up to three input channels, making it adaptable for various segmentation scenarios, from nuclei-only to full RGB images.

{% hint style="info" %}
If you use Cellpose-SAM in your research, please ensure you cite the relevant papers for both [Cellpose](/citations#cellpose) and the [Segment Anything Model (SAM)](/citations#segment-anything-model-sam).
{% endhint %}

#### How Cellpose-SAM works

Cellpose-SAM processes images by taking input from up to three configurable channel "slots":

* **Single Channel Input:**
  * To segment nuclei, provide the nuclear stain channel to Slot 1.
  * To segment cell boundaries, provide the cytoplasm/membrane channel to Slot 1.
* **Dual Channel Input:** For improved cell boundary segmentation, you can provide the cytoplasm/membrane channel to Slot 1 and the nuclear channel to Slot 2.
* **Triple Channel Input (RGB):** To segment cells in an RGB image, map the Red, Green, and Blue channels to Slots 1, 2, and 3 respectively.

The model then uses this information to perform segmentation.

#### Available models

Currently, the primary model available is:

* **cellpose-sam**: This is the base model and should be suitable for most general-purpose cell segmentation tasks.

#### Key parameters

* **Model**: Selects the segmentation model. Defaults to `cellpose-sam`.
* **Channel for Slot 1**: **Required.** The primary channel for segmentation. Select the source channel for the model's first input. If multiple are selected, only the first will be used.
* **Channel for Slot 2**: (Optional) The secondary channel, often used for nuclear information when segmenting cytoplasm. If multiple are selected, only the first will be used.
* **Channel for Slot 3**: (Optional) The tertiary channel, typically used for the blue channel in RGB images. If multiple are selected, only the first will be used.
* **Diameter**: The approximate diameter of the cells in pixels. While important for original Cellpose, Cellpose-SAM is less sensitive to this parameter. A value around **30 pixels** often works well as a starting point, but can be adjusted (0-200 pixels, default 10).
* **Smoothing**: Controls the simplification of the generated polygons (0-10, default 0.7). Higher values create smoother outlines. A value of 0.7 is a good default.
* **Padding**: Expands (positive values) or contracts (negative values) the final polygons in pixels (-20 to 20 pixels, default 0).
* **Tile Size**: The size of image tiles (in pixels) for processing (0-2048, default 1024). Larger tiles require more memory.
* **Tile Overlap**: The fractional overlap between adjacent tiles (0-1, default 0.1). Ensure this overlap is larger than your largest cells (e.g., for 1024px tiles with 0.1 overlap, objects should be <102px).

#### Best practices

1. **Channel Selection**:
   * For nuclei: Use your nuclear stain in Slot 1.
   * For cell boundaries: Use your cytoplasm/membrane channel in Slot 1. Consider adding a nuclear channel to Slot 2 for refinement.
   * For RGB images: Map R, G, B to Slots 1, 2, and 3.
2. **Diameter Setting**: Start with a diameter around 30 pixels. Adjust if necessary, but exact precision is less critical than with standard Cellpose.
3. **Review Results**: Always visually inspect segmentation and adjust parameters if needed.
4. **Post-process**: Utilize NimbusImage's manual editing tools to correct any segmentation errors.

### Cellpose for automated cell finding

Cellpose is a deep learning-based tool for automatically finding and segmenting cells in microscopy images. It has been trained on a large collection of diverse cell images, making it highly effective for many cell types without requiring additional training. Cellpose is a powerful starting point for cell segmentation, allowing you to quickly generate cell outlines that can be refined with NimbusImage's interactive tools.

{% hint style="info" %}
If you use Cellpose in your research, please cite the [relevant papers](/citations#cellpose).
{% endhint %}

{% hint style="info" %}
Note that NimbusImage also allows for retraining of the Cellpose models to (often greatly) enhance performance for your specific dataset.
{% endhint %}

#### Available models

NimbusImage includes several pre-trained Cellpose models:

* **cyto3**: The most accurate for general cell segmentation (recommended default)
* **cyto2**: An older model for cell segmentation
* **cyto**: The original cell segmentation model
* **nuclei**: Specifically trained for nuclear segmentation

#### Key parameters

* **Primary Channel**: The main channel to use for segmentation
  * For cytoplasm segmentation (Cyto3): use your cytoplasm/membrane channel
  * For nuclear segmentation (Nuclei): use your nuclear stain channel (e.g., DAPI)
* **Secondary Channel** (optional): A secondary channel to improve segmentation
  * For cytoplasm segmentation (Cyto3): you can add your nuclear channel
  * For nuclear segmentation (Nuclei): leave this blank (adding a secondary channel may decrease performance)
* **Diameter**: The approximate diameter of cells in pixels
  * **This parameter is crucial for good results**
  * Set this as close as possible to the actual cell diameter in your images
* **Smoothing**: Controls how much the cell outlines are simplified (0-10)
  * Higher values create smoother outlines with fewer vertices
  * Default of 0.7 works well for most images
  * Increase for smoother boundaries, decrease for more precise outlines
  * Very precise outlines can decrease performance, especially if you have a large number of objects
* **Padding**: Expand or contract the final cell outlines in pixels
  * Positive values expand the outlines (useful if cells appear too small)
  * Negative values contract the outlines (useful if segmentation is too generous)
  * Default of 0 means no adjustment

#### Advanced parameters for large images

* **Tile Size**: The size of each image tile in pixels
  * Default of 1024 works well for most images
  * Decrease if you encounter errors
  * Larger tiles will require more memory and can cause Cellpose to crash
* **Tile Overlap**: The fraction of overlap between adjacent tiles
  * Default of 0.1 (10% overlap) works well in most cases
  * **Important**: Make sure your overlap is larger than your largest cells
  * For example, for 1024 pixel tiles with 0.1 overlap, the largest cell should be less than 102 pixels across

#### Best practices

1. **Start with the right model**: Use cyto3 for general cell segmentation or nuclei for nuclear segmentation, or use your own custom retrained model
2. **Set the diameter carefully**: This is the most important parameter for accurate results
3. **Check results visually**: Always inspect the segmentation and refine parameters if needed
4. **Use the secondary channel** when segmenting cytoplasm if you have a good nuclear stain
5. **Post-process as needed**: Use NimbusImage's manual editing tools to correct any segmentation errors

### Cellpose Training

(Currently for Cellpose 3.0 only; Cellpose-SAM training coming soon!) NimbusImage offers the ability to train custom Cellpose models directly within the platform using your own annotated data. This feature allows you to create specialized segmentation models tailored to your specific cell types or imaging conditions. Custom models will often provide greatly improved performance for your specific dataset, even if your cells look pretty "normal", and especially if they don't!

#### Training data preparation

To train a custom model, you'll need:

1. Representative images with cells you want to segment
2. Accurate cell annotations (outlines) created manually or corrected from automated results
3. Optional: Defined regions of interest for training

#### Key parameters

* **Base Model**: The pre-trained model to use as a starting point
  * **cyto3**: Recommended for most cell types
  * **nuclei**: Use when training a nuclear segmentation model
  * **Custom models**: Previously trained models will also appear here
* **Nuclear Model?**: Check this box if you're training a model for nuclear segmentation
  * When checked, the model will be optimized for nuclear detection
* **Output Model Name**: Name for your custom model
  * This model will be saved and appear in the Cellpose worker's model list
* **Primary Channel**: The main channel for segmentation
  * For cytoplasm models: use your cytoplasm/membrane channel
  * For nuclear models: use your nuclear stain channel
* **Secondary Channel**: The secondary channel to improve segmentation
  * For cytoplasm models: your nuclear channel
  * For nuclear models: leave blank or set to -1
* **Training Tag**: The tag applied to annotated cells used for training
  * All cells with this tag will be used to train the model
  * Use this to select high-quality annotations
* **Training Region**: Optional tag (recommended) to define specific regions for training
  * If selected, only annotations within these regions will be used
  * Useful for limiting training to representative areas of your image

#### Training parameters

Unless you have a specific reason to change these, leave them at the default values.

* **Learning Rate**: Controls how quickly the model adapts during training
  * Default: 0.01
  * Lower values (0.001) create more stable but slower training
  * Higher values can speed up training but might decrease stability
* **Epochs**: Number of training iterations
  * Default: 1000
  * More epochs generally improve results but take longer
  * Consider increasing for complex cell types
* **Weight Decay**: Regularization parameter to prevent overfitting
  * Default: 0.0001
  * Higher values create simpler models that may generalize better

#### Training workflow

1. Create high-quality annotations of your cells
   * Tag these annotations with a consistent label (e.g., "training\_cells")
   * Ensure annotations are accurate and representative
   * **Don't forget that what you do NOT annotate will also be used for training!**
2. Optional: Define training regions
   * Create rectangles or polygons around areas with good examples
   * Tag these regions (e.g., "training\_region")
   * **Choosing specific regions can be very helpful in focusing the retraining on specific areas of your image**
3. Add a Cellpose Training tool from the toolset menu
   * Configure all parameters as described above
   * Run the training process
4. Use your custom model
   * After training completes, your model will appear in the Cellpose worker's model list
   * Select it when using the regular Cellpose tool for segmentation

#### Tips for successful training

1. **Provide diverse examples**: Include cells of different sizes, shapes, and intensities
2. **Quality over quantity**: A smaller set of perfect annotations is better than many poor ones. A few good images, carefully annotated, will usually do the trick.
3. **Choose representative regions**: Select areas with good imaging quality and typical cells. Be sure to include examples of cells that the default algorithm might have trouble with.
4. **Be patient**: Training can take several minutes to complete

#### Advanced usage

Your custom Cellpose models are saved in a `.cellpose` directory at the root of your Private or Public folder. You can:

* Manually add models trained offline to this directory
* Share models between team members by copying model files
* Use these models in the standard Cellpose Python package

The integration between NimbusImage and Cellpose makes it easy to create specialized models for your specific research needs without requiring deep learning expertise.

### Piscis for automated spot finding

Piscis is a deep learning-based tool for automatically finding and segmenting spots in microscopy images. It has been trained on a large collection of diverse spot images, making it highly effective for many spot types without requiring additional training. Piscis is a powerful starting point for spot segmentation, allowing you to quickly generate spot outlines that can be refined with NimbusImage's interactive tools. It can be retrained on your own data as well, which can often give you great results if the default models don't work well for your data.

{% hint style="info" %}
If you use Piscis in your research, please cite the [relevant paper](/citations#piscis).
{% endhint %}

> **Key tip**: If you're getting too many or too few spots, try different models first before adjusting other parameters. The built-in models vary in sensitivity, and selecting the right one is usually more effective than tweaking threshold values.

#### How Piscis works

Piscis uses a specialized neural network designed specifically for detecting small punctate structures in fluorescence microscopy images, such as:

* RNA molecules in FISH experiments
* Protein clusters
* Vesicles
* Small organelles
* Synaptic puncta

The model can work in both 2D (single slice) and 3D (Z-stack) modes, making it flexible for different experimental setups.

#### Key parameters

* **Model**: Select which pre-trained Piscis model to use
  * Different models have varying levels of sensitivity
  * Try several models if you're not getting optimal results
  * Custom trained models will also appear in this list
* **Mode**: Choose between "Current Z" or "Z-Stack"
  * **Current Z**: Process each Z-slice independently (2D mode)
  * **Z-Stack**: Process the entire Z-stack as a 3D volume (better for connecting spots across Z)
* **Scale**: Adjust for the size of spots (0-5)
  * Default value of 1 works well for most applications
  * Increase to detect larger spots
  * Decrease to detect smaller spots
  * Affects how the model interprets spot size relative to the training data
* **Threshold**: Confidence threshold for spot detection (0-9)
  * Default value of 1.0 works for most cases
  * Note that this parameter has a relatively minor effect compared to changing models
  * Higher values create stricter detection (fewer spots)
  * Lower values create more lenient detection (more spots)
* **Skip Frames Without**: Optional tag to skip processing frames
  * If specified, only process frames containing objects with the given tag
  * Useful for optimizing processing time by focusing on relevant frames

#### Advanced features

* **Batch processing**: Process multiple positions, Z-slices, or time points
  * Use the "Batch XY", "Batch Z", and "Batch Time" fields to specify ranges
  * Format example: "1-3, 5-8" processes positions 1, 2, 3, 5, 6, 7, 8
  * Note: If using "Z-Stack" mode, the "Batch Z" field is ignored

#### Best practices

1. **Start with the default model**: Try the default "20230905" model first
2. **Try different models**: If detection isn't optimal, switching models is more effective than adjusting thresholds
3. **Use Z-Stack mode** for 3D data where spots may span multiple Z-slices
4. **Validate results visually**: Always check the detection results manually
5. **Consider retraining**: For specialized applications, retraining on your own data can significantly improve results

#### Example workflow

1. Add a new Piscis tool from the toolset menu
2. Select your channel containing spots
3. Choose a model (start with the default)
4. Select either "Current Z" or "Z-Stack" mode
5. Run the model
6. Review the results
7. If needed, try a different model or adjust parameters and run again

#### Training custom models

If the pre-built models don't work well for your specific spot detection needs, consider training a custom model using the Piscis Train tool (documented separately). Custom-trained models will appear in the model selection dropdown once trained.

Piscis is particularly effective for RNA FISH and similar applications where automatic detection of small punctate structures is needed, saving significant time compared to manual annotation.

### Piscis Training

The Piscis Training tool allows you to create custom spot detection models tailored to your specific microscopy data. By training on your own annotated examples, you can significantly improve spot detection performance for challenging or unique datasets.

> **Key tip**: You don't need extensive training data to get good results! Even a few carefully annotated regions can produce a highly effective custom model.

#### Why train a custom model?

Consider training a custom Piscis model when:

* Default models consistently detect too many or too few spots
* Your spots have unusual characteristics (size, intensity, shape)
* You're working with specialized microscopy techniques
* Background noise or artifacts are causing detection issues

#### Training data preparation

To train an effective custom model:

1. **Create point annotations** for the spots you want to detect
   * Tag them consistently (e.g., "training\_spots")
   * Be thorough within your selected regions - mark all visible spots
2. **Define training regions** where your annotations are complete
   * Use rectangles or polygons to outline areas with fully annotated spots
   * Tag these regions consistently (e.g., "training\_region")
   * Focus on high-quality regions rather than quantity

#### Key parameters

* **Initial Model Name**: The base model to start training from
  * Starting from an existing model (like "20230905") speeds up training
  * The base model provides initial weights that get refined with your data
* **New Model Name**: What to call your custom model
  * Default is a timestamp (e.g., "20250305\_143022")
  * Consider using a descriptive name for your experiment or spot type
* **Annotation Tag**: The tag used on your spot annotations
  * Only points with this tag will be used for training
* **Region Tag**: The tag used on your training regions
  * Only annotations within these regions will be used for training
  * Crucial for ensuring the model learns from fully annotated areas

#### Training parameters

* **Learning Rate**: Controls how quickly the model adapts (default: 0.2)
  * Higher values can lead to faster convergence but may be less stable
  * Lower values produce more stable but slower training
* **Weight Decay**: Regularization parameter to prevent overfitting (default: 0.0001)
  * Higher values create simpler models that may generalize better
* **Epochs**: Number of training iterations (default: 40)
  * More epochs generally improve results but take longer
  * The default is usually sufficient for good performance
* **Random Seed**: Controls randomness in training for reproducibility (default: 42)
  * Change this value if you want to try different random initializations

#### Training workflow

1. **Create point annotations**
   * Manually mark spots in representative areas of your image
   * Apply a consistent tag (e.g., "training\_points")
2. **Define training regions**
   * Draw rectangles or polygons around fully annotated areas
   * Apply a consistent tag (e.g., "training\_region")
3. **Configure the Piscis Train tool**
   * Select a base model
   * Configure training parameters (or use defaults)
   * Specify your annotation and region tags
4. **Run the training process**
   * This will take several minutes depending on your data
   * The model will be saved with your specified name
5. **Use your custom model**
   * Your trained model will automatically appear in the Piscis tool's model list
   * Select it when using Piscis for spot detection

#### Best practices

1. **Quality over quantity**: A few well-annotated regions are better than many poorly annotated ones
2. **Include challenging examples**: Include difficult spots in your training data
3. **Use representative regions**: Select areas that reflect the variability in your dataset
4. **Start small**: Begin with a small training set and evaluate before expanding
5. **Iterative improvement**: Train, test, correct annotations, and train again for best results

#### Testing your model

After training, test your model by:

1. Using the standard Piscis tool with your new model
2. Comparing results against manual annotations in regions not used for training
3. Adjusting the Scale parameter slightly if needed for fine-tuning

#### Model storage

Your custom Piscis models are saved in a `.piscis` directory at the root of your Private or Public folder. Once training completes, the model files are automatically stored in this location and will appear in the Piscis tool's model dropdown menu for future use. You can:

* Manually add models trained offline to this directory
* Share models between team members by copying model files

Custom-trained Piscis models often dramatically improve spot detection accuracy for specialized applications, saving significant time in your image analysis workflow.

### CondensateNet for automated condensate segmentation

CondensateNet is a deep learning-based tool for automatically detecting and segmenting biomolecular condensates in brightfield microscopy images. It uses a Feature Pyramid Network (FPN) architecture with an EfficientNet encoder to identify condensates and create polygon annotations for each one, which you can then analyze using NimbusImage's object properties and tagging features.

{% hint style="info" %}
If you use CondensateNet in your research, please cite the [relevant paper](/citations#condensatenet).
{% endhint %}

#### How CondensateNet works

CondensateNet processes brightfield images through a three-stage pipeline:

1. **Preprocessing**: Normalizes the input image
2. **Inference**: Runs the FPN model to produce probability masks and flow fields
3. **Post-processing**: Converts predictions to instance segmentation using watershed-based methods, outputting polygon annotations for each detected condensate

#### Key parameters

* **Probability Threshold**: Minimum confidence score for a detection to be included (0–1, default: 0.15). Lower values detect more condensates, including faint ones; higher values detect only high-confidence condensates.
* **Min Size**: Minimum condensate size in pixels (default: 15). Objects smaller than this are discarded.
* **Max Size**: Maximum condensate size in pixels (default: 600). Objects larger than this are discarded.
* **Smoothing**: Polygon simplification tolerance (default: 0.3). Higher values produce simpler polygon outlines with fewer vertices.
* **Padding**: Expand or shrink detected polygons in pixels (default: 0). Positive values dilate outlines; negative values erode them.

#### Advanced parameters for large images

* **Tile Size**: Size of tiles for processing large images in pixels (default: 1024). Smaller tiles use less memory but may miss large objects.
* **Tile Overlap**: Fraction of overlap between adjacent tiles (0–1, default: 0.1). Objects spanning tile boundaries are stitched together using the overlap region.
* **Important**: Ensure your objects are smaller than the overlap region. For example, with a tile size of 1024 and overlap of 0.1, objects should be less than approximately 102 pixels in their longest dimension for correct stitching.

#### Batch processing

* Use the **Batch XY**, **Batch Z**, and **Batch Time** fields to specify ranges for processing multiple positions, Z-slices, or time points (format: "1-3, 5-8"). Defaults to the current tile.

#### Best practices

1. **Adjust the probability threshold** as your primary tuning parameter — start with the default of 0.15 and increase if you see too many false positives or decrease if you're missing condensates
2. **Use Min/Max Size** to filter out noise (small detections) or non-condensate objects (large detections)
3. **Use larger tile sizes** (1024 recommended) for consistent detection — smaller tiles can cause detection differences due to per-tile intensity normalization
4. **Review results visually**: Always inspect the segmentation and refine parameters if needed
5. **Post-process as needed**: Use NimbusImage's manual editing tools to correct any segmentation errors


# Tools for connecting objects

In many cases, you may want to connect objects together, for instance, the same cell through a time lapse video, or spots to a nucleus. These connections can be made manually using connection tools such as Lasso connect or also automated connection algorithms such as Connect to Nearest. Connections can also be deleted manually. These connections can also sometimes be made when a property is computed to show you what objects were used in the computation.

## Best practices for connections

* **Use tags effectively**: Properly tagging your objects makes connection tools more precise
* **Assign hotkeys**: Set up hotkeys for your most frequently used connection tools
* **Think about directionality**: Remember that connections have direction (parent to child) which can be important for certain analyses

Connections form the foundation for many powerful analyses in NimbusImage, enabling you to quantify relationships between objects and trace structures across time.

## Manual connection tools: click and lasso connect

NimbusImage provides several intuitive tools for manually creating and removing connections between objects:

### Click connect

The **Click connect** tool allows you to create connections between objects by simply clicking them in sequence:

1. First, click on a "parent" object
2. Next, click on a "child" object
3. A connection will be established from the parent to the child

This tool is ideal for precisely connecting specific objects, like linking individual RNA spots to their corresponding cells or connecting organelles to their parent structures.

**Configuration options:**

* **Parent Annotation Tags**: Filter which types of objects can be selected as parents
* **Child Annotation Tags**: Filter which types of objects can be selected as children
* **Filter by layer**: Optionally restrict selections to objects on specific layers

### Lasso connect

The **Lasso connect** tool allows you to quickly connect multiple objects at once:

1. Draw a lasso around all the objects you want to connect
2. NimbusImage will automatically establish connections between the selected objects

This is particularly useful for:

* Connecting multiple spots to a cell at once
* Connecting sequential points in a time-lapse track
* Creating connections between groups of related objects

In time-lapse mode, the Lasso connect tool will intelligently connect objects sequentially by time point, making it extremely valuable for track creation and repair.

### Click disconnect

The **Click disconnect** tool allows you to remove individual connections:

1. Click on a connected parent object
2. Click on its connected child object
3. The connection between them will be removed

This is useful for removing incorrect connections without affecting other valid connections.

### Lasso disconnect

The **Lasso disconnect** tool allows you to quickly remove multiple connections at once:

1. Draw a lasso around the connected objects
2. All connections between objects within the lasso will be removed

This is particularly helpful when you need to clear all connections in a region and rebuild them correctly.

## Automated connection tools

NimbusImage provides powerful automated tools that can establish connections between objects based on various criteria, saving you considerable time compared to manual connections.

### Connect to nearest

The **Connect to nearest** tool automatically connects objects based on spatial proximity:

1. Each object with the "parent" tag will be connected to its nearest object(s) with the "child" tag
2. The connections are established based on configurable distance and relationship criteria

**Configuration options:**

* **Parent tag**: Tag that identifies which objects will serve as parents in the connections
* **Child tag**: Tag that identifies which objects will serve as children in the connections
* **Connect across Z**: When enabled, allows connections between objects on different Z-slices
* **Connect across T**: When enabled, allows connections between objects at different time points
* **Connect to closest centroid or edge**: Choose whether to measure distance from:
  * **Centroid**: The central point of each object (faster, simpler)
  * **Edge**: The boundary of each object (more precise for irregularly shaped objects)
* **Restrict connection**: Apply additional constraints to connections:
  * **None**: Connect based solely on distance
  * **Touching parent**: Only connect children that physically touch their parent
  * **Within parent**: Only connect children that are completely contained within their parent
* **Max distance (pixels)**: The maximum allowed distance between parent and child objects
* **Connect up to N children**: Limit the number of children that can connect to each parent

This tool is particularly useful for:

* Connecting RNA spots to their nearest nucleus
* Assigning cells to their closest blood vessel
* Connecting subcellular structures to their parent cells
* Efficiently processing large datasets with many objects

Let me update the documentation section on the "Connect timelapse" tool with more detailed information based on the code you've provided:

### Connect timelapse

The **Connect timelapse** tool specializes in automatically tracking objects across sequential time points:

1. Objects with the same tag are connected from one time frame to the next
2. Connections are established based on spatial proximity between frames
3. The algorithm intelligently handles object movement between frames

This is especially valuable for cell tracking, particle movement analysis, and other time-dependent studies.

**Configuration options:**

* **Object to connect tag**: Specifies which objects to track across time points (all objects with this tag will be connected)
* **Connect across gaps**: Allows connecting objects even when there are missing time points
  * Set a value from 0-10 to determine how many time points can be skipped
  * For example, a value of 1 would connect an object at t=5 directly to t=7 if t=6 is missing
* **Max distance**: The maximum pixel distance objects can move between frames and still be considered the same object
  * Set this based on how much your objects typically move between frames
  * Lower values (5-20 pixels) work well for slow-moving objects
  * Higher values may be needed for rapidly moving objects or lower frame rates

**How it works:**

1. The algorithm processes each spatial location (XY, Z) separately
2. For each time point, it searches for the closest matching objects in subsequent time points
3. Connections are created from later time points to earlier ones (children to parents)
4. All connections are automatically tagged with "Time lapse connection" for easy identification

This tool is perfect for:

* Automatically generating cell lineage trees
* Tracking particle movement over time
* Analyzing cell migration patterns
* Measuring growth or movement rates

**Best practices:**

* Start with a small max distance (10-20 pixels) and increase if needed
* Use the "Connect across gaps" feature when you have intermittently missing objects. These can be later fixed manually using [Time lapse mode](https://github.com/arjunrajlaboratory/NimbusImageGitBook/blob/main/documentation/documentation/time-lapse-mode.md)
* When tracking dividing cells, use this tool first, then manually correct division events
* Review tracks in Time lapse mode to identify and fix any tracking errors
* For very dense or challenging datasets, consider tracking a subset of objects first

After running the Connect timelapse tool, you can use the Time lapse mode (discussed in the [Time lapse mode](https://github.com/arjunrajlaboratory/NimbusImageGitBook/blob/main/documentation/documentation/time-lapse-mode.md) section) to visualize, review, and manually correct the resulting tracks.


# Measuring object properties

Ultimately, most researchers want to extract numbers from their image data. These could correspond to fluorescent intensity across cells, or number of cells per colony, or density of filaments per region. NimbusImage allows you to make these computations easily by defining **properties**. A property (think: area) can be associated with an object and listed and exported for plotting and analysis. You can easily compute a lot of different properties using NimbusImage out of the box because of the flexibility that its tagging and connection system allows. For instance, if you want to find the count the number of spots connected to the basement membrane, that is easy to do with just a few clicks.

First, open the **Object List** and click the blue **"Measure objects"** button. This brings up the Measure objects panel:

<figure><img src="/files/DLXohR06ugYeq97qmUNU" alt=""><figcaption><p>Create new properties on the left; the properties already computed for your objects are listed on the right</p></figcaption></figure>

In the **Create New Property** section, choose the **tag** of the objects you want to quantify (for example, `nucleus`) — or select a shape — and click **"Create Property"**. NimbusImage runs the appropriate property worker, and when it finishes the new measurements appear under **Object Properties** on the right (here, "nucleus Blob metrics", "nucleus Blob intensity measurements", and "nucleus Blob annulus intensity").

To display specific values, click **"Show in annotation list…"**, expand the property (e.g. "nucleus Blob metrics"), and check the metrics you want, such as **Area**:

<div align="left"><figure><img src="/files/dzvikIvIcJMweiMvPsxl" alt="" width="563"><figcaption><p>Choose which computed metrics to show in the annotation list</p></figcaption></figure></div>

The selected property now shows up as a column in the annotation list:

<div align="left"><figure><img src="/files/IasiVQBlFJUcgLD6YAL1" alt="" width="563"><figcaption><p>The Area property listed alongside each object</p></figcaption></figure></div>

You can also press **"t"** while viewing the image to overlay the property values directly on the objects. When you're ready to analyze the numbers elsewhere, export them to a CSV (or TSV) from the **Import / export data** menu → **Export CSV**:

<div align="left"><figure><img src="/files/KGKaomtCjhWSojqBEfqn" alt="" width="500"><figcaption><p>The CSV export dialog lets you choose scope, format, which properties to include, and how to handle missing values</p></figcaption></figure></div>

## Blob metrics (area, perimeter, etc.)

The Blob Metrics property worker calculates a comprehensive set of morphological measurements for blob-shaped (polygon) objects in your dataset. This is particularly useful for analyzing cell shapes, nuclei, or any other blob-like structures you've annotated.

### Available metrics:

* **Area**: The total area enclosed by the object (in square pixels or physical units)
* **Perimeter**: The length of the object's boundary (in pixels or physical units)
* **Centroid**: The geometric center (x,y coordinates) of the object
* **Elongation**: Measures how stretched out the object is (value between 0-1, where 1 is maximally elongated)
* **Convexity**: Ratio of the object's area to the area of its convex hull (measures how convex vs. concave the shape is)
* **Solidity**: Ratio of the object's perimeter to the perimeter of its convex hull
* **Rectangularity**: How well the object fits within its minimum bounding rectangle
* **Circularity**: How closely the object resembles a perfect circle (4π × Area/Perimeter²)
* **Eccentricity**: Measures how much the object deviates from being circular (value between 0-1, where 0 is a circle)

### How to use:

1. Create blob objects in your image (manually or using automated tools)
2. Tag these objects appropriately (e.g., `nucleus`, `cell`, etc.)
3. Create a new property using the Blob Metrics worker
4. Select which tags to analyze
5. Choose whether to use physical units (μm, mm, etc.) or pixel units
6. Run the property worker to calculate metrics for all matching objects

### Physical units:

When the "Use physical units" option is enabled, all measurements will be converted from pixels to the selected physical unit (μm, mm, m, or nm) based on the pixel size metadata in your image. This allows for consistent measurements across datasets with different magnifications or resolutions.

This property is useful for:

* Measuring and comparing cell or organelle sizes
* Analyzing shape changes in response to treatments
* Quantifying morphological differences between cell types
* Correlating shape features with biological function

### Best practices for intensity measurements:

1. **Background correction**: Consider using background subtraction before measuring intensities for more accurate results
2. **Consistent exposure**: For comparative studies, ensure all images were acquired with the same exposure settings
3. **Channel selection**: Carefully select which channel to measure based on your experimental design
4. **Annulus size**: When using annular measurements, adjust the radius to match the biological structure you're analyzing (e.g., typical cytoplasm width)
5. **Validation**: Visually verify that your measurements align with the visible intensity patterns in your images

## Blob Intensity

The Blob Intensity property worker calculates pixel intensity statistics inside blob-shaped (polygon) objects in your dataset. This is ideal for measuring fluorescence within cells, nuclei, or other structures you've annotated.

### Available metrics:

* **Mean Intensity**: The average pixel intensity within the object
* **Max Intensity**: The brightest pixel value within the object
* **Min Intensity**: The dimmest pixel value within the object
* **Median Intensity**: The median pixel value (50th percentile)
* **25th Percentile Intensity**: The intensity value below which 25% of pixels fall
* **75th Percentile Intensity**: The intensity value below which 75% of pixels fall
* **Total Intensity**: The sum of all pixel intensities within the object

### How to use:

1. Create blob objects in your image (manually or using automated tools)
2. Tag these objects appropriately (e.g., `nucleus`, `cell`, etc.)
3. Create a new property using the Blob Intensity worker
4. Select the channel you want to measure intensity from (this can be different from the layer where annotations are drawn)
5. Run the property worker to calculate intensity metrics for all matching objects

### Applications:

* Quantifying protein expression levels within cells
* Measuring nuclear vs. cytoplasmic signal ratios
* Comparing fluorescence intensities between experimental conditions
* Identifying cells with high or low expression of a marker

## Blob Intensity Percentile

This worker extends the basic intensity analysis by allowing you to specify exactly which percentile to measure, giving you more flexibility for your specific analysis needs.

### Parameters:

* **Channel**: The image channel to measure intensity from. Note that this can be different from the channel where annotations are drawn. So you can calculate, e.g., the RFP intensity in objects defined by the DAPI channel to calculate nuclear RFP intensity.
* **Percentile**: A value between 0 and 99.99999 to specify which percentile intensity to calculate (default: 50)

### Output:

* **Nth Percentile Intensity**: The intensity value at your specified percentile

### When to use:

* When you need to focus on a specific portion of the intensity distribution
* For filtering out outliers (using high or low percentiles)
* When the median (50th percentile) doesn't fully capture the intensity characteristics you're interested in

## Blob Annulus Intensity

The Blob Annulus Intensity worker measures pixel intensity in a ring-shaped region around each blob object. This is particularly valuable for quantifying cytoplasmic signals around nuclei or membrane markers surrounding cells.

### Parameters:

* **Channel**: The image channel to measure intensity from
* **Radius**: The width of the annular region in pixels (default: 10)

### Available metrics:

* **Mean Intensity**: The average pixel intensity within the annular region
* **Max Intensity**: The brightest pixel value within the annular region
* **Min Intensity**: The dimmest pixel value within the annular region
* **Median Intensity**: The median pixel value in the annular region
* **25th Percentile Intensity**: The intensity value below which 25% of pixels fall
* **75th Percentile Intensity**: The intensity value below which 75% of pixels fall
* **Total Intensity**: The sum of all pixel intensities within the annular region

### Applications:

* Measuring cytoplasmic fluorescence around nuclear objects
* Quantifying membrane-associated markers surrounding cells
* Analyzing protein localization patterns at cell boundaries
* Studying gradient distributions of signals around organelles

## Blob Annulus Intensity Percentile

This worker combines the flexibility of percentile selection with annular region measurement, allowing for precise control over which statistical metric to use in your ring-shaped regions of interest.

### Parameters:

* **Channel**: The image channel to measure intensity from
* **Radius**: The width of the annular region in pixels (default: 10)
* **Percentile**: A value between 0 and 99.99999 to specify which percentile intensity to calculate (default: 50)

### Output:

* **Nth Percentile Intensity**: The intensity value at your specified percentile within the annular region


# Interacting with objects

One of the main advantages of working in NimbusImage is the ability to directly interact with your objects. This interactive approach allows you to quickly refine your analysis by removing incorrect objects, adding missing ones, and organizing them with tags—all within the same interface.

## Selecting and manipulating objects

<figure><img src="/files/IaFn8J3lQjPcD9Xa63dP" alt=""><figcaption><p>Green blob objects drawn on an image</p></figcaption></figure>

To interact with objects in your dataset:

* **Shift-drag** across objects to select multiple objects at once
* Once selected, a popup menu appears with several options:
  * **Delete selected** - Remove the selected objects
  * **Delete unselected** - Keep only the selected objects and remove all others
  * **Tag selected** - Add or change tags for the selected objects
  * **Color selected** - Apply custom colors to the selected objects
  * **Copy selected IDs** - Copy the object IDs to clipboard for reference

<figure><img src="/files/qiSgLB7Y8cudjlNUBozU" alt=""><figcaption><p>Shift-drag allows you to select objects, revealing a popup menu to allow deletion, tagging, coloring, and identification by ID</p></figcaption></figure>

{% hint style="info" %}
The selection tool is particularly useful for cleaning up results from automated segmentation. You can quickly remove falsely identified objects or select groups of objects to apply a consistent tag.
{% endhint %}

## Object browser and filtering

The Object Browser provides powerful tools for managing which objects are visible in your view:

<figure><img src="/files/5XpVYmMQ24Q9tURJFjYT" alt="" width="563"><figcaption><p>The Filters panel shows options for showing and hiding particular tags, plus property-value and advanced filters</p></figcaption></figure>

Key features include:

* **Tag filtering** - Filter objects by their tags (e.g., "nucleus" or "Brightfield blob")
* **Tag match options** - Choose if objects should match "Any" or "All" of the selected tags
* **Current frame only** - When enabled, shows only objects in the currently displayed time frame in the object list (helpful for time-lapse data)
* **Show annotations from hidden layers** - By default, annotations remain visible even when their corresponding layer is hidden; toggle this off to hide annotations when their layer is hidden

### Advanced filtering options

The Object Browser offers three powerful filtering mechanisms:

1. **Property value filter** - Filter objects based on measurements like area, intensity, or other computed properties
2. **Annotation ID filter** - Find specific objects by their unique IDs
3. **Region filter** - Draw a region of interest and show only objects within that area

These filters can be combined to precisely target objects meeting multiple criteria.

## Annotation list

The Annotation List provides a detailed tabular view of all objects in your dataset:

<figure><img src="/files/HZQ1iI9wCx2TdKqeBYBd" alt="" width="563"><figcaption><p>The annotation list shows all your objects</p></figcaption></figure>

The list offers several useful features:

* **Customizable columns** - Show or hide information like Annotation ID, Index, Shape, Tags, XY coordinates, Z position, and Time
* **Sorting** - Click any column header to sort by that property
* **Navigation** - Click on any row to navigate directly to that object in the image viewer
* **Bulk actions** - Select multiple objects using the checkboxes and perform actions like deletion or tagging
* **Pagination** - For datasets with many objects, navigate through pages with the pagination controls

{% hint style="info" %}
For very large datasets (hundreds of thousands of objects or more), NimbusImage loads annotations lazily and handles the list on the server so everything stays responsive. See [Working with large annotation datasets](/documentation/analyzing-image-data-with-objects-connections-and-properties/large-annotation-datasets).
{% endhint %}

## Working with properties

Properties allow you to measure features of your objects. These measurements can be displayed alongside your objects and used for filtering:

<figure><img src="/files/DLXohR06ugYeq97qmUNU" alt=""><figcaption><p>The Measure objects panel: create new properties on the left, and manage the properties already computed for your objects on the right</p></figcaption></figure>

From the Properties panel, you can:

* **View available properties** - See what measurements are available for each object type
* **Show in list** - Select which properties should appear in the Annotation List
* **Use as filter** - Enable properties to be used for filtering in the Object Browser
* **Measure objects** - Create new properties by applying different measurement algorithms to your objects

{% hint style="info" %}
Press "t" while viewing your image to show property values directly on the objects themselves, making it easy to visualize measurements in context.
{% endhint %}


# Working with large annotation datasets

NimbusImage can visualize very large annotation datasets — hundreds of thousands, or even millions, of objects — while staying responsive. This is especially useful for spatial data (for example, Xenium datasets with hundreds of thousands of cells).

<figure><img src="/files/Dw12GfUyRFZEtHSs8WMJ" alt=""><figcaption><p>A Xenium H&#x26;E slide with nearly 709,000 cell annotations. The indicator at the top ("Showing 15,900 of 708,780 in view") reflects the lazy-loading described below — only a subset is drawn at a time to keep navigation smooth.</p></figcaption></figure>

{% hint style="info" %}
This works automatically. You don't need to turn anything on: NimbusImage detects when a dataset is large and switches to the lazy-loading behavior described below. Smaller datasets behave exactly as before, loading every object fully at every zoom level.
{% endhint %}

## How lazy loading works

To stay fast with huge numbers of objects, NimbusImage avoids loading everything at once. Instead, it loads and draws only what you need to see:

* **Stubs load first.** Each annotation initially loads as a lightweight "stub" — its position and metadata, but not its full outline coordinates. Loading stubs is fast even for very large datasets.
* **Shapes fill in on demand.** As you view an area, NimbusImage fetches the full coordinates ("hydrates") for the objects in your viewport, prioritizing larger objects and anything you've selected.
* **Dots stand in for shapes.** When more objects are in view than can be drawn as full outlines, the extras appear as small dots so you can still see where everything is. Zoom in and the outlines fill in as fewer objects compete for the budget.
* **Panning and zooming load more.** As you navigate, NimbusImage loads detail for the newly visible area and keeps a cache of recently seen shapes, so revisiting an area is instant.

The result is that scrolling, zooming, and panning stay smooth even on datasets that would previously have been too large to open comfortably.

## The object list for large datasets

The [Annotation List](/documentation/analyzing-image-data-with-objects-connections-and-properties/interacting-with-objects#annotation-list) adapts to dataset size:

* For datasets below a threshold, the list works entirely in your browser, exactly as before.
* For larger datasets, filtering, sorting, and pagination happen **on the server**, so the list stays fast even with hundreds of thousands of objects. Property-value filters are also applied server-side.

{% hint style="info" %}
In server-side mode, changing a filter returns the list to the first page.
{% endhint %}

## Advanced settings for large numbers of annotations

The defaults suit most datasets, but power users can tune the lazy-loading behavior. Open the **Settings** panel and expand **"Advanced settings for large numbers of annotations."**

{% hint style="warning" %}
Showing more annotations at once makes panning large datasets slower. Increase these limits gradually. Each setting has an allowed range; if you enter a value outside it (or one that conflicts with another setting), NimbusImage snaps it to a legal value and briefly shows an "Adjusted to …" note.
{% endhint %}

* **Stub mode threshold** (default: 100,000; range: 1,000–200,000) — The dataset annotation count above which stub-only (lazy) mode activates: stubs load first, and coordinates and property values load on demand. Independent of the render budget below.
* **Max visible annotations** (default: 50,000; range: 1,000–200,000) — The maximum number of annotations drawn per frame (as dots or shapes). This is also the size gate: datasets at or below this value render fully at every zoom. Higher values show more at once but make panning large datasets slower.
* **Max hydrated annotations** (default: 20,000; range: 500–200,000) — The maximum number of annotations drawn as full shapes per refresh; the rest show as dots. Cannot exceed **Max visible annotations**.
* **Hydration cache cap** (default: 40,000; range: 500–200,000) — The total cap on cached full-shape annotations. The cache accumulates across pans and zooms; least-recently-used shapes are evicted once the cap is exceeded (selected objects are protected until the selection alone exceeds the cap). Cannot be below **Max hydrated annotations**.
* **Zoomed-out coverage target** (default: 0.3; range: 0.01–1) — The fraction of the screen that rendered dots may cover when fully zoomed out (only for datasets larger than the render cap). Lower values give a sparser, cleaner overview. The budget doubles per zoom level up to the cap.
* **Viewport refresh threshold** (default: 0.2; range: 0.01–2) — How much the zoom or pan must change (for example, 0.2 = 20% of the viewport) before the view re-renders and re-hydrates. Higher values mean fewer refreshes and less loading churn while navigating.
* **Global threshold (all layers)** (default: on) — When on, the visibility threshold applies to the total number of annotations across all layers. When off, each layer is checked independently.


# Importing and exporting objects and properties

NimbusImage provides flexible options for exporting your analysis data, allowing you to perform additional analysis in external tools, back up your work, or transfer annotations between datasets. This section covers the different export formats and options available.

## Exporting data for analysis

After completing your image analysis in NimbusImage, you can export your data in several formats:

1. **CSV format** - For spreadsheet analysis in tools like Excel, R, or Python
2. **TSV format** - Tab-separated values, useful when property names contain commas
3. **JSON format** - For complete data backup or transfer between datasets

### Exporting properties as CSV or TSV

CSV export is ideal for statistical analysis and data visualization in external tools:

1. Open the **Import / export data** menu in the top toolbar
2. Select **"Export CSV"**
3. Configure your export options:
   * **Scope**: Export the current dataset only, or all datasets in the collection
   * **Annotations to Export**: All, filtered, or selected annotations
   * **File Format**: Choose between CSV (comma-separated) and TSV (tab-separated). CSV is the default.
   * **Property Export Options**: Choose to export all properties, only listed properties, or select specific properties
   * **Undefined Value Handling**: Decide how to represent missing values (Empty string, NA, or NaN)
4. Enter a filename
5. Click "DOWNLOAD"

The resulting file contains:

* Object identifiers and metadata (Id, Channel, XYZ coordinates, Time)
* Object tags and attributes
* All selected property values

<figure><img src="/files/KGKaomtCjhWSojqBEfqn" alt="" width="563"><figcaption><p>The export dialog allows you to customize the file format, which properties to include, and how to handle missing values</p></figcaption></figure>

{% hint style="info" %}
We recommend using the empty string option for undefined values, because it is generally recognized by most analysis software.
{% endhint %}

{% hint style="info" %}
If your property names contain commas (from older tag-based naming), the export dialog will display a warning recommending TSV format. TSV avoids column misalignment issues that commas in property names can cause in CSV files. Property names with commas are automatically quoted in CSV exports, but TSV is the more reliable option.
{% endhint %}

### Exporting complete annotation data as JSON

The JSON export provides a comprehensive record of all annotation data:

1. Open the **Import / export data** menu in the top toolbar
2. Select **"Export to JSON"**
3. Choose what to include:
   * Export annotations (objects)
   * Export annotation connections
   * Export properties
   * Export property values
4. Enter a filename
5. Click "EXPORT SELECTED ITEMS"

<figure><img src="/files/xGJqs49iZvC6ulh3ZZ1c" alt="" width="563"><figcaption><p>The JSON export dialog lets you select exactly which components of your analysis to include</p></figcaption></figure>

The exported JSON file contains:

* Complete geometric data for all annotations (coordinates, shapes, colors)
* All connection information between objects
* Property definitions and calculated values
* Metadata about the dataset

{% hint style="info" %}
JSON export is particularly valuable for:

* Creating a complete backup of your analysis
* Transferring annotations between compatible datasets
* Advanced programmatic analysis using the complete data structure
* Archiving analysis results alongside raw data
  {% endhint %}

## Importing annotation data

NimbusImage allows you to import previously exported JSON files, making it possible to:

1. Restore annotations from backups
2. Transfer annotations between compatible datasets
3. Share analysis with collaborators

To import annotation data:

1. Navigate to the dataset where you want to import annotations
2. Open the **Import / export data** menu in the top toolbar
3. Select **"Import from JSON"**
4. Select your JSON file
5. Review the import options
6. Click "IMPORT"

{% hint style="warning" %}
When importing annotations, be aware that:

* The target dataset should have a compatible structure with the source dataset
* Importing will not overwrite existing annotations unless explicitly configured to do so
* For time-lapse datasets, ensure the time points in the imported data match the structure of your target dataset
  {% endhint %}

## Data ownership and transparency

NimbusImage's export capabilities ensure that you maintain complete ownership of your analysis data. By supporting standard formats like CSV and comprehensive JSON exports, you can:

* Perform advanced analysis in your preferred tools
* Maintain complete backups of your work
* Share results transparently with collaborators
* Integrate NimbusImage analysis into broader workflows
* Create reproducible analysis pipelines

The combination of interactive analysis within NimbusImage and flexible data export options provides a powerful workflow that respects scientific integrity while maintaining ease of use.


# Image processing

Images often can be improved through various image processing techniques. These are for things like background correction to remove uneven illumination, image registration to fix shaky timelapses, and enhance spots.

NimbusImage supports a number of these image processing techniques and we are planning to make more in the near future.

## Overall workflow

The image processing workflow in NimbusImage follows these steps:

1. **Select "ADD NEW TOOL"** from the Toolset panel
2. **Choose a processing tool** (such as "Crop") and create the tool
3. **Configure the tool parameters** as needed in the worker panel that appears after clicking on the tool
4. **Run the worker process** to apply the selected tool to your image
5. **Review results** a new dropdown appears just below the dataset navigator that allows you to switch between the orignal and processed images

<div align="left"><figure><img src="/files/gF5ogCpj4wramtO9zE9Q" alt=""><figcaption><p>A processing tool's worker panel (here, Crop) where you configure parameters and click Compute</p></figcaption></figure></div>

<div align="left"><figure><img src="/files/qXM9fTdTq3cLMMdzRguW" alt="" width="314"><figcaption><p>After processing, a "Select Image" dropdown lets you switch between the original and the processed images</p></figcaption></figure></div>

## Crop

The Crop tool allows you to reduce your image dimensions by selecting only a portion of the original image. This is useful for focusing on regions of interest, removing unnecessary image areas. You can both remove entire slices and also crop to particular regions.

### How to use

1. **Add the Crop tool** by clicking the "ADD NEW TOOL" button in the Toolset panel
2. **Configure crop parameters** using one of the following methods:
   * **XY Range**: Specify which XY positions to retain (especially useful for multi-position datasets)
   * **Z Range**: Specify which Z-slices to retain (for 3D images)
   * **Time Range**: Specify which time points to retain (for time-lapse sequences)
   * **Crop Rectangle**: Select a previously drawn rectangle or polygon annotation to define the crop region.
3. **Process the image** by running the worker
4. **Review the result** by switching between "Original image" and "cropped" in the dropdown menu

### Parameters

* **XY Range**: Enter position numbers to retain (format: "1-3, 5-8"). Default is all positions.
* **Z Range**: Enter Z-slice numbers to retain (format: "1-3, 5-8"). Default is all Z-slices.
* **Time Range**: Enter time point numbers to retain (format: "1-3, 5-8"). Default is all time points.
* **Crop Rectangle**: Select a tag that identifies a rectangle or polygon annotation to define the crop region.

### Technical details

The Crop tool works by creating a new image that contains only the specified region of interest from the original image. For annotation-based cropping, the tool uses the bounding box coordinates of the selected annotation to define the crop region. All metadata from the original image is preserved in the cropped output.

## Registration

The Registration tool corrects for movement and shift in time-lapse image sequences, helping to stabilize your data for more accurate analysis. This is particularly useful for long time-lapse experiments where sample drift occurs. It allows you to use both automated algorithms and manual control points to guide the registration process; you can even use both at the same time.

### How to use

1. **Add the Registration tool** by clicking the "ADD NEW TOOL" button in the Toolset panel
2. **Set the reference** parameters:
   * **Reference Z Coordinate**: Specify which Z-slice to use as reference
   * **Reference Time Coordinate**: Specify which time point to use as reference
   * **Reference Channel**: Select which channel to use for registration calculations
   * **Reference region tag**: Optionally restrict registration to a specific region of interest
3. **Select correction options**:
   * **Channels to correct**: Check which channels should be adjusted
   * **Control point tag**: Optionally use point annotations to guide registration
   * **Algorithm**: Choose the registration method that best suits your data
4. **Process the image** by running the worker
5. **Review the result** by switching between "Original image" and "registered" in the dropdown menu

### Parameters

* **Apply to XY coordinates**: Specify which XY positions to correct (format: "1-3, 5-8")
* **Reference Z Coordinate**: The Z-slice used as reference (default: 1)
* **Reference Time Coordinate**: The time point used as reference (default: 1)
* **Reference Channel**: Channel used for calculating registration
* **Channels to correct**: Select which channels to apply registration to
* **Reference region tag**: Optional tag for a region to use for registration calculations
* **Control point tag**: Optional tag for point annotations to use as registration anchors
* **Apply algorithm after control points**: When checked, applies the algorithm after control point corrections. For instance, you can use control points to roughly register your images and then use the algorithm to fine-tune the registration.
* **Algorithm**: Registration method to use (strongly recommended to use the default "Translation" algorithm):
  * **None (control points only)**: Uses only control points for registration
  * **Translation**: Corrects for X/Y movement (shifting)
  * **Rigid**: Corrects for translation and rotation
  * **Affine**: Corrects for translation, rotation, and scaling

### Technical details

The Registration tool calculates transformation matrices between time points using the StackReg algorithm from the PyStackReg library. For time-lapse sequences, each frame is aligned relative to the reference frame, creating a stable series where features remain in consistent positions.

The tool can use manual control points (annotated points that indicate the same feature across time points) to guide registration or can automatically detect and track features. When both are used, control points provide initial guidance followed by algorithmic refinement.

## Histogram Matching

The Histogram Matching tool normalizes intensity distributions across multiple images by matching their histograms to a reference image. This is particularly useful for correcting intensity variations in time-lapse sequences or multi-position acquisitions, ensuring consistent visualization and analysis.

### How to use

1. **Add the Histogram Matching tool** by clicking the "ADD NEW TOOL" button in the Toolset panel
2. **Set the reference image** by specifying:
   * **Reference XY Coordinate**: The position to use as reference
   * **Reference Z Coordinate**: The Z-slice to use as reference
   * **Reference Time Coordinate**: The time point to use as reference
3. **Select channels to correct** by checking the appropriate channel boxes
4. **Process the image** by running the worker
5. **Review the result** by switching between "Original image" and "normalized" in the dropdown menu

### Parameters

* **Reference XY Coordinate**: The XY position to use as intensity reference (default: 1)
* **Reference Z Coordinate**: The Z-slice to use as intensity reference (default: 1)
* **Reference Time Coordinate**: The time point to use as intensity reference (default: 1)
* **Channels to correct**: Select which channels should be histogram-matched

### Technical details

The Histogram Matching tool works by analyzing the intensity distribution of each specified channel in the reference image, then transforming the histograms of all other images to match that reference. This process preserves the relative differences in intensity within each image while making the overall intensity ranges consistent across the entire dataset.

This technique is especially valuable when:

* Comparing images acquired with different exposure settings
* Analyzing time-lapse data where photobleaching causes intensity decay over time
* Standardizing multi-position acquisitions with varying background intensities
* Preparing datasets for quantitative analysis that requires consistent intensity values

The implementation uses scikit-image's `match_histograms` function to perform precise histogram transformations while maintaining image details.

## Gaussian Blur

The Gaussian Blur tool smooths images by applying a Gaussian filter, which reduces noise and detail. This is useful for removing high-frequency noise, creating soft focus effects, or as a preprocessing step for other analysis techniques.

### How to use

1. **Add the Gaussian Blur tool** by clicking the "ADD NEW TOOL" button in the Toolset panel
2. **Configure the blur settings**:
   * **Sigma**: Control the blur strength (higher values create stronger blurring)
   * **Channel**: Select the default channel to blur
   * **All channels**: Check which channels should be processed
3. **Process the image** by running the worker
4. **Review the result** by switching between "Original image" and the blurred result in the dropdown menu

### Parameters

* **Sigma**: Determines the strength of the blur effect (range: 0-100, default: 20)
* **Channel**: The default channel to blur
* **All channels**: Select multiple channels to apply blurring to

### Technical details

The Gaussian Blur tool applies a Gaussian filter to the selected channels of your image. This filter uses a Gaussian function (bell curve) to create a weighted average of each pixel's neighborhood. The sigma parameter controls the standard deviation of this Gaussian function - larger values consider pixels from a wider area, creating stronger blurring effects.

The implementation uses scikit-image's `filters.gaussian` function to perform the blurring operation. The tool preserves the original image's data type and dynamic range while applying the blur effect proportionally to the image's intensity values.

This technique is particularly useful for:

* Reducing random noise in images
* Softening edges and textures
* Preprocessing images before feature detection or segmentation
* Creating depth-of-field effects

## Deconvolution (Deconwolf)

The Deconvolution tool uses [deconwolf](https://github.com/elgw/deconwolf), an open-source 3D deconvolution engine, to computationally reverse the optical blurring inherent in fluorescence microscopy images. It applies the Richardson-Lucy algorithm with a theoretically generated Born-Wolf point spread function (PSF) to produce sharper images with improved contrast and resolution. GPU acceleration is supported and enabled by default.

This tool is designed for fluorescence microscopy Z-stacks. If the input image has only a single Z-slice, deconvolution is not applicable and the image will pass through unchanged.

### How to use

1. **Add the Deconvolution tool** by clicking the "ADD NEW TOOL" button in the Toolset panel
2. **Select channels to deconvolve** using the channel checkboxes. Unselected channels pass through to the output unchanged.
3. **Set optical parameters** either manually or by enabling "Auto-extract from ND2" to read them from your image metadata:
   * **Numerical Aperture (NA)**: The NA of your objective lens
   * **Refractive Index**: The immersion medium refractive index (1.0 for air, 1.515 for oil)
   * **Pixel Size XY**: Lateral pixel size in nanometers
   * **Z Step**: Axial step size between Z-slices in nanometers
   * **Emission Wavelength**: Emission wavelengths for your channels
4. **Adjust processing settings** as needed:
   * **Iterations**: Number of Richardson-Lucy iterations (higher = sharper but slower)
   * **Use GPU**: Enable for faster processing (falls back to CPU automatically if unavailable)
   * **Tile Size / Overlap**: For processing large images in tiles
5. **Process the image** by running the worker
6. **Review the result** by switching between "Original image" and the deconvolved result in the dropdown menu

### Parameters

* **Channels to deconvolve**: Select which channels to deconvolve; unselected channels pass through unchanged
* **Auto-extract from ND2**: Attempt to read optical parameters (pixel size, NA, refractive index, emission wavelengths) from image metadata. Any parameters not found fall back to the manually entered values.
* **Numerical Aperture (NA)**: Numerical aperture of the objective lens (range: 0.1–1.7, default: 0.75)
* **Refractive Index (ni)**: Immersion medium refractive index (range: 1.0–1.6, default: 1.0)
* **Pixel Size XY (nm)**: Lateral pixel size in nanometers (range: 1–10000, default: 325)
* **Z Step (nm)**: Axial step size between Z-slices in nanometers (range: 1–50000, default: 5000)
* **Emission Wavelength (nm)**: Comma-separated emission wavelengths, one per channel in order. A single value applies to all channels. Defaults to 450, 520, 580, 680 nm if left blank.
* **Iterations**: Number of Richardson-Lucy iterations (range: 1–200, default: 50). Typical range is 20–100.
* **Use GPU**: Enable GPU acceleration via OpenCL. Falls back to CPU automatically if no compatible GPU is available.
* **Tile Size (pixels)**: Maximum tile dimension for processing large images (range: 256–8192, default: 1024). Images exceeding this size in either dimension are processed in tiles.
* **Tile Overlap (pixels)**: Overlap between adjacent tiles to reduce edge artifacts (range: 0–500, default: 100).

### Technical details

The tool wraps two deconwolf command-line programs:

* **`dw_bw`** generates a theoretical PSF using the Born-Wolf diffraction model given the optical parameters. The PSF axial size is set to `2 × num_z_slices − 1` to cover the full extent of the image.
* **`dw`** performs Richardson-Lucy deconvolution of each Z-stack against the corresponding PSF.

Each Z-stack (grouped by XY position, timepoint, and channel) is deconvolved independently. The deconvolved and pass-through frames are then assembled into a multi-dimensional TIFF preserving the original image structure.

**GPU acceleration**: When enabled, deconvolution is attempted on the GPU first. If OpenCL fails (e.g., no compatible GPU is present), the worker automatically falls back to CPU processing, so the tool is safe to use on any machine.

**Tiling**: For images where either dimension exceeds the tile size, deconwolf's built-in tiling mode splits the image into overlapping tiles, deconvolves each independently, and stitches them back together. The overlap parameter controls how much adjacent tiles share to minimize edge artifacts.

**ND2 metadata extraction**: When auto-extraction is enabled, the worker reads pixel size, NA, refractive index, and emission wavelengths from the image's ND2 metadata. Any parameters not found in the metadata fall back to the manually entered values.

For more details on the deconwolf algorithm, see: Wernersson, E. (2024). deconwolf — Large deconvolution with GPU or CPU. *SoftwareX*, 27, 101747.


# Snapshots

How to use Snapshots to "bookmark" and download image and movies from your data

Snapshots serve a few purposes:

1. Bookmark a location in your dataset to facilitate sharing.
2. Download images of specific regions for publication purposes.
3. Download movies from your dataset to make it easy to share these with people.

## Making a Snapshot

Making a snapshot is easy. Just open the Snapshot pane by clicking here.

Drag the red rectangle to cover the area of interest. The pixel-precise location area are also given in numerical fields, so you can make it precisely the size you would like. A couple convenience functions are there:

1. **Set frame to current viewport.** If you've zoomed into a place you like, then click this button and the frame of the Snapshot will be set to precisely the region you zoomed to.
2. **Set frame to maximum.** This button will reset the frame to contain the entire image in the view.

## Selecting multiple Snapshots

You can select multiple snapshots using checkboxes next to each snapshot in your snapshot list. This makes it easy to:

* Download images for multiple snapshots at once
* Delete multiple snapshots simultaneously
* Organize and manage your snapshot collection efficiently

Simply check the boxes next to the snapshots you want to work with, then choose the appropriate action from the available options.

## Downloading Images and Movies

### Image Download Options

<div align="left"><figure><img src="/files/TRgwwlM15jnnBYMTnjzs" alt="" width="375"><figcaption><p>Downloading options</p></figcaption></figure></div>

There are multiple ways in which you can download Snapshot images for use in a publication or presentation.

**Scaled layers vs Raw channels.** You can either download contrasted images or raw pixel value images. Note that all contrasts are linear and hence allowed by most major journals.

**Format.** Select the desired file format for your downloaded images. PNG is the default option, which preserves image quality.

**Layer download options.** There are several ways you can download your images:

1. **Download images for current location.** Gives you images for the current snapshot location with these options:
   * *All layers.* Provides an image file for each layer separately.
   * *Composite layers.* Provides a composite image with all layers merged together, matching what is on screen.
   * *Individual layers.* Allows you to download an image just for the specific layer selected.
2. **Download images for all snapshots.** Applies the selected download options to all snapshots in your dataset.
3. **Download movie for current location.** Creates a movie from the current snapshot location.
4. **Download screenshot of current viewport.** Allows you to download a "screenshot" of exactly what you see on screen, including all annotations and the scale bar if enabled.

### Scale Bar Options

You can add a scale bar to your exported images by checking the "Add scalebar" option. Click the settings icon next to the scale bar option to customize:

<div align="left"><figure><img src="/files/FHz9ViRXgQWpSsQhI7Jc" alt="" width="375"><figcaption></figcaption></figure></div>

**Pixel size options:**

* Use pixel size from dataset (based on pixel size reported in the microscope metadata)
* Manually select pixel size

**Scalebar length options:**

* Automatic scalebar length (automatically calculated to be optimal for most cases)
* Manually select scalebar length

You can also adjust the color of the scale bar using the color slider.

### Time-lapse Movie Options

When downloading a movie from your dataset, you have several options to customize:

<div align="left"><figure><img src="/files/eswAR20OrGeDdO42gekg" alt="" width="375"><figcaption></figcaption></figure></div>

**Time Range:**

* Start Time: The beginning frame number (default: 1)
* End Time: The final frame number

**Frames per Second:** Controls the playback speed of your movie (default: 10 fps)

**Download Format Options:**

* Download zipped sequence of image files (useful if you want to make a movie with some other software)
* Download GIF (useful for sharing on social media)
* Download movie (video file for presentations, WebM format)

**Time Stamp Options:**

* Insert time stamp: Adds a time indicator to each frame
* Initial time: Starting value for the time stamp (default: 0)
* Time step: Increment between frames (default: 1)
* Units: Time units to display (hours, minutes, seconds, etc.)

After configuring your settings, click "Download Movie" to generate and download your time-lapse movie.


# Time lapse mode

How to track and analyze objects across time using Time lapse mode

Time lapse mode in NimbusImage provides powerful capabilities for tracking and analyzing objects across time points. This feature is particularly useful for cell tracking, movement analysis, and other time-dependent studies.

## Enabling Time lapse mode

When working with time lapse datasets, the Time lapse mode option automatically becomes available in the interface:

<div align="left"><figure><img src="/files/UJB0eHJOxcU5EOA09JYp" alt="" width="314"><figcaption></figcaption></figure></div>

1. Look for the "Time lapse mode" checkbox in the variable navigation panel
2. Check the box to enable tracking visualization and special time lapse features

When enabled, Time lapse mode reveals additional options in the same panel (shown above): a **Track window** slider, a **Tags** filter, a **Show labels** toggle, and a **Delete all timelapse connections** button.

## Understanding tracks and connections

In Time lapse mode, objects are connected across time points to form "tracks" that represent the same biological entity (like a cell) over time.

### Visualizing tracks

Tracks appear as connected lines between objects across different time points:

<figure><img src="/files/DDKrPzc8XBWdRpBL1zWW" alt=""><figcaption><p>Two tracked cells at the current time point ("Curr T=9"), each linked back through earlier frames to its start ("T=1")</p></figcaption></figure>

Key features of track visualization:

* **Current time point**: The current time point is highlighted with "Curr T=X" label and typically appears larger
* **Connected objects**: All objects connected to the current object are shown as a track
* **Time labels**: Each object shows its time point (T=1, T=7, etc.). These labels are clickable to take you right to that time point.
* **Connection colors**:
  * **Colored connections**: Normal connections between consecutive time points. Each color represents a different track.
  * **Red connections**: Connections that skip time points (track connecting from e.g. t=8 to t=10)
  * **Line thickness**: Forward-in-time connections are thicker than backward-in-time connections

### Track window setting

The "Track window" slider controls how many time points before and after the current time point are shown in the track visualization:

* Higher values show more of the track's history and future
* Lower values focus on just the immediate connections
* Adjust based on the density of your data and analysis needs

The tags field allows you to only do time-lapse analysis on a subset of objects defined by the specified tags.

Delete all timelapse connections will delete all connections made by the "Connect timelapse" tool and also the "Lasso connect".

## Creating and editing tracks

### Using Connect timelapse tool

NimbusImage provides a dedicated tool for connecting objects across time:

Key settings:

* **Object to connect tag**: Select which type of objects to connect (based on their tags)
* **Connect across gaps**: Allows connecting objects even when there are missing time points
* **Max distance**: Maximum pixel distance between objects in consecutive frames to be considered for connection

To use the tool:

1. Create the Tool from the toolset menu
2. Configure the settings
3. Click "COMPUTE" to automatically connect objects based on proximity and settings

### Using Lasso connect for manual tracking

One of the most powerful features is the ability to use a lasso tool to manually define tracks:

1. Create a lasso connect tool from the toolset menu
2. Draw a lasso around the objects you want to connect across time
3. NimbusImage will **automatically connect them sequentially by time point**

This feature is particularly helpful for:

* Connecting "orphaned" objects to existing tracks
* Creating new tracks from scratch
* Fixing tracking errors where automatic tracking failed

Here's an example of connecting up an "orphan" cell at t=8 (orphans are in gray). The track is connected up until t=7 and from t=9 onwards, but sometimes you get a gap in the track because of a missed cell segmentation. Here, we drew in the missing cell manually, but then you want to connect up the track:

<div align="left"><figure><img src="/files/dzJkrbHusoR6hdoNQyBV" alt="" width="563"><figcaption></figcaption></figure></div>

Using "Lasso connect", you can just circle (sloppily) all the points in the track, and it will "auto-magically" connect the tracks up sequentially:

<div align="left"><figure><img src="/files/HVQ9xgYmWZ4rTrlmeEkt" alt="" width="563"><figcaption></figcaption></figure></div>

## Navigating time with tracks

Tracks provide an intuitive way to navigate through time:

* **Click on any point in a track** to jump directly to that time point
* Use this to quickly inspect the history or future of a specific object
* Especially useful when analyzing division events or complex behaviors

## Best practices for time lapse analysis

1. **Start with automatic connections** using the Connect timelapse tool
2. **Review and fix tracks** using the lasso connect tool for any errors
3. **Use track window setting** to adjust visualization density
4. **Enable "Show labels"** to see time point information directly on objects
5. **Create properties** to analyze track information (velocity, displacement, etc.)

## Exporting time lapse data

Once you've established tracks, you can:

1. Create properties to measure changes over time
2. Export track data to CSV for further analysis in Python/R
3. Create snapshots to document specific tracking events
4. Download time lapse movies showing your tracks (see [Snapshots](/documentation/snapshots) for more details)

## Common applications

Time lapse mode is particularly useful for:

* Cell migration tracking
* Mitotic event analysis
* Particle movement studies
* Growth measurements over time
* Interaction analysis between objects

By combining NimbusImage's flexible object tagging system with Time lapse mode, you can create sophisticated tracking analyses that capture the dynamic nature of your biological systems.