JNIfTI - Fast and Portable NIfTI Reader/Writer for MATLAB/Octave

JNIfTI Toolbox

Fast and portable NIfTI-1/2 reader/writer for MATLAB and Octave

Version 0.8 MATLAB R2008a+ GNU Octave 4.0+ Apache 2.0 / GPL v3 NIH Funded

🧠 What is JNIfTI?

JNIfTI is a fully functional NIfTI-1/2 reader/writer that supports both MATLAB and GNU Octave. It can read and write compressed/uncompressed NIfTI files (.nii, .nii.gz) and Analyze 7.5 files (.hdr/.img).

More importantly, JNIfTI converts NIfTI data to its JSON-based replacement format - providing a much more flexible, human-readable, and extensible alternative to the rigid binary NIfTI format.

🏆 NeuroJSON Project

JNIfTI is part of the NeuroJSON project (neurojson.org), funded by US NIH grant U24-NS124027. It implements the JNIfTI Specification Draft 2 for standardized neuroimaging data exchange.

6+
Years Development
2
NIfTI Versions
10+
Core Functions
View on GitHub See Examples Specification

📋 JNIfTI Format Advantages

JNIfTI (.jnii for text, .bnii for binary) provides a modern alternative to traditional NIfTI files:

🔍 Human-Readable

  • Text-based JSON format (.jnii)
  • Self-documenting structure
  • Easy to inspect and validate
  • Version control friendly

⚡ High Performance

  • Binary format option (.bnii)
  • Internal compression support
  • Fast memory-mapped reading
  • Efficient data storage

🌐 Cross-Platform

  • JSON standard compatibility
  • Python support via pyjdata
  • JavaScript/web compatible
  • Universal parsers available

📦 JData Compliant

  • Follows JData specification
  • Complex data annotations
  • Metadata preservation
  • Extension support
JNIfTI Spec View Examples

⚡ Key Capabilities

  • Universal Compatibility: Works with MATLAB R2008a+ and GNU Octave 4.0+
  • Complete NIfTI Support: Read/write NIfTI-1 and NIfTI-2 formats
  • Compression Support: Handle .nii.gz files natively with optional ZMat acceleration
  • Analyze 7.5 Support: Read legacy .hdr/.img format files
  • Memory-Mapped I/O: Fast disk-based reading in MATLAB using memmapfile
  • Bi-directional Conversion: Convert between NIfTI ↔ JNIfTI seamlessly
  • Internal Compression: JNIfTI supports zlib, gzip, lzma compression
  • Zero Dependencies: Basic NIfTI reading requires no additional toolboxes
View Examples Browse Functions

Why Choose JNIfTI?

Modern neuroimaging data format for the 21st century

🔄

Bidirectional Conversion

Seamlessly convert between traditional NIfTI-1/2 and modern JNIfTI formats

📖

Human-Readable

Text-based JSON format makes data inspection and debugging effortless

🗜️

Compression Options

Internal compression with zlib, gzip, lzma for efficient storage

⚡

Fast Performance

Memory-mapped I/O in MATLAB for rapid data access

🔧

Easy to Extend

JSON structure allows easy addition of custom metadata and extensions

🌍

Universal Format

Compatible with any JSON parser across all programming languages

Code Examples

Quick start with JNIfTI Toolbox

% Read NIfTI files with loadnifti
nii = loadnifti('brain.nii.gz');

% Access image data and header
img = nii.NIFTIData;
header = nii.NIFTIHeader;

% Save image to NIfTI file with savenifti
img = uint16(reshape(1:10*30*20, [10, 30, 20]));
savenifti(img, 'output.nii');
savenifti(img, 'output.nii.gz');  % compressed

% Save with NIfTI-2 format
savenifti(img, 'output_v2.nii', 'nifti2');
% Create JNIfTI structure with jnifticreate
jnii = jnifticreate(uint8(magic(10)), ...
       'Name', '10x10 magic matrix', ...
       'Description', 'Test data');

% Save to text JNIfTI with savejnifti
savejnifti(jnii, 'magic10.jnii');

% Save to binary JNIfTI with compression
savejnifti(jnii, 'magic10.bnii', 'Compression', 'zlib');

% Load JNIfTI files with loadjnifti
data = loadjnifti('magic10.jnii');
data = loadjnifti('magic10.bnii');
% Convert NIfTI to JNIfTI with nii2jnii
jnii = nii2jnii('brain.nii.gz');

% Save as text JNIfTI
nii2jnii('brain.nii.gz', 'brain.jnii');

% Save as binary JNIfTI with compression
nii2jnii('brain.nii.gz', 'brain.bnii', ...
         'compression', 'zlib');

% Convert JNIfTI back to NIfTI with jnii2nii
nii = jnii2nii('brain.jnii');
jnii2nii('brain.bnii', 'new_brain.nii.gz');
% Save with different compression methods
jnii = jnifticreate(uint8(magic(100)));

% Zlib compression (good balance)
savejnifti(jnii, 'data.bnii', 'Compression', 'zlib');

% Gzip compression
savejnifti(jnii, 'data_gz.bnii', 'Compression', 'gzip');

% LZMA compression (highest ratio, slower)
savejnifti(jnii, 'data_lzma.bnii', 'Compression', 'lzma');

% Use gzipencode/gzipdecode for in-memory compression
[compressed, info] = gzipencode(img);
decompressed = gzipdecode(compressed, info);
% Create custom NIfTI header with nifticreate
img = single(rand(64, 64, 30));
header = nifticreate(img, 'nifti1');

% Create JNIfTI with custom metadata
jnii = jnifticreate(img, ...
       'Name', 'fMRI scan', ...
       'Description', 'Resting state data', ...
       'VoxelSize', [3, 3, 3.5, 2], ...
       'Unit', struct('L', 'mm', 'T', 's'));

% Access and modify header fields
jnii.NIFTIHeader.ScaleSlope = 1.5;
jnii.NIFTIHeader.ScaleOffset = 0;

savejnifti(jnii, 'custom.jnii');

Key Features

Everything you need for neuroimaging data processing

📁

Multiple Formats

NIfTI-1, NIfTI-2, Analyze 7.5, and JNIfTI (.jnii/.bnii) support

🗜️

Compression

Native gzip support, optional ZMat for zlib/lzma/lz4

⚡

Fast I/O

Memory-mapped reading in MATLAB for optimal performance

🔄

Easy Conversion

Seamless conversion between NIfTI and JNIfTI formats

🎯

Standalone

Zero dependencies for basic NIfTI reading/writing

📋

Metadata Rich

Full header mapping to human-readable JSON fields

Core Functions

Complete API reference

NIfTI I/O

  • loadnifti - Read NIfTI-1/2 files
  • savenifti - Write NIfTI-1/2 files
  • nifticreate - Create NIfTI header

JNIfTI I/O

  • loadjnifti - Read JNIfTI files
  • savejnifti - Write JNIfTI files
  • savejnii - Save text JNIfTI
  • savebnii - Save binary JNIfTI
  • jnifticreate - Create JNIfTI structure

Format Conversion

  • nii2jnii - NIfTI to JNIfTI
  • jnii2nii - JNIfTI to NIfTI
  • niiheader2jnii - Header conversion

Utilities

  • niicodemap - Code/string mapping
  • niiformat - Header format descriptor
  • memmapstream - Memory mapping

Compression (Octave)

  • gzipencode / gzipdecode
  • octavezmat - Fallback compression

Installation

Get started in minutes

📦 Manual Installation

For reading uncompressed NIfTI files:

addpath('/path/to/jnifty');
rehash;

🐧 Debian/Ubuntu

Install via package manager:

sudo apt-get install octave-jnifti

🎩 Fedora

Install official package:

sudo dnf install octave-jnifti

🗜️ With Full Features

For .nii.gz and JNIfTI support:

% Install JSONLab
addpath('/path/to/jsonlab');

% Optional: ZMat for Octave
addpath('/path/to/zmat');

🔧 From GitHub

Clone the repository:

git clone https://github.com/NeuroJSON/jnifty.git

📚 Dependencies

Optional toolboxes:

% JSONLab (for JNIfTI)
github.com/NeuroJSON/jsonlab

% ZMat (for compression)
github.com/NeuroJSON/zmat

Ready to Process Neuroimaging Data?

Join the NeuroJSON community

6+
Years Development
0.8
Current Version
2
Specifications
Download Latest Release JNIfTI Specification

Supported by NIH Grant U24-NS124027

Apache 2.0 or GPL v3 License

Powered by Habitat