Read bitmap data

MuPAD® notebooks will be removed in a future release. Use MATLAB® live scripts instead.

MATLAB live scripts support most MuPAD functionality, though there are some differences. For more information, see Convert MuPAD Notebooks to MATLAB Live Scripts.


import::readbitmap(filename, <ReturnType = DOM_HFARRAY | DOM_ARRAY | DOM_LIST>)


import::readbitmap is used for reading ASCII or binary data files storing bitmap images of pictures. The following standard graphical formats can be read: BMP, DCX, DDS, WAD, GIF, ICO, JPG, LIF, MDL, PCD, PCX, PIC, PIX, PNG, PNM, PSD, PSP, PXR, RAW, SGI, TGA, TIF, WAL, XPM. The format of the pixel data is determined automatically from the contents of the file. The return value [w, h, colordata] provides the pixel height h, the pixel width w, and the color data of the bitmap image.

Either the complete return value or just the third element, colordata, can be passed to the function plot::Raster to generate a plot object that can be used in a MuPAD® graphics. E.g., the command


creates a MuPAD graphics of the bitmap stored in the JPG file “mypicture.jpeg”.


Most of the standard graphical formats store the pixel data row by row in the usual reading order starting with the upper left corner of the image. The pixel data in the returned array colordata (if requesting ReturnType = DOM_ARRAY), however, are to be interpreted as follows:

colordata[1, 1] is the RGB color of the lower left corner.

colordata[h, 1] is the RGB color of the upper left corner.

colordata[1, w] is the RGB color of the lower right corner.

colordata[h, w] is the RGB color of the upper right corner.

The interpretation of the other return types is analogous, see below for details on the return types.

This is consistent with the interpretation of a color array by plot::Raster.

import::readbitmap(filename) searches for the file in various directories:

  • First, the name is interpreted as a relative file name: filename is concatenated to each directory given by the environment variable READPATH.

  • Then the file name is interpreted as an absolute path name.

  • Then the file name is interpreted relative to the “working directory.”

  • Last, the file name is concatenated to the directory path.

If a file can be opened with one of this names, then the file is read.

Note that the meaning of “working directory” depends on the operating system. On Microsoft® Windows® systems and on Apple Mac OS X systems, the “working directory” is the folder where MuPAD is installed. On UNIX® systems, it is the current working directory in which MuPAD was started; when started from a menu or desktop item, this is typically the user's home directory.

A path separator (“/”) is inserted as necessary when concatenating a given path and filename.

import::readbitmap does not accept file handles returned by fopen. Nor can it handle files which have been compressed by gzip, but since most bitmap formats employ high quality compression in any case, there is little reason to try compressing them again in any case.


Example 1

We import a PGM (portable graymap) picture:

[w, h, Norton] := import::readbitmap("Norton.pgm"):

The bitmap image is to be embedded in a MuPAD graphics. We use the width w and the height h to place the bitmap in a rectangle whose sides have the same ratio as the original bitmap. With Scaling = Constrained we make sure that this aspect ratio is also used in the final graphics:

xmin := 2: xmax := xmin + w/100:
ymin := 0.5: ymax := ymin + h/100:
plot(plot::Function2d(x*sin(PI/x), x = -1..4.5, AdaptiveMesh = 2),
     plot::Raster(Norton, x = xmin ..xmax, y = ymin .. ymax),
     Scaling = Constrained, Footer = "Work And Play"):



The file name: a non-empty character string



Option, specified as ReturnType = DOM_HFARRAY | DOM_ARRAY | DOM_LIST

Set the type of the actual color data returned as colordata.

If set to DOM_LIST, colordata is a nested list, the outermost list containing h lists, each of which represents one row of image data and contains w lists of three floating-point numbers, each of which represents an RGB Colors color.

If set to DOM_ARRAY, colordata is an array containing lists with color information, as in array(2, 1..h, 1..w, [color1, color2, …] ). The interpretation is analogous to the nested lists described above.

If set to DOM_HFARRAY, which is the default setting, colordata is a DOM_HFARRAY of dimensions hfarray(3, 1..h, 1..w, 1..3, [actual data]). The interpretation of these floating-point values is as described above for the DOM_LIST case.

Return Values

list[w, h, colordata]. The integer w is the pixel width of the bitmap. The integer h is the pixel height of the bitmap. colordata provides the RGB colors of the bitmap. Its type depends on the setting of the option ReturnType.

See Also

MuPAD Functions

MuPAD Graphical Primitives