Metadata-Version: 2.4
Name: eozin
Version: 0.1.0a1
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Requires-Dist: pillow
Requires-Dist: pyglet>=2.1.13 ; extra == 'viewer'
Provides-Extra: viewer
Summary: A fast digital pathology image decoder powered by Rust
Keywords: pathology,wsi,medical-imaging,rust,decoder
Author-email: Yuji Ota <yujota.oss@gmail.com>
License: BSD-3-Clause
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://youruser.github.io/eozin/docs/
Project-URL: Homepage, https://github.com/yujota/eozin
Project-URL: Issues, https://github.com/yujota/eozin/issues
Project-URL: Repository, https://github.com/yujota/eozin.git

# Eozin Python: <small>The *dye-namic solution* for digital pathology</small>

A fast digital pathology image decoder powered by Rust.
The library's primary purpose is to provide efficient access to individual tiles within 
digital pathology images.
The name is derived from eosin, an essential dye solution used in pathological diagnosis.


## Quickstart

This example demonstrates how to select the lowest resolution level from a digital 
pathology image in a native Rust environment, retrieve the central tile within that level, 
and save it as a JPEG file.

```python
from eozin import Eozin

slide = Eozin("/some/slide.svs")
width, height = slide.dimensions();

# Get the index of the lowest resolution level
lowest_resolution_level = slide.level_count() - 1;

# level_tile_ranges returns [(horizontal_tiles, vertical_tiles)]
lowres_tile_ranges = decoder.level_tile_ranges[lowest_resolution_level];

# Retrieve the tile at the center of the level
lowres_centered_tile = slide.read_tile(
  lowest_resolution_level, 
  lowres_tile_ranges[0] // 2, 
  lowres_tile_ranges[1] // 2, 
)

lowres_centered_tile.show()

# OpenSlide like functionality
slide.read_region((0, 0), 0, (1024, 1024))
```

## Core Concept

Digital pathology images are captured using high-magnification microscopes, 
resulting in massive images that can reach hundreds of thousands of pixels in dimension.
Because storing such large images in standard formats is impractical, 
they are designed as containers comprising small rectangular images called **tiles**.

Furthermore, since downscaling these images on the fly is computationally expensive, 
they typically store multiple lower-resolution versions, referred to as **levels**. 
Vendors have developed various proprietary formats, and libraries like OpenSlide 
and bioformats have been instrumental in handling them.

The motivation for Eozin is to provide lightweight and fast access to these tiles. 
Specifically, each tile is stored as a fragmented byte sequence; Eozin calculates 
the byte offset based on the requested level and coordinates, then appends 
the necessary headers so the buffer can be interpreted as a standard image format.

Pixel-level processing (such as intensity manipulation) is intentionally left 
to established libraries—such as the `image` crate in Rust, `Pillow` in Python, 
or `Blob` objects in JS/Web environments.

Since the I/O and decoding logic are completely decoupled, Eozin can be adapted to 
various environments. Client-side rendering in the browser achieves performant 
response times, and its efficiency is also ideal for high-throughput AI 
interpretation and analysis.


## Notes
Vendor and file format names mentioned in this library are the property of their respective owners.
This library is not certified for clinical use.

