### Build and Install Wheel

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

Commands for creating a wheel file and installing 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 via pip

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

Standard installation command from the repository root.

```bash
pip install .
```

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

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

### Install Dependencies

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

Commands to install project dependencies and the package from the private feed.

```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 pylibCZIrw and dependencies

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

Install the required packages for working with CZI files.

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

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

### Editable Installation

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

Commands for installing the package in editable mode for development.

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

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

### Define Tiling Strategy and Get Tile Locations

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

Utilize the cztile package to define a tiling strategy for large images. This example demonstrates creating a tiling strategy with specified tile dimensions and overlap, then calculating the tile locations based on a scene's bounding rectangle.

```python
import os
import pyczi
from cztile.fixed_total_area_strategy import AlmostEqualBorderFixedTotalAreaStrategy2D
from pyczi.reader import ReaderFileInputTypes

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

# create a "tile" by specifying the desired tile dimension and the
# minimum required overlap between tiles (depends on the processing)
tiler = AlmostEqualBorderFixedTotalAreaStrategy2D(
    total_tile_width=1600,
    total_tile_height=1400,
    min_border_width=128
)

# create CZI instance to read some metadata 
with pyczi.open_czi(czifile_DAPI_PGC, ReaderFileInputTypes.Curl) as czidoc_r:
    # get the size of the bounding rectange for the scence
    tiles = tiler.tile_rectangle(czidoc_r.scenes_bounding_rectangle[0])

# show the created tile locations
for tile in tiles:
    print(tile.roi.x, tile.roi.y, tile.roi.w, tile.roi.h)
```

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

### Install Testing and Quality Packages

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

Install additional packages required for code quality analysis and testing. This command installs packages listed in 'requirements_test.txt'.

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

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

### Example: Update Document Info and Scaling

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

A practical example demonstrating how to update general document information and scaling parameters for a CZI file using the metadata builder.

```APIDOC
### Example: update document info and scaling

```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()
```
```

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

### Install Project Packages

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

Install the necessary Python packages for the project from the activated conda environment. This command installs the main package.

```bash
pip install .
```

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

### Starting an Edit Session

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

Demonstrates how to initiate an edit session using `edit_czi` and obtain a metadata builder. It covers both manual commit and auto-commit scenarios.

```APIDOC
## Starting an Edit Session

Edits are made via a metadata builder returned by the editor. The builder accumulates changes and writes them back on `commit()`.

```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:
    ...
```

- `create_metadata_builder()` initializes the builder from the current file state.
- `begin_edit()` is an alias for creating a builder.
- `edit_session()` yields a builder and auto-commits once on successful exit if `can_commit()` returns True.
```

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

### Install with In-Tree Build

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

Required for specific pip versions to handle in-tree builds correctly.

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

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

### Example: Update Display Settings for a Channel

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

Illustrates how to modify the display settings for a specific channel within a CZI file, including enabling/disabling, tinting, and setting color and range.

```APIDOC
### Example: update display settings for an existing channel

```python
from pylibCZIrw.czi import edit_czi, Rgb8Color, TintingMode, ChannelDisplaySettingsDataClassWithNameAndDescription
with edit_czi(file_path) as editor: builder = editor.create_metadata_builder()
ds = ChannelDisplaySettingsDataClassWithNameAndDescription(
    is_enabled=True,
    tinting_mode=TintingMode.Color,
    tinting_color=Rgb8Color(r=255, g=0, b=0),
    black_point=0.05,
    white_point=0.95,
    description="Edited by API",
)

builder.set_display_settings({0: ds})  # update channel 0 if it exists

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

```
```

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

### Run local linting with MegaLinter

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

Executes the project's linting suite locally using Docker to match the CI environment. Requires Docker Desktop to be installed.

```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
```

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

### Install Specific Python Version

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

Adjusts the virtual environment to match required Python version dependencies.

```bash
conda install python==<version_number>
```

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

### Write CZI Scenes

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

Write data and tag it with a scene index. The scene index defaults to zero. This example writes data to the same plane but with different scene indices.

```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)
```

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

### Start an Edit Session for CZI Metadata

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

Initiates an edit session for a CZI file using a context manager. The builder accumulates changes and can be committed later. Alternatively, `edit_session()` provides auto-commit on successful exit.

```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: ...
```

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

### Create and Write to a New CZI File

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

Create a new CZI file and write pixel data to it. The pixel type is determined from the numpy array's shape and data type. This example writes data for two channels with different pixel types.

```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)
```

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

### Create and Write CZI Files

Source: https://context7.com/zeiss/pylibczirw/llms.txt

Shows how to initialize a new CZI file and write image data with optional compression settings.

```python
from pylibCZIrw import czi as pyczi
import numpy as np

# Create random image data
image_data = np.random.randint(0, 65535, size=(512, 512, 1), dtype=np.uint16)

# Create new CZI file
with pyczi.create_czi("/path/to/new_image.czi", exist_ok=True) as czidoc:
    # Write single plane
    czidoc.write(
        data=image_data,
        plane={'C': 0, 'Z': 0, 'T': 0}
    )

# Create with default compression
with pyczi.create_czi(
    "/path/to/compressed.czi",
    exist_ok=True,
    compression_options="zstd0:ExplicitLevel=10"
) as czidoc:
    czidoc.write(data=image_data, plane={'C': 0})
```

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

### Creating a CZI File

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

Demonstrates how to create a new CZI file using a context manager. It covers default behavior, handling existing files with `exist_ok`, and setting compression options.

```APIDOC
## Creating a CZI File

Like with opening, creating a new empty CZI can be done in a context manager using a [path-like-object](https://docs.python.org/3/library/os.html#os.PathLike) (in this case, file_path).

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

This creates a new czi file at the provided path and **opens it in write mode.**  
**Note:** Any intermediate-level directories needed to contain the leaf directory are generated if necessary.  
**Note:** Per default, a [FileExistsError](https://docs.python.org/3/library/exceptions.html#FileExistsError) is raised in case `file_path` already exists. The error can be ignored by calling  
`with czi.create_czi(file_path, exist_ok = True) as czi:`

The compression option is an optional parameter for czi.creat_czi function and can be overwritten with each individual call to the write function. The compression option can be defined by calling
`with czi.create_czi(file_path, exist_ok = True, compression_options = zstd0:) as czi:`
```

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

### Import pylibCZIrw

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

Import the library to begin using the bindings.

```python
from pylibCZIrw import czi
```

```python
from _pylibCZIrw import czi
```

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

### Get Total Bounding Rectangle

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

Retrieves the X and Y dimensions for all scenes in a CZI file. Use this to get the overall spatial extent of the image data.

```python
with pyczi.open_czi(czifile_scenes, pyczi.ReaderFileInputTypes.Curl) as czidoc:
    # get the total bounding box for all scenes
    total_bounding_rectangle = czidoc.total_bounding_rectangle

print(total_bounding_rectangle)
```

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

### Configure ZSTD Compression

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

Demonstrates setting up ZSTD compression options during CZI file creation or per-write call.

```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")
```

```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)
    )
```

```python
# The compression option could be defined while creating an czi file and could still be overwritten 
# with each individual call to the write function.
with pyczi.create_czi(newczi_uncompressed, exist_ok=True, compression_options = "uncompressed:") as czidoc_w:
                
        czidoc_w.write(
            data=array_big,
            plane={"C": 0, "T": 0, "Z": 0},
            scene=0,
            location=(0,0)
        )
```

```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)}")
```

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

### Get Pixel Type

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

Discover the pixel type of image channels.

```APIDOC
## Get the pixel type

A channel's pixel type can be discovered with using: **`get_channel_pixel_type`**

### `get_channel_pixel_type(channel_index)`

#### Description
Retrieves the pixel type for a specific channel.

#### Parameters
##### Path Parameters
- **channel_index** (int) - Required - The index of the channel to query.

#### Response Example
```json
{
  "example": "BGR"
}
```

Or we can simply get all pixel types using: **`pixel_types`**

### `pixel_types`

#### Description
Retrieves all pixel types as a dictionary, where the key is the channel index.

#### Method
GET (Implicit)

#### Endpoint
N/A (Attribute access)

#### Response Example
```json
{
  "example": "{'0': 'BGR', '1': 'Gray'}"
}
```
```

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

### Initialize Missing Submodules

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

Run this command if you forgot to link submodules during the initial clone.

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

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

### Get Image Dimensions

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

Retrieve various dimension properties of CZI image files.

```APIDOC
## Get Image Dimensions

There are different properties that allow us to retrieve information about dimensions.
The **`total_bounding_box`** gives us all the dimensions of all **orthogonal planes** of the CZI image file.

### `total_bounding_box`

#### Description
Retrieves all dimensions of all orthogonal planes of the CZI image file.

#### Method
GET (Implicit)

#### Endpoint
N/A (Attribute access)

#### Response Example
```json
{
  "example": "{'C': 1, 'Z': 1, 'T': 1, 'X': 512, 'Y': 512}"
}
```

##

The **`total_bounding_rectangle`** gives us the X and Y dimensions of the CZI, i.e. the (X, Y) of the **`total_bounding_box`**.

### `total_bounding_rectangle`

#### Description
Retrieves the X and Y dimensions of the CZI image.

#### Method
GET (Implicit)

#### Endpoint
N/A (Attribute access)

#### Response Example
```json
{
  "example": "[512, 512]"
}
```

**Scenes are not orthogonal to the other dimensions.**
They are contained within the 2D planes and can be seen simply as tags for certain regions.

The **`scene_bounding_rectangle`** give us the bounding rectangle for each scene.

### `scene_bounding_rectangle`

#### Description
Retrieves the bounding rectangle for each individual scene within the CZI image.

#### Method
GET (Implicit)

#### Endpoint
N/A (Attribute access)

#### Response Example
```json
{
  "example": "[[0, 0, 512, 512], [0, 0, 256, 256]]" 
}
```
```

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

### Clean Git Repository

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

Removes untracked files and directories to resolve interface discovery issues after installation.

```bash
git clean -fdx
```

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

### Define CZI file locations

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

Define URLs for sample CZI files used in the tutorial.

```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"
```

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

### Get pixel types

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

Retrieve pixel type information for specific channels or all channels in the CZI file.

```python
with czi.open_czi(demo_czi_read) as czi_doc:
    c0_pixel_type = czi_doc.get_channel_pixel_type(0)
    print(c0_pixel_type)
```

```python
with czi.open_czi(demo_czi_read) as czi_doc:
    pixel_type = czi_doc.pixel_types
    print(pixel_type)
```

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

### Define and Configure _pylibCZIrw_API Library

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

Sets up the static library target, includes necessary directories, links required dependencies, and enforces C++17 standards.

```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)

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)
```

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

### Get All Pixel Types

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

Retrieves all pixel types for all channels in a CZI file as a dictionary. The keys are channel indices.

```python
with pyczi.open_czi(czifile_scenes, pyczi.ReaderFileInputTypes.Curl) as czidoc:
    # get all pixel types as a dictionary, where the key is the channel index
    pixel_type = czidoc.pixel_types

print(pixel_type)
```

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

### GET /open_czi

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

Opens a CZI file in read-only mode using a file path or stream, with optional subblock caching configurations.

```APIDOC
## GET /open_czi

### Description
Opens a CZI file in read-only mode. Supports optional cache configuration to manage memory usage and subblock caching.

### Method
GET

### Endpoint
czi.open_czi(file_path, cache_options=None)

### Parameters
#### Path Parameters
- **file_path** (path-like-object) - Required - The path to the CZI file or a stream.

#### Request Body
- **cache_options** (CacheOptions) - Optional - Configuration object defining cache type, max_memory_usage, and max_sub_block_count.

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

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

### Get Channel Pixel Type

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

Retrieves the pixel type for a specific channel using its index. Ensure the channel index is valid for the CZI file.

```python
with pyczi.open_czi(czifile_scenes, pyczi.ReaderFileInputTypes.Curl) as czidoc:
    # get the pixel type for the 1st channel
    c0_pixel_type = czidoc.get_channel_pixel_type(0)

print(c0_pixel_type)
```

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

### Camera and Image Configuration Parameters

Source: https://github.com/zeiss/pylibczirw/blob/main/pylibCZIrw/tests/integration/metadata/test_data/test_additional_metadata_metadata.txt

Overview of available camera and image configuration properties and their metadata.

```APIDOC
## Camera and Image Configuration

### Description
This section lists the available configuration parameters for camera settings and image processing properties. These properties define the operational constraints and metadata for the imaging system.

### Parameters
- **CameraBias** (Integer) - Read-only - Default bias value.
- **CameraOrientation** (Integer) - Read-only - Current orientation setting. Options: 0:Original, 1:Flip, 2:Reverse, 4:Rotate, 7:FlipReverseRotate, 3:FlipReverse, 6:ReverseRotate, 5:FlipRotate.
- **CameraPixelType** (Integer) - Read-only - Pixel format (e.g., Gray16).
- **ExposureTime** (Double) - Read-write - Exposure time in seconds. Range: 0.1 to 2000. Increment: 0.1.
- **ImageOrientation** (Integer) - Read-write - Image orientation setting. Options: 0:Original, 1:Flip, 2:Reverse, 4:Rotate, 7:FlipReverseRotate, 3:FlipReverse, 6:ReverseRotate, 5:FlipRotate.
- **ImagePixelType** (Integer) - Read-only - Pixel format for the image.
```

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

### Get Total Bounding Box Dimensions

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

Retrieves all dimensions for orthogonal planes of a CZI image file. Use when you need comprehensive dimensional information.

```python
with pyczi.open_czi(czifile_5dstack, pyczi.ReaderFileInputTypes.Curl) as czidoc:
    # get the image dimensions as an dictionary, where the key identifies the dimension
    total_bounding_box = czidoc.total_bounding_box

print(total_bounding_box)
```

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

### 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.

```python
from _pylibCZIrw import czi_writer
```

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

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

### Get Scene and Total Bounding Boxes

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

Retrieves the bounding box information for all scenes and the total image. This is useful for iterating over scenes or understanding image structure.

```python
total_bounding_box = get_total_bounding_box()
scene_bounding_rectangle = czi.get_scene_bounding_rectangle()
total_bounding_rectangle = czi.get_total_bounding_rectangle()

print(total_bounding_box)
# {'X': (0, 1000), 'Y': (0, 1000)}
print(scene_bounding_rectangle)
# { 0: (0, 0, 400, 400), 1: (500, 0, 1000, 400), 2: (0, 500, 400, 1000), 3: (500, 500, 1000, 1000)}
print(total_bounding_rectangle)
# '(0, 0, 1000, 1000)'
```

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

### Instantiate CZI Reader

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

Opens a .czi file at the specified path and returns a CZI reader object.

```APIDOC
## Instantiate czi_reader

### Description
Opens the .czi at the given path and returns a corresponding czi reader object.

### Method
Constructor

### Endpoint
N/A (Object Instantiation)

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

### Request Example
```python
from _pylibCZIrw import czi_reader

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

### Response
#### Success Response (Object)
- **czi_reader_object** (object) - A reader object for the CZI file.
```

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

### Get Scene Bounding Rectangles

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

Retrieves the bounding rectangle for each individual scene within a CZI file. Useful for understanding the spatial extent of tagged regions.

```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)
```

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

### Prepare Data for Writing

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

Generate a numpy array to be written into a new CZI file.

```python
array = np.random.randint(low=1, high=10, size=(32, 64, 64)).astype(np.uint8)
print(array.shape)
```

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

### Clone Repository with Submodules

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

Use this command to clone the repository and its submodules. Ensure submodules are included during the initial clone.

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

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

### Create a new CZI file

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

Use a context manager to create a new CZI file at the specified path. Intermediate directories are generated if they don't exist. By default, a FileExistsError is raised if the file already exists.

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

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

### Get Raw XML Metadata from CZI File

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

Use this method to retrieve the complete raw XML metadata as a string from a CZI file. Ensure the Czi_im object is properly initialized.

```python
Czi_im.GetXmlMetadata()
```

```xml
<?xml version="1.0"?>
<ImageDocument>
 <Metadata>
  <Experiment Version="1.1">
   <RunMode>OptimizeBeforePerformEnabled,ValidateAndAdaptBeforePerformEnabled</RunMode>
   <BeforeHardwareSetting>Before Exp [AF488, AF555] Smart</BeforeHardwareSetting>
   <AfterHardwareSetting>After Exp [AF488, AF555] Smart</AfterHardwareSetting>
   <ExperimentBlockIndex>0</ExperimentBlockIndex>
   <IsSegmented>false</IsSegmented>
   <IsStandardMode>true</IsStandardMode>
   <ImageTransferMode>MemoryMappedAndFileStream</ImageTransferMode>
   <AutoSave IsActivated="false" EnableSingleFileSave="false">
    <StorageFolder>C:\Users\m1srh\Documents\Zen_Output</StorageFolder>
    <Name>New</Name>
    <IsAutoSubFolder>true</IsAutoSubFolder>
    <IsAutoSubFolderExternal>true</IsAutoSubFolderExternal>
    <IsClosedOnCompletion>false</IsClosedOnCompletion>
    <SingleFileSaveFormat>JPG</SingleFileSaveFormat>
    <ConvertTo8Bit>false</ConvertTo8Bit>
    <AddXmlMetadata>false</AddXmlMetadata>
    <ApplyDisplayMappings>false</ApplyDisplayMappings>
    <SaveOriginalData>true</SaveOriginalData>
    <UseChannelNames>false</UseChannelNames>
    <Quality>90</Quality>
    <CompressionMethod>None</CompressionMethod>
    <SingleFileSaveDestinationFolder>C:\Users\m1srh\Pictures</SingleFileSaveDestinationFolder>
    <SingleFileName>New</SingleFileName>
    <DimensionsForSeparateFolders>-C;-T;-Z;-S</DimensionsForSeparateFolders>
   </AutoSave>
   <Scripting IsActivated="false">
    <RunMacroBeforeExperiment>false</RunMacroBeforeExperiment>
    <MacroBeforeExperiment />
    <ErrorActionBeforeExperiment>ErrorAction_Continue</ErrorActionBeforeExperiment>
    <RunMacroAfterExperiment>false</RunMacroAfterExperiment>
    <MacroAfterExperiment />
    <ErrorActionAfterExperiment>ErrorAction_Continue</ErrorActionAfterExperiment>
   </Scripting>
   <BlockExecutionOrder>1</BlockExecutionOrder>
   <LoopDefinitions />
   <ExperimentBlocks>
    <AcquisitionBlock IsActivated="true" BlockReference="635971657741838632">
     <RunMode>ComponentUpdateEnabled,StateUpdateEnabled</RunMode>
     <BeforeHardwareSetting />
     <AfterHardwareSetting />
     <SubDimensionSetups>
      <RegionsSetup IsActivated="true">
       <SampleHolder>
        <Overlap>0.1</Overlap>
        <ScanMode>Meander</ScanMode>
        <PositionedRegionsScanMode>FirstYThenX</PositionedRegionsScanMode>
        <TemplateShapesScanMode>Meander</TemplateShapesScanMode>
        <IsConstantTiles>false</IsConstantTiles>
        <TileRegionAnchorMode>Center</TileRegionAnchorMode>
        <StageReferencePoint>0,0</StageReferencePoint>
        <UseStageBacklashCorrection>true</UseStageBacklashCorrection>
        <UseFocusBacklashCorrection>true</UseFocusBacklashCorrection>
        <IsOptimizedPositionedRegionsSorting>true</IsOptimizedPositionedRegionsSorting>
        <IsOptimizedTemplateShapesSorting>true</IsOptimizedTemplateShapesSorting>
        <UseStageContinualSpeed>false</UseStageContinualSpeed>
        <StageContinualSpeed>1</StageContinualSpeed>
        <UseStageContinualAcceleration>false</UseStageContinualAcceleration>
        <StageContinualAcceleration>1</StageContinualAcceleration>
        <MoveToLoadPositionBetweenRegions>false</MoveToLoadPositionBetweenRegions>
        <MoveToLoadPositionBetweenShapes>false</MoveToLoadPositionBetweenShapes>
        <SplitScenesInSeparateFiles>false</SplitScenesInSeparateFiles>
        <TileRegionCoveringMode>AlignedToLocalTileRegion</TileRegionCoveringMode>
        <TemplateShapesFillMode>PredefinedSize</TemplateShapesFillMode>
        <TemplateShapesFillGrade>0.25</TemplateShapesFillGrade>
        <TemplateShapesFillWidth>71.68</TemplateShapesFillWidth>
        <TemplateShapesFillHeight>71.68</TemplateShapesFillHeight>
        <IsOnlineStitchingEnabled>false</IsOnlineStitchingEnabled>
        <IsOnlinePyramidEnabled>true</IsOnlinePyramidEnabled>
        <GlobalInterpolationExpansionDegree>2</GlobalInterpolationExpansionDegree>
        <LocalInterpolationExpansionDegree>2</LocalInterpolationExpansionDegree>
        <IsFocusSurfaceOutlierRemovingEnabled>true</IsFocusSurfaceOutlierRemovingEnabled>
        <FocusSurfaceOutlierExpansionDegree>1</FocusSurfaceOutlierExpansionDegree>
        <FocusSurfaceOutlierThresholdSigma>2.75</FocusSurfaceOutlierThresholdSigma>
        <UseDefaultSurfaceFit>true</UseDefaultSurfaceFit>
        <UsedSurfaceFitTypeName />
        <DelayAfterStageMove>0</DelayAfterStageMove>
        <TileDimension>
         <Width>64</Width>
         <Height>64</Height>
         <CenterOffsetX>0</CenterOffsetX>
         <CenterOffsetY>0</CenterOffsetY>
        </TileDimension>
        <OnlineStitchingParameter>
         <UseFocusReferenceChannel>true</UseFocusReferenceChannel>
         <ReferenceChannelId>0</Re
```

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

### Set Display Settings with Color, Black/White Levels for CZI Channels

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

Demonstrates setting advanced display settings for CZI channels, including color, black point, and white point levels. This overwrites existing settings and does not enforce 1:1 channel-to-setting relationships.

```python
# 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)
```

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

### Write Tiled and Z-Stack Data

Source: https://context7.com/zeiss/pylibczirw/llms.txt

Illustrates writing image tiles at specific spatial locations and constructing Z-stacks.

```python
from pylibCZIrw import czi as pyczi
import numpy as np

# Create tile data
tile = np.random.randint(0, 255, size=(256, 256, 1), dtype=np.uint8)

with pyczi.create_czi("/path/to/tiled.czi", exist_ok=True) as czidoc:
    # Write tiles at different locations
    czidoc.write(data=tile, plane={'C': 0}, location=(0, 0))
    czidoc.write(data=tile, plane={'C': 0}, location=(256, 0))
    czidoc.write(data=tile, plane={'C': 0}, location=(0, 256))
    czidoc.write(data=tile, plane={'C': 0}, location=(256, 256))

    # Write with specific compression per tile
    czidoc.write(
        data=tile,
        plane={'C': 1},
        location=(0, 0),
        compression_options="zstd1:ExplicitLevel=5"
    )

# Write Z-stack
z_stack = np.random.randint(0, 65535, size=(32, 512, 512), dtype=np.uint16)

with pyczi.create_czi("/path/to/zstack.czi", exist_ok=True) as czidoc:
    for z in range(32):
        czidoc.write(
            data=z_stack[z, :, :, np.newaxis],
            plane={'Z': z, 'C': 0}
        )
```

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

### Read CZI with Zoom Factor

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

Control the zoom level when reading a CZI file by specifying a zoom factor between 0 and 1. This example demonstrates reading with a zoom of 1 and 0.1.

```python
with czi.open_czi(demo_czi_read) as czi_doc:
    frame_0 = czi_doc.read(zoom=1, pixel_type='Gray8')
    frame_1 = czi_doc.read(zoom=0.1, pixel_type='Gray8')

    fig, ax = plt.subplots(2, 1, figsize=(150, 150))
    ax[0].imshow(frame_0.squeeze())
    ax[1].imshow(frame_1.squeeze())
```

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

### Write CZI Metadata

Source: https://context7.com/zeiss/pylibczirw/llms.txt

Demonstrates how to write image data and associated metadata, including display settings and custom attributes, to a new CZI file.

```python
from pylibCZIrw import czi as pyczi
from pylibCZIrw.czi import (
    ChannelDisplaySettingsDataClass,
    TintingMode,
    Rgb8Color
)
import numpy as np

image = np.random.randint(0, 65535, size=(512, 512, 1), dtype=np.uint16)

with pyczi.create_czi("/path/to/with_metadata.czi", exist_ok=True) as czidoc:
    # Write image data
    czidoc.write(data=image, plane={'C': 0})
    czidoc.write(data=image, plane={'C': 1})

    # Configure display settings for channels
    display_settings = {
        0: ChannelDisplaySettingsDataClass(
            is_enabled=True,
            tinting_mode=TintingMode.Color,
            tinting_color=Rgb8Color(r=np.uint8(255), g=np.uint8(0), b=np.uint8(0)),
            black_point=0.0,
            white_point=1.0
        ),
        1: ChannelDisplaySettingsDataClass(
            is_enabled=True,
            tinting_mode=TintingMode.Color,
            tinting_color=Rgb8Color(r=np.uint8(0), g=np.uint8(255), b=np.uint8(0)),
            black_point=0.1,
            white_point=0.9
        )
    }

    # Write complete metadata
    czidoc.write_metadata(
        document_name='My Experiment',
        channel_names={0: 'DAPI', 1: 'GFP'},
        scale_x=0.1e-6,  # 100nm per pixel in meters
        scale_y=0.1e-6,
        scale_z=0.5e-6,
        custom_attributes={
            'Experimenter': 'John Doe',
            'Temperature': 37.0,
            'Exposure_ms': 100,
            'IsCalibrated': True
        },
        display_settings=display_settings
    )
```

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

### Write CZI Data to Specific Location

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

Write CZI data to a specific location within a plane by providing upper-left pixel coordinates. This example writes the same data to the default location and then to a new location.

```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))
```

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

### Read CZI with Background Color

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

Set a background color when reading a CZI file. The background color must match the returned pixel type. Examples show reading with black and red backgrounds.

```python
with czi.open_czi(demo_czi_read) as czi_doc:
    black_background = (0, 0, 0) #black
    other_background = (255, 0, 0) #red

    frame_0 = czi_doc.read(background_pixel=black_background)
    frame_1 = czi_doc.read(background_pixel=other_background)

    fig, ax = plt.subplots(2, 1, figsize=(150, 150))
    ax[0].imshow(frame_0)
    ax[1].imshow(frame_1)
```

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

### Instantiate czi_reader object

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

Opens a .czi file at the specified path and returns a reader object.

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

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

### Read Display Settings

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

Retrieves per-channel display settings from the CZI file. Returns a dictionary mapping channel index to display settings.

```python
editor.read_display_settings()
```

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

### Create and Write New CZI File

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

Initialize a new CZI file and write numpy array data into specific Z-planes.

```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}
        )
```

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

### Set Display Settings for CZI Channels (Color Only)

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

Shows how to specify display settings for CZI channels, including setting a specific color for each channel using Rgb8Color and TintingMode.Color. This overwrites existing settings.

```python
# 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)
```

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

### Import pylibCZIrw czi module

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

Initial import required to access reading and writing APIs.

```python
from pylibCZIrw import czi
```

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

### Write CZI with Random Data using Tiling

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

Use this code to read a CZI file and write a new one with random data, applying a tiling strategy for efficient handling of large images. Ensure the czitile package and necessary imports are available.

```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)
```

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

### Open CZI Files for Reading

Source: https://context7.com/zeiss/pylibczirw/llms.txt

Use open_czi to create a context manager for local or remote files. Optional caching and reader configurations can be applied to optimize performance.

```python
from pylibCZIrw import czi as pyczi
from pylibCZIrw.czi import ReaderFileInputTypes, CacheOptions, CacheType, ReaderOptions

# Open from local file
with pyczi.open_czi("/path/to/image.czi") as czidoc:
    data = czidoc.read()
    print(f"Image shape: {data.shape}")

# Open from HTTP URL with caching
cache_options = CacheOptions(
    type=CacheType.Standard,
    max_memory_usage=500 * 1024**2,  # 500 MB
    max_sub_block_count=100
)

with pyczi.open_czi(
    "https://example.com/image.czi",
    ReaderFileInputTypes.Curl,
    cache_options=cache_options
) as czidoc:
    data = czidoc.read()

# Open with advanced reader options
reader_options = ReaderOptions(
    enable_mask_awareness=True,
    enable_visibility_check_optimization=True,
    lax_subblock_coordinate_checks=False
)

with pyczi.open_czi("/path/to/image.czi", reader_options=reader_options) as czidoc:
    data = czidoc.read()
```

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

### Create Conda Environment

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

Create a new conda environment for the project. Replace `<some-path\PyCIrW>` with your desired path and `<environment_name>` with a name for your environment.

```bash
conda create -p <some-path\PyCIrW> python
```