QuBaLab

https://qupath.github.io/qubalab-docs/
Admin
QuBaLab is a Python package for exploring quantitative bioimage analysis, especially in combination...
Tokens:29,763
Snippets:202
Trust Score:9.7
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Get extension version using gateway.entry_point.getExtensionVersion()

Source: https://qupath.github.io/qubalab-docs/notebooks_files/communicating_with_qupath.html

Calls the getExtensionVersion() function on the QuPath entry point and prints the result. The output shows the extension version as '0.0.1-SNAPSHOT'.

```python
print(f"Extension version: {gateway.entry_point.getExtensionVersion()}")

```

```output
Extension version: 0.0.1-SNAPSHOT

```

--------------------------------

### Visualize Dask array with napari

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Visualizes a Dask array from level_to_dask() in napari. Requires napari to be manually installed (not installed by default). The array is reordered from (c, y, x) to (y, x, c) using da.moveaxis before viewing.

```python
import napari
import dask.array as da

level = 0
image = server.level_to_dask(level)

# image has resolutions (c, y, x) while napari accepts
# resolutions (y, x, c), so they need to be reordered
image = da.moveaxis(image, [0], [2])

napari.view_image(image)
napari.run()
```

--------------------------------

### Show QuPath screenshot with create_snapshot

Source: https://qupath.github.io/qubalab-docs/notebooks_files/communicating_with_qupath.html

Uses qupath_gateway.create_snapshot() to capture the current QuPath interface and display it with matplotlib. This is a simple example of using the gateway functions.

```python
import matplotlib.pyplot as plt

plt.imshow(qupath_gateway.create_snapshot())
plt.axis(False)
plt.show()

```

--------------------------------

### ImageServer.metadata (property)

Source: https://qupath.github.io/qubalab-docs/qubalab.images.html

Gets the image metadata.

```APIDOC
## ImageServer.metadata (property)

### Description
Gets the image metadata.

### Method
metadata (property)

### Parameters
None

### Returns
- **ImageMetadata** - The image metadata.

```

--------------------------------

### Access image metadata with QuPathServer

Source: https://qupath.github.io/qubalab-docs/notebooks_files/communicating_with_qupath.html

Retrieves and prints image metadata from the server, including path, name, level shapes, pixel calibration, pixel type, downsamples, and channel information. The output shows an example of the printed metadata for a sample image.

```python
# Access image metadata

metadata = server.metadata

print(f'Image path: {metadata.path}')
print(f'Image name: {metadata.name}')
print()

print('Levels:')
for level, shape in enumerate(metadata.shapes):
    print(f'Shape of level {level}: {shape}')
print()

print('Pixel calibration:')
print(f'Pixel length on x-axis: {metadata.pixel_calibration.length_x}')
print(f'Pixel length on y-axis: {metadata.pixel_calibration.length_y}')
print()

print(f'Pixel type: {metadata.dtype}')
print()

print(f'Downsamples: {metadata.downsamples}')
print()

print('Channels:')
for channel in metadata.channels:
    print(channel)

```

```text
Image path: /home/leo/Documents/IGC/Images/CMU-1.tiff
Image name: CMU-1.tiff

Levels:
Shape of level 0: ImageShape(x=46000, y=32914, t=1, c=3, z=1)
Shape of level 1: ImageShape(x=11500, y=8228, t=1, c=3, z=1)
Shape of level 2: ImageShape(x=2875, y=2057, t=1, c=3, z=1)

Pixel calibration:
Pixel length on x-axis: PixelLength(length=0.499, unit='micrometer')
Pixel length on y-axis: PixelLength(length=0.499, unit='micrometer')

Pixel type: uint8

Downsamples: (1.0, 4.0, 16.0)

Channels:
ImageChannel(name='Red', color=(1.0, 0.0, 0.0))
ImageChannel(name='Green', color=(0.0, 1.0, 0.0))
ImageChannel(name='Blue', color=(0.0, 1.0, 0.0))

```

--------------------------------

### get_objects

Source: https://qupath.github.io/qubalab-docs/qubalab.qupath.html

Gets the objects (e.g., detections, annotations) of the current or specified image in QuPath.

```APIDOC
## get_objects(image_data=None, gateway=None, object_type=None, converter=None) -> list[Feature] | list[ImageFeature] | list[JavaObject]

### Description
Get the objects (e.g. detections, annotations) of the current or specified image in QuPath.

### Parameters
- **image_data** (JavaObject | None) - Optional - The image_data to retrieve objects from. Can be None to use the current ImageData opened in QuPath.
- **gateway** (JavaGateway | None) - Optional - The gateway to use. Can be None to use the default gateway.
- **object_type** (ObjectType | None) - Optional - The type of object to get. Can be None to get all objects except the root.
- **converter** (str | None) - Optional - The converter to use for the objects.

### Returns
- **list[Feature] | list[ImageFeature] | list[JavaObject]** - The objects of the current or specified image.
```

--------------------------------

### Access ImageServer metadata

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Accesses image metadata via the ImageServer.metadata property and prints path, name, level shapes, pixel calibration, pixel type, downsamples, and channels. The output shows the metadata for the OpenSlideServer example, including a 3-channel uint8 image with three pyramid levels and 0.499 micrometer pixel spacing.

```python
# Access image metadata

metadata = server.metadata

print(f'Image path: {metadata.path}')
print(f'Image name: {metadata.name}')
print()

print('Levels:')
for level, shape in enumerate(metadata.shapes):
    print(f'Shape of level {level}: {shape}')
print()

print('Pixel calibration:')
print(f'Pixel length on x-axis: {metadata.pixel_calibration.length_x}')
print(f'Pixel length on y-axis: {metadata.pixel_calibration.length_y}')
print()

print(f'Pixel type: {metadata.dtype}')
print()

print(f'Downsamples: {metadata.downsamples}')
print()

print('Channels:')
for channel in metadata.channels:
    print(channel)

```

```text
Image path: /var/folders/zt/w6w5hpx561d_n1n6613yy7dh0000gt/T/tmpep6bfoli
Image name: tmpep6bfoli

Levels:
Shape of level 0: ImageShape(x=46000, y=32914, t=1, c=3, z=1)
Shape of level 1: ImageShape(x=11500, y=8228, t=1, c=3, z=1)
Shape of level 2: ImageShape(x=2875, y=2057, t=1, c=3, z=1)

Pixel calibration:
Pixel length on x-axis: PixelLength(length=0.499, unit='micrometer')
Pixel length on y-axis: PixelLength(length=0.499, unit='micrometer')

Pixel type: <class 'numpy.uint8'>

Downsamples: (1, 4, 16)

Channels:
ImageChannel(name='Red', color=(1, 0, 0))
ImageChannel(name='Green', color=(0, 1, 0))
ImageChannel(name='Green', color=(0, 0, 1))

```

--------------------------------

### Get current image name using gateway.entry_point.getCurrentImageName()

Source: https://qupath.github.io/qubalab-docs/notebooks_files/communicating_with_qupath.html

Calls the getCurrentImageName() function on the QuPath entry point and prints the result. The output shows the current image name as 'CMU-1.tiff'.

```python
print(f"Current image name: {gateway.entry_point.getCurrentImageName()}")

```

```output
Current image name: CMU-1.tiff

```

--------------------------------

### Create a labeled image with LabeledImageServer

Source: https://qupath.github.io/qubalab-docs/notebooks_files/working_with_objects.html

Creates a QuPathServer for the image opened in QuPath, then a LabeledImageServer with a downsample of 20 to generate a labeled image. Reads the entire labeled image with read_region() and plots it using qubalab's plotImage utility. The labeled image is a single-channel image where objects are represented by integer labels.

```python
from qubalab.images.qupath_server import QuPathServer
from qubalab.images.labeled_server import LabeledImageServer

# Create a QuPathServer that represents the image currently opened in QuPath
qupath_server = QuPathServer(gateway)

# Set a downsample. The labeled image will be 20 times smaller than the image currently opened in QuPath
downsample = 20

# Create the LabeledImageServer. This doesn't create labeled image yet
labeled_server = LabeledImageServer(qupath_server.metadata, annotations, downsample=downsample)

# Request the pixel values of the entire labeled image. Pixel values will be created as they are requested 
label_image = labeled_server.read_region()

# label_image is an image of shape (c, y, x), not easily plottable
# We use a utility function from qubalab to plot the image
from qubalab.display.plot import plotImage
import matplotlib.pyplot as plt
_, ax = plt.subplots()
plotImage(ax, label_image)
```

--------------------------------

### Create OpenSlideServer from image path

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Creates an OpenSlideServer from the CMU-1.svs path. The output shows warnings when OpenSlide is unavailable and TiffSlide is used as a fallback.

```python
from qubalab.images.openslide_server import OpenSlideServer


# Create the ImageServer from the image path. This will read the image metadata but not the pixel values yet.
# This function has optional parameters you can find in the documentation
openslide_server = OpenSlideServer(cmu_path)

```

```text
/Users/lleplat/QuPath/Projects/qubalab/qubalab/qubalab/images/openslide_server.py:9: UserWarning: Unable to import OpenSlide, will try TiffSlide instead
  warnings.warn(f'Unable to import OpenSlide, will try TiffSlide instead')
/Users/lleplat/QuPath/Projects/qubalab/qubalab/qubalab/images/openslide_server.py:37: UserWarning: compatibility: aliasing tiffslide.TiffSlide to 'OpenSlide'
  self._reader = openslide.OpenSlide(path)

```

--------------------------------

### get_current_image_data

Source: https://qupath.github.io/qubalab-docs/qubalab.qupath.html

Gets the current ImageData opened in QuPath through the provided gateway.

```APIDOC
## get_current_image_data(gateway=None) -> JavaObject

### Description
Get the current ImageData opened in QuPath through the provided gateway.

### Parameters
- **gateway** (JavaGateway | None) - Optional - The gateway to use. Can be None to use the default gateway.

### Returns
- **JavaObject** - The current ImageData opened in QuPath.
```

--------------------------------

### Download CMU-1.svs sample image

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Downloads the CMU-1.svs sample image using the get_image function. The output shows the download progress and saved path.

```python
# Download or get image
cmu_path = get_image("CMU-1.svs", "https://openslide.cs.cmu.edu/download/openslide-testdata/Aperio/CMU-1.svs")

```

```text
Downloading CMU-1.svs...
CMU-1.svs saved to /var/folders/zt/w6w5hpx561d_n1n6613yy7dh0000gt/T/tmpep6bfoli

```

--------------------------------

### count_objects

Source: https://qupath.github.io/qubalab-docs/qubalab.qupath.html

Gets a count of all objects in the current or specified image, useful for checking if a reasonable number of objects is available.

```APIDOC
## count_objects(image_data=None, gateway=None, object_type=None) -> int

### Description
Get a count of all objects in the current or specified image. Since requesting the objects can be slow, this can be used to check if a reasonable number of objects is available.

### Parameters
- **image_data** (JavaObject | None) - Optional - The image_data to retrieve objects from. Can be None to use the current ImageData opened in QuPath.
- **gateway** (JavaGateway | None) - Optional - The gateway to use. Can be None to use the default gateway.
- **object_type** (ObjectType | None) - Optional - The type of object to get. Can be None to get all objects except the root.

### Returns
- **int** - The number of such objects in the current or specified image.
```

--------------------------------

### Download LuCa-7color sample image

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Downloads the LuCa-7color fluorescence sample image using the get_image function. The output shows the download progress and saved path.

```python
# Download or get image
luca_path = get_image("LuCa-7color_[13860,52919]_1x1component_data.tif", "https://downloads.openmicroscopy.org/images/Vectra-QPTIFF/perkinelmer/PKI_fields/LuCa-7color_%5b13860,52919%5d_1x1component_data.tif")

```

```text
Downloading LuCa-7color_[13860,52919]_1x1component_data.tif...
LuCa-7color_[13860,52919]_1x1component_data.tif saved to /var/folders/zt/w6w5hpx561d_n1n6613yy7dh0000gt/T/tmpj98oxoz0

```

--------------------------------

### Assign ImageServer variable

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Assigns the OpenSlideServer instance to a variable for use in subsequent examples. The comment notes that aicsimageio_server or icc_profile_server can be substituted.

```python
server = openslide_server  # you can change it to aicsimageio_server or icc_profile_server

```

--------------------------------

### QuPathServer constructor

Source: https://qupath.github.io/qubalab-docs/qubalab.images.html

Creates a QuPathServer instance that communicates with a QuPath ImageServer through a Gateway. Parameters allow specifying the gateway, the QuPath server, and pixel access method.

```APIDOC
## QuPathServer(gateway=None, qupath_server=None, pixel_access='base_64', **kwargs)

### Description
Creates a QuPathServer instance that communicates with a QuPath ImageServer through a Gateway. Parameters allow specifying the gateway, the QuPath server, and pixel access method.

### Parameters
- **gateway** (JavaGateway | None) - Optional - The gateway between Python and QuPath. If not specified, the default gateway is used
- **qupath_server** (JavaObject | None) - Optional - A Java object representing the QuPath ImageServer. If not specified, the currently opened in QuPath ImageServer is used
- **pixel_access** (str) - Optional - How to send pixel values from QuPath to Python. Can be 'base_64' to convert pixels to base 64 encoded text, 'bytes' to convert pixels to bytes, or 'temp_files' to use temporary files
- **resize_method** - Optional - The resampling method to use when resizing the image for downsampling. Bicubic by default

### Raises
- **ValueError** - When pixel_access has an unexpected value
```

--------------------------------

### Get annotations as JavaObject

Source: https://qupath.github.io/qubalab-docs/notebooks_files/working_with_objects.html

Retrieves annotations as Java objects using the default converter. The output shows the annotation's name and type.

```python
annotations = qupath_gateway.get_objects(object_type = object_type)

for annotation in annotations:
    print(annotation)
```

```text
Hello from Python (Region*)
Annotation
```

--------------------------------

### Create QuPathServer instance

Source: https://qupath.github.io/qubalab-docs/notebooks_files/communicating_with_qupath.html

Creates a QuPathServer object from the qubalab.images.qupath_server module, passing the gateway. This server implements the ImageServer interface, providing access to image metadata and pixel data.

```python
from qubalab.images.qupath_server import QuPathServer

server = QuPathServer(gateway)

```

--------------------------------

### Get annotations as GeoJSON

Source: https://qupath.github.io/qubalab-docs/notebooks_files/working_with_objects.html

Retrieves annotations as GeoJSON, returning ImageFeature objects that are no longer connected to QuPath. The output shows the type of the first object.

```python
annotations = qupath_gateway.get_objects(object_type = object_type, converter='geojson')

print(type(annotations[0]))
```

```text
<class 'qubalab.objects.image_feature.ImageFeature'>
```

--------------------------------

### qubalab.images.wrapped_image_server module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Module for wrapped image server.

```APIDOC
## Class: WrappedImageServer

### Description
Wraps an existing image server.

### Properties
- `base_server` - The base image server.

### Methods
- `close()` - Closes the server.
```

--------------------------------

### Create IccProfileServer from existing server

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Creates an IccProfileServer from an existing OpenSlideServer. The two servers share metadata but pixel values may differ slightly.

```python
from qubalab.images.icc_profile_server import IccProfileServer

# Create the IccProfileServer from the existing OpenslideServer. The two servers will have the same metadata, but pixel values might differ a bit
icc_profile_server = IccProfileServer(openslide_server)

```

--------------------------------

### Create AICSImageIoServer from image path

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Creates an AICSImageIoServer from the LuCa-7color image path. The output shows a pydantic migration warning.

```python
from qubalab.images.aicsimageio_server import AICSImageIoServer


# Create the ImageServer from the image path. This will read the image metadata but not the pixel values yet.
# This function has optional parameters you can find in the documentation
aicsimageio_server = AICSImageIoServer(luca_path)

```

```text
/Users/lleplat/QuPath/Projects/qubalab/qubalab/.venv/lib/python3.12/site-packages/pydantic/_migration.py:283: UserWarning: `pydantic.error_wrappers:ValidationError` has been moved to `pydantic:ValidationError`.
  warnings.warn(f'`{import_path}` has been moved to `{new_location}`.')

```

--------------------------------

### OpenSlideServer constructor

Source: https://qupath.github.io/qubalab-docs/qubalab.images.html

Creates an OpenSlideServer instance to read RGB images using OpenSlide. Parameters control alpha stripping, single channel extraction, and bounding rectangle limiting.

```APIDOC
## OpenSlideServer(path, strip_alpha=True, single_channel=False, limit_bounds=True, **kwargs)

### Description
Creates an OpenSlideServer instance to read RGB images using OpenSlide. Parameters control alpha stripping, single channel extraction, and bounding rectangle limiting.

### Parameters
- **path** (str) - Required - The local path to the image to open
- **strip_alpha** (bool) - Optional - Whether to strip the alpha channel from the image
- **single_channel** (bool) - Optional - Whether to keep only the first channel of the image
- **limit_bounds** (bool) - Optional - Whether to only consider a rectangle bounding the non-empty region of the slide, if such rectangle is defined in the properties of the image
- **resize_method** - Optional - The resampling method to use when resizing the image for downsampling. Bicubic by default
```

--------------------------------

### create_snapshot

Source: https://qupath.github.io/qubalab-docs/qubalab.qupath.html

Creates and returns a snapshot of QuPath, either the entire window or just the viewer.

```APIDOC
## create_snapshot(gateway=None, snapshot_type='qupath') -> ndarray

### Description
Create and return a snapshot of QuPath.

### Parameters
- **gateway** (JavaGateway | None) - Optional - The gateway to use. Can be None to use the default gateway.
- **snapshot_type** (str) - Optional - What to include in the snapshot. 'qupath' for the entire qupath window or 'viewer' for only the viewer.

### Returns
- **ndarray** - A numpy array with dimensions (y, x, c) representing an RGB image.

### Raises
- **ValueError** - If the snapshot type was not recognized.
```

--------------------------------

### qubalab.images.utils module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Utility functions for image handling.

```APIDOC
## Functions

### `base64_to_image()`
Converts a base64 string to an image.

### `bytes_to_image()`
Converts bytes to an image.
```

--------------------------------

### qubalab.images.image_server module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Module for the base ImageServer class.

```APIDOC
## Class: ImageServer

### Description
Base class for image servers.

### Methods
- `close()` - Closes the image server.
- `level_to_dask()` - Converts a level to a Dask array.
- `read_region()` - Reads a region from the image.
- `to_dask()` - Converts the image to a Dask array.

### Properties
- `metadata` - Image metadata.
```

--------------------------------

### qubalab.images.labeled_server module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Module for labeled image server.

```APIDOC
## Class: LabeledImageServer

### Description
Server for labeled images.

### Methods
- `close()` - Closes the server.
```

--------------------------------

### Create multichannel masks with LabeledImageServer

Source: https://qupath.github.io/qubalab-docs/notebooks_files/working_with_objects.html

Creates a multichannel LabeledImageServer to generate a stack of masks, one per annotation. The resulting masks array has (n+1) channels, where channel i corresponds to the i-th annotation. Plots the first mask using plotImage with channel=1.

```python
# Create another LabeledImageServer, which will represent a stack of masks here
mask_server = LabeledImageServer(qupath_server.metadata, annotations, downsample=downsample, multichannel=True)

# Compute and return the masks
masks = mask_server.read_region()

# masks contains (n+1) channels, where n is the number of annotations
# The i channel corresponds to the mask representing the i annotation
# Let's plot the first mask corresponding to the first annotation
_, ax = plt.subplots()
plotImage(ax, masks, channel=1)
```

--------------------------------

### qubalab.images.openslide_server module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Module for OpenSlide server.

```APIDOC
## Class: OpenSlideServer

### Description
Server for OpenSlide images.

### Methods
- `close()` - Closes the server.
```

--------------------------------

### Create QuPath gateway with qubalab

Source: https://qupath.github.io/qubalab-docs/notebooks_files/working_with_objects.html

Creates a gateway to QuPath using the default port 25333 and an optional auth token. The output confirms the gateway was created successfully.

```python
from qubalab.qupath import qupath_gateway

token = None   # change the value of this variable if you provided a token while creating the QuPath gateway
port = 25333   # change the value of this variable if you provided a different port while creating the QuPath gateway
gateway = qupath_gateway.create_gateway(auth_token=token, port=port)

print("Gateway created")
```

```text
Gateway created
```

--------------------------------

### Read tile at arbitrary downsample with to_dask

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Reads a tile from an arbitrary downsample using ImageServer.to_dask() with downsample=1.5. Note that requesting an arbitrary downsample is very slow because all pixels are requested on first compute, and a UserWarning about affine_transform on a large dask array may be emitted.

```python
# Read and show a tile of the image at an arbitray downsample

downsample = 1.5
image = server.to_dask(downsample)

# Pixel values are not read yet, but you can get the shape of the image
print(f'Image shape at downsample {downsample}: {image.shape}')

# Only read a 2000x1000 pixels tile whose top left pixel is located at x=13000 and y=15000 on the downsampled image
x = 13000
y = 15000
width = 2000
height = 1000
tile = image[:, y:y+height, x:x+width]

print(f'Tile shape: {tile.shape}')

# Compute array. This will only read the pixel values of the tile, not the entire image
# This can take some time as explained above
tile = tile.compute()

_, ax = plt.subplots()
plotImage(ax, tile)
```

```text
/Users/lleplat/QuPath/Projects/qubalab/qubalab/qubalab/images/image_server.py:200: UserWarning: Warning - calling affine_transform on a large dask array can be *very* slow
  warnings.warn('Warning - calling affine_transform on a large dask array can be *very* slow')
```

```text
Image shape at downsample 1.5: (3, 21943, 30667)
Tile shape: (3, 1000, 2000)
```

--------------------------------

### qubalab.qupath.qupath_gateway.get_project

Source: https://qupath.github.io/qubalab-docs/qubalab.qupath.html

Returns the currently opened QuPath project as a JavaObject. Optionally accepts a gateway to use.

```APIDOC
## qubalab.qupath.qupath_gateway.get_project

### Description
Returns the currently opened QuPath project.

### Parameters
- **gateway** (JavaGateway | None) - The gateway to use. Can be None to use the default gateway.

### Returns
- A Java Object representing the currently opened QuPath project.
```

--------------------------------

### Access QuPathGUI Java object via gateway.entry_point.getQuPath()

Source: https://qupath.github.io/qubalab-docs/notebooks_files/communicating_with_qupath.html

Retrieves a QuPathGUI Java object using getQuPath(), stores it in a variable, and prints its type, imageData property, and version. The output shows the type is a py4j JavaObject, and the version is '0.6.0-SNAPSHOT'.

```python
qupath_GUI = gateway.entry_point.getQuPath()  # qupath_GUI represents a QuPathGUI Java object

print(f"Type of qupath_GUI: {type(qupath_GUI)}")    # qupath_GUI is a JavaObject 

# The documentation of a QuPathGUI Java object can be found here:
# https://qupath.github.io/javadoc/docs/qupath/lib/gui/QuPathGUI.html
# For example, we can call the imageData property and the getVersion() function:
print(f"Image data: {qupath_GUI.imageData}")
print(f"Version: {qupath_GUI.getVersion()}")

```

```output
Type of qupath_GUI: <class 'py4j.java_gateway.JavaObject'>
Image data: <py4j.java_gateway.JavaMember object at 0x7f0408d1fd70>
Version: 0.6.0-SNAPSHOT

```

--------------------------------

### qubalab.images.qupath_server module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Module for QuPath server.

```APIDOC
## Class: QuPathServer

### Description
Server for QuPath images.

### Methods
- `close()` - Closes the server.
```

--------------------------------

### Convert scikit-image threshold masks to QuPath annotations

Source: https://qupath.github.io/qubalab-docs/notebooks_files/working_with_objects.html

Uses scikit-image to segment the QuPath image into annotations. Reads the image with `read_region()` at a downsample of 20, converts to grayscale (handling RGB), applies a Gaussian filter with sigma 2, then for each threshold (Otsu and Triangle) creates a maskaine and `ImageFeature.create_from_label_image()` to add annotations to QuPath. The mask is scaled to match the QuPath image. Requires `qupath_server` and `qupath_gateway` variables.

```python
import numpy as np
import matplotlib.pyplot as plt
from skimage.filters import gaussian, threshold_otsu, threshold_triangle
from skimage.color import rgb2gray
from qubalab.objects.image_feature import ImageFeature


# Set a downsample. The labeled image will be 20 times smaller than the image currently opened in QuPath
downsample = 20

# Set different threshold methods to apply to the image
threshold_methods = {
    'Otsu' : threshold_otsu,
    'Triangle' : threshold_triangle
}

# Read image opened in QuPath
image = qupath_server.read_region(downsample=downsample)

# Convert the image to greyscale
if qupath_server.metadata.is_rgb:
    # If the image is RGB, we convert it to grayscale
    # read_region() returns an image with the (c, y, x) shape.
    # To use rgb2gray, we need to move the channel axis so that
    # the shape becomes (y, x, c)
    image = np.moveaxis(image, 0, -1)
    image = rgb2gray(image)
else:
    # Else, we only consider the first channel of the image
    image = image[0, ...]

# Apply a gaussian filter
image = gaussian(image, 2.0)

# Iterate over threshold methods
for i, (name, method) in enumerate(threshold_methods.items()):
    # Apply threshold to image
    threshold = method(image)

    # Create mask from threshold
    mask = image < threshold

    # Create annotations from mask
    annotations = ImageFeature.create_from_label_image(
        mask,   
        scale=downsample,   # mask is 20 times smaller than the QuPath image, so we scale
                            # the annotations to fit the QuPath image
        classification_names=name,  # set a single classification to the detected annotations
    )

    # Add annotations to QuPath
    qupath_gateway.add_objects(annotations)

    # Plot mask
    plt.subplot(1, len(threshold_methods), i+1)
    plt.imshow(mask)
    plt.title(f'{name} (threshold={threshold:.2f})')
    plt.axis(False)
plt.show()
```

--------------------------------

### qubalab.images.aicsimageio_server module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Module for AICSImageIO server integration.

```APIDOC
## Module: qubalab.images.aicsimageio_server

### Description
Module for AICSImageIO server integration.
```

--------------------------------

### qubalab.images.metadata package

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Package for image metadata handling.

```APIDOC
## Package: qubalab.images.metadata

### Modules
- `image_channel`
- `image_metadata`
- `image_shape`
- `pixel_calibration`
```

--------------------------------

### Define get_image utility function

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Utility function to download or retrieve an image from a URL, using the cache folder if set. Creates the cache directory if needed.

```python
# Define a utility function to find or download an image

from pathlib import Path
import urllib.request

if cache_folder != "":
    Path(cache_folder).mkdir(parents=True, exist_ok=True)

def get_image(image_name, image_url):
    if cache_folder == "":
        filename = None
    else:
        filename = Path(cache_folder) / image_name
    
    if filename is None or not(filename.exists()):
        print(f"Downloading {image_name}...")
        path, _ = urllib.request.urlretrieve(image_url, filename=filename)
        print(f'{image_name} saved to {path}')
    else:
        path = filename
        print(f'{image_name} found in {path}')

    return path

```

--------------------------------

### create_gateway

Source: https://qupath.github.io/qubalab-docs/qubalab.qupath.html

Creates a new JavaGateway to communicate with QuPath, requiring QuPath to be launched with Py4J activated.

```APIDOC
## create_gateway(auto_convert=True, auth_token=None, port=25333, set_as_default=True, **kwargs) -> JavaGateway

### Description
Create a new JavaGateway to communicate with QuPath. This requires launching QuPath and activating Py4J from there first.

### Parameters
- **auto_convert** (bool) - Optional - If True, the gateway will try to automatically convert Python objects like sequences and maps to Java Objects.
- **auth_token** (str | None) - Optional - The authentication token to use to connect. Can be None if no authentication is used.
- **port** (int) - Optional - The port to use to connect.
- **set_as_default** (bool) - Optional - Whether to set the created gateway as the default gateway.
- **kwargs** - Optional - Additional arguments to give to the JavaGateway constructor.

### Returns
- **JavaGateway** - The created gateway.

### Raises
- **RuntimeError** - If the connection to QuPath couldn't be established.
```

--------------------------------

### qubalab.images.icc_profile_server module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Module for ICC profile server operations.

```APIDOC
## Class: IccProfileServer

### Description
Server for handling ICC profiles.

### Methods
- `icc_transform` - Performs ICC profile transformation.
```

--------------------------------

### qubalab.objects.geometry module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Module for geometry handling.

```APIDOC
## Classes
- `ImagePlane`

## Functions
- `add_plane_to_geometry()` - Adds a plane to a geometry.
```

--------------------------------

### ImageShape.from_tczyx

Source: https://qupath.github.io/qubalab-docs/qubalab.images.metadata.html

Creates an ImageShape from a list of arguments in the order: width, height, time points, channels, z-stacks. Raises IndexError if fewer than five arguments are provided.

```APIDOC
## ImageShape.from_tczyx

### Description
Creates an ImageShape from a list of arguments.

### Method
from_tczyx

### Parameters
#### Parameters
- **args** (list) - Required - Image width, image height, number of time points, number of channels, number of z-stacks (in that order).

### Returns
- **ImageShape** - An ImageShape corresponding to the arguments.

### Raises
- **IndexError** - When there are less than five arguments.
```

--------------------------------

### ImageServer.to_dask()

Source: https://qupath.github.io/qubalab-docs/qubalab.images.html

Converts the image to one or more dask arrays at arbitrary downsample factors.

```APIDOC
## ImageServer.to_dask(downsample=None)

### Description
Converts this image to one or more dask arrays, at any arbitrary downsample factor. It turns out that requesting at an arbitrary downsample level is very slow - currently, all pixels are requested upon first compute (even for a small region), and then resized. Prefer using ImageServer.level_to_dask() instead.

### Method
to_dask(downsample=None)

### Parameters
- **downsample** (float | Iterable[float] | None) - Optional - The downsample factor to use, or a list of downsample factors to use. If None, all available resolutions will be used.

### Returns
- **dask.array.Array | tuple[dask.array.Array, ...]** - A dask array or tuple of dask arrays, depending upon whether one or more downsample factors are required.

```

--------------------------------

### ImageServer.level_to_dask()

Source: https://qupath.github.io/qubalab-docs/qubalab.images.html

Returns a dask array representing a single resolution of the image.

```APIDOC
## ImageServer.level_to_dask(level=0, chunk_width=1024, chunk_height=1024)

### Description
Returns a dask array representing a single resolution of the image. Pixels of the returned array can be accessed with the following order: (t, c, z, y, x). There may be less dimensions for simple images.

### Method
level_to_dask(level=0, chunk_width=1024, chunk_height=1024)

### Parameters
- **level** (int) - Optional - The pyramid level (0 is full resolution). Must be less than the number of resolutions of the image.
- **chunk_width** (int) - Optional - The size of the chunks on the x-axis.
- **chunk_height** (int) - Optional - The size of the chunks on the y-axis.

### Returns
- **dask.array.Array** - A dask array containing all pixels of the provided level.

### Raises
- **ValueError** - When level is not valid.

```

--------------------------------

### qubalab.objects.draw module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Module for drawing functions.

```APIDOC
## Functions

### `draw_geometry()`
Draws a geometry.
```

--------------------------------

### Set cache folder for image downloads

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Defines the cache folder for downloaded images. Leave blank to avoid caching.

```python
cache_folder = ""   # define a folder where images will be stored. Leave blank to not use any cache

```

--------------------------------

### PixelLength.create_microns

Source: https://qupath.github.io/qubalab-docs/qubalab.images.metadata.html

Creates a PixelLength with a unit of micrometers (µm). This is a static factory method for micron-based pixel lengths.

```APIDOC
## PixelLength.create_microns

### Description
Creates a PixelLength with a unit of micrometers (µm).

### Method
create_microns (static)

### Parameters
#### Parameters
- **length** (float) - Required - The length of the pixel.

### Returns
- **PixelLength** - A pixel length of the provided length with the 'micrometer' unit.
```

--------------------------------

### qubalab.images.region_2d module

Source: https://qupath.github.io/qubalab-docs/qubalab.html

Module for 2D region handling.

```APIDOC
## Class: Region2D

### Description
Represents a 2D region.

### Methods
- `downsample_region()` - Downsamples the region.
- `scale_region()` - Scales the region.

### Properties
- `geometry` - Geometry of the region.
- `height` - Height of the region.
- `t` - Time index.
- `width` - Width of the region.
- `x` - X coordinate.
- `y` - Y coordinate.
- `z` - Z index.
```

--------------------------------

### Read tile from full resolution with level_to_dask

Source: https://qupath.github.io/qubalab-docs/notebooks_files/opening_images.html

Reads a tile from the full resolution image using level_to_dask() with level 0. The tile is defined by x=13000, y=15000, width=2000, height=1000, and only the tile's pixels are read on compute.

```python
# Read and show tile of full resolution image with level_to_dask

first_level = 0
highest_resolution = server.level_to_dask(first_level)

print(f'Full resolution image shape: {highest_resolution.shape}')

# Only read a 2000x1000 pixels tile whose top left pixel is located at x=13000 and y=15000 on the full resolution image
x = 13000
y = 15000
width = 2000
height = 1000
tile = highest_resolution[:, y:y+height, x:x+width]

print(f'Tile shape: {tile.shape}')

# Compute array. This will only read the pixel values of the tile, not the entire image
tile = tile.compute()

_, ax = plt.subplots()
plotImage(ax, tile)
```

```text
Full resolution image shape: (3, 32914, 46000)
Tile shape: (3, 1000, 2000)
```
Tokens:
Raw