multibandread (MATLAB Functions)

Read band interleaved data from binary file

Syntax

X = multibandread(filename, size, precision, offset, interleave, 
byteorder)
X = multibandread(...,subset1,subset2,subset3)

Description

X = multibandread(filename, size, precision, offset, interleave, byteorder) reads multiband data from the binary file filename. This function defines band as the third dimension in a 3-D array, as shown in this figure.

You can use the parameters to multibandread to specify many aspects of the read operation, such as which bands to read. See Parameters for more information.

If you only read one band, the return value X is a 2-D array. If you read multiple bands, X is 3-D. By default, X is an array of type double; however, you can use the precision parameter to specify any other data type.

X = multibandread(...,subset1,subset2,subset3) reads a subset of the data in the file. You can use up to three subsetting parameters to specify the data subset along row, column, and band dimensions. See Subsetting Parameters for more information.

Parameters

This table describes the arguments accepted by multibandread.

filename
String containing the name of the file to be read.

size
Three-element vector of integers consisting of [height, width, N], where
height is the total number of rows

width is the total number of elements in each row

N is the total number of bands.

This will be the dimensions of the data if it is read in its entirety.

precision

String specifying the format of the data to be read, such as 'uint8', 'double', 'integer*4', or any of the other precisions supported by the fread function.
Note: You can also use the precision parameter to specify the format of the output data. For example, to read uint8 data and output a uint8 array, specify a precision of 'uint8=>uint8' (or '*uint8'). To read uint8 data and output it in MATLAB in single precision, specify 'uint8=>single'. See fread for more information.

offset
Scalar specifying the zero-based location of the first data element in the file. This value represents the number of bytes from the beginning of the file to where the data begins.

interleave
String specifying the format in which the data is stored
'bsq' -- Band-Sequential

'bil'-- Band-Interleaved-by-Line

'bip'-- Band-Interleaved-by-Pixel

For more information about these interleave methods, see the multibandwrite reference page.

byteorder
String specifying the byte ordering (machine format) in which the data is stored, such as
'ieee-le' -- Little-endian

'ieee-be' -- Big-endian

See fopen for a complete list of supported formats.

`filename`	String containing the name of the file to be read.
`size`	Three-element vector of integers consisting of `[height, width, N]`, where `height` is the total number of rows `width` is the total number of elements in each row `N` is the total number of bands. This will be the dimensions of the data if it is read in its entirety.
`precision`	String specifying the format of the data to be read, such as `'uint8'`, `'double'`, `'integer4'`, or any of the other precisions supported by the `fread` function. Note: You can also use the `precision` parameter to specify the format of the output data. For example, to read `uint8` data and output a `uint8` array, specify a precision of `'uint8=>uint8'` (or `'uint8'`). To read `uint8` data and output it in MATLAB in single precision, specify `'uint8=>single'`. See `fread` for more information.
`offset`	Scalar specifying the zero-based location of the first data element in the file. This value represents the number of bytes from the beginning of the file to where the data begins.
`interleave`	String specifying the format in which the data is stored `'bsq`' -- Band-Sequential `'bil'`-- Band-Interleaved-by-Line `'bip'`-- Band-Interleaved-by-Pixel For more information about these interleave methods, see the `multibandwrite` reference page.
`byteorder`	String specifying the byte ordering (machine format) in which the data is stored, such as `'ieee-le'` -- Little-endian `'ieee-be'` -- Big-endian See `fopen` for a complete list of supported formats.

Subsetting Parameters

You can specify up to three subsetting parameters. Each subsetting parameter is a three-element cell array, {dim, method, index}, where

dim
Text string specifying the dimension to subset along. It can have any of these values:
'Column'

'Row'

'Band'

method
Text string specifying the subsetting method. It can have either of these values:
'Direct'

'Range'

If you leave out this element of the subset cell array, multibandread uses 'Direct' as the default.

index

If method is 'Direct', index is a vector specifying the indices to read along the Band dimension.
If method is 'Range', index is a three-element vector of [start, increment, stop] specifying the range and step size to read along the dimension specified in dim. If index is a two-element vector, multibandread assumes that the value of increment is 1.

`dim`	Text string specifying the dimension to subset along. It can have any of these values: `'Column'` `'Row'` `'Band'`
`method`	Text string specifying the subsetting method. It can have either of these values: `'Direct'` `'Range'` If you leave out this element of the subset cell array, `multibandread` uses `'Direct'` as the default.
`index`	If `method` is `'Direct'`, `index` is a vector specifying the indices to read along the Band dimension. If `method` is `'Range'`, `index` is a three-element vector of `[start, increment, stop]` specifying the range and step size to read along the dimension specified in `dim`. If `index` is a two-element vector, `multibandread` assumes that the value of `increment` is `1`.

Examples

Read data from a multiband file into an 864-by-702-by-3 uint8 matrix, im.

im = multibandread('bipdata.img',...
[864,702,3],'uint8=>uint8',0,'bip','ieee-le');

Read all rows and columns, but only bands 3, 4, and 6.

im = multibandread('bsqdata.img',...
[512,512,6],'uint8',0,'bsq','ieee-le',...
{'Band','Direct',[3 4 6]});

Read all bands and subset along the rows and columns.

im = multibandread('bildata.int',...
[350,400,50],'uint16',0,'bil','ieee-le',...
{'Row','Range',[2 2 350]},...
{'Column','Range',[1 4 350]});

See Also

fread, fopen, multibandwrite

mu2lin multibandwrite