K-Dense-AI/scientific-agent-skills / skills/omero-integration
omero-integration
VerifiedInspects and automates microscopy data workflows against OMERO.server with omero-py, BlitzGateway, OMERO CLI, tables, annotations, ROIs, rendering, and documented OMERO.web APIs. Use this skill for scoped OMERO inventory, metadata export, import/export planning, or reviewed write workflows.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.9 KB |
| references/advanced.md | markdown | 10.4 KB |
| references/connection.md | markdown | 10.7 KB |
| references/data_access.md | markdown | 9.9 KB |
| references/image_processing.md | markdown | 7.7 KB |
| references/metadata.md | markdown | 9.1 KB |
| references/rois.md | markdown | 8.9 KB |
| references/scripts.md | markdown | 8.7 KB |
| references/sources.md | markdown | 10.9 KB |
| references/tables.md | markdown | 8.6 KB |
| scripts/export_image_metadata.py | script | 17.1 KB |
| scripts/inventory.py | script | 8.2 KB |
| scripts/omero_common.py | script | 14.2 KB |
| scripts/plan_transfer.py | script | 12.0 KB |
| scripts/validate_config.py | script | 4.0 KB |
references/rois.md
View on GitHub# Regions of Interest (ROIs)
ROIs and shape labels may encode phenotypes, diagnoses, sample identifiers, or
analysis decisions. Export geometry and labels only within an explicit scope.
## Model Semantics
The OMERO 5.6 line uses the June 2016 OME schema. The OME ROI model defines
eight concrete 2D shape types:
- Ellipse
- Label
- Line
- Mask
- Point
- Polygon
- Polyline
- Rectangle
Plane selectors are optional:
- `TheZ`: z-section; absent means all z-sections
- `TheT`: timepoint; absent means all timepoints
- `TheC`: channel; absent means all channels
Do not coerce absent values to zero. A 3D ROI is represented as a union of 2D
shapes across planes; it is not a native volumetric mesh.
Display fields include RGBA fill/stroke colors, stroke width, fill rule, dash
array, text label, and font properties. Geometry and display metadata are
distinct. A shape can also have an affine `Transform`; preserve its six
coefficients (`A00`, `A01`, `A02`, `A10`, `A11`, `A12`) when exporting local
coordinates. Ignoring it can move or distort a reconstructed ROI.
## Current Service Status
The current Python examples still retrieve ROIs with:
```python
roi_service = conn.getRoiService()
result = roi_service.findByImage(image_id, None, conn.SERVICE_OPTS)
```
However, the current OMERO Blitz API marks the `IRoi` interface deprecated.
That means “still available but at removal risk,” not “already removed.” OME
does not document a general replacement for every `IRoi` method in the pages
reviewed for this snapshot.
Therefore:
- isolate `IRoi` use behind a small function;
- do not build new broad workflows around legacy measurement-table helpers;
- verify the target server's generated API before relying on it;
- record this dependency in long-lived integrations.
The official OMERO.web JSON API also documents paginated ROI listing by image:
`/api/v0/m/rois/?image=<id>&limit=<n>&offset=<n>`. Its page cap is on
ROIs, and each returned ROI still includes its child shapes. Use it only when the site
exposes the documented `api` app over HTTPS and its authentication model is
appropriate.
## Bounded ROI Read
`findByImage()` does not expose page arguments. Apply explicit image, ROI, and
shape caps and report truncation:
```python
image_id = 123
max_rois = 100
max_shapes_per_roi = 500
roi_service = conn.getRoiService()
result = roi_service.findByImage(image_id, None, conn.SERVICE_OPTS)
rois = list(result.rois)
roi_truncated = len(rois) > max_rois
for roi in rois[:max_rois]:
shapes = list(roi.copyShapes())
print(
{
"roi_id": roi.getId().getValue(),
"shape_count_returned": min(len(shapes), max_shapes_per_roi),
"shape_truncated": len(shapes) > max_shapes_per_roi,
}
)
```
The cap limits client processing/output, not necessarily server work:
`findByImage()` has already loaded all matching ROIs and their shapes,
including mask payloads. Masks are omitted from the JSON, not from that
service response. For a known very
large image, do not call it casually; consider the documented paginated JSON
API or a site-reviewed query.
The bundled exporter requires explicit image IDs and uses redaction defaults:
```bash
python -B scripts/export_image_metadata.py \
--image-id 123 \
--max-rois-per-image 100 \
--max-shapes-per-roi 500 \
--output ./image-123-metadata.json
```
Review the dry run, then add `--execute`. ROI labels remain redacted unless
`--include-roi-labels` is specified. The exporter preserves the affine
transform and flags `geometry_truncated` when a Points string exceeds the
length cap. Such a record is an inventory, not reconstructable geometry.
## Reading Shape Fields
Generated model values are usually wrapped in OMERO rtypes. Preserve `None`:
```python
def unwrap(value):
if value is None:
return None
getter = getattr(value, "getValue", None)
return getter() if callable(getter) else value
for roi in result.rois[:max_rois]:
for shape in list(roi.copyShapes())[:max_shapes_per_roi]:
record = {
"id": unwrap(shape.getId()),
"the_z": unwrap(shape.getTheZ()),
"the_t": unwrap(shape.getTheT()),
"the_c": unwrap(shape.getTheC()),
"label_redacted": True,
}
print(record)
```
Use type checks before geometry access:
```python
import omero.model
if isinstance(shape, omero.model.RectangleI):
geometry = {
"x": unwrap(shape.getX()),
"y": unwrap(shape.getY()),
"width": unwrap(shape.getWidth()),
"height": unwrap(shape.getHeight()),
}
elif isinstance(shape, omero.model.EllipseI):
geometry = {
"x": unwrap(shape.getX()),
"y": unwrap(shape.getY()),
"radius_x": unwrap(shape.getRadiusX()),
"radius_y": unwrap(shape.getRadiusY()),
}
elif isinstance(shape, omero.model.LineI):
geometry = {
"x1": unwrap(shape.getX1()),
"y1": unwrap(shape.getY1()),
"x2": unwrap(shape.getX2()),
"y2": unwrap(shape.getY2()),
}
elif isinstance(shape, (omero.model.PolygonI, omero.model.PolylineI)):
geometry = {"points": unwrap(shape.getPoints())}
```
Validate coordinates against image dimensions. Preserve floating-point
coordinates; do not truncate them to integers merely for JSON.
For masks:
- export position, dimensions, plane selectors, and byte count only by default;
- do not serialize mask bytes into broad JSON;
- treat decoded masks as pixel-derived data;
- validate width/height and bit packing against the current model before
reconstructing.
## Creating an ROI Is a Write
Current core-model pattern:
```python
import omero.model
from omero.rtypes import rdouble, rint, rstring
image = conn.getObject("Image", image_id)
if image is None:
raise LookupError("Image unavailable")
x = 50.0
y = 100.0
width = 200.0
height = 150.0
z = 0
t = 0
if x < 0 or y < 0 or x + width > image.getSizeX() or y + height > image.getSizeY():
raise ValueError("Rectangle is outside image bounds")
if not 0 <= z < image.getSizeZ() or not 0 <= t < image.getSizeT():
raise ValueError("Plane index is outside image bounds")
rectangle = omero.model.RectangleI()
rectangle.setX(rdouble(x))
rectangle.setY(rdouble(y))
rectangle.setWidth(rdouble(width))
rectangle.setHeight(rdouble(height))
rectangle.setTheZ(rint(z))
rectangle.setTheT(rint(t))
rectangle.setTextValue(rstring("reviewed-region"))
roi = omero.model.RoiI()
roi.setImage(image._obj)
roi.addShape(rectangle)
saved = conn.getUpdateService().saveAndReturnObject(roi, conn.SERVICE_OPTS)
print(saved.getId().getValue())
```
Before execution, confirm:
- image ID, group, and dimensions;
- shape count and coordinate system;
- Z/T/C semantics;
- label sensitivity;
- write permission;
- whether an existing ROI should be updated rather than duplicated.
## RGBA Encoding
The official Python example encodes color bytes as a signed 32-bit integer:
```python
def rgba_to_int(red, green, blue, alpha=255):
channels = (red, green, blue, alpha)
if any(not 0 <= value <= 255 for value in channels):
raise ValueError("RGBA channels must be in 0..255")
return int.from_bytes(channels, byteorder="big", signed=True)
```
Use `rint(rgba_to_int(...))` for generated shape color fields. Do not swap RGBA
order or assume an unsigned representation.
## Intensity Measurements
The historical Python example uses
`IRoi.getShapeStatsRestricted(shape_ids, z, t, channel_indices)`. Since
`IRoi` is deprecated:
1. verify the method in the target server's generated API;
2. cap shape and channel counts;
3. preserve channel indexing (pixel channels are zero-based);
4. record the exact server/client versions;
5. do not describe the result as a replacement for a validated analysis
pipeline.
For simple rectangular reads, a bounded pixel tile may be clearer:
```python
pixels = image.getPrimaryPixels()
z = 0
c = 0
t = 0
x = 10
y = 20
width = 100
height = 80
tile = next(pixels.getTiles([(z, c, t, (x, y, width, height))]))
```
Confirm the current API's tile generator behavior and cap tile area. Polygon,
polyline, ellipse, and mask measurements require a correctly defined raster
mask; a bounding box alone is not the ROI.
## Updates and Deletion
Updating a shape and saving an ROI is a write that can affect downstream
measurements. Deleting an ROI removes its shapes. Never add delete support to a
read-only export script.
Before update/delete:
- show image, ROI, and shape IDs;
- retrieve current values;
- check permissions and group context;
- obtain approval for the exact IDs;
- avoid namespace/label-based bulk selection;
- wait for command completion and verify the result.
## ROI Export Checklist
- Explicit image IDs only
- One group context
- Maximum images, ROIs per image, and shapes per ROI
- Labels redacted by default
- Mask bytes omitted
- No pixel values unless separately requested
- Plane selectors preserve `None`
- Geometry strings have a length cap
- `IRoi` deprecation recorded
- Connection closed in `finally`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |