Metadata-Version: 2.4
Name: qlty
Version: 1.2.2
Summary: Unstitch and stitch back pytorch tensors
Author-email: "Petrus H. Zwart" <PHZwart@lbl.gov>
License: BSD
Project-URL: Homepage, https://github.com/phzwart/qlty
Project-URL: Documentation, https://qlty.readthedocs.io/
Project-URL: Repository, https://github.com/phzwart/qlty
Project-URL: Issues, https://github.com/phzwart/qlty/issues
Keywords: qlty,pytorch,tensor,stitch,unstitch,patch,image
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
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: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: numpy>=1.20.1
Requires-Dist: torch>=1.11
Requires-Dist: einops>=0.3.0
Requires-Dist: scipy>=1.8.1
Requires-Dist: zarr>=2.11.1
Requires-Dist: numba>=0.56.0
Requires-Dist: dask>=2021.12.0
Requires-Dist: umap-learn>=0.5.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Provides-Extra: tests
Requires-Dist: pytest>=8.0.0; extra == "tests"
Dynamic: description
Dynamic: description-content-type
Dynamic: license-file

====
qlty
====

.. image:: https://img.shields.io/pypi/v/qlty.svg
        :target: https://pypi.python.org/pypi/qlty

.. image:: https://img.shields.io/travis/phzwart/qlty.svg
        :target: https://travis-ci.com/phzwart/qlty

.. image:: https://readthedocs.org/projects/qlty/badge/?version=latest
        :target: https://qlty.readthedocs.io/en/latest/?version=latest
        :alt: Documentation Status

qlty is a Python library designed to handle large 2D or 3D tensors efficiently by splitting them into smaller, manageable chunks. This library is particularly useful for processing large datasets that do not fit into memory, enabling chunked processing for machine learning workflows.

Features
--------

* Efficient tensor splitting and stitching
* Intelligent border handling to minimize artifacts
* Support for both in-memory and disk-cached processing
* 2D and 3D tensor support
* Sparse data handling utilities
* Patch pair extraction helpers for partially overlapping regions in 2D and 3D
* Pre-tokenization utilities (``pretokenizer_2d``) for preparing patches for sequence models
* Numba acceleration for 2D stitching and batch token processing with parallel execution

Quick Start
-----------

Installation::

    pip install qlty torch zarr numpy einops dask numba

Basic Usage::

    import torch
    from qlty import NCYXQuilt

    # Create a quilt object
    quilt = NCYXQuilt(
        Y=128, X=128,
        window=(32, 32),
        step=(16, 16),
        border=(5, 5),
        border_weight=0.1
    )

    # Split data into patches
    data = torch.randn(10, 3, 128, 128)
    patches = quilt.unstitch(data)

    # Process patches (e.g., with a neural network)
    processed = your_model(patches)

    # Stitch back together
    reconstructed, weights = quilt.stitch(processed)

Documentation
-------------

Full documentation is available at https://qlty.readthedocs.io

* `Installation Guide <installation.html>`_
* `Usage Guide <usage.html>`_
* `Examples <examples.html>`_
* `API Reference <api.html>`_
* `Troubleshooting <troubleshooting.html>`_

Modules
-------

In-Memory Classes
~~~~~~~~~~~~~~~~~

* **NCYXQuilt**: 2D tensor splitting and stitching (shape: N, C, Y, X)
* **NCZYXQuilt**: 3D tensor splitting and stitching (shape: N, C, Z, Y, X)

Disk-Cached Classes
~~~~~~~~~~~~~~~~~~~

* **LargeNCYXQuilt**: 2D with on-disk caching using Zarr
* **LargeNCZYXQuilt**: 3D with on-disk caching using Zarr

License
-------

* Free software: BSD license

Credits
-------

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage


=======
History
=======

1.3.0 (2025-01-XX)
------------------

* Added ``pretokenizer_2d`` module for pre-tokenization of patches with sequence model support (2D).
* New functions: ``tokenize_patch()`` and ``build_sequence_pair()`` for converting patches
  into token sequences with overlap information.
* Optimized batch processing with numba JIT compilation and parallel execution.
* Supports both single patches and batched processing for efficient training workflows.
* Designed for self-supervised learning, contrastive learning, and transformer-based models.

1.2.0 (2025-11-13)
------------------

* Added optional rotation-aware extraction for 2D patch pairs with matching overlap handling.
* Expanded tests and documentation to cover rotated patch workflows.

1.1.0 (2025-11-12)
------------------

* Restored Numba acceleration for 2D quilting via color-based parallel stitching that avoids write races.
* Expanded 3D patch-pair sampling tests to cover edge cases and fallback logic, driving coverage to 100%.
* Updated documentation to describe partially overlapping patch-pair utilities.
* Noted that NCZYXQuilt and the Large* variants still need analogous race-free acceleration.

0.1.0 (2021-10-20)
------------------

* First release on PyPI.

0.1.1 (some time ago)
---------------------

* Minor bug fixes

0.1.2. (2022-9-13)
------------------

* Support for N-channel 3D tensors
* On disc-accmulation for large datasets


0.1.3. (2022-9-13)
------------------

* Cleanup and ready to redistribute


0.1.4. (2023-8-28)
------------------

* Bug fix / behavoir change

0.1.5. (2023-12-28)
-------------------

* Changes to qlty3DLarge:
  bug fixes
  normalizing / averaging now done by dask

0.1.6. (2024-03-10)
-------------------
  bug fixes

0.1.7. (2024-03-12)
-------------------
*  bug fix in border tensor definition.

0.2.0. (2024-03-12)
-------------------
*  bug fixes
*  2DLarge, mimics 3DLarge
