anybioimage 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,148 @@
1
+ ---
2
+ name: anybioimage
3
+ description: "Integrate and use the anybioimage BioImageViewer widget to display biological images, overlays, and annotations in Jupyter and marimo notebooks. Use this skill when asked to display images with BioImageViewer, add mask overlays or segmentation results, annotate images with rectangles/polygons/points, enable SAM (Segment Anything Model) for interactive segmentation, load multi-dimensional 5D images (TCZYX) with BioImage, show multichannel fluorescence images with per-channel colors and contrast, export annotations as DataFrames, or integrate anybioimage into a marimo or Jupyter workflow."
4
+ ---
5
+
6
+ # anybioimage Skill
7
+
8
+ `anybioimage` provides `BioImageViewer`, an interactive widget for visualizing biological images with mask overlays, annotations, and SAM segmentation in Jupyter and marimo notebooks.
9
+
10
+ ## Installation
11
+
12
+ ```bash
13
+ uv pip install -e ".[all]" # Full install with all dependencies
14
+ uv pip install -e ".[sam]" # SAM support only
15
+ ```
16
+
17
+ ## Quickstart
18
+
19
+ ### Jupyter
20
+
21
+ ```python
22
+ from anybioimage import BioImageViewer
23
+ import numpy as np
24
+
25
+ viewer = BioImageViewer()
26
+ viewer.set_image(np.random.randint(0, 255, (512, 512), dtype=np.uint8))
27
+ viewer # Display inline
28
+ ```
29
+
30
+ ### Marimo
31
+
32
+ ```python
33
+ import marimo as mo
34
+ from anybioimage import BioImageViewer
35
+
36
+ @app.cell
37
+ def _():
38
+ viewer = BioImageViewer()
39
+ viewer.set_image(image_data)
40
+ return mo.ui.anywidget(viewer)
41
+ ```
42
+
43
+ **Marimo rules:**
44
+ - Always wrap with `mo.ui.anywidget(viewer)`
45
+ - Only edit code inside `@app.cell` decorators
46
+ - Run `marimo check --fix` after editing
47
+
48
+ ## Image Input
49
+
50
+ | Input | Method | Notes |
51
+ |-------|--------|-------|
52
+ | numpy array | `set_image(arr)` | Auto-squeezed to 2D |
53
+ | BioImage | `set_image(BioImage("file.tif"))` | Full 5D, lazy loading |
54
+ | OME-Zarr | `set_image(BioImage("file.ome.zarr"))` | Multi-resolution |
55
+
56
+ ### BioImage (5D multichannel)
57
+
58
+ ```python
59
+ from bioio import BioImage
60
+
61
+ viewer = BioImageViewer()
62
+ img = BioImage("multichannel.ome.tiff")
63
+ viewer.set_image(img)
64
+ # Dimension controls (T, C, Z) appear automatically in the UI
65
+ ```
66
+
67
+ ## Masks / Overlays
68
+
69
+ ```python
70
+ # Add a segmentation mask
71
+ mask_id = viewer.add_mask(labels_array, name="Nuclei", color="#ff0000", opacity=0.5)
72
+
73
+ # Contour-only overlay
74
+ mask_id2 = viewer.add_mask(cell_labels, name="Cells", contours_only=True, contour_width=2)
75
+
76
+ # Convenience: clear all + add one
77
+ viewer.set_mask(labels_array, name="Segmentation")
78
+
79
+ # Update settings
80
+ viewer.update_mask_settings(mask_id, opacity=0.8, visible=False)
81
+
82
+ # Remove
83
+ viewer.remove_mask(mask_id)
84
+ viewer.clear_masks()
85
+
86
+ # Inspect
87
+ print(viewer.masks_df) # DataFrame: id, name, visible, opacity, color, contours
88
+ ```
89
+
90
+ `color` accepts hex strings. Colors auto-cycle from a 10-color palette if not specified.
91
+
92
+ ## Annotations
93
+
94
+ ```python
95
+ # Access as DataFrames (user-drawn or programmatically set)
96
+ rois = viewer.rois_df # columns: id, x, y, width, height
97
+ polygons = viewer.polygons_df # columns: id, points (list of {x, y})
98
+ points = viewer.points_df # columns: id, x, y
99
+
100
+ # Export
101
+ rois.to_csv("rois.csv")
102
+
103
+ # Set programmatically
104
+ viewer.rois_df = existing_rois_df
105
+
106
+ # Clear
107
+ viewer.clear_rois()
108
+ viewer.clear_polygons()
109
+ viewer.clear_points()
110
+ viewer.clear_all_annotations()
111
+ ```
112
+
113
+ **Drawing tools (keyboard shortcuts):** Pan (P), Select (V), Rectangle (R), Polygon (G), Point (O)
114
+
115
+ ## SAM Integration
116
+
117
+ ```python
118
+ # Enable (downloads model on first use via Ultralytics)
119
+ viewer.enable_sam("mobile_sam") # Recommended: ~40MB, fast
120
+
121
+ # Draw rectangles or click points → SAM auto-segments
122
+ # SAM results appear as a mask overlay layer
123
+
124
+ viewer.clear_sam_masks() # Clear SAM results
125
+ viewer.disable_sam() # Disable and unload model
126
+ ```
127
+
128
+ Model options: `"mobile_sam"` (default), `"sam_b"`, `"sam_l"`, `"fast_sam"`
129
+
130
+ ## Visual Settings
131
+
132
+ ```python
133
+ viewer.image_visible = True
134
+ viewer.image_brightness = 0.2 # -1.0 to 1.0
135
+ viewer.image_contrast = 0.3 # -1.0 to 1.0
136
+ viewer.canvas_height = 600 # pixels
137
+
138
+ # Annotation colors
139
+ viewer.roi_color = "#ff0000"
140
+ viewer.polygon_color = "#00ff00"
141
+ viewer.point_color = "#0000ff"
142
+ viewer.point_radius = 5 # pixels
143
+ ```
144
+
145
+ ## Reference Files
146
+
147
+ - **[api_reference.md](references/api_reference.md)** — Full method signatures, all traitlets, channel settings, internal details
148
+ - **[examples.md](references/examples.md)** — Complete workflow examples (fluorescence imaging, segmentation pipelines, annotation export)
@@ -0,0 +1,234 @@
1
+ # anybioimage API Reference
2
+
3
+ ## Table of Contents
4
+ 1. [BioImageViewer — Public Methods](#public-methods)
5
+ 2. [Masks API](#masks-api)
6
+ 3. [Annotations API](#annotations-api)
7
+ 4. [SAM API](#sam-api)
8
+ 5. [Traitlets (synced state)](#traitlets)
9
+ 6. [Channel Settings](#channel-settings)
10
+ 7. [Utility Functions](#utility-functions)
11
+
12
+ ---
13
+
14
+ ## Public Methods
15
+
16
+ ### Image Loading
17
+
18
+ ```python
19
+ viewer.set_image(data)
20
+ ```
21
+ - `data`: `np.ndarray` (auto-squeezed to 2D) or `BioImage` object
22
+ - For numpy: no multi-dim controls shown
23
+ - For BioImage: full 5D support, lazy loading, channel settings auto-initialized
24
+
25
+ ---
26
+
27
+ ## Masks API
28
+
29
+ ```python
30
+ mask_id = viewer.add_mask(
31
+ labels, # np.ndarray of integer labels (0 = background)
32
+ name=None, # str, auto-generated if None
33
+ color=None, # hex str e.g. "#ff0000", auto-cycles if None
34
+ opacity=0.5, # float 0–1
35
+ visible=True, # bool
36
+ contours_only=False, # bool, show boundary contours only
37
+ contour_width=1, # int, contour thickness in pixels
38
+ ) -> str # returns unique mask_id
39
+ ```
40
+
41
+ ```python
42
+ viewer.set_mask(labels, name=None, contours_only=False, contour_width=1)
43
+ # Clears all existing masks, then adds one mask
44
+ ```
45
+
46
+ ```python
47
+ viewer.remove_mask(mask_id) # Remove a single mask by ID
48
+ viewer.clear_masks() # Remove all masks
49
+ viewer.get_mask_ids() -> list # List all current mask IDs
50
+ viewer.update_mask_settings(mask_id, **kwargs)
51
+ # Supported kwargs: name, color, opacity, visible, contours_only, contour_width
52
+ ```
53
+
54
+ ```python
55
+ viewer.masks_df # pandas DataFrame
56
+ # Columns: id, name, visible, opacity, color, contours
57
+ ```
58
+
59
+ **Color cycling palette:** 10 colors auto-assigned in order. Override with explicit `color="#rrggbb"`.
60
+
61
+ ---
62
+
63
+ ## Annotations API
64
+
65
+ All coordinates are in **image pixel space** (not screen/canvas space).
66
+
67
+ ### ROIs (Rectangles)
68
+
69
+ ```python
70
+ viewer.rois_df # get: DataFrame with columns id, x, y, width, height
71
+ viewer.rois_df = df # set: DataFrame with same columns
72
+ viewer.clear_rois()
73
+ ```
74
+
75
+ ### Polygons
76
+
77
+ ```python
78
+ viewer.polygons_df # get: DataFrame with columns id, points
79
+ viewer.polygons_df = df # set
80
+ viewer.clear_polygons()
81
+ # points column: list of dicts [{x: float, y: float}, ...]
82
+ ```
83
+
84
+ ### Points
85
+
86
+ ```python
87
+ viewer.points_df # get: DataFrame with columns id, x, y
88
+ viewer.points_df = df # set
89
+ viewer.clear_points()
90
+ ```
91
+
92
+ ### Clear all
93
+
94
+ ```python
95
+ viewer.clear_all_annotations()
96
+ ```
97
+
98
+ ### Annotation display traitlets
99
+
100
+ ```python
101
+ viewer.rois_visible = True
102
+ viewer.roi_color = "#ff0000" # hex
103
+
104
+ viewer.polygons_visible = True
105
+ viewer.polygon_color = "#00ff00" # hex
106
+
107
+ viewer.points_visible = True
108
+ viewer.point_color = "#0000ff" # hex
109
+ viewer.point_radius = 5 # int, pixels
110
+
111
+ viewer.selected_annotation_id # str, read-only (user interaction)
112
+ viewer.selected_annotation_type # "roi" | "polygon" | "point"
113
+ ```
114
+
115
+ ### Tool modes
116
+
117
+ ```python
118
+ viewer.tool_mode # "pan" | "select" | "draw" | "polygon" | "point"
119
+ # Keyboard shortcuts in viewer: P=pan, V=select, R=rectangle, G=polygon, O=point
120
+ ```
121
+
122
+ ---
123
+
124
+ ## SAM API
125
+
126
+ ```python
127
+ viewer.enable_sam(model_type="mobile_sam")
128
+ # Downloads model on first use via Ultralytics
129
+ # Supported: "mobile_sam" (~40MB), "sam_b" (~375MB), "sam_l" (~1.2GB), "fast_sam" (~140MB)
130
+
131
+ viewer.disable_sam()
132
+ viewer.clear_sam_masks()
133
+ viewer.delete_sam_label_at(x, y) # Delete SAM label at pixel coordinates
134
+ ```
135
+
136
+ **Workflow:** After `enable_sam()`, drawing a rectangle or placing a point automatically triggers SAM segmentation. Results appear as a mask layer. The rectangle/point annotation is removed after processing.
137
+
138
+ ---
139
+
140
+ ## Traitlets
141
+
142
+ These are synchronized between Python and the JavaScript frontend. All can be read/written from Python.
143
+
144
+ ### Image state
145
+
146
+ | Traitlet | Type | Description |
147
+ |----------|------|-------------|
148
+ | `image_data` | `Unicode` | Base64 PNG of current rendered frame |
149
+ | `width` | `Int` | Image width in pixels |
150
+ | `height` | `Int` | Image height in pixels |
151
+ | `image_visible` | `Bool` | Show/hide base image |
152
+ | `image_brightness` | `Float` | -1.0 to 1.0 |
153
+ | `image_contrast` | `Float` | -1.0 to 1.0 |
154
+ | `canvas_height` | `Int` | Canvas height in pixels (default 800) |
155
+
156
+ ### Multi-dimensional navigation
157
+
158
+ | Traitlet | Type | Description |
159
+ |----------|------|-------------|
160
+ | `dim_t` | `Int` | Number of timeframes |
161
+ | `dim_c` | `Int` | Number of channels |
162
+ | `dim_z` | `Int` | Number of Z-slices |
163
+ | `current_t` | `Int` | Current timeframe (0-indexed) |
164
+ | `current_c` | `Int` | Current channel (single-channel mode) |
165
+ | `current_z` | `Int` | Current Z-slice |
166
+ | `current_resolution` | `Int` | Current resolution level |
167
+ | `resolution_levels` | `List` | Available resolution levels |
168
+
169
+ ### Scenes
170
+
171
+ | Traitlet | Type | Description |
172
+ |----------|------|-------------|
173
+ | `scenes` | `List[Unicode]` | Available scene names |
174
+ | `current_scene` | `Unicode` | Active scene name |
175
+
176
+ ---
177
+
178
+ ## Channel Settings
179
+
180
+ `viewer._channel_settings` is a list of dicts, one per channel:
181
+
182
+ ```python
183
+ {
184
+ "name": str, # Channel name
185
+ "color": str, # Hex color e.g. "#00ff00"
186
+ "visible": bool,
187
+ "min": float, # Contrast lower bound (0–1, relative to data range)
188
+ "max": float, # Contrast upper bound (0–1, relative to data range)
189
+ "data_min": float, # Global data minimum for normalization
190
+ "data_max": float, # Global data maximum for normalization
191
+ }
192
+ ```
193
+
194
+ Example: set channel 0 to red, channel 1 to cyan:
195
+
196
+ ```python
197
+ settings = viewer._channel_settings.copy()
198
+ settings[0]["color"] = "#ff0000"
199
+ settings[1]["color"] = "#00ffff"
200
+ viewer._channel_settings = settings
201
+ ```
202
+
203
+ Default channel colors follow the `CHANNEL_COLORS` palette: GFP green, RFP red, DAPI blue, etc.
204
+
205
+ ---
206
+
207
+ ## Utility Functions
208
+
209
+ ```python
210
+ from anybioimage import normalize_image, array_to_base64, labels_to_rgba, hex_to_rgb, composite_channels, MASK_COLORS, CHANNEL_COLORS
211
+ ```
212
+
213
+ ```python
214
+ normalize_image(data, global_min=None, global_max=None) -> np.ndarray
215
+ # Normalize array to uint8 (0-255). Uses data range if min/max not provided.
216
+
217
+ array_to_base64(data) -> str
218
+ # Convert (H,W), (H,W,3), or (H,W,4) array to base64 PNG string.
219
+
220
+ labels_to_rgba(labels, contours_only=False, contour_width=1) -> np.ndarray
221
+ # Convert integer label array to RGBA (H,W,4). 0 = transparent.
222
+
223
+ hex_to_rgb(hex_color) -> tuple[int, int, int]
224
+ # "#ff0000" -> (255, 0, 0)
225
+
226
+ composite_channels(channels, colors, mins, maxs, data_mins=None, data_maxs=None) -> np.ndarray
227
+ # Additive blend of multiple 2D channel arrays into RGB uint8.
228
+ # channels: list of (H,W) arrays
229
+ # colors: list of hex strings
230
+ # mins/maxs: contrast bounds per channel (0-1)
231
+
232
+ MASK_COLORS # list of 10 hex colors for mask auto-assignment
233
+ CHANNEL_COLORS # list of 8 hex colors for channel auto-assignment
234
+ ```
@@ -0,0 +1,237 @@
1
+ # anybioimage Usage Examples
2
+
3
+ ## Table of Contents
4
+ 1. [Basic 2D Image Display](#basic-2d-image-display)
5
+ 2. [Multichannel Fluorescence Image](#multichannel-fluorescence-image)
6
+ 3. [Segmentation Mask Overlay](#segmentation-mask-overlay)
7
+ 4. [Multiple Mask Layers](#multiple-mask-layers)
8
+ 5. [SAM Segmentation Workflow](#sam-segmentation-workflow)
9
+ 6. [Annotation Export Pipeline](#annotation-export-pipeline)
10
+ 7. [Marimo Integration](#marimo-integration)
11
+ 8. [Large Image (OME-Zarr)](#large-image-ome-zarr)
12
+
13
+ ---
14
+
15
+ ## Basic 2D Image Display
16
+
17
+ ```python
18
+ from anybioimage import BioImageViewer
19
+ import numpy as np
20
+
21
+ viewer = BioImageViewer()
22
+ viewer.set_image(np.random.randint(0, 255, (512, 512), dtype=np.uint8))
23
+ viewer.canvas_height = 600
24
+ viewer
25
+ ```
26
+
27
+ ---
28
+
29
+ ## Multichannel Fluorescence Image
30
+
31
+ ```python
32
+ from anybioimage import BioImageViewer
33
+ from bioio import BioImage
34
+
35
+ viewer = BioImageViewer()
36
+ img = BioImage("dapi_gfp_rfp.ome.tiff") # 3-channel fluorescence
37
+ viewer.set_image(img)
38
+ # UI shows channel controls with default colors: DAPI=blue, GFP=green, RFP=red
39
+ # User can toggle channels and adjust contrast in the viewer
40
+
41
+ # Programmatically set channel colors
42
+ settings = list(viewer._channel_settings)
43
+ settings[0]["color"] = "#0000ff" # DAPI → blue
44
+ settings[1]["color"] = "#00ff00" # GFP → green
45
+ settings[2]["color"] = "#ff0000" # RFP → red
46
+ viewer._channel_settings = settings
47
+
48
+ viewer
49
+ ```
50
+
51
+ ---
52
+
53
+ ## Segmentation Mask Overlay
54
+
55
+ ```python
56
+ from anybioimage import BioImageViewer
57
+ import numpy as np
58
+ from skimage.filters import threshold_otsu
59
+ from skimage.measure import label
60
+
61
+ # Load and segment
62
+ image = np.load("nuclei.npy")
63
+ thresh = threshold_otsu(image)
64
+ binary = image > thresh
65
+ labels = label(binary) # integer label array
66
+
67
+ # Display with overlay
68
+ viewer = BioImageViewer()
69
+ viewer.set_image(image)
70
+ mask_id = viewer.add_mask(labels, name="Nuclei", color="#ff4400", opacity=0.6)
71
+
72
+ viewer
73
+ ```
74
+
75
+ ### Contours only
76
+
77
+ ```python
78
+ viewer.add_mask(labels, name="Nuclei outlines", contours_only=True, contour_width=2)
79
+ ```
80
+
81
+ ---
82
+
83
+ ## Multiple Mask Layers
84
+
85
+ ```python
86
+ viewer = BioImageViewer()
87
+ viewer.set_image(image)
88
+
89
+ # Add multiple segmentation results as separate layers
90
+ nuc_id = viewer.add_mask(nuclei_labels, "Nuclei", "#ff0000", opacity=0.5)
91
+ cell_id = viewer.add_mask(cell_labels, "Cells", "#00ff00", contours_only=True)
92
+ mito_id = viewer.add_mask(mito_labels, "Mitochondria", "#0000ff", opacity=0.4)
93
+
94
+ # Inspect all layers
95
+ print(viewer.masks_df)
96
+
97
+ # Toggle visibility
98
+ viewer.update_mask_settings(mito_id, visible=False)
99
+
100
+ # Change opacity
101
+ viewer.update_mask_settings(cell_id, opacity=0.8)
102
+
103
+ viewer
104
+ ```
105
+
106
+ ---
107
+
108
+ ## SAM Segmentation Workflow
109
+
110
+ ```python
111
+ from anybioimage import BioImageViewer
112
+ from bioio import BioImage
113
+
114
+ viewer = BioImageViewer()
115
+ img = BioImage("cells.tif")
116
+ viewer.set_image(img)
117
+
118
+ # Enable SAM (downloads model ~40MB on first use)
119
+ viewer.enable_sam("mobile_sam")
120
+
121
+ # Now interact in the viewer:
122
+ # - Draw rectangle (R key) → SAM segments the region
123
+ # - Click point (O key) → SAM segments the object at that point
124
+ # - Press Delete on a SAM mask to remove it
125
+ # - viewer.clear_sam_masks() to reset all SAM results
126
+
127
+ viewer
128
+ ```
129
+
130
+ ### Export SAM results as mask
131
+
132
+ ```python
133
+ # After interactive segmentation, access the SAM mask layer
134
+ sam_mask_id = viewer._sam_mask_id
135
+ print(viewer.masks_df[viewer.masks_df["id"] == sam_mask_id])
136
+
137
+ # Or access the raw label array
138
+ sam_labels = viewer._sam_labels_array # numpy array of integer labels
139
+ ```
140
+
141
+ ---
142
+
143
+ ## Annotation Export Pipeline
144
+
145
+ ```python
146
+ viewer = BioImageViewer()
147
+ viewer.set_image(image)
148
+ # User draws annotations interactively...
149
+
150
+ # Export all annotation types
151
+ rois = viewer.rois_df
152
+ polygons = viewer.polygons_df
153
+ points = viewer.points_df
154
+
155
+ print(f"ROIs: {len(rois)}, Polygons: {len(polygons)}, Points: {len(points)}")
156
+
157
+ # Save to CSV
158
+ rois.to_csv("rois.csv", index=False)
159
+ points.to_csv("points.csv", index=False)
160
+
161
+ # Filter by position
162
+ large_rois = rois[(rois["width"] > 50) & (rois["height"] > 50)]
163
+
164
+ # Set annotations programmatically (e.g. load from previous session)
165
+ viewer.rois_df = large_rois
166
+ ```
167
+
168
+ ---
169
+
170
+ ## Marimo Integration
171
+
172
+ ```python
173
+ import marimo as mo
174
+ from anybioimage import BioImageViewer
175
+ from bioio import BioImage
176
+
177
+ @app.cell
178
+ def _():
179
+ viewer = BioImageViewer()
180
+ return viewer
181
+
182
+ @app.cell
183
+ def _(viewer):
184
+ from bioio import BioImage
185
+ img = BioImage("data.tif")
186
+ viewer.set_image(img)
187
+ return mo.ui.anywidget(viewer)
188
+
189
+ @app.cell
190
+ def _(viewer):
191
+ # Reactive: updates when user draws annotations
192
+ rois = viewer.rois_df
193
+ return rois
194
+
195
+ @app.cell
196
+ def _(rois):
197
+ # Display annotation table
198
+ mo.ui.table(rois)
199
+ ```
200
+
201
+ **Key marimo rules:**
202
+ - Always return `mo.ui.anywidget(viewer)` from the cell that displays the viewer
203
+ - Each cell should be a pure function of its inputs
204
+ - Run `marimo check --fix` after editing
205
+
206
+ ---
207
+
208
+ ## Large Image (OME-Zarr)
209
+
210
+ ```python
211
+ from anybioimage import BioImageViewer
212
+ from bioio import BioImage
213
+
214
+ viewer = BioImageViewer()
215
+
216
+ # Multi-resolution OME-Zarr with lazy loading
217
+ img = BioImage("large_dataset.ome.zarr")
218
+ viewer.set_image(img)
219
+
220
+ # Viewer automatically:
221
+ # - Uses tile-based rendering for 1MP+ images
222
+ # - Selects resolution level based on zoom
223
+ # - Prefetches adjacent Z/T slices during navigation
224
+ # - Shows resolution level controls if multiple levels available
225
+
226
+ viewer.canvas_height = 900
227
+ viewer
228
+ ```
229
+
230
+ ### Navigate programmatically
231
+
232
+ ```python
233
+ # Set slice position
234
+ viewer.current_t = 5 # timeframe 5
235
+ viewer.current_z = 10 # z-slice 10
236
+ # Image updates automatically
237
+ ```