jnifti toolbox v0.5

lib/matlab/README.md

@@ -1,5 +1,10 @@
 # JNIfTI Toolbox - Fast and portable NIfTI-1/2 reader and NIfTI-to-JNIfTI converter
 
+* Copyright (C) 2019  Qianqian Fang <q.fang at neu.edu>
+* License: GNU General Public License version 3 (GPL v3) or Apache License 2.0, see License*.txt
+* Version: 0.5 (Ascendence)
+* URL: http://github.com/fangq/jnifti
+
 ## Overview
 
 This is a fully functional NIfTI-1/2 reader/writer that supports both 
@@ -27,7 +32,7 @@ The JNIfTI toolbox is also capable of reading/writing gzip-compressed NIfTI and
 Analyze7.5 files (.nii.gz, .hdr.gz, .img.gz). This feature is supported in MATLAB
 directly without needing another toolbox (MATLAB must be in the JVM-enabled mode).
 
-To process gzip-compressed NIfTI/Analyze files in Octave and MATLAB with -nojvm,
+To process gzip-compressed NIfTI/Analyze files in Octave and MATLAB with `-nojvm`,
 one need to install the open-source JSONLab and ZMat toolboxes, both supporting
 MATLAB and Octave. They can be downloaded at
 
@@ -39,3 +44,40 @@ data format supports internal compression (as oppose to external compression suc
 as \*.gz files). To create or read compressed JNIfTI files in Octave, one must 
 install the ZMat toolbox, as listed above.
 
+## Usage
+
+### `nii2jnii` - To convert a NIfTI-1/2 file to a JNIfTI file or data structure
+Example:
+```
+  nii=nii2jnii('test.nii', 'nii');         % read a .nii file as a nii structure
+  nii=nii2jnii('test.nii.gz');             % read a .nii.gz file as a jnii structure
+  nii2jnii('test.nii.gz', 'newdata.jnii') ;% read a .nii.gz file and convert to a text-JNIfTI file  
+  nii2jnii('test.nii.gz', 'newdata.bnii','compression','zlib'); % read a .nii.gz file and convert to a binary-JNIfTI file with compression
+```
+### `loadnifti` - To read a NIfTI-1/2 (.nii or .nii.gz) file (alias to `nii2jnii`)
+Example:
+```
+  nii=loadnifti('test.nii.gz');             % read a .nii.gz file as a jnii structure
+  nii=loadnifti('test.nii', 'nii');         % read a .nii file as a nii structure
+```
+### `savenifti` - To write an image as NIfTI-1/2 (.nii or .nii.gz) file
+Example:
+```
+  savenifti(img,'test.nii.gz');         % save an array img to a compressed nifti file
+  savenifti(img, 'test.nii', 'nifti2'); % save an array img to a nifti-2 file file
+  savenifti(img, 'test.nii', header);   % save an array img with an existing header
+```
+### `loadjnifti` - To read a JNIfTI (.jnii or .bnii) file
+Example:
+```
+  jnii=nii2jnii('test.nii.gz');
+  savejnifti(jnii, 'magic10.bnii','Compression','gzip');
+  newjnii=loadjnifti('magic10.bnii');
+```
+### `savejnifti` - To write a JNIfTI structure into a file (.jnii or .bnii)
+Example:
+```
+  jnii=jnifticreate(uint8(magic(10)),'Name','10x10 magic matrix');
+  savejnifti(jnii, 'magic10.jnii');
+  savejnifti(jnii, 'magic10_debug.bnii','Compression','gzip');
+```

lib/matlab/loadnifti.m

@@ -0,0 +1,21 @@
+function varargout = loadnifti (varargin)
+%
+%    jnii=loadnifti(filename)
+%        or
+%    nii=loadnifti(filename,option)
+%
+%    Read a NIfTI-1/2 (*.nii/.nii.gz) or Analyze 7.5 (*.hdr/*.img/.hdr.gz/.img.gz) 
+%    image file.
+%
+%    author: Qianqian Fang (q.fang <at> neu.edu)
+%
+%    Please run `help nii2jnii` to see the input output outputs.
+%    This function is an alias to nii2jnii
+%
+%
+%    this file is part of JNIfTI specification: https://github.com/fangq/jnifti
+%
+%    License: Apache 2.0, see https://github.com/fangq/jnifti for details
+%
+
+[varargout{1:nargout}]=nii2jnii(varargin{:});

lib/matlab/nifticreate.m

@@ -20,7 +20,7 @@
 %    License: Apache 2.0, see https://github.com/fangq/jnifti for details
 %
 
-if(nargin<1)
+if(nargin<2)
     format='nifti1';
 end
 
@@ -38,7 +38,11 @@
 header.dim(1:ndims(img)+1)=cast([ndims(img),size(img)], class(header.dim));
 header.pixdim(1:ndims(img)+1)=cast(1, class(header.pixdim));
 header.vox_offset=cast(headerlen+4, class(header.vox_offset));
-header.magic(1:3)=cast('ni1',class(header.magic));
+if(header.sizeof_hdr==540)
+    header.magic(1:3)=cast('ni2',class(header.magic));
+else
+    header.magic(1:3)=cast('ni1',class(header.magic));
+end
 header.srow_x(1)=cast(1, class(header.srow_x));
 header.srow_y(2)=cast(1, class(header.srow_y));
 header.srow_z(3)=cast(1, class(header.srow_z));

lib/matlab/nii2jnii.m

@@ -16,10 +16,11 @@
 %
 %    input:
 %        fname: the file name to the .nii, .nii.gz, .hdr/.img or .hdr.gz/.img.gz file
-%        format:'nii' for reading the NIfTI-1/2/Analyze files; 'jnii' to
-%               convert the nii data into an in-memory JNIfTI structure.
+%        format:'nii' for reading the NIfTI-1/2/Analyze files; 
+%               'jnii' to convert the nii data into an in-memory JNIfTI structure.
+%               'niiheader' return only the nii header without the image data
 %
-%               if format is not 'nii' or 'jnii' and nii2jnii is called without 
+%               if format is not listed above and nii2jnii is called without 
 %               an output, format must be a string specifying the output JNIfTI
 %               file name - *.jnii for text-based JNIfTI, or *.bnii for the 
 %               binary version

lib/matlab/savenifti.m

@@ -0,0 +1,74 @@
+function bytestream=savenifti(img, filename, varargin)
+%
+%    savenifti(img, filename)
+%        or
+%    savenifti(img, filename, rawhdr)
+%    savenifti(img, filename, 'nifti2')
+%    bytestream=savenifti(img)
+%
+%    Write an image to a NIfTI (*.nii) or compressed NIfTI file (.nii.gz)
+%
+%    author: Qianqian Fang (q.fang <at> neu.edu)
+%
+%    input:
+%        img: this is a numerical array to be stored in the NIfTI file
+%        filename: output file name, can have a suffix of '.nii' or '.nii.gz'
+%                 if a .gz suffix is used, this function needs the JSONLab 
+%                 (http://gitlab.com/fangq/jsonlab) and ZMat (http://gitlab.com/fangq/zmat)
+%                 to perform the compression.
+%        rawhdr (optional): a struct, as a pre-created/loaded NIfTI header data structure
+%                if rawhdr is 'nifti1' or 'nifti2', this function calls 
+%                nifticreate to create a default header.
+%    output:
+%        bytestream (optional): the output file byte stream. it only returns this output if
+%                no filename is given. 
+%
+%    example:
+%        a=single(rand(10,20,30));
+%        savenifti(a,'randnii.nii');
+%        savenifti(a,'randnii2.nii.gz','nifti2'); % needs zmat
+%
+%
+%    this file is part of JNIfTI specification: https://github.com/fangq/jnifti
+%
+%    License: Apache 2.0, see https://github.com/fangq/jnifti for details
+%
+
+
+if(~isempty(varargin))
+    if(isstruct(varargin{1}))
+        header=varargin{1};
+    elseif(ischar(varargin{1}))
+        header=nifticreate(img,varargin{1});
+    end
+else
+    header=nifticreate(img);
+end
+
+names=fieldnames(header);
+buf=[];
+for i=1:length(names)
+    buf=[buf,typecast(header.(names{i}),'uint8')];
+end
+
+if(length(buf)~=352 && length(buf)~=544)
+    error('incorrect nifti-1/2 header %d',length(buf));
+end
+
+buf=[buf,typecast(img(:)','uint8')];
+
+if(nargout>1 && nargin<2)
+    bytestream=buf;
+    return;
+end
+
+if(regexp(filename,'\.[Gg][Zz]$'))
+    buf=gzipencode(buf);
+end
+
+fid=fopen(filename,'wb');
+if(fid==0)
+    error('can not write to the specified file');
+end
+fwrite(fid,buf);
+fclose(fid);