gtagora-workbook-py

Agora workbook utilities for Python

Pure, dependency-free (no numpy, no HTTP client) helpers for working with the JSON shape of an Agora Workbook - mask RLE encoding, default CMR contour/landmark button templates, and merging new masks/contour groups into an existing workbook session. No network code lives here; it's meant to be shared by anything that needs to build or read Workbook data, whether that's a REST client (see gtagora-connector-py, which depends on this package) or code with direct database access.

Installation

pip install gtagora-workbook-py

Usage

Mask encoding/decoding (workbook.mask)

Encode a (size_x * size_y) label array into the base64 RLE format used by a Workbook mask's mSliceMask[i].mBase64Values, and decode it back:

from workbook.mask import encode_mask, decode_mask

encoded = encode_mask(labels)  # labels: flat list of ints, one per pixel
decoded = decode_mask(encoded, len(labels))
assert decoded == labels

Decode a full Workbook mask dict (mSizeX/Y/Z/T plus one mSliceMask entry per (z, t)) into a flat list and its (X, Y, Z, T) shape:

from workbook.mask import decode_full_mask

decoded = decode_full_mask(mask)  # mask: one entry of workbook['mask']['mMasks']
print(decoded.shape)  # (size_x, size_y, size_z, size_t)

Convert to a numpy array with a single call:

import numpy as np

array = np.array(decoded.data, dtype=np.uint8).reshape(decoded.shape)

Default CMR templates (workbook.templates)

from workbook.templates import default_cmr_contour_buttons, default_cmr_landmark_buttons, new_cmr_workbook_body

object_buttons = default_cmr_contour_buttons() + default_cmr_landmark_buttons()
body = new_cmr_workbook_body(dataset_id=158, name='CMR Workbook')  # ready to POST to a Workbook endpoint

Merging into an existing workbook session (workbook.session)

from workbook.session import merge_contour_session, merge_mask_session, resolve_contour_buttons

# insert/replace `mask` (by its 'name') into an existing mask session
mask_session = merge_mask_session(workbook['mask'], workbook_id=workbook['id'], mask=mask)

# insert/replace contour groups (by 'name') and set the object buttons
contour_session = merge_contour_session(
    workbook['contour'], workbook_id=workbook['id'],
    contour_groups=contour_groups, object_buttons=object_buttons)

# a workbook's own contour buttons, or the default CMR set if it has none yet
object_buttons = resolve_contour_buttons(workbook.get('contour'))