OMERO¶

There are several module for OMERO that will be documented here.

OMERO Downloader¶

Use to download an OMERO dataset to a folder.

Adtapted from https://gist.github.com/will-moore/a9f90c97b5b6f1a0da277a5179d62c5a Documentation: https://downloads.openmicroscopy.org/omero/5.3.1/api/python/omero/omero.plugins.html

biom3d.omero_downloader.OBJ_INFO = "obj should be 'Project:ID' or 'Dataset:ID'"¶: Usage: python download_pdi.py Project:123 my_project_directory

biom3d.omero_downloader.download_attachment(hostname: str, username: str, password: str, session_id: str | None, attachment_id: int, config: bool = True) → str | None[source]¶

Download an attachment (OMERO FileAnnotation) to the local file system.

Parameters:

hostname (str) – Hostname of the OMERO server.
username (str) – OMERO username.
password (str) – OMERO password.
session_id (str, optional) – Optional OMERO session ID to reuse an existing session.
attachment_id (int) – ID of the FileAnnotation to download.
config (bool, default=True) – Whether to save to “configs/” directory. If False, saves to “logs/”.

Returns:

Local path of the downloaded file, or None if not found.

Return type:

str or None

biom3d.omero_downloader.download_datasets(conn: omero.gateway.BlitzGateway, datasets: list, target_dir: str) → None[source]¶

Download datasets using OMERO BlitzGateway connection.

Parameters:

conn (BlitzGateway) – Active OMERO connection.
datasets (list) – List of OMERO dataset objects to download.
target_dir (str) – Path to the directory where the datasets will be downloaded.

Return type:

None

biom3d.omero_downloader.download_datasets_cli(datasets: list, target_dir: str) → None[source]¶

Download datasets using OMERO CLI interface.

Parameters:

datasets (list) – A list of OMERO Dataset objects to download.
target_dir (str) – Path to the directory where the datasets will be downloaded.

Return type:

None

biom3d.omero_downloader.download_object(username: str, password: str, hostname: str, obj: str, target_dir: str, session_id: str | None = None) → tuple[list, str][source]¶

Connect to OMERO and download a dataset or project via BlitzGateway.

Parameters:

username (str) – OMERO username.
password (str) – OMERO password.
hostname (str) – OMERO server hostname.
obj (str) – Object identifier, e.g. “Dataset:123” or “Project:456”.
target_dir (str) – Target directory for download.
session_id (str, optional) – Existing OMERO session ID to reuse.

Returns:

datasets (list) – Represent a list of OMERO datasets
target_dir (str) – Final target folder path.

biom3d.omero_downloader.download_object_cli(cli: omero.cli.CLI, obj: str, target_dir: str)[source]¶

Download a dataset or project using OMERO CLI and its ID.

Parameters:

cli (omero.cli.CLI) – Authenticated CLI session.
obj (str) – OMERO object string, e.g. “Dataset:123” or “Project:456”.
target_dir (str) – Directory where data will be downloaded.

Returns:

datasets (list) – Represent a list of OMERO datasets
target_dir (str) – Final target folder path.

Examples

with cli_login() as cli:
    download_object_cli(cli, args.obj, args.target)

biom3d.omero_downloader.main(argv: list[str]) → None[source]¶

Entry point for downloading OMERO datasets or projects from command-line arguments.

Parses command-line arguments for object identifier, destination directory, and connection credentials. Then triggers the download using download_object.

Parameters:: argv (list of str) – List of command-line arguments (excluding the script name). Typically sys.argv[1:].
Return type:: None

OMERO Uploader¶

Sample code to import files and directories.

The OMERO session used for expimportort is created using the standard OMERO CLI. If a CLI session already exists it will be reused.

Remember to logout of any existing sessions if you want to export to a different server!

This utility has several optional arguments, see –help for details.

Each of the remaining arguments will form a fileset:

Files will be imported into single-file filesets
Directories will be imported into a fileset containing all files in that directory

See http://www.openmicroscopy.org/community/viewtopic.php?f=6&t=8407 Uses code from https://gitlab.com/openmicroscopy/incubator/omero-python-importer/-/blob/master/import.py

biom3d.omero_uploader.assert_import(client: omero.client, proc: Any, files: list[str], wait: int) → omero.cmd.Response | None[source]¶

Upload files to OMERO and assert that they are correctly imported.

This function uploads files using the provided processor, waits for the import job to complete, and verifies that at least one image (pixel set) has been imported successfully.

Parameters:

client (omero.client) – Active OMERO client used to communicate with the server.
proc (object) – Upload processor, must implement verifyUpload() method compatible with OMERO.
files (list of str) – List of file paths to upload and import.
wait (int) – Behavior for waiting on the job: - 0: Do not wait. - <0: Wait indefinitely until import finishes. - >0: Wait for the specified number of milliseconds.

Returns:

Response object from the OMERO server if waiting, otherwise None.

Return type:

omero.cmd.Response or None

Raises:

Exception – If an OMERO error response is returned (omero.cmd.ERR).
AssertionError – If no images (pixels) were imported.

Notes

Prints the hash of each uploaded file.

biom3d.omero_uploader.create_fileset(files: list[str]) → omero.model.FilesetI[source]¶

Create a new OMERO Fileset object from a list of local file paths.

This function constructs a Fileset with entries corresponding to the given local files. It sets only the filename (not the full path) as the client path and attaches system version information as metadata for traceability.

Parameters:: files (list of str) – List of local file paths to include in the fileset.
Returns:: An OMERO Fileset object populated with the given files and linked to an UploadJob.
Return type:: omero.model.FilesetI

Notes

The clientPath is set to the basename of each file.
System information (OS, architecture, OMERO version) is added to the UploadJob.
If locale detection fails, it is silently skipped.

biom3d.omero_uploader.create_settings() → omero.grid.ImportSettings[source]¶

Create and configure an OMERO ImportSettings object.

This function initializes a new ImportSettings object and sets several default import parameters, including thumbnail generation and checksum algorithm.

Returns:: Configured OMERO import settings object.
Return type:: omero.grid.ImportSettings

Notes

Enables thumbnail generation (doThumbnails=True).
Disables skipping of stats info (noStatsInfo=False).
Sets the checksum algorithm to SHA-1 160-bit.
User-specified import options are left unset (None).

biom3d.omero_uploader.full_import(client: omero.client, fs_path: str, wait: int = -1) → omero.cmd.Response | None[source]¶

Perform a full import of a local file or directory into OMERO.

This function handles all steps required to import data into OMERO: - Retrieves the managed repository. - Gathers files from the given path. - Creates a Fileset and ImportSettings. - Starts the import process. - Optionally waits for the import job to complete and validates it.

Parameters:

client (omero.client) – Active OMERO client session.
fs_path (str) – Path to a single file or a directory containing files to import.
wait (int, default=-1) – Determines how long to wait for the import to complete: - 0 : Do not wait. - <0: Wait indefinitely (default). - >0: Wait up to the specified number of milliseconds.

Returns:

OMERO command response if waiting for completion, otherwise None.

Return type:

omero.cmd.Response or None

Raises:

AssertionError – If no files are found in the specified fs_path.
Exception – If OMERO returns an error during the import process.

Notes

Ensures proc is closed properly after the import, even if an error occurs.

biom3d.omero_uploader.get_files_for_fileset(fs_path: str) → list[str][source]¶

Retrieve the list of files from a given file or directory path.

If the input path is a file, return it as a single-item list. If the input path is a directory, return a list of all non-hidden files in it.

Parameters:: fs_path (str) – Path to a file or directory.
Returns:: List of file paths. If fs_path is a file, returns [fs_path]. If fs_path is a directory, returns the paths of all non-hidden files inside.
Return type:: list of str

Notes

Hidden files (starting with .) are ignored when fs_path is a directory.
Does not recurse into subdirectories.

biom3d.omero_uploader.run(username: str, password: str, host: str, project: int, attachment: str | None = None, dataset_name: str | None = None, path: str | None = None, is_pred: bool = False, wait: int = -1, session_id: str | None = None) → None[source]¶

Upload a new dataset or prediction result to OMERO and optionally attach log files.

This function handles several OMERO tasks: - Connects to OMERO (via credentials or session ID). - Optionally creates a new dataset and imports image files from a given path. - If specified, attaches a zipped log directory (excluding image outputs) to the dataset.

Parameters:

username (str) – OMERO username (ignored if session_id is provided).
password (str) – OMERO password (ignored if session_id is provided).
host (str) – Hostname or IP of the OMERO server.
project (int) – ID of the existing dataset or project to attach data to.
attachment (str, optional) – Folder name used for zipping logs and attaching them to the dataset.
dataset_name (str, optional) – Name for the new dataset (if path is provided).
path (str, optional) – Local directory containing files to import into OMERO.
is_pred (bool, default=False) – Indicates if the uploaded data is a prediction result.
wait (int, default=-1) – Time (in ms) to wait for the OMERO import process: - 0: do not wait - <0: wait indefinitely (default) - >0: wait up to specified time
session_id (str, optional) – Existing OMERO session ID (used instead of logging in with username/password).

Return type:

None

Notes

The function can be used both for training logs and prediction results.
When path is provided, a new dataset is created and populated with the files.
When attachment is specified, the corresponding log folder is zipped (excluding images) and attached as a FileAnnotation.
The function automatically links imported images to the dataset.

Raises:

AssertionError – If no files are found in the specified import path.
Exception – If OMERO returns an error during import or file upload.

biom3d.omero_uploader.upload_files(proc: omero.gateway.UploadProcess, files: list[str], client: omero.gateway.BlitzGateway)[source]¶

Upload multiple files to OMERO using the provided upload process.

The function reads each file in chunks (1 MB) and streams the content to OMERO via the upload handler obtained from the process. It also computes and returns the SHA1 hashes of the uploaded files using the OMERO client.

Parameters:

proc (omero.gateway.UploadProcess) – The OMERO upload process object that manages file uploads.
files (list of str) – List of local file paths to upload.
client (omero.gateway.BlitzGateway or similar) – OMERO client instance used to compute SHA1 hashes of files.

Returns:

List of SHA1 hash strings corresponding to each uploaded file.

Return type:

list of str

Notes

Files are read in 1MB blocks to efficiently handle large files.
The uploader resource for each file is properly closed after upload.
Prints upload progress per file.

OMERO Prediction¶

Note

This module can be replaced by preprocess_train with action pred.

Predictions with Omero.

This script can download data from Omero, compute predictions, and upload back into Omero.

Download a dataset or project from Omero, perform predictions, and optionally upload the results back.

Depending on whether the object is a “Dataset” or “Project”, the function handles: - downloading the data (either via Omero API or CLI), - running inference, - optionally uploading the predicted results back to Omero, - cleaning up temporary files if upload is done.

Parameters:

obj (str) – Type and ID of the object to process (e.g., “Dataset:123” or “Project:456”).
target (str) – Target location for downloading.
log (str) – Path to the model folder.
dir_out (str) – Path to the directory where predictions should be saved.
host (str, optional) – Hostname of the Omero server, if using API authentication.
user (str, optional) – Username for Omero authentication.
pwd (str, optional) – Password for Omero authentication.
upload_id (str, optional) – ID of the project to upload predictions back to. If None, uploading is skipped.
ext (str, default="_predictions") – Suffix to append to prediction output directories.
attachment (str, optional) – Path to an optional attachment file to include in the upload (e.g., logs or configs).
session_id (str, optional) – Session ID for Omero (used for authenticated operations).
skip_preprocessing (bool, default=False) – Whether to skip preprocessing steps before prediction.

Returns:

Path to the output directory containing predictions, or None if an error occurred.

Return type:

str or None

Notes

The function prints messages that can be parsed remotely with the format “REMOTE:key:value”.
Uploading back to Omero is deprecated but still supported.

OMERO Preprocess, Train & Pred¶

Group preprocessing, training and prediction with OMERO data.

biom3d.omero_preprocess_train.load_csv(filename: str) → list[list[str]][source]¶

Load a CSV file and return its content as a list of rows.

Parameters:: filename (str) – Path to the CSV file to load.
Returns:: Data extracted from the CSV file, where each row is a list of string values.
Return type:: list of list of str

Notes

Assumes the file is comma-delimited.
The file is read entirely into memory.

biom3d.omero_preprocess_train.plot_learning_curve(last_folder: str) → None[source]¶

Plot training and validation loss curves from a CSV log file.

The CSV file is expected at <last_folder>/log/log.csv and must contain: - Epoch numbers in the first column, - Training loss in the second column, - Validation loss in the third column.

Parameters:: last_folder (str) – Path to the folder containing the training logs.
Return type:: None

Notes

The resulting plot is saved as <last_folder>/image/Learning_curves_plot.png.

biom3d.omero_preprocess_train.run(obj_raw: str, obj_mask: str | None, num_classes: int, config_dir: str, base_config: str, ct_norm: bool, desc: str, max_dim: int, num_epochs: int, target: Literal['preprocess', 'preprocess_train', 'train', 'pred'], action: str, host: str | None = None, user: str | None = None, pwd: str | None = None, upload_id: int | None = None, dir_out: str | None = None, omero_session_id: str | None = None) → str | None[source]¶

Execute the pipeline for preprocessing, training, or prediction using OMERO data.

Depending on the specified action (preprocess, preprocess_train, train, or pred), this function: - Downloads raw and optionally mask datasets from OMERO (via API or CLI). - Performs preprocessing and/or training. - Downloads model configurations and runs inference. - Optionally uploads resulting images/logs back to OMERO. - Generates learning curve plots after training.

Parameters:

obj_raw (str) – Identifier of the raw OMERO object (e.g., “Dataset:123”).
obj_mask (str, optional) – Identifier of the corresponding mask object, if available.
num_classes (int) – Number of segmentation classes for the training.
config_dir (str) – Target folder for auto-configuration result.
base_config (str) – Path to an existing configuration file which will be updated with the preprocessed values.
ct_norm (bool) – Whether to apply CT normalization during preprocessing.
desc (str) – Model name.
max_dim (int) – Maximum dimension of a patch.
num_epochs (int) – Number of epochs for model training.
target (str) – Output directory for data to download into.
action (str literal) – Action to perform. One of: “preprocess”, “preprocess_train”, “train”, “pred”.
host (str, optional) – OMERO server host (for API-based downloads).
user (str, optional) – OMERO username.
pwd (str, optional) – OMERO password.
upload_id (int, optional) – OMERO project ID where outputs should be uploaded.
dir_out (str, optional) – Directory to store prediction outputs.
omero_session_id (str, optional) – Session ID for authenticated OMERO access.

Returns:

Path to the output directory if applicable (e.g., after training), otherwise None.

Return type:

str or None

Notes

If upload_id is provided, results are uploaded back to OMERO after training or preprocessing.
Model logs are extracted and plotted to visualize learning curves.
Model zip files and config attachments are managed using download_attachment.
On Windows, the model upload at the end will fail due to lock preventing zipping.

Raises:: RuntimeError – If object type is unrecognized or missing required information.

biom3d.omero_preprocess_train.unzip_file(zip_path: str, extract_to: str) → str[source]¶

Extract a zip file to a specific directory and return the extraction path.

Parameters:

zip_path (str) – Path to the zip archive.
extract_to (str) – Directory where contents should be extracted.

Returns:

Full path of the directory where the archive was extracted.

Return type:

str

Notes

Creates a subdirectory named after the zip file (without extension) inside extract_to.
The extracted directory is created if it doesn’t exist.