Skip to main content

Neuroglancer compressed_segmentation codec.

Project description

PyPI version

Compress Seg Picture

Library for compressing and decompressing image segmentation (adapted from neuroglancer)

import compressed_segmentation as cseg

sx, sy, sz = (128,128,128)
dtype = np.uint64
order = 'C'

labels = np.arange(0, sx*sy*sz, dtype=dtype).reshape((sx,sy,sz), order=order)
compressed = cseg.compress(labels, order=order)
recovered = cseg.decompress(
    compressed, (sx,sy,sz) dtype=dtype, order=order

arr = CompressedSegmentationArray(
    compressed, shape=(sx,sy,sz), dtype=dtype
label = arr[54,32,103] # random access to single voxels w/o decompressing
uniq_labels = arr.labels() # get all distinct values w/o decompressing
binary2 = arr.remap({ 1: 2 }, preserve_missing_labels=False) # remap labels in segmentation w/o decompressing
recovered = arr.numpy() # decompress to a numpy array, same as decompress
124213 in arr # test if a value is in the array
cseg compress connectomics.npy
cseg decompress connectomics.npy.cseg --volume-size 512,512,512 --bytes 4

NOTE: This repository is the PyPI distribution repo but is based on work done by Jeremy Maitin-Shepard (Google), Stephen Plaza (Janelia Research Campus), and William Silversmith (Princeton) here:

This library contains routined to decompress and compress segmentation and to manipulate compressed segmentation data defined by the neuroglancer project. compressed_segmentation essentially renumbers large bit width labels to smaller ones in chunks. This provides for large reductions in memory usage and higher compression.

Note that limitations in the compressed_segmentation format restrict the size of the chunk that can be compressed. As this limitation is data dependent, for example a random array with 1024 labels passes testing at 256x256x128, but 256x256x256 often does not.


  • Compression and decompression
  • Random access to voxels without decompression
  • Read out unique values without decompression
  • Remap labels without decompression
  • Command line interface for numpy files
  • (TBD) Interface to relabel and manipulate segmentation from the compressed data
  • C++, Python, and Go interface (see original repo for Golang)

C++ Compilation

Compiling as a shared library. Feel free to subsititute e.g. clang for the C++ compiler.

g++ -std=c++11 -O3 -fPIC -shared -I./include src/ src/ -o

Python Installation

pip Binary Installation

$ pip install compressed-segmentation

$ python
>>> import compressed_segmentation as cseg
>>> help(cseg)

If there are pre-built binaries available for your architecture this should just work.

pip Source Installation

If you need to build from source, you will need to have a C++ compiler installed:

$ sudo apt-get install g++ python3-dev 
$ pip install numpy
$ pip install compressed-segmentation

$ python
>>> import compressed_segmentation as cseg
>>> help(cseg)

Direct Installation

Requires a C++ compiler such as g++ or clang.

Works with both Python 2 and 3. Encodes from / decodes to 3D or 4D numpy ndarrays.

$ sudo apt-get install g++ python3-dev 
$ pip install -r requirements.txt
$ python install

$ python
>>> import compressed_segmentation as cseg
>>> help(cseg)


Please see the licenses in this repo.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

compressed_segmentation-2.2.0.tar.gz (193.2 kB view hashes)

Uploaded source

Built Distributions

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page