compressed-image
compressed-image is a header-only library for reading, storing and modifying images and channels as losslessly compressed in-memory buffers
allowing for very memory-efficient representations of these. This library acts as a stop-gap between storing images purely
in-memory and reading them from disk on-demand.
It trades a bit of performance for significantly lower memory usage. For more detailed information please have a look at the benchmark section on readthedocs.
It is written entirely using C++20 while also providing pre-built python binaries that are pip-installable.
Features
- Storing images as compressed buffers
- Support for multiple compressions algorithms such as
lz4,zstd,blosclzetc. - Reading files directly from disk into compressed chunks for low memory usage
- Random access compression/decompression without having to decompress the entire image
- Lazy image/channel representations with extremely low memory footprints
- Cross-platform support (linux, windows, macos)
- Interoperability with NumPy
When should you use this?
This library is for you if you want to optimize memory usage in your application and still work efficiently with image data. It's especially useful when:
- You need to keep many images in memory at once but don't want to pay the full memory cost.
- You're working with high-resolution images or large datasets and want to avoid I/O bottlenecks.
- You want fast, random access to image chunks without having to decompress the entire image up front.
- You're building tools, pipelines, or applications that process images frequently but can't afford the memory footprint of uncompressed data.
If you're hitting memory limits or just want a smarter way to handle images
in-memory without sacrificing speed, compressed-image was built for that.
Performance
The compressed-image library is aimed at high performance computing allowing you to store many images in-memory
simultaneously while not having to pay the associated memory cost. It performs equal or faster during image reads
with significantly lower memory usage
Quickstart
This is a simple example of getting you up and running with compressed-image, loading a file from disk and then interacting
with the channels. For more detailed examples have a look at the examples/ directory
cpp
#include <compress/image.h>
auto image = compressed::image<uint8_t>::read("/some/file/path");
// Retrieve the red channel from the image
auto channel_r = image.channel("R"); // could also get it via image.channel(0)
// Iterate over the chunks in the channel, this will decompress the
// chunk and recompress it on the fly.
for (auto chunk_r : channel_r)
{
std::for_each(std::execution::par_unseq, chunk_r.begin(), chunk_r.end(), [](auto& pixel)
{
// perform some computation on the chunk in parallel
});
}
// Otherwise you can also get the image data directly as a full channel. Although this is less memory efficient
std::vector<uint8_t> channel_r_decompressed = channel_r.get_decompressed();
python
import compressed_image as compressed
image = compressed.Image.read(np.float16, "/some/file/path", subimage=0)
channel_r: compressed.Channel = image[0]
# Iterate over the chunks in the channel, this is more memory efficient than decompressing all the data
# at once
for chunk_idx in range(channel_r.num_chunks()):
chunk = channel_r.get_chunk(chunk_idx)
# modify chunk as you wish
# set the chunk back again, this will recompress the data
channel_r.set_chunk(chunk, chunk_idx)
# If you instead wish to decompress the buffer as one you can do that too:
channel_r_decompressed = channel_r.get_decompressed()
Documentation
The complete user-facing documentation is hosted on readthedocs where you can find more information on benchmarks and technical class documentation.
1 maintainer
Metadata
1 maintainer
Release files for compressed-image 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| compressed_image-1.0.1.tar.gz | 15.3 MB | Details |
Built distributions (wheels)
Total release size: 113.3 MB
Release files / compressed_image-1.0.1.tar.gz
| Download URL | compressed_image-1.0.1.tar.gz |
|---|---|
| Size | 15.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
96c7d701b529d4123b25fbdf688dc514adc9a3eb9cdfa34977c3d819deac03e0
|
|
BLAKE2b-256 checksum How to use checksums |
aee704bb0647119e5678dd754aa21cb310eb2413355fd32fc6355ead77b32bfa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp313-cp313-win_amd64.whl
| Download URL | compressed_image-1.0.1-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 5.8 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
bdb62e993c5bb57aee1979400985111e0866aff2633e75e8a29e768af0ae85c1
|
|
BLAKE2b-256 checksum How to use checksums |
9667f7de99657624d5cc7cf1cf753a187754f339cfa6a567713c0245165afb41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp313-cp313-manylinux_2_34_x86_64.whl
| Download URL | compressed_image-1.0.1-cp313-cp313-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 7.5 MB |
| Tags | CPython 3.13 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
a71dc9abaa5deabb2f9e046afb25f0f350ca0f26ef0aa7d0bdffc9657183d9fc
|
|
BLAKE2b-256 checksum How to use checksums |
5515fe6b380f3d560a3d629a08a6f7d05695d21715c8837156436d2c313aa270
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp313-cp313-macosx_14_0_arm64.whl
| Download URL | compressed_image-1.0.1-cp313-cp313-macosx_14_0_arm64.whl |
|---|---|
| Size | 7.8 MB |
| Tags | CPython 3.13 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
0ce60a96c2d48eaf6a592cd6b9798763985b516443f8a487baa90ab088f036b5
|
|
BLAKE2b-256 checksum How to use checksums |
843b0b5d0d3dbd26791d81fdf27d5094143e7dd609b3223b17710420b1be0943
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp312-cp312-win_amd64.whl
| Download URL | compressed_image-1.0.1-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 5.8 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
c8a7c78266e064fbb43d0c3d245f5063b300bbde7747b794375125306e34a7c3
|
|
BLAKE2b-256 checksum How to use checksums |
ae5143e92d6a4775988db05e8a587c1383664a6b4546852e53f007ac58e5d623
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp312-cp312-manylinux_2_34_x86_64.whl
| Download URL | compressed_image-1.0.1-cp312-cp312-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 7.5 MB |
| Tags | CPython 3.12 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
f755b4f843ccebd700c695c4bb4261e9427628c48bb98c3409a3409668570752
|
|
BLAKE2b-256 checksum How to use checksums |
a213a097306685aa0cf0760e6b5bee81f4a53fd059fabb093295c4619241af1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp312-cp312-macosx_14_0_arm64.whl
| Download URL | compressed_image-1.0.1-cp312-cp312-macosx_14_0_arm64.whl |
|---|---|
| Size | 7.8 MB |
| Tags | CPython 3.12 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
9d167d1581c63435139904a2c23e19e1e48387354ee1f13bd14a070b8554bc2c
|
|
BLAKE2b-256 checksum How to use checksums |
06103cd23f536f97990875441dcb0eb8c72bb6f073e0e6019f43e4c2d5f8a14a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp311-cp311-win_amd64.whl
| Download URL | compressed_image-1.0.1-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 5.8 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
4bdd2d1525f6d479e5291911e46720c52f8e53ece841643a92cf8adc22e74555
|
|
BLAKE2b-256 checksum How to use checksums |
ff5c5562376faa388c1472120adbda0396385423572bd7a8a3d5578bc520ba7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp311-cp311-manylinux_2_34_x86_64.whl
| Download URL | compressed_image-1.0.1-cp311-cp311-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 7.5 MB |
| Tags | CPython 3.11 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
2f1f9a5fd144b05e0bcfbb440d2b5d8ee0813f2c087522b1ec4745d8a1b1ce99
|
|
BLAKE2b-256 checksum How to use checksums |
1c79bac0e262765ad76232e37b8857c29bbad540e4c086d0ccfb0b1d53ee4582
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp311-cp311-macosx_14_0_arm64.whl
| Download URL | compressed_image-1.0.1-cp311-cp311-macosx_14_0_arm64.whl |
|---|---|
| Size | 7.8 MB |
| Tags | CPython 3.11 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
fa0c9f4cbf6e89ee57d94ad89ca41ea7201d7d4ace8c6701df482df11ed248bc
|
|
BLAKE2b-256 checksum How to use checksums |
bc2db0203c9299493025b1d110e3820e1fec8a01569ab65c7fbf0526c41553cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp310-cp310-win_amd64.whl
| Download URL | compressed_image-1.0.1-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 5.8 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
747dd23def3332202af87362c783500a742d849d1525d5844ad48c3bd6955e30
|
|
BLAKE2b-256 checksum How to use checksums |
02bced4d481d678caa9f3ff4745c73d6ff9fbc70e03115172eb526d50202e7aa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp310-cp310-manylinux_2_34_x86_64.whl
| Download URL | compressed_image-1.0.1-cp310-cp310-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 7.5 MB |
| Tags | CPython 3.10 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
117e464a9bf69b8db0e90c84f3697097f11493e612e4185129925c2d0973f296
|
|
BLAKE2b-256 checksum How to use checksums |
cb8593087edcdaf6d0515ac8f493f0c8e4ba1c1cb38ed9c3bb6f0b7a3b7149ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp310-cp310-macosx_14_0_arm64.whl
| Download URL | compressed_image-1.0.1-cp310-cp310-macosx_14_0_arm64.whl |
|---|---|
| Size | 7.8 MB |
| Tags | CPython 3.10 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
af018e31cd1d5920ee447a4093f6a0e6017f7c0e1ac4c72de53243d3ca25d1e8
|
|
BLAKE2b-256 checksum How to use checksums |
a0dae80f1ea6108fe7f3ef30c4dae16549fe74b60ef8ab08fb404833dc152853
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp39-cp39-win_amd64.whl
| Download URL | compressed_image-1.0.1-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 5.9 MB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
764d35f8ba148a1e1b57ce82c8f2967df83915b4f83c10943b0b3b68643abec0
|
|
BLAKE2b-256 checksum How to use checksums |
142affb8b0c64b510ffd6572880c15e0bfa61749e6ca8d45d5a30c4513fa8c09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency logRelease files / compressed_image-1.0.1-cp39-cp39-manylinux_2_34_x86_64.whl
| Download URL | compressed_image-1.0.1-cp39-cp39-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 7.5 MB |
| Tags | CPython 3.9 Linux glibc 2.34+ x86-64 |
|
SHA-256 checksum How to use checksums |
548a0f1b40c6c8eba865bd688d8006ef81833e8358137b935186cdcec42aa83e
|
|
BLAKE2b-256 checksum How to use checksums |
25fce4edc85e1220aefa0bb07cf1cb90cd7261730b15001365a5e70f909d1619
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 1, 2025.
Transparency log
