## Reading a NIFTI formatted image volume

The easiest way to read an image file is to use `loadVolume`:

        fileName <- system.file("extdata", "global_mask.nii", package="neuroim")
        vol <- loadVolume(fileName)

## Working with image volumes

Information about the geometry of the image volume is easily accessed:

        print(vol)
    #> BrainVolume
    #>   Type           : DenseBrainVolume
    #>   Dimension      : 64 64 25
    #>   Spacing        : 3.5  X  3.5  X  3.70000004768372
    #>   Origin         : 110  X  -110  X  -46.25
    #>   Axes           : Right-to-Left Posterior-to-Anterior Inferior-to-Superior

`loadVolume` returns an object of class `DenseBrainVolume` which extends an R array' and has 3 dimensions (x,y,z).

        class(vol)
    #> [1] "DenseBrainVolume"
    #> attr(,"package")
    #> [1] "neuroim"

        is.array(vol)
    #> [1] TRUE

        dim(vol)
    #> [1] 64 64 25

        vol[1,1,1]
    #> [1] 0

        vol[64,64,24]
    #> [1] 0

Arithmetic can be performed on images as if they were ordinary arrays:

        vol2 <- vol + vol
        sum(vol2) == 2 * sum(vol)
    #> [1] TRUE

        vol3 <- vol2 - 2*vol
        all(vol3 == 0)
    #> [1] TRUE

A numeric image volume can be converted to a binary image as follows:

        vol2 <- as.logical(vol)
        print(vol2[1,1,1])
    #> [1] FALSE

We can also create a `BrainVolume` instance from an `array` or `numeric` vector:

        # create an 64X64X64 array of zeros
        x <- array(0, c(64,64,64))

        # create a 'BrainSpace' instance that describes the geometry of the image including, at minimu its dimensions and voxel spacing
        bspace <- BrainSpace(Dim=c(64,64,64), spacing=c(1,1,1))
        vol <- BrainVolume(x, bspace)
        vol
    #> BrainVolume
    #>   Type           : DenseBrainVolume
    #>   Dimension      : 64 64 64
    #>   Spacing        : 1  X  1  X  1
    #>   Origin         : 0  X  0  X  0
    #>   Axes           : Left-to-Right Posterior-to-Anterior Inferior-to-Superior

We do not usually have to create `BrainSpace` objects because this information is usually read from disk. Thus, `BrainSpace` objects are usually copied from existing images using the `space` extractor function when needed:

        vol2 <- BrainVolume((vol+1)*25, space(vol))
        max(vol2)
    #> [1] 25

        space(vol2)
    #> BrainSpace
    #>   Type           : BrainSpace
    #>   Dimension      : 64 64 64
    #>   Spacing        : 1  X  1  X  1
    #>   Origin         : 0  X  0  X  0
    #>   Coordinate Transform : 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1

## Writing a NIFTI formatted image volume

When we're ready to write an image volume to disk, we use `writeVolume`

        writeVolume(vol2, "output.nii")

        ## adding a '.gz' extension results ina gzipped file.
        writeVolume(vol2, "output.nii.gz")