### Install pyisyntax

Source: https://github.com/anibali/pyisyntax/blob/master/README.md

Use pip to install the library in your Python environment.

```console
$ pip install pyisyntax
```

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

### Install pyisyntax

Source: https://context7.com/anibali/pyisyntax/llms.txt

Install the pyisyntax library using pip. No additional setup is required.

```bash
pip install pyisyntax
```

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

### Complete Workflow Example for Pathology Image Processing

Source: https://context7.com/anibali/pyisyntax/llms.txt

A comprehensive example demonstrating a typical workflow for extracting and processing pathology image data from an iSyntax file. This includes saving macro and label images, creating thumbnails, and extracting regions of interest at multiple resolutions.

```python
from isyntax import ISyntax
import PIL.Image
import numpy as np
import io
from pathlib import Path

def process_slide(slide_path: str, output_dir: str):
    """Process an iSyntax slide and extract various data."""
    output = Path(output_dir)
    output.mkdir(exist_ok=True)

    with ISyntax.open(slide_path, cache_size=4000) as isyntax:
        # Print slide information
        print(f"Slide: {slide_path}")
        print(f"Dimensions: {isyntax.dimensions}")
        print(f"Levels: {isyntax.level_count}")
        print(f"Resolution: {isyntax.mpp_x} µm/pixel")
        print(f"Barcode: {isyntax.barcode}")

        # Save macro image
        macro_jpeg = isyntax.read_macro_image_jpeg()
        if macro_jpeg:
            (output / "macro.jpg").write_bytes(macro_jpeg)
            print("Saved macro image")

        # Save label image
        label_jpeg = isyntax.read_label_image_jpeg()
        if label_jpeg:
            (output / "label.jpg").write_bytes(label_jpeg)
            print("Saved label image")

        # Create thumbnail from lowest resolution level
        lowest_level = isyntax.level_count - 1
        dims = isyntax.level_dimensions[lowest_level]
        thumbnail = isyntax.read_region(0, 0, dims[0], dims[1], level=lowest_level)
        PIL.Image.fromarray(thumbnail).save(output / "thumbnail.png")
        print(f"Saved thumbnail ({dims[0]}x{dims[1]})")

        # Extract a region of interest at multiple resolutions
        roi_x, roi_y = 1000, 1000
        roi_size = 512

        for level in [0, 2, 4]:
            scale = isyntax.level_downsamples[level]
            # Adjust coordinates for the level
            lx, ly = roi_x // scale, roi_y // scale
            lsize = roi_size // scale

            region = isyntax.read_region(lx, ly, lsize, lsize, level=level)
            PIL.Image.fromarray(region).save(output / f"roi_level{level}.png")
            print(f"Saved ROI at level {level} ({lsize}x{lsize})")

# Usage
process_slide("sample.isyntax", "./output")
```

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

### Read Label Image as JPEG

Source: https://context7.com/anibali/pyisyntax/llms.txt

Retrieve the label image as JPEG-compressed data. This function returns a memoryview of the JPEG bytes or None if unavailable. The example shows saving to a file and decompressing with Pillow, including displaying image dimensions and converting to PNG.

```python
from isyntax import ISyntax
import PIL.Image
import io

with ISyntax.open("my_slide.isyntax") as isyntax:
    # Get the label image as compressed JPEG data
    jpeg_data = isyntax.read_label_image_jpeg()

    if jpeg_data is not None:
        # Save to file
        with open("label_image.jpg", "wb") as f:
            f.write(jpeg_data)

        # Decompress and display
        label_image = PIL.Image.open(io.BytesIO(jpeg_data), formats=["JPEG"])
        print(f"Label image size: {label_image.size}")
        label_image.save("label.png")  # Convert to PNG
    else:
        print("Label image not available")
```

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

### Read ICC Color Profile

Source: https://context7.com/anibali/pyisyntax/llms.txt

Extract the embedded ICC color profile for accurate color reproduction. This function returns a memoryview of the profile data or None if unavailable. The example demonstrates saving the profile and its potential use with Pillow for color-managed conversions.

```python
from isyntax import ISyntax

with ISyntax.open("my_slide.isyntax") as isyntax:
    # Get the ICC color profile
    icc_profile = isyntax.read_icc_profile()

    if icc_profile is not None:
        # Save the ICC profile
        with open("color_profile.icc", "wb") as f:
            f.write(icc_profile)

        print(f"ICC profile size: {len(icc_profile)} bytes")

        # Use with Pillow for color-managed conversion
        import PIL.Image
        import PIL.ImageCms

        pixels = isyntax.read_region(0, 0, 256, 256, level=4)
        image = PIL.Image.fromarray(pixels)

        # Apply color profile if needed
        # srgb_profile = PIL.ImageCms.createProfile("sRGB")
        # transform = PIL.ImageCms.buildTransformFromOpenProfiles(
        #     PIL.ImageCms.ImageCmsProfile(io.BytesIO(icc_profile)),
        #     srgb_profile, "RGBA", "RGBA"
        # )
    else:
        print("ICC profile not available")
```

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

### Manage development dependencies

Source: https://github.com/anibali/pyisyntax/blob/master/README.md

Commands for syncing and updating project dependencies using uv.

```console
$ uv sync --frozen
```

```console
$ uv lock
```

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

### Open iSyntax File with ISyntax.open

Source: https://context7.com/anibali/pyisyntax/llms.txt

Opens an iSyntax file for reading. It is recommended to use the context manager for automatic resource cleanup. Custom cache sizes can be specified.

```python
from isyntax import ISyntax
from pathlib import Path

# Open using context manager (recommended)
with ISyntax.open("my_slide.isyntax") as isyntax:
    print(f"Dimensions: {isyntax.dimensions}")
    print(f"Number of levels: {isyntax.level_count}")
    # Resources automatically cleaned up when exiting context

# Open with custom cache size (default is 2000)
with ISyntax.open("my_slide.isyntax", cache_size=4000) as isyntax:
    print(f"Tile size: {isyntax.tile_width}x{isyntax.tile_height}")

# Open using Path object
slide_path = Path("/data/slides/sample.isyntax")
with ISyntax.open(slide_path) as isyntax:
    print(f"Levels: {isyntax.level_dimensions}")
```

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

### ISyntax.open

Source: https://context7.com/anibali/pyisyntax/llms.txt

Opens an iSyntax file for reading and returns an ISyntax object. It is recommended to use this method within a context manager to ensure proper resource cleanup. Custom cache sizes can also be specified.

```APIDOC
## ISyntax.open

### Description
Opens an iSyntax file for reading and returns an ISyntax object that can be used as a context manager to ensure proper resource cleanup.

### Method
`ISyntax.open(path, cache_size=2000)`

### Parameters
#### Path Parameters
- **path** (str or Path) - Required - The path to the iSyntax file.
- **cache_size** (int) - Optional - The size of the cache to use (default is 2000).

### Request Example
```python
from isyntax import ISyntax
from pathlib import Path

# Open using context manager (recommended)
with ISyntax.open("my_slide.isyntax") as isyntax:
    print(f"Dimensions: {isyntax.dimensions}")
    print(f"Number of levels: {isyntax.level_count}")

# Open with custom cache size
with ISyntax.open("my_slide.isyntax", cache_size=4000) as isyntax:
    print(f"Tile size: {isyntax.tile_width}x{isyntax.tile_height}")

# Open using Path object
slide_path = Path("/data/slides/sample.isyntax")
with ISyntax.open(slide_path) as isyntax:
    print(f"Levels: {isyntax.level_dimensions}")
```

### Response
#### Success Response (200)
- **ISyntax object** - An object representing the opened iSyntax file, providing access to its properties and methods.
```

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

### Access ISyntax Level Properties

Source: https://context7.com/anibali/pyisyntax/llms.txt

Access detailed information about individual resolution levels in an image pyramid using the wsi (whole slide image) property. This includes scale factor, dimensions, tile information, and microns per pixel (MPP).

```python
from isyntax import ISyntax

with ISyntax.open("my_slide.isyntax") as isyntax:
    # Access the WSI image object
    wsi = isyntax.wsi

    print(f"Total levels: {wsi.level_count}")

    # Iterate through all levels
    for i, level in enumerate(wsi.levels):
        print(f"Level {i}:")
        print(f"  Scale factor: {level.scale} (2^{level.scale}x downsample)")
        print(f"  Dimensions: {level.width} x {level.height}")
        print(f"  Tiles: {level.width_in_tiles} x {level.height_in_tiles}")
        print(f"  MPP: {level.mpp_x} x {level.mpp_y} microns/pixel")

    # Access a specific level
    level_0 = wsi.get_level(0)  # Full resolution
    print(f"Full res: {level_0.width}x{level_0.height}")

    level_4 = wsi.get_level(4)  # 16x downsampled
    print(f"Level 4: {level_4.width}x{level_4.height}")

    # WSI offset from macro image
    print(f"WSI offset: ({wsi.offset_x}, {wsi.offset_y})")
```

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

### read_tile

Source: https://context7.com/anibali/pyisyntax/llms.txt

Reads RGBA pixel data from a specific tile at the given tile coordinates and level. Tiles are the native storage units in the pyramid structure.

```APIDOC
## read_tile

### Description
Reads RGBA pixel data from a specific tile at the given tile coordinates and level. Returns a numpy array with shape [tile_height, tile_width, 4]. Tiles are the native storage units in the pyramid structure.

### Method
`isyntax.read_tile(tile_x, tile_y, level)`

### Parameters
#### Path Parameters
- **tile_x** (int) - Required - The x-coordinate (column) of the tile.
- **tile_y** (int) - Required - The y-coordinate (row) of the tile.
- **level** (int) - Required - The resolution level from which to read the tile.

### Request Example
```python
from isyntax import ISyntax
import numpy as np

with ISyntax.open("my_slide.isyntax") as isyntax:
    # Read the tile at column 0, row 0 from the lowest resolution level
    tile = isyntax.read_tile(tile_x=0, tile_y=0, level=7)

    # Tile dimensions match the file's tile size (typically 256x256)
    print(f"Tile shape: {tile.shape}")

    # Read a specific tile from a higher resolution level
    tile = isyntax.read_tile(tile_x=10, tile_y=20, level=0)

    # Access pixel at specific coordinates within the tile
    pixel_rgba = tuple(tile[45, 97])  # Row 45, Column 97
    print(f"Pixel RGBA: {pixel_rgba}")

    # Iterate through all tiles at a level
    level_tiles = isyntax.level_tiles[4]  # (cols, rows) for level 4
    for tile_y in range(level_tiles[1]):
        for tile_x in range(level_tiles[0]):
            tile_data = isyntax.read_tile(tile_x, tile_y, level=4)
            # Process tile_data...
```

### Response
#### Success Response (200)
- **tile** (numpy.ndarray) - A numpy array with shape [tile_height, tile_width, 4] and dtype uint8, representing the RGBA pixel data of the requested tile.
```

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

### Access ISyntax Slide Metadata Properties

Source: https://context7.com/anibali/pyisyntax/llms.txt

Retrieve slide dimensions, level information, tile details, physical scale (MPP), offset, and barcode. Ensure the ISyntax file is opened correctly.

```python
from isyntax import ISyntax

with ISyntax.open("my_slide.isyntax") as isyntax:
    # Full resolution dimensions (width, height)
    print(f"Dimensions: {isyntax.dimensions}")
    # Output: Dimensions: (37382, 73222)

    # Number of resolution levels in the pyramid
    print(f"Level count: {isyntax.level_count}")
    # Output: Level count: 8

    # Dimensions at each level
    print(f"Level dimensions: {isyntax.level_dimensions}")
    # Output: Level dimensions: [(37382, 73222), (18691, 36611), ..., (292, 572)]

    # Downsampling factor for each level
    print(f"Level downsamples: {isyntax.level_downsamples}")
    # Output: Level downsamples: [1, 2, 4, 8, 16, 32, 64, 128]

    # Number of tiles (cols, rows) at each level
    print(f"Level tiles: {isyntax.level_tiles}")
    # Output: Level tiles: [(256, 384), (128, 192), ..., (2, 3)]

    # Tile dimensions
    print(f"Tile size: {isyntax.tile_width}x{isyntax.tile_height}")
    # Output: Tile size: 256x256

    # Microns per pixel (physical scale)
    print(f"MPP X: {isyntax.mpp_x}")  # Output: MPP X: 0.25
    print(f"MPP Y: {isyntax.mpp_y}")  # Output: MPP Y: 0.25

    # WSI offset relative to macro image origin (in pixels)
    print(f"Offset X: {isyntax.offset_x}")  # Output: Offset X: 13531
    print(f"Offset Y: {isyntax.offset_y}")  # Output: Offset Y: 22053

    # Read slide barcode
    print(f"Barcode: '{isyntax.barcode}'")
```

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

### Extract macro image

Source: https://github.com/anibali/pyisyntax/blob/master/README.md

Retrieves the macro image from an iSyntax file as compressed JPEG data and saves it to disk.

```python
from isyntax import ISyntax

with ISyntax.open("my_file.isyntax") as isyntax:
    # The macro image will be returned as compressed JPEG data.
    jpeg_data = isyntax.read_macro_image_jpeg()
    # This JPEG data can be written directly to a file.
    with open("macro_image.jpg", "wb") as f:
        f.write(jpeg_data)
    # Alternatively, you could decompress the data using Pillow:
    # pil_image = PIL.Image.open(io.BytesIO(jpeg_data), formats=["JPEG"])
```

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

### Read Macro Image as JPEG

Source: https://context7.com/anibali/pyisyntax/llms.txt

Obtain the macro image as JPEG-compressed data. This function returns a memoryview of the JPEG bytes or None if the image is not available. Includes verification of JPEG magic bytes and options for saving or decompressing with Pillow.

```python
from isyntax import ISyntax
import PIL.Image
import io

with ISyntax.open("my_slide.isyntax") as isyntax:
    # Get the macro image as compressed JPEG data
    jpeg_data = isyntax.read_macro_image_jpeg()

    if jpeg_data is not None:
        # Verify JPEG magic bytes
        assert jpeg_data[:2] == b"\xff\xd8"

        # Save directly to file
        with open("macro_image.jpg", "wb") as f:
            f.write(jpeg_data)

        # Or decompress using Pillow
        pil_image = PIL.Image.open(io.BytesIO(jpeg_data), formats=["JPEG"])
        pil_image.show()

        print(f"JPEG size: {len(jpeg_data)} bytes")
    else:
        print("Macro image not available")
```

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

### Read and display WSI region

Source: https://github.com/anibali/pyisyntax/blob/master/README.md

Opens an iSyntax file and extracts a specific region as a numpy array for use with Pillow.

```python
from isyntax import ISyntax
import PIL.Image

with ISyntax.open("my_file.isyntax") as isyntax:
    # Read pixels from the specified region into a numpy array
    pixels = isyntax.read_region(500, 500, 400, 200, level=4)
    # Convert numpy array into a PIL image
    pil_image = PIL.Image.fromarray(pixels)
    # Show the image
    pil_image.show()
```

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

### read_macro_image_jpeg

Source: https://context7.com/anibali/pyisyntax/llms.txt

Reads the associated macro image as JPEG-compressed data.

```APIDOC
## read_macro_image_jpeg

### Description
Reads the associated macro image (low-resolution overview of the entire slide) as JPEG-compressed data.

### Response
- **Returns** (memoryview|None) - The JPEG bytes or None if unavailable.
```

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

### Read Tile with read_tile

Source: https://context7.com/anibali/pyisyntax/llms.txt

Reads RGBA pixel data from a specific tile at the given tile coordinates and level. Tiles are the native storage units in the pyramid structure. This function can be used to iterate through all tiles at a level.

```python
from isyntax import ISyntax
import numpy as np

with ISyntax.open("my_slide.isyntax") as isyntax:
    # Read the tile at column 0, row 0 from the lowest resolution level
    tile = isyntax.read_tile(tile_x=0, tile_y=0, level=7)

    # Tile dimensions match the file's tile size (typically 256x256)
    print(f"Tile shape: {tile.shape}")  # Output: Tile shape: (256, 256, 4)

    # Read a specific tile from a higher resolution level
    tile = isyntax.read_tile(tile_x=10, tile_y=20, level=0)

    # Access pixel at specific coordinates within the tile
    pixel_rgba = tuple(tile[45, 97])  # Row 45, Column 97
    print(f"Pixel RGBA: {pixel_rgba}")  # Output: Pixel RGBA: (145, 108, 87, 255)

    # Iterate through all tiles at a level
    level_tiles = isyntax.level_tiles[4]  # (cols, rows) for level 4
    for tile_y in range(level_tiles[1]):
        for tile_x in range(level_tiles[0]):
            tile_data = isyntax.read_tile(tile_x, tile_y, level=4)
            # Process tile_data...
```

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

### read_label_image_jpeg

Source: https://context7.com/anibali/pyisyntax/llms.txt

Reads the associated label image as JPEG-compressed data.

```APIDOC
## read_label_image_jpeg

### Description
Reads the associated label image (typically containing slide identification information) as JPEG-compressed data.

### Response
- **Returns** (memoryview|None) - The JPEG bytes or None if unavailable.
```

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

### ISyntax Metadata Properties

Source: https://context7.com/anibali/pyisyntax/llms.txt

Access various metadata properties of the ISyntax object including dimensions, resolution levels, and physical scale.

```APIDOC
## ISyntax Metadata Properties

### Description
Access image dimensions, resolution levels, tile information, and physical measurements through various properties of the ISyntax object.

### Properties
- **dimensions** (tuple) - Full resolution dimensions (width, height)
- **level_count** (int) - Number of resolution levels in the pyramid
- **level_dimensions** (list) - Dimensions at each level
- **level_downsamples** (list) - Downsampling factor for each level
- **level_tiles** (list) - Number of tiles (cols, rows) at each level
- **tile_width** (int) - Width of a tile
- **tile_height** (int) - Height of a tile
- **mpp_x** (float) - Microns per pixel X
- **mpp_y** (float) - Microns per pixel Y
- **offset_x** (int) - WSI offset X relative to macro image origin
- **offset_y** (int) - WSI offset Y relative to macro image origin
- **barcode** (str) - Slide barcode
```

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

### read_icc_profile

Source: https://context7.com/anibali/pyisyntax/llms.txt

Reads the ICC color profile embedded in the image.

```APIDOC
## read_icc_profile

### Description
Reads the ICC color profile embedded in the image for accurate color reproduction.

### Response
- **Returns** (memoryview|None) - The ICC profile data or None if unavailable.
```

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

### read_region

Source: https://context7.com/anibali/pyisyntax/llms.txt

Reads RGBA pixel data from a specified rectangular region at a given resolution level. The data is returned as a numpy array.

```APIDOC
## read_region

### Description
Reads RGBA pixel data from a specified rectangular region at a given resolution level. Returns a numpy array with shape [height, width, 4] containing RGBA pixel values.

### Method
`isyntax.read_region(x, y, width, height, level)`

### Parameters
#### Path Parameters
- **x** (int) - Required - The x-coordinate of the top-left corner of the region.
- **y** (int) - Required - The y-coordinate of the top-left corner of the region.
- **width** (int) - Required - The width of the region to read.
- **height** (int) - Required - The height of the region to read.
- **level** (int) - Required - The resolution level from which to read the region.

### Request Example
```python
from isyntax import ISyntax
import PIL.Image
import numpy as np

with ISyntax.open("my_slide.isyntax") as isyntax:
    # Read a 400x200 pixel region at position (500, 500) from level 4
    pixels = isyntax.read_region(x=500, y=500, width=400, height=200, level=4)

    # pixels is a numpy array with shape (200, 400, 4) and dtype uint8
    print(f"Shape: {pixels.shape}")
    print(f"Dtype: {pixels.dtype}")

    # Convert to PIL Image for display or saving
    pil_image = PIL.Image.fromarray(pixels)
    pil_image.save("region.png")

    # Read from full resolution (level 0)
    high_res_pixels = isyntax.read_region(1000, 1000, 256, 256, level=0)

    # Access individual pixel RGBA values
    r, g, b, a = pixels[100, 200]  # Get pixel at row 100, column 200
    print(f"RGBA: ({r}, {g}, {b}, {a})")
```

### Response
#### Success Response (200)
- **pixels** (numpy.ndarray) - A numpy array with shape [height, width, 4] and dtype uint8, representing the RGBA pixel data of the requested region.
```

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

### Read Region with read_region

Source: https://context7.com/anibali/pyisyntax/llms.txt

Reads RGBA pixel data from a specified rectangular region at a given resolution level. The result is a numpy array. This function can be used to convert the pixel data to a PIL Image.

```python
from isyntax import ISyntax
import PIL.Image
import numpy as np

with ISyntax.open("my_slide.isyntax") as isyntax:
    # Read a 400x200 pixel region at position (500, 500) from level 4
    pixels = isyntax.read_region(x=500, y=500, width=400, height=200, level=4)

    # pixels is a numpy array with shape (200, 400, 4) and dtype uint8
    print(f"Shape: {pixels.shape}")  # Output: Shape: (200, 400, 4)
    print(f"Dtype: {pixels.dtype}")  # Output: Dtype: uint8

    # Convert to PIL Image for display or saving
    pil_image = PIL.Image.fromarray(pixels)
    pil_image.save("region.png")

    # Read from full resolution (level 0)
    high_res_pixels = isyntax.read_region(1000, 1000, 256, 256, level=0)

    # Access individual pixel RGBA values
    r, g, b, a = pixels[100, 200]  # Get pixel at row 100, column 200
    print(f"RGBA: ({r}, {g}, {b}, {a})")
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.