# Specification (v1)

`vlsi` contains three files, two of which are needed to decode the sparse index.

## 0/ Metadata file `{filename}`

utf-8 encoeded text file. *Must* start with `SPATIALINDEX-UTF8-V1`. Not needed to decode sparse index.

## 2/ Spatial dictionary file `{filename}.spatialindex.voxel.nii.gz`

uint64 NiFTi-1 image file. Each voxel encodes two 32 bit values, offset and bytes.

2.1/ Higher 32 bit (i.e. `voxel_value >> 32`) encodes offset. 

2.2/ Lower 32 bit (i.e. `voxel_value & 0xffffffff`) encodes size.

2.3/ For every voxel, offset (2.1) + size (2.2) *must* be less or equal to the file size of attr file (3.)

## 3/ Data file `{filename}.spatialindex.attr.bin`

3.1/ For all voxel in (2.), byte range from offset (2.1) to 
offset + size (2.2) (i.e. `seek(offset); read(bytes)`) represent must be retrievable.

> n.b. The interpretation of the bytes returned is deliberately not specifically defined. Client using `vlsi` is responsible for decoding the returned bytes.


## Potential future developments

- Binary Spec

Binary probability file/metadata file to improve performance and further reduce memory usage.

## References


