pylibCZIrw

https://github.com/zeiss/pylibczirw
Admin
pylibCZIrw is a Python wrapper for the libCZI C++ library that provides read and write access to CZI...
Tokens:25,740
Snippets:299
Trust Score:9.6
License:GPL-3.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install dependencies

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Install required dependencies for the CziConverter repository.

```bash
pip install .
```

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

### Editable installation

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Install the package in editable mode for development purposes.

```bash
pip install . -e
```

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

### Build and install wheel

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Commands to create a wheel file and install it in a target project.

```bash
python setup.py bdist_wheel
```

```bash
pip install <RepositoryDirectory>\pylibczirw\dist\pylibCZIrw-3.4.0-cp310-cp310-win_amd64.whl
```

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

### Install pylibCZIrw and dependencies

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Install the required library and its dependencies using pip.

```python
# Install pylibCZIrw and dependencies
! pip install --upgrade pip
! pip install "pylibCZIrw~=4.1" "cztile>=0.0,<1.0" matplotlib tqdm pooch
```

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

### Install project dependencies

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Commands to install the package and testing requirements within the active environment.

```bash
pip install .
pip install -r requirements_test.txt
```

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

### Install pylibczirw via pip

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Standard installation command for the library from the repository root.

```bash
pip install .
```

```bash
pip install --use-feature=in-tree-build .
```

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

### Initialize CZI File Paths and Data

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Setup random data and file paths for demonstrating compression.

```python
# create some array to write to CZI
array_big = np.random.randint(low=1, high=50, size=(4096, 4096)).astype(np.uint16)

# create the filename for the new CZI image file
newczi_uncompressed = os.path.join(os.getcwd(), "newCZI_uncompressed.czi")

# create the filename for the new CZI image file
newczi_compressed = os.path.join(os.getcwd(), "newCZI_compressed.czi")
```

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

### Install package requirements

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Commands to upgrade pip and install package requirements from PyPI.

```bash
python -m pip install --upgrade --requirement requirements.txt
```

```bash
python -m pip install pylibCZIrw --index-url https://pkgs.dev.azure.com/ZEISSgroup/RMS-DEV/_packaging/RMS-PyPI/pypi/simple
```

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

### Install with In-Tree Build

Source: https://github.com/zeiss/pylibczirw/blob/main/TROUBLESHOOTING.md

Required when pip installation hangs during the build process.

```bash
pip install --use-feature=in-tree-build .[all]
```

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

### Configure Python Interpreter Path

Source: https://github.com/zeiss/pylibczirw/blob/main/TROUBLESHOOTING.md

Example path for setting the base Python interpreter in PyCharm.

```text
%USERPROFILE%\.conda\envs\pylibczi310\python.exe
```

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

### Create and write pixel data to a CZI file

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] High level API.ipynb

Demonstrates initializing a new CZI document and writing numpy arrays as pixel data for specific channels.

```python
import numpy as np

demo_czi_write = r'D:\pylibCZIrw_demo\demo_write_0.czi'

with czi.create_czi(demo_czi_write) as new_czi_doc:
    plane_0 = {'C': 0}
    plane_1 = {'C': 1}
    data_gray8 = np.random.randint(255, size=(1024,1024,1),dtype=np.uint8)
    data_bgr24 = np.random.randint(255, size=(1024,1024,3),dtype=np.uint8)

    new_czi_doc.write(data=data_gray8, plane=plane_0)
    new_czi_doc.write(data=data_bgr24, plane=plane_1)
```

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

### Get Dimension Size

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Returns the size of the specified dimension.

```python
Czi_im.GetDimensionSize(dim) #the .czi has 300 scenes
```

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

### Clone repository with submodules

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Use this command to clone the repository and initialize all submodules automatically.

```bash
git clone --recurse-submodules
```

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

### Get Channel Pixel Type

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Retrieves the pixel type for a specific channel index.

```python
Czi_im.GetChannelPixelType(0)
```

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

### Create and Write to a New CZI File

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Demonstrates opening a new CZI file using a context manager and writing pixel data plane by plane.

```python
# create the filename for the new CZI image file
newczi_4dstack = os.path.join(os.getcwd(), "newCZI_stack.czi")
numZ = 32

# open a new CZI and allow overwrite (!!!) to play around ...
with pyczi.create_czi(newczi_4dstack, exist_ok=True) as czidoc_w:
    # loop over all z-planes and channels
    for frame in tqdm(range(numZ)):
        # get the 2d array for the current plane and add axis to get (Y, X, 1) as shape
        # write the plane with shape (Y, X, 1) to the new CZI file
        czidoc_w.write(
            data=array[frame, ...][..., np.newaxis],
            plane={"Z": frame}
        )
```

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

### Get Scene Bounding Box

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Accesses bounding box coordinates and dimensions for a specific scene.

```python
scene0_x = stats.sceneBoundingBoxes[0].boundingBox.x # x position of top left corner of scene 0
```

```python
scene0_y = stats.sceneBoundingBoxes[0].boundingBox.y # y position of top left corner of scene 0
```

```python
scene0_w = stats.sceneBoundingBoxes[0].boundingBox.w # total width of scene 0
```

```python
scene0_h = stats.sceneBoundingBoxes[0].boundingBox.h # total height of scene 0
```

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

### Create a new CZI file

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Initializes a new CZI file in write mode using a context manager. Use exist_ok=True to prevent FileExistsError if the path already exists.

```python
with czi.create_czi(file_path) as czi:
```

```python
with czi.create_czi(file_path, exist_ok = True) as czi:
```

```python
with czi.create_czi(file_path, exist_ok = True, compression_options = zstd0:) as czi:
```

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

### Project Initialization and C++ Standard

Source: https://github.com/zeiss/pylibczirw/blob/main/CMakeLists.txt

Sets the minimum CMake version, project name, and enforces C++17 standards.

```cmake
cmake_minimum_required(VERSION 3.11)

cmake_policy(SET CMP0091 NEW) # enable new "MSVC runtime library selection" (https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html)

project(_pylibCZIrw VERSION ${PYLIBCZIRW_VERSION})

# Ensure every target (and the atomic probe) uses a modern C++ standard
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
```

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

### Initialize submodules manually

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Use this command if submodules were not linked during the initial repository clone.

```bash
git submodule update --init
```

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

### Perform Tile-wise Read, Process, and Write

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Uses pyczi to open a source file for reading and a destination file for writing, iterating through tiles to process and save data.

```python
# open an existing CZI file for reading planes and a new CZI to insert
# the newly processed chunks into the new CZI file

# create to figures
fig1, ax1 = plt.subplots(1, 4, figsize=(16, 8))
fig2, ax2 = plt.subplots(1, 4, figsize=(16, 8))

# counter figures
a = 0

# open a CZI instance to read and in parallel one to write
with pyczi.open_czi(czifile_DAPI_PGC, ReaderFileInputTypes.Curl) as czidoc_r:
    with pyczi.create_czi(newczi_tile, exist_ok=True) as czidoc_w:
        # loop over all tiles created by the "tiler"
        for tile in tqdm(tiles):
            # read a specific tile from the CZI using the roi parameter
            tile2d = czidoc_r.read(
                plane={"C": 0},
                roi=(
                    tile.roi.x,
                    tile.roi.y,
                    tile.roi.w,
                    tile.roi.h
                )
            )

            # process the current tile using a function
            tile2d_processed = process2d(tile2d, sigma=11)

            # show sthe tiles to illustrate the idea
            ax1[a].imshow(tile2d[..., 0], interpolation="nearest", cmap="gray", vmin=100, vmax=4000)
            ax1[a].set_title("Tile: " + str(a))
            ax2[a].imshow(tile2d_processed[..., 0], interpolation="nearest", cmap="gray", vmin=100, vmax=4000)
            ax2[a].set_title("Tile: " + str(a))

            # write the new CZI file using the processed data
            czidoc_w.write(
                tile2d_processed,
                plane={"C": 0},
                location=(
                    tile.roi.x,
                    tile.roi.y
                )
            )

            a += 1
```

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

### Write CZI file with metadata and display settings

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Illustrates writing image data to a CZI file, including custom attributes, channel naming, and display settings for colors and levels.

```python
data = inference_service.run() # [2, y, x] array with 2 being the number of classes.

with czi.open_czi(path, 'w'):

    class_nuclei = data[0,:,:]
    channel_0 = { 'C': 0 }

    czi.write(data=class_nuclei, location=(0,0), plane=channel_0, compression_options = "zstd0:ExplicitLevel=0" )

    class_background = data[1,:,:]
    channel_1 = { 'C': 1 }

    czi.write(data=class_background, location=(0,0), plane=channel_1, compression_options = "zstd1:ExplicitLevel=2" )

    # If we stopped here, we'd have a valid CZI. But we want to name the channels after the classes.

    channel_names = { 0: "C1", 1: "C2" }
    custom_attributes = {"key1": "value1", "key2": "value2"}

    czi.write_metadata(channel_names=channel_names, scale_x=0.1 `* 1e-6, scale_y=0.1 * 1e-6, custom_attributes=custom_attributes)

    # If we want to specify specific colors for specific channels, we write as follows:
    # In this case we are specifying c1 as blue and c2 as green.
    
    display_setting_dict: Dict[int, ChannelDisplaySettingsDataClass] = {}
    tint_color_c1 = Rgb8Color(np.uint8(0x00), np.uint8(0xFF), np.uint8(0x00))
    channel_setting_c1 = ChannelDisplaySettingsDataClass(True, TintingMode.Color, tint_color_c1)
    display_setting_dict[0] = channel_setting_c1
    tint_color_c2 = Rgb8Color(np.uint8(0x00), np.uint8(0x00), np.uint8(0xFF))
    channel_setting_c2 = ChannelDisplaySettingsDataClass(True, TintingMode.Color, tint_color_c2)
    display_setting_dict[1] = channel_setting_c2

    czi.write_metadata(display_settings=display_setting_dict)

    # Similarly, if we want to specify specific colors and black/white levels for specific channels, we write as follows:
    # In this case we are specifying c1 as blue and c2 as green.
    # Additionally we specify c1 with black point as 0.2 and white point as 0.8 and c2 with black point as 0.3 and white point as 0.75.

    display_setting_dict: Dict[int, ChannelDisplaySettingsDataClass] = {}
    tint_color_c1 = Rgb8Color(np.uint8(0x00), np.uint8(0xFF), np.uint8(0x00))
    channel_setting_c1 = ChannelDisplaySettingsDataClass(True, TintingMode.Color, tint_color_c1, 0.2, 0.8)
    display_setting_dict[0] = channel_setting_c1
    tint_color_c2 = Rgb8Color(np.uint8(0x00), np.uint8(0x00), np.uint8(0xFF))
    channel_setting_c2 = ChannelDisplaySettingsDataClass(True, TintingMode.Color, tint_color_c2, 0.3, 0.75)
    display_setting_dict[1] = channel_setting_c2

    czi.write_metadata(display_settings=display_setting_dict)

    # Note: writing display setting for a channel overwrites any existing display setting as we do not fetch the current display setting.
    # Note: There is no 1:1 relationship enforced. A user may decide to add display settings to each channel or only to some channels.
    #       Similarly, it is not verified if the user sends more display settings than channels present.
    #       Display setting that are not written will be set as 'empty' regardless of if the initially existed for that channel.
```

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

### czi.create_czi(file_path, exist_ok=False, compression_options=None)

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Creates a new empty CZI file at the specified path and opens it in write mode.

```APIDOC
## czi.create_czi

### Description
Creates a new empty CZI file at the provided path and opens it in write mode. Intermediate directories are created if necessary.

### Parameters
- **file_path** (path-like-object) - Required - The path where the CZI file will be created.
- **exist_ok** (bool) - Optional - If True, ignores FileExistsError if the file already exists. Defaults to False.
- **compression_options** (str) - Optional - String representation of compression options.
```

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

### Initialize CZI Reader

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Import the reader class and instantiate it with a file path to open a .czi file.

```python
from _pylibCZIrw import czi_reader
```

```python
Czi_im = czi_reader("test/well.czi")
```

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

### Update document info and scaling

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Demonstrates updating general document information and pixel scaling factors using the metadata builder.

```python
from pylibCZIrw.czi import edit_czi, ScalingInfoDto, GeneralDocumentInfoDto
with edit_czi(file_path) as editor: builder = editor.create_metadata_builder()
builder.set_general_document_info(
    info=GeneralDocumentInfoDto(title="New Title"),
    user_name="EditorUser",
    comment="Edited by API",
)

builder.set_scaling_info(scale_x=0.25, scale_y=0.25)  # leave Z unchanged

if builder.can_commit():
    builder.commit()

# Verify
info = editor.read_general_document_info()
scaling = editor.read_scaling_info()
```

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

### Initialize an edit session

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Create a metadata builder to stage changes before committing them to the file.

```python
with edit_czi(file_path) as editor: builder = editor.create_metadata_builder() # or use auto-commit on success: with editor.edit_session() as builder: ...
```

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

### Instantiate CZI Writer

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Creates a new CZI file at the specified path and returns a writer object.

```python
from _pylibCZIrw import czi_writer
```

```python
CziWriter = czi_writer("demo_names.czi")
```

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

### Run local linting with Mega-Linter

Source: https://github.com/zeiss/pylibczirw/blob/main/CONTRIBUTING.md

Executes the project's linting suite locally using a Docker container to match CI/CD validation.

```bash
docker run --rm -t `
  -v "${PWD}:/tmp/lint" `
  -w /tmp/lint `
  -e VALIDATE_ALL_CODEBASE=true `
  -e IGNORE_GIT_SUBMODULES=true `
  -e PRETTIER_DEFAULT_OPTIONS="--end-of-line=lf" `
  -e FILTER_REGEX_EXCLUDE="(^|/)?libs/(pybind11|libCZIrw)/" `
  oxsecurity/megalinter:v7
```

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

### Dependency and Build Configuration

Source: https://github.com/zeiss/pylibczirw/blob/main/CMakeLists.txt

Configures build flags for libCZI and global project settings like PIC and shared library status.

```cmake
# bring in libczi (which is a git-submodule of this repository)
# we turn off some unnecessary things 
set(LIBCZI_BUILD_UNITTESTS OFF CACHE  BOOL "" FORCE)
set(LIBCZI_BUILD_DYNLIB OFF CACHE  BOOL "" FORCE)
set(LIBCZI_BUILD_CZICMD OFF CACHE  BOOL "" FORCE)
set(LIBCZI_DO_NOT_SET_MSVC_RUNTIME_LIBRARY ON CACHE  BOOL "" FORCE) # instruct to NOT set the runtime library (we do this ourselves above)

# this will instruct to build a static library for CPR (in case we download and build it ourselves within libCZI)
# TODO(JBL): - not sure whether it is a good idea to fiddle with this "general" variable here, is there are way to have it more specific to the CPR-build
#               (and maybe this should better be handled in libCZI)
#            - same applies to enabling PIC (position independent code) below - is there a way to do this more specific to the CPR-build?
#            - should we do this only for Linux - and maybe only if we build CPR ourselves?
set(BUILD_SHARED_LIBS FALSE CACHE  BOOL "" FORCE)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
```

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

### Open a CZI file with reader options

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Configures both cache and reader options to control tile composition and coordinate validation.

```python
cache_options = CacheOptions(
  type = CacheType.Standard,
  max_memory_usage = 500 * 1024**2 # 500 Megabytes
  max_sub_block_count = 100,
)
reader_options = ReaderOptions(
  enable_mask_awareness = True,
  lax_subblock_coordinate_checks = False,
  ignore_sizem_for_pyramid_subblocks = True,
)
with czi.open_czi(file_path, cache_options=cache_options, reader_options=reader_options) as czi:
    ...
```

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

### Open CZI files with context managers

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Use a context manager to open CZI files from local disk or via HTTP URL.

```python
from pylibCZIrw import pyczi

with czi.open_czi(file_path) as czi:

    # add your code here

with czi.open_czi(file_url, pyczi.ReaderFileInputTypes.Curl) as czi:

    # add your code here
```

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

### Configuration File Generation

Source: https://github.com/zeiss/pylibczirw/blob/main/CMakeLists.txt

Generates the project configuration header from an input template.

```cmake
# Set library version in the code
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/_pylibCZIrw/src/pylibCZIrw_Config.h.in ${CMAKE_CURRENT_SOURCE_DIR}/_pylibCZIrw/src/pylibCZIrw_Config.h @ONLY)
```

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

### Import pylibczirw library

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Import statements for accessing the library bindings.

```python
from pylibCZIrw import czi
```

```python
from _pylibCZIrw import czi
```

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

### Create and activate conda environment

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Commands to create a new conda environment and activate it for project development.

```bash
conda create -p <some-path\PyPI\pylibCZIrw> python
conda activate <environment_name>
```

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

### Initialize RgbFloatColor for Background

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Import and configure the RgbFloatColor object to set the background fill color.

```python
from _pylibCZIrw import RgbFloatColor
```

```python
bgColor = RgbFloatColor()
bgColor.r = 0
bgColor.g = 0
bgColor.b = 0 # Here the background color will be black (very uncommon choice)
```

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

### Write data with scene indexing

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] High level API.ipynb

Illustrates tagging written data with a specific scene index.

```python
demo_czi_write = r'D:\pylibCZIrw_demo\demo_write_scenes.czi'

with czi.create_czi(demo_czi_write) as new_czi_doc:
    new_czi_doc.write(data=data_gray8, plane=plane_0, scene=0)
    #test
    new_czi_doc.write(data=data_gray8, plane=plane_0, location=(2000, 0), scene=1)
```

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

### Import required modules

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Import the necessary pylibCZIrw components and standard Python libraries for image processing and visualization.

```python
from pylibCZIrw import czi as pyczi
from pylibCZIrw.czi import ReaderFileInputTypes, CacheOptions, CacheType
import json
import timeit
from matplotlib import pyplot as plt
import matplotlib.cm as cm
import numpy as np
import os, sys
from tqdm import tqdm
from tqdm.contrib import itertools as it
from matplotlib.patches import Rectangle
from IPython.display import display, JSON

# show the used python env
print("Using:", sys.executable)
```

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

### Open a CZI file for editing

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Use the edit_czi context manager to access the file and read existing metadata.

```python
from pylibCZIrw.czi import edit_czi
with edit_czi(file_path) as editor: assert editor.is_open xml = editor.read_metadata_xml()
```

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

### Pull Git Submodules

Source: https://github.com/zeiss/pylibczirw/blob/main/TROUBLESHOOTING.md

Use this command to initialize and pull linked library dependencies if the libs folder is empty.

```bash
git pull --recurse-submodules
```

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

### Open a CZI file with subblock caching

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Configures subblock caching behavior using CacheOptions to manage memory and subblock count limits.

```python
cache_options = CacheOptions(
  type = CacheType.Standard,
  max_memory_usage = 500 * 1024**2 # 500 Megabytes
  max_sub_block_count = 100,
)
with czi.open_czi(file_path, cache_options=cache_options) as czi:
    ...
```

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

### Import pylibCZIrw czi module

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] High level API.ipynb

Import the czi module to access reading and writing functionality.

```python
from pylibCZIrw import czi
```

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

### write(data, **kwargs)

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Writes pixel data to a CZI file with optional configuration for location, plane, and compression.

```APIDOC
## write(data, **kwargs)

### Description
Writes pixel data to the CZI file. Supports specifying the location, plane, and compression settings.

### Parameters
- **data** (array) - Required - The pixel data to write.
- **location** (tuple) - Optional - The coordinate location for the data.
- **plane** (dict) - Optional - The plane index for the data.
- **compression_options** (dict) - Optional - Settings for data compression.
- **scene** (int) - Optional - The scene index for the data.
```

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

### Configure library build properties

Source: https://github.com/zeiss/pylibczirw/blob/main/_pylibCZIrw/src/api/CMakeLists.txt

Sets include directories, link dependencies, compiler standards, and position-independent code properties for the library.

```cmake
target_include_directories(_pylibCZIrw_API PRIVATE ${libCZI_SOURCE_DIR})
target_link_libraries(_pylibCZIrw_API INTERFACE libCZIStatic JxrDecodeStatic)
target_compile_features(_pylibCZIrw_API PRIVATE cxx_std_17)
set_property(TARGET _pylibCZIrw_API PROPERTY POSITION_INDEPENDENT_CODE ON)
```

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

### Compare CZI File Sizes

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Calculate and print the file size difference between compressed and uncompressed CZI files.

```python
size = os.path.getsize(newczi_uncompressed)/1024.0**2
print(f"Size of the uncompressed CZI file : {np.round(size, 2)} MB ")

size_comp = os.path.getsize(newczi_compressed)/1024.0**2
print(f"Size of the compressed CZI file 1 : {np.round(size_comp, 2)} MB ")

print(f"ZSTD Compression Ratio 1: {np.round(size/size_comp, 2)}")
```

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

### Write Tile and Metadata

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Writes a tile to the CZI document and updates the file metadata.

```python
CziWriter.AddTile("T0Z0C0",demo_bitmap, 0, 0, 0)
```

```python
CziWriter.WriteMetadata("Document title", {0:"cusstom_name"})
```

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

### Configure Metadata Edit Test Executable

Source: https://github.com/zeiss/pylibczirw/blob/main/_pylibCZIrw/tests/CMakeLists.txt

Defines the cziedit_tests target using edit_metadata_tests.cpp and links required static libraries.

```cmake
set(TARGET_EDIT_TESTS cziedit_tests)
add_executable(${TARGET_EDIT_TESTS} "edit_metadata_tests.cpp")
target_include_directories(${TARGET_EDIT_TESTS} PRIVATE ${libCZI_SOURCE_DIR})
target_link_libraries(${TARGET_EDIT_TESTS} PRIVATE libCZIStatic _pylibCZIrw_API)
```

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

### Initialize IntRect for ROI

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Import and instantiate the IntRect object to define the region of interest.

```python
from _pylibCZIrw import IntRect
```

```python
roi = IntRect()
roi.x = scene0_x
roi.y = scene0_y
roi.w = scene0_w
roi.h = scene0_h
```

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

### read

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Reads pixel data from the CZI file.

```APIDOC
## read(**kwargs)

### Description
Reads pixel data and returns it as a numpy array. The shape and data type depend on the pixel type (BGR: [y, x, 3], Gray: [y, x, 1]).

### Parameters
- **kwargs** (dict) - Configuration parameters for reading pixel data.

### Returns
- **numpy.ndarray** - The pixel data array.
```

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

### Define _pylibCZIrw_API static library

Source: https://github.com/zeiss/pylibczirw/blob/main/_pylibCZIrw/src/api/CMakeLists.txt

Defines the static library target and its associated source and header files.

```cmake
add_library(
  _pylibCZIrw_API STATIC 
  CZIreadAPI.cpp
  CZIwriteAPI.cpp
  PImage.cpp
  CZIreadAPI.h
  CZIwriteAPI.h
  PImage.h
  inc_libCzi.h
  site.h 
  site.cpp
  StaticContext.cpp
  StaticContext.h
  SubBlockCache.h
  ReaderOptions.h
  CZIeditAPI.h
  CZIeditAPI.cpp)
```

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

### write(data, location=(0, 0), plane=None, compression_options=None, scene=0)

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Writes pixel data as a single subblock into the CZI file.

```APIDOC
## write

### Description
Writes a numpy array as a single subblock in the CZI at a specific location. Data is expected in BGR format.

### Parameters
- **data** (numpy array) - Required - The pixel data to be written. [1, y, x] for single channel, [3, y, x] for BGR.
- **location** (tuple) - Optional - The pixel coordinates (x, y) of the upper-left pixel. Defaults to (0, 0).
- **plane** (dict) - Optional - Dictionary specifying plane coordinates (e.g., {'C': 0, 'T': 1, 'Z': 4}). Defaults to all 0.
- **compression_options** (str) - Optional - String representation of compression options.
- **scene** (int) - Optional - Integer specifying the scene index. Defaults to 0.
```

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

### Define Python Module and Link Dependencies

Source: https://github.com/zeiss/pylibczirw/blob/main/_pylibCZIrw/src/bindings/CMakeLists.txt

Configures the pybind11 module and links necessary internal libraries and include directories.

```cmake
pybind11_add_module(_pylibCZIrw MODULE 
        CZIrw.cpp 
        PbHelper.h 
        PbHelper.cpp
        include_python.h)

target_link_libraries(_pylibCZIrw PRIVATE _pylibCZIrw_API)
target_include_directories(_pylibCZIrw PRIVATE ${libCZI_SOURCE_DIR})
target_compile_features(_pylibCZIrw PRIVATE cxx_std_17)
```

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

### Open a CZI file

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Opens a CZI file in read-only mode using a context manager.

```python
with czi.open_czi(file_path) as czi:
```

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

### MSVC Runtime Library Selection

Source: https://github.com/zeiss/pylibczirw/blob/main/CMakeLists.txt

Forces the use of the static version of the MSVC runtime library.

```cmake
 # Instruct to use the static-version of the runtime library (on Windows) -> c.f. https://cmake.org/cmake/help/latest/variable/CMAKE_MSVC_RUNTIME_LIBRARY.html
set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
```

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

### Configure Memory Check Test Executable

Source: https://github.com/zeiss/pylibczirw/blob/main/_pylibCZIrw/tests/CMakeLists.txt

Defines the mem_check target using read_memcheck.cpp and links required static libraries.

```cmake
set(TARGET_MEMTEST mem_check)
add_executable(${TARGET_MEMTEST} "read_memcheck.cpp")
target_include_directories(${TARGET_MEMTEST} PRIVATE ${libCZI_SOURCE_DIR})
target_link_libraries(${TARGET_MEMTEST} PRIVATE libCZIStatic JxrDecodeStatic _pylibCZIrw_API)
```

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

### czi_writer

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Creates a new CZI file and returns a writer object.

```APIDOC
## czi_writer(filepath)

### Description
Initializes a new CZI file at the specified path and returns a writer object used for adding data.

### Parameters
- **filepath** (str) - Required - The path where the .czi file will be created.

### Returns
- **czi_writer_object** (Object) - The writer object used to perform write operations.
```

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

### czi_reader(filepath)

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Instantiates a new czi_reader object to open and process a .czi file.

```APIDOC
## czi_reader(filepath)

### Description
Opens the .czi file at the specified path and returns a czi_reader object for further operations.

### Parameters
- **filepath** (string) - Required - The file system path to the .czi file.

### Example
```python
from _pylibCZIrw import czi_reader
Czi_im = czi_reader("test/well.czi")
```
```

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

### Write CZI metadata

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] High level API.ipynb

Configures document properties such as names and scaling factors using write_metadata.

```python
demo_czi_write = r'D:\pylibCZIrw_demo\demo_write_metdata.czi'

with czi.create_czi(demo_czi_write) as new_czi_doc:
    new_czi_doc.write(data=data_gray8, plane={'C': 0})
    new_czi_doc.write(data=data_gray8, plane={'C': 1})
    plane_1 = {'C': 1}
    new_czi_doc.write_metadata(
        document_name='foo',
        channel_names={ 0: "foo", 1: "bar" },
        scale_x=1 * 1e-6, scale_y=2 * 1e-6, scale_z=3 * 1e-6
    )
```

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

### Platform-Specific Atomic Library Configuration

Source: https://github.com/zeiss/pylibczirw/blob/main/CMakeLists.txt

Configures additional libraries for std::atomic on macOS to avoid probe issues.

```cmake
# On macOS we don't need extra libs for std::atomic; avoid probe issues
if(APPLE)
  set(ADDITIONAL_LIBS_REQUIRED_FOR_ATOMIC "" CACHE INTERNAL "Additional libs for std::atomic" FORCE)
endif()
```

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

### Tiling a large image with cztile

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] High level API.ipynb

Uses the AlmostEqualBorderFixedTotalAreaStrategy2D to define tiling parameters and writes random data to a new CZI file based on the original file's scene dimensions.

```python
from cztile.fixed_total_area_strategy import AlmostEqualBorderFixedTotalAreaStrategy2D

demo_czi_write = r'D:\pylibCZIrw_demo\copy_with_random_data.czi'

with czi.open_czi(demo_czi_read) as czi_doc_r:
    with czi.create_czi(demo_czi_write) as czi_doc_w:
        # define tile strategy
        tiler = AlmostEqualBorderFixedTotalAreaStrategy2D(
            total_tile_width=450,
            total_tile_height=450,
            min_border_width=15
        )

        # tile scene bounding rectangles instead of the whole 2D plane
        for scene_index in czi_doc_r.scenes_bounding_rectangle.keys():
            tiles = tiler.tile_rectangle(czi_doc_r.scenes_bounding_rectangle[scene_index])
            for t in range(czi_doc_r.total_bounding_box['T'][1]):
                for z in range(czi_doc_r.total_bounding_box['Z'][1]):
                    for c in range(czi_doc_r.total_bounding_box['C'][1]):
                        for tile in tiles:
                            #write non-overlapping data
                            # data = np.random.randint(255, size=(tile.center.h, tile.center.w, 1), dtype=np.uint8)
                            # czi_doc_w.write(
                            #     data,
                            #     location=(tile.center.x, tile.center.y),
                            #     plane={'C': c, 'Z': z, 'T': t},
                            #     scene=scene_index)
                            #write overlapping data
                            data = np.random.randint(255, size=(tile.roi.h, tile.roi.w, 1), dtype=np.uint8)
                            czi_doc_w.write(
                                data,
                                location=(tile.roi.x, tile.roi.y),
                                plane={'C': c, 'Z': z, 'T': t},
                                scene=scene_index)
```

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

### enumerate_subblocks(func)

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Enumerates all subblocks in a CZI file and applies a provided function to each.

```APIDOC
## enumerate_subblocks(func)

### Description
Iterates through all subblocks within the CZI file and executes the provided callback function for each subblock.
```

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

### enumerate_subblocks(func)

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Enumerates all subblocks in the CZI document, executing a callback function for each subblock. The callback receives the index and a SubBlockInfo object, and should return a boolean to control enumeration continuation.

```APIDOC
## enumerate_subblocks(func)

### Description
Enumerates all subblocks in the CZI document, calling the provided function for each subblock.

### Parameters
- **func** (callable) - Required - A function that takes two arguments: `index` (int) and `info` (SubBlockInfo). The function should return `True` to continue enumeration or `False` to stop.
```

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

### write_metadata(document_name, channel_names, scale_x, scale_y, scale_z, custom_attributes, display_settings)

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Explicitly writes metadata to the CZI file.

```APIDOC
## write_metadata

### Description
Writes metadata to the CZI file. If not called, metadata is automatically written upon closing the file.

### Parameters
- **document_name** (str) - Optional - Sets the Document.Title metadata node.
- **channel_names** (dict) - Optional - Dictionary mapping channel indices to names (e.g., {0: "C1", 1: "C2"}).
- **scale_x** (float) - Optional - Extent of a pixel in x-direction in meters.
```

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

### Subdirectory Inclusion

Source: https://github.com/zeiss/pylibczirw/blob/main/CMakeLists.txt

Adds project subdirectories for libraries, API, bindings, and tests.

```cmake
add_subdirectory(libs/libCZIrw)

# bring in pybind11 (which is a git-submodule of this repository)
add_subdirectory(libs/pybind11)

# this is a static library containing the C-API which we want to expose to Python
add_subdirectory(_pylibCZIrw/src/api)

# this is the Python-module which we want to build, exposing the C-API (from above) to Python
add_subdirectory(_pylibCZIrw/src/bindings)

# bring in the tests specific to pylibCZIrw
add_subdirectory(_pylibCZIrw/tests)
```

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

### Enable Subblock Caching for CZI Reading

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Configures caching options for a CZI reader to improve performance when reading from streams or compressed images.

```python
num_executions = 100

for use_cache in [True, False]:
    cache_options = CacheOptions(CacheType.Standard) if use_cache else None

    with pyczi.open_czi(newczi_compressed, ReaderFileInputTypes.Standard, cache_options=cache_options) as czi_document:
        total_time = timeit.timeit(czi_document.read, number=num_executions)
        average_time = total_time / num_executions

        print(
            f"Average time for read_czi (use_cache={use_cache}) over "
            f"{num_executions} executions: {average_time:.6f} seconds"
        )
```

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

### Configure local Git submodule recursion

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Sets the local configuration to automatically recurse into submodules for supported Git commands.

```bash
git config --local submodule.recurse true
```

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

### Manage Git submodules for libCZIrw

Source: https://github.com/zeiss/pylibczirw/blob/main/README.md

Commands to update the libCZIrw submodule to a specific fork and branch.

```bash
cd <RepositoryDirectory>/pylibczirw/libs/libCZIrw
git remote add fork https://github.com/<my fork>.git
git fetch fork
git checkout write_colormode_to_displaysettingsxml
```

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

### read(**kwargs)

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Reads pixel data from a CZI file based on specified parameters such as ROI, plane, scene, and zoom.

```APIDOC
## read(**kwargs)

### Description
Reads pixel data from the CZI file. Users can specify various parameters to extract specific regions or planes.

### Parameters
- **roi** (tuple) - Optional - Region of interest to read.
- **plane** (dict) - Optional - Specific plane coordinates to read.
- **scene** (int) - Optional - Scene index to read.
- **zoom** (float) - Optional - Zoom level for the read operation.
- **pixel_type** (str) - Optional - Desired output pixel type.
- **background_pixel** (int) - Optional - Value for background pixels.
```

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

### Retrieve scene bounding rectangles

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Provides the bounding rectangle for each individual scene within the CZI file.

```python
with pyczi.open_czi(czifile_scenes, pyczi.ReaderFileInputTypes.Curl) as czidoc:
    # get the bounding boxes for each individual scene
    scenes_bounding_rectangle = czidoc.scenes_bounding_rectangle

print(scenes_bounding_rectangle)
```

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

### Write Compressed CZI Data

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Write data to a CZI file using zstd0 compression with an explicit level.

```python
with pyczi.create_czi(newczi_compressed, exist_ok=True) as czidoc_w:
    
    # The CZIWriter class has a compression parameter that allows to define a default compression for each write call.
    # The write call will the allow you to change the compression for a specific case by setting its compression parameter explicitly as here changing to the zstd0: 
    # writing the image with "zstd0" compression.
    czidoc_w.write(
        data=array_big,
        plane={"C": 0, "T": 0, "Z": 0},
        scene=0,
        compression_options = "zstd0:ExplicitLevel=10",
        location=(0,0)
    )
```

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

### edit_czi(file_path)

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Opens a CZI file for metadata editing using a context manager.

```APIDOC
## edit_czi(file_path)

### Description
Opens an existing CZI file and returns an editor object for metadata operations.

### Usage
```python
from pylibCZIrw.czi import edit_czi
with edit_czi(file_path) as editor:
    # Perform operations
```
```

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

### GetSubBlockStats()

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Retrieves statistics about sub-blocks within the CZI file, including bounding box information.

```APIDOC
## GetSubBlockStats()

### Description
Returns a SubBlockStatistics object that can be used to retrieve useful information about the CZI, such as scene bounding boxes.

### Example
```python
stats = Czi_im.GetSubBlockStats()
# Accessing bounding box of scene 0
scene0_x = stats.sceneBoundingBoxes[0].boundingBox.x
scene0_y = stats.sceneBoundingBoxes[0].boundingBox.y
scene0_w = stats.sceneBoundingBoxes[0].boundingBox.w
scene0_h = stats.sceneBoundingBoxes[0].boundingBox.h
```
```

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

### Set Pixel Type

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Import and set the destination bitmap pixel type.

```python
from _pylibCZIrw import PixelType
pixel_type = PixelType.Gray8
```

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

### Define CZI file paths

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Define variables for CZI file locations, including local paths or URLs.

```python
# Define CZI locations

czifile_DAPI_PGC = r"https://github.com/zeiss-microscopy/OAD/raw/master/jupyter_notebooks/pylibCZIrw/data/DAPI_PGC.czi"

czifile_5dstack = r"https://github.com/zeiss-microscopy/OAD/raw/master/jupyter_notebooks/pylibCZIrw/data/T%3D3_Z%3D5_CH%3D2_X%3D240_Y%3D170.czi"

czifile_scenes = r"https://github.com/zeiss-microscopy/OAD/raw/master/jupyter_notebooks/pylibCZIrw/data/w96_A1%2BA2.czi"

czifile_timeseries = r"https://github.com/zeiss-microscopy/OAD/blob/master/jupyter_notebooks/pylibCZIrw/data/CellDivision_T%3D16_CH%3D2_ZSTD.czi"
```

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

### Enumerate all subblocks in a CZI document

Source: https://github.com/zeiss/pylibczirw/blob/main/API.md

Iterates through every subblock in the file, providing access to header information via a callback function.

```python
with czi.open_czi(file_path) as czi_doc:
    def print_subblock_info(index, info):
        rect = info.logicalRect
        print(f"Subblock {index}:")
        print(f"  Position: ({rect.x}, {rect.y})")
        print(f"  Size: {rect.w} x {rect.h}")
        print(f"  Pixel type: {info.pixelType.name}")
        print(f"  Compression: {info.get_compression_mode().name}")
        print(f"  Coordinates: {info.coordinate.to_dict()}")
        return True  # Continue enumeration

    czi_doc.enumerate_subblocks(print_subblock_info)
```

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

### Define CZI file path

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] High level API.ipynb

Set the local path to the CZI file for processing.

```python
demo_czi_read = r'D:\pylibCZIrw_demo\demo_read.czi'
```

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

### AddTile

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] Low level binding.ipynb

Writes a plane (tile) to the CZI document.

```APIDOC
## AddTile(dimension_string, bitmap, x, y, z)

### Description
Adds a tile (plane) to the CZI document using the provided bitmap and coordinate information.

### Parameters
- **dimension_string** (str) - Required - The dimension string (e.g., "T0Z0C0").
- **bitmap** (PImage) - Required - The bitmap object to write.
- **x** (int) - Required - X coordinate.
- **y** (int) - Required - Y coordinate.
- **z** (int) - Required - Z coordinate.
```

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

### Write pixel data to specific coordinates

Source: https://github.com/zeiss/pylibczirw/blob/main/[Doc] High level API.ipynb

Shows how to specify an offset location when writing data to a plane.

```python
demo_czi_write = r'D:\pylibCZIrw_demo\demo_write_1.czi'

with czi.create_czi(demo_czi_write) as new_czi_doc:
    new_czi_doc.write(data=data_gray8, plane=plane_0)
    new_czi_doc.write(data=data_gray8, plane=plane_0, location=(2000, 2000))
```

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

### Write CZI Metadata

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Write image data and custom metadata including scaling and attributes to a CZI file.

```python
# create the filename for the new CZI image file
newczi_mdata = os.path.join(os.getcwd(), "newczi_mdata.czi")
numZ = 32

# open a new CZI and allow overwrite (!!!) to play around ...
with pyczi.create_czi(newczi_mdata, compression_options = "zstd0:ExplicitLevel=10", exist_ok=True) as czidoc_w:
    # loop over all z-planes
    for z in tqdm(range(numZ)):
        # get the 2d array for the current plane and add axis to get (Y, X, 1) as shape
        # write the plane with shape (Y, X, 1) to the new CZI file
        czidoc_w.write(
            data=array[z, ...][..., np.newaxis],
            plane={"Z": z}
        )

    # write the document title, channel names, custom attributes and XYZ scaling to the CZI file
    czidoc_w.write_metadata(
        document_name='new_czi_z=32',
        channel_names={0: "Red"},
        custom_attributes={"key1": "value1", "key2": "value2"},
        scale_x=0.1 * 10 ** -6,
        scale_y=0.1 * 10 ** -6,
        scale_z=0.2 * 10 ** -6
    )
```

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

### Apply Zoom Factor to CZI Read

Source: https://github.com/zeiss/pylibczirw/blob/main/doc/jupyter_notebooks/pylibCZIrw_4_1_0.ipynb

Apply a zoom factor between 0 and 1 to read images at lower resolutions. This is useful for performance when full resolution is not required.

```python
# define the ROI using upper left, width and height as coordinates
my_roi = (300, 400, 300, 300)

# define two different zoom factors
zl1 = 1.0
zl2 = 0.25

with pyczi.open_czi(czifile_scenes, pyczi.ReaderFileInputTypes.Curl) as czidoc:
    
    z1 = czidoc.read(plane={'C': 0}, roi=my_roi, scene=0, zoom=zl1, pixel_type='Gray8')
    z2 = czidoc.read(plane={'C': 0}, roi=my_roi, scene=0, zoom=zl2, pixel_type='Gray8')

fig, ax = plt.subplots(1, 2, figsize=(16, 8))
ax[0].imshow(z1[..., 0], cmap=cm.inferno)
ax[1].imshow(z2[..., 0], cmap=cm.inferno)

print("Shape Zoomlevel = ", zl1, z1.shape)
print("Shape Zoomlevel = ", zl2, z2.shape)
```
Tokens:
Raw