The READ_MRSID function extracts and returns image data from a MrSID file at the specified level and location. It is a wrapper around the object interface that presents MrSID image loading in a familiar way to users of the READ_* image routines. However this function is not as efficient as the object interface and the object interface should be used whenever possible. See IDLffMrSID for information about the object interface.

Note: This routine is only available under Microsoft Windows.

Examples


; Query the file.
result = QUERY_MRSID(FILE_SEARCH(!DIR, 'test_gs.sid'), info)
 
; If result is not zero, read in an image from the file and
; display it.
IF (result NE 0) THEN BEGIN
   PRINT, info
   imageData = READ_MRSID(FILE_SEARCH(!DIR, 'test_gs.sid'), $
      SUB_RECT = [0, 0, 200, 200], LEVEL = 3)
   oImage = OBJ_NEW('IDLgrImage', imageData, ORDER = 0)
   XOBJVIEW, oImage, BACKGROUND = [255,255,0]
ENDIF
 
; Use the file access object to query the file.
oMrSID = OBJ_NEW('IDLffMrSID', FILEPATH('test_gs.sid',$
      SUBDIRECTORY=[‘examples’, ‘data’]))
oMrSID->GetProperty, PIXEL_TYPE=pt, $ 
   CHANNELS = chan, DIMENSIONS = dims, $
   TYPE = type, LEVELS = lvls
PRINT, pt, chan, dims, type, lvls
 
; Use the object to read in an image from the file.
lvls = -3
dimsatlvl = oMrSID->GetDimsAtLevel(lvls)
PRINT, dimsatlvl
imageData = oMrSID->GetImageData(LEVEL = 3)
PRINT, size(imageData)
OBJ_DESTROY, oImage

Syntax


Result = READ_MRSID ( Filename [, LEVEL=lvl] [, SUB_RECT=rect] )

Return Value


ImageData returns an n-by-w-by-h array containing the image data where n is 1 for grayscale or 3 for RGB images, w is the width and h is the height.

Note: The returned image is ordered bottom-up, the first pixel returned is located at the bottom-left of the image. This differs from how data is stored in the MrSID file where the image is top-down, meaning the pixel at the start of the file is located at the top-left of the image.

Arguments


Filename

A scalar string containing the full path and filename of the MrSID file to read.

Keywords


LEVEL

Set this keyword to an integer that specifies the level at which to read the image. If this keyword is not set, the maximum level (see QUERY_MRSID) is used which returns the minimum resolution.

SUB_RECT

Set this keyword to a four-element vector [x, y, xdim, ydim] specifying the position of the lower left-hand corner and the dimensions of the sub-rectangle of the MrSID image to return. This is useful for displaying only a portion of the high-resolution image. If this keyword is not set, the entire image will be returned. This may require significant memory if a high-resolution level is selected. If the sub-rectangle is greater than the bounds of the image at the selected level the area outside the image bounds will be set to black.

Note: The elements of SUB_RECT are measured in pixels at the current level. This means the point x = 10, y = 10 at level 1 will be located at x = 20, y = 20 at level 0 and x = 5, y = 5 at level 2.

Version History


5.5

Introduced