Spatial Codec

Modified: 2021-06

Navigation

1. About
2. Quickstart
3. Dev
4. License

About

Spatial codec is a spatial encoding and decoding algorithm developed for iteratively mapping any number of bytes to a 3D (N3 space) matrix. The algorithm uses a psuedo variant of Hilbert's Space Filling Curve which preserves the relative localization of bits in 3D independant of the matrix dimension which is a convienient property for error correction and scalable network policies.

Quickstart

Install scodec from the package index

python3 -m pip install --upgrade pip
...
python3 -m pip install scodec

You may be required to install some apt packages on some linux distros:

sudo xargs -a apt-packages.txt apt install -y

API

Spatial codec provides an api for interacting in 2 (N2) and 3 (N3) dimensional space. Below is an example of using the N2 space api:

from scodec.n2 import N2

# configure a 2D spatial codec using a 64 bit block size
sc = N2(block_size=64)
# encode utf-8 string and enable matplotlib visualizer
space_encode = sc.stream_encode(bytes("Hello World", "utf-8"), mpl=True)
# feed spatial encode stream back into stream decode
bytestream = sc.stream_decode(space_encode)

CLI Tool

The codec provides a cli tool for ease of use. Run the algorithm for a specified block size -b / --block, with a data stream -d / --data and dimension -n / --dimension (2 or 3). The MPL visualizer can be enabled with the -v= flag.

# n2 codec invocation
python3 -m scodec -n 2 -b 256 -d "Hello world this is a codec test" -v=
...
# n3 codec invocation 
python3 -m scodec -n 3 -b 8 -d "H" -v=

License

BSD 2-Clause License available here