The READ_BINARY function reads the contents of a binary file using a passed template or basic command line keywords. Data is read from the given filename or from the current file position in the open file pointed to by FileUnit. If no template is provided, keywords can be used to read a single IDL array of data.

Examples

The following reads the data in a binary file, head.data, and passes the data to an iVolume display:

vHeadData = READ_BINARY(FILEPATH('head.dat', $
   SUBDIRECTORY=['examples', 'data']), DATA_DIMS=[80,100,57])
IVOLUME, vHeadData

When the iVolume window appears, click Render on the Volume panel to display the data.

Also see the following :

Syntax

Result = READ_BINARY ([Filename] | FileUnit [, TEMPLATE=template] | [[, DATA_START=value] [, DATA_TYPE=typecodes] [, DATA_DIMS=array] [, ENDIAN=string]] )

Return Value

The result is an array or anonymous structure containing all of the entities read from the file.

Arguments

Filename

A scalar string containing the name of the binary file to read. If filename and file unit are not specified, a dialog allows the user to choose a file.

FileUnit

A scalar containing an open IDL file unit number to read from.

Keywords

DATA_DIMS

Set this keyword to a scalar or array of up to eight elements specifying the size of the data to be read and returned. For example, DATA_DIMS=[512,512] specifies that a two-dimensional, 512 by 512 array be read and returned. DATA_DIMS=0 specifies that a single, scalar value be read and returned. Default is -1, which, if a TEMPLATE is not supplied that specifies otherwise, indicates that READ_BINARY will read to end-of-file and store the result in a 1-D array.

DATA_START

Set this keyword to specify where to begin reading in a file. This value is as an offset, in bytes, that will be applied to the initial position in the file. The default is 0.

DATA_TYPE

Set this keyword to an IDL typecode of the data to be read. See documentation for the SIZE function for a listing of typecodes. Default is 1 (IDL’s BYTE typecode).

ENDIAN

Set this keyword to one of three string values: “big”, “little” or “native” which specifies the byte ordering of the file to be read. If the computer running READ_BINARY uses byte ordering that is different than that of the file, READ_BINARY will swap the order of bytes in multi-byte data types read from the file. (Default: “native” = perform no byte swapping.)

TEMPLATE

Set this keyword to a template structure (created using the BINARY_TEMPLATE function) describing the file to be read. The TEMPLATE keyword cannot be used simultaneously with keywords DATA_START, DATA_TYPE, DATA_DIMS, or ENDIAN.

When a template is used with READ_BINARY, the return value is a structure containing fields specified by the template. If a template is not used, the return value is an array.

Additional Examples

Working with a READ_Binary Data Structure

READ_BINARY returns a structure containing binary data, which is formatted according to specified keywords or a template. The following example returns a structure containing the data in the surface.dat file, found in the examples/data subdirectory of the IDL installation directory.

  1. Enter the following statement at the IDL command line to open the Binary Template dialog:

    sTemplate = BINARY_TEMPLATE()

  2. Complete the steps described in Using the BINARY_TEMPLATE Interface to define the format of the data.

  3. Use READ_BINARY to access the data, defined by the template created in the previous step:

    data = READ_BINARY(FILEPATH('surface.dat', $
       SUBDIRECTORY=['examples', 'data']), TEMPLATE = sTemplate)

  4. The variable data now contains the binary data. Use the format structureName.fieldName to access individual fields of data. The following lines display the data in an iSurface tool:

    ISURFACE, data.marbells

Note: The Variable Watch window contains the sTemplate and data structures. Expand these items for information about the structure fields.

Displaying Binary Images with Direct Graphics

Binary images are composed of pixels having one of two values, usually zero or one. With most color tables, pixels having values of zero or one are displayed with almost the same color, such as with a the default grayscale color table. Thus, a binary image is usually scaled to display the zeros as black and the ones as white.

The following example imports a binary image of the world from the continent_mask.dat binary file. In this image, the oceans are zeros (black) and the continents are ones (white). This type of image can be used to mask out data over the oceans. The image contains byte data values and is 360 pixels by 360 pixels. Complete the following steps for a detailed description of the process.

See displaybinaryimage_direct.pro in the examples/doc/image subdirectory of the IDL installation directory for code that duplicates this example. Run the example procedure by entering displaybinaryimage_direct at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT displaybinaryimage_direct.pro.

  1. Determine the path to the continent_mask.dat file:

    file = FILEPATH('continent_mask.dat', $
       SUBDIRECTORY = ['examples', 'data'])

  2. Initialize the image size parameter:

    imageSize = [360, 360]

  3. Use READ_BINARY to import the image from the file:

    image = READ_BINARY(file, DATA_DIMS = imageSize)

  4. If you are running IDL on a TrueColor display, set the DECOMPOSED keyword to the DEVICE command to zero before your first color table related routine is used within an IDL session or program. This command implies a color table will be used. 

    DEVICE, DECOMPOSED = 0

  5. Load a grayscale color table:

    LOADCT, 0

  6. Create a window and display the original image with the TV procedure:

    WINDOW, 0, XSIZE = imageSize[0], YSIZE = imageSize[1], $
       TITLE = 'A Binary Image, Not Scaled'
    TV, image

    The resulting window should be all black (blank). The binary image contains zeros and ones, which are almost the same color (black). Binary images should be displayed with the TVSCL procedure in order to scale the ones to white.

  7. Create another window and display the scaled binary image:

    WINDOW, 1, XSIZE = imageSize[0], YSIZE = imageSize[1], $
       TITLE = 'A Binary Image, Scaled'
    TVSCL, image

    The following figure shows the results of scaling this display.

Displaying a Grayscale Binary Image

Features within grayscale images are created by pixels that have varying intensities. Pixel values range from least intense (black) to the most instance (white). Since a grayscale image is composed of pixels of varying intensities, it is best displayed with a color table that progresses linearly from black to white. Although IDL has several such predefined color tables, the grayscale color table (B-W LINEAR), is the most fitting choice when displaying grayscale images. IDL’s B-W LINEAR color table is represented by an index value of 0.

The following example imports a grayscale image from the convec.dat binary file. This grayscale image shows the convection of the Earth’s mantle. The image contains byte data values and is 248 pixels by 248 pixels. Since the data type is byte, this image does not need to be scaled before display. If the data was of any type other than byte and the data values were not within the range from 0 to 255, the image would need to be scaled prior to being displayed. Complete the following steps for a detailed description of the process.

See displaygrayscaleimage_direct.pro in the examples/doc/image subdirectory of the IDL installation directory for code that duplicates this example. Run the example procedure by entering displaygrayscaleimage_direct at the IDL command prompt or view the file in an IDL Editor window by entering .EDIT displaygrayscaleimage_direct.pro.

  1. Determine the path to the convec.dat file:

    file = FILEPATH('convec.dat', $
       SUBDIRECTORY = ['examples', 'data'])

  2. Initialize the image size parameter:

    imageSize = [248, 248]

  3. Using READ_BINARY, import the image from the file:

    image = READ_BINARY(file, DATA_DIMS = imageSize)

  4. If you are running IDL on a TrueColor display, set the DECOMPOSED keyword to the DEVICE command to zero before your first color table related routine is used within an IDL session or program.

    DEVICE, DECOMPOSED = 0

  5. Load a grayscale color table:

    LOADCT, 0

  6. Create a window and display the original image with the TV procedure:

    WINDOW, 0, XSIZE = imageSize[0], YSIZE = imageSize[1], $
       TITLE = 'A Grayscale Image'
    TV, image

    The following figure shows the resulting grayscale image display.

Version History

5.3

Introduced

See Also

BINARY_TEMPLATE