Getting Started (Image Processing Toolbox)

Image Processing Toolbox

Example 1 -- Some Basic Topics

Before beginning with this exercise, start MATLAB. If you are new to MATLAB, you should first read the MATLAB Getting Started documentation.

You should already have installed the Image Processing Toolbox, which runs seamlessly from MATLAB. For information about installing the toolbox, see the MATLAB Installation Guide for your platform.

All of the images used in this example are supplied with the Image Processing Toolbox. Note that the images shown in this documentation differ slightly from what you see on your screen because the surrounding MATLAB figure window has been removed to save space.

1. Read and Display an Image

Clear the MATLAB workspace of any variables and close open figure windows.

```
clear, close all
```

To read an image, use the imread command. Let's read in a TIFF image named pout.tif (which is one of the sample images that is supplied with the Image Processing Toolbox), and store it in an array named I.

```
I=imread('pout.tif');
```

Now call imshow to display I.

```
imshow(I)
```

Here's What Just Happened

Step 1. The imread function recognized pout.tif as a valid TIFF file and stored it in the variable I. (For the list of graphics formats supported, see imread in the Image Processing Toolbox online "Function Reference.")
The functions imread and imshow read and display graphics images in MATLAB. In general, it is preferable to use imshow for displaying images because it handles the image-related MATLAB properties for you. (The MATLAB function image is for low-level programming tasks.)
Note that if pout.tif were an indexed image, the appropriate syntax for imread would be,
[X, map] = imread('pout.tif');
(For more information on the supported image types, see Image Types in the Toolbox.)

Here's What Just Happened
Step 1. The `imread` function recognized `pout.tif` as a valid TIFF file and stored it in the variable `I`. (For the list of graphics formats supported, see `imread` in the Image Processing Toolbox online "Function Reference.") The functions `imread` and `imshow` read and display graphics images in MATLAB. In general, it is preferable to use `imshow` for displaying images because it handles the image-related MATLAB properties for you. (The MATLAB function `image` is for low-level programming tasks.) Note that if `pout.tif` were an indexed image, the appropriate syntax for `imread` would be, `[X, map] = imread('pout.tif');` (For more information on the supported image types, see Image Types in the Toolbox.)

2. Check the Image in Memory

Enter the whos command to see how I is stored in memory.

```
whos
```

MATLAB responds with

Name      Size         Bytes  Class

  I       291x240        69840  uint8 array

Grand total is 69840 elements using 69840 bytes

Here's What Just Happened

Step 2. You called the whos command to see how pout.tif had been stored into the MATLAB workspace. As you saw, pout.tif is stored as a 291-by-240 array. Since pout.tif was an 8-bit image, it gets stored in memory as an uint8 array. MATLAB can store images in memory as uint8, uint16, or double arrays. (See Reading a Graphics Image for an explanation of when the different storage classes are used.)

Here's What Just Happened
Step 2. You called the `whos` command to see how `pout.tif` had been stored into the MATLAB workspace. As you saw, `pout.tif` is stored as a 291-by-240 array. Since `pout.tif` was an 8-bit image, it gets stored in memory as an `uint8` array. MATLAB can store images in memory as `uint8`, `uint16`, or `double` arrays. (See Reading a Graphics Image for an explanation of when the different storage classes are used.)

3. Perform Histogram Equalization

As you can see, pout.tif is a somewhat low contrast image. To see the distribution of intensities in pout.tif in its current state, you can create a histogram by calling the imhist function. (Precede the call to imhist with the figure command so that the histogram does not overwrite the display of the image I in the current figure window.)

figure, imhist(I) % Display a histogram of I in a new figure.

Notice how the intensity range is rather narrow. It does not cover the potential range of [0, 255], and is missing the high and low values that would result in good contrast.

Now call histeq to spread the intensity values over the full range, thereby improving the contrast of I. Return the modified image in the variable I2.

I2 = histeq(I);   % Equalize I and output in new array I2.

Display the new equalized image, I2, in a new figure window.

figure, imshow(I2)  % Display the new equalized image I2.

Call imhist again, this time for I2.

figure, imhist(I2) % Show the histogram for the new image I2.

See how the pixel values now extend across the full range of possible values.

Here's What Just Happened

Step 3. You adjusted the contrast automatically by using the function histeq to evenly distribute the image's pixel values over the full potential range for the storage class of the image. For an image X, with a storage class of uint8, the full range is , for uint16 it is , and for double it is . Note that the convention elsewhere in this user guide (and for all MATLAB documentation) is to denote the above ranges as [0,255], [0,65535], and [0,1], respectively.
If you compare the two histograms, you can see that the histogram of I2 is more spread out and flat than the histogram of I1. The process that flattened and spread out this histogram is called histogram equalization.
For more control over adjusting the contrast of an image (for example, if you want to choose the range over which the new pixel values should span), you can use the imadjust function, which is demonstrated under 5. Adjust the Image Contrast in Exercise 2.

Here's What Just Happened
Step 3. You adjusted the contrast automatically by using the function `histeq` to evenly distribute the image's pixel values over the full potential range for the storage class of the image. For an image `X`, with a storage class of `uint8`, the full range is , for `uint16` it is , and for `double` it is . Note that the convention elsewhere in this user guide (and for all MATLAB documentation) is to denote the above ranges as [0,255], [0,65535], and [0,1], respectively. If you compare the two histograms, you can see that the histogram of `I2` is more spread out and flat than the histogram of `I1`. The process that flattened and spread out this histogram is called histogram equalization. For more control over adjusting the contrast of an image (for example, if you want to choose the range over which the new pixel values should span), you can use the `imadjust` function, which is demonstrated under 5. Adjust the Image Contrast in Exercise 2.

4. Write the Image

Write the newly adjusted image I2 back to disk. Let's say you'd like to save it as a PNG file. Use imwrite and specify a filename that includes the extension 'png'.

```
imwrite (I2, 'pout2.png');
```

Here's What Just Happened

Step 4. MATLAB recognized the file extension of 'png' as valid and wrote the image to disk. It wrote it as an 8-bit image by default because it was stored as a uint8 intensity image in memory. If I2 had been an image array of type RGB and class uint8, it would have been written to disk as a 24-bit image. If you want to set the bit depth of your output image, use the BitDepth parameter with imwrite. This example writes a 4-bit PNG file.
imwrite(I2, 'pout2.png', 'BitDepth', 4);
Note that all output formats do not support the same set of output bit depths. See imwrite in the Reference for the list of valid bit depths for each format. See also Writing a Graphics Image for a tutorial discussion on writing images using the Image Processing Toolbox.

Here's What Just Happened
Step 4. MATLAB recognized the file extension of `'png'` as valid and wrote the image to disk. It wrote it as an 8-bit image by default because it was stored as a `uint8` intensity image in memory. If `I2` had been an image array of type RGB and class `uint8`, it would have been written to disk as a 24-bit image. If you want to set the bit depth of your output image, use the `BitDepth` parameter with `imwrite`. This example writes a 4-bit PNG file. `imwrite(I2, 'pout2.png', 'BitDepth', 4);` Note that all output formats do not support the same set of output bit depths. See `imwrite` in the Reference for the list of valid bit depths for each format. See also Writing a Graphics Image for a tutorial discussion on writing images using the Image Processing Toolbox.

5. Check the Contents of the Newly Written File

Now, use the imfinfo function to see what was written to disk. Be sure not to end the line with a semicolon so that MATLAB displays the results. Also, be sure to use the same path (if any) as you did for the call to imwrite, above.

```
imfinfo('pout2.png')
```

MATLAB responds with

```
ans = 
```
Filename:
'pout2.png'

FileModDate:
'03-Jun-1999 15:50:25'

FileSize:
36938

Format:
'png'

FormatVersion:
[]

Width:
240

Height:
291

BitDepth:
8

ColorType:
'grayscale'
```
 


 

                  . . .
```

`Filename:`	`'pout2.png'`
`FileModDate:`	`'03-Jun-1999 15:50:25'`
`FileSize:`	`36938`
`Format:`	`'png'`
`FormatVersion:`	`[]`
`Width:`	`240`
`Height:`	`291`
`BitDepth:`	`8`
`ColorType:`	`'grayscale'`

Note This example shows only a subset of all the fields returned by imfinfo. Also, the value in the FileModDate field for your file will be different from what is shown above. It will show the date and time that you used imwrite to create your image.

Here's What Just Happened

Step 5. When you called imfinfo, MATLAB displayed all of the header fields for the PNG file format that are supported by the toolbox. You can modify many of these fields by using additional parameters in your call to imwrite. The additional parameters that are available for each file format are listed in tables in the reference entry for imwrite. (See Querying a Graphics File for more information about using imfinfo.)

Here's What Just Happened
Step 5. When you called `imfinfo`, MATLAB displayed all of the header fields for the PNG file format that are supported by the toolbox. You can modify many of these fields by using additional parameters in your call to `imwrite`. The additional parameters that are available for each file format are listed in tables in the reference entry for `imwrite`. (See Querying a Graphics File for more information about using `imfinfo`.)

Getting Started Example 2 -- Advanced Topics