1@c Copyright (C) 1996-2019 John W. Eaton 2@c 3@c This file is part of Octave. 4@c 5@c Octave is free software: you can redistribute it and/or modify it 6@c under the terms of the GNU General Public License as published by 7@c the Free Software Foundation, either version 3 of the License, or 8@c (at your option) any later version. 9@c 10@c Octave is distributed in the hope that it will be useful, but 11@c WITHOUT ANY WARRANTY; without even the implied warranty of 12@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13@c GNU General Public License for more details. 14@c 15@c You should have received a copy of the GNU General Public License 16@c along with Octave; see the file COPYING. If not, see 17@c <https://www.gnu.org/licenses/>. 18 19@node Image Processing 20@chapter Image Processing 21 22Since an image is basically a matrix, Octave is a very powerful 23environment for processing and analyzing images. To illustrate 24how easy it is to do image processing in Octave, the following 25example will load an image, smooth it by a 5-by-5 averaging filter, 26and compute the gradient of the smoothed image. 27 28@example 29@group 30I = imread ("myimage.jpg"); 31S = conv2 (I, ones (5, 5) / 25, "same"); 32[Dx, Dy] = gradient (S); 33@end group 34@end example 35 36@noindent 37In this example @code{S} contains the smoothed image, and @code{Dx} 38and @code{Dy} contains the partial spatial derivatives of the image. 39 40@menu 41* Loading and Saving Images:: 42* Displaying Images:: 43* Representing Images:: 44* Plotting on top of Images:: 45* Color Conversion:: 46@end menu 47 48@node Loading and Saving Images 49@section Loading and Saving Images 50 51The first step in most image processing tasks is to load an image 52into Octave which is done with the @code{imread} function. 53The @code{imwrite} function is the corresponding function 54for writing images to the disk. 55 56In summary, most image processing code will follow the structure of this code 57 58@example 59@group 60I = imread ("my_input_image.img"); 61J = process_my_image (I); 62imwrite (J, "my_output_image.img"); 63@end group 64@end example 65 66@DOCSTRING(imread) 67 68@DOCSTRING(imwrite) 69 70@DOCSTRING(IMAGE_PATH) 71 72It is possible to get information about an image file on disk, without actually 73reading it into Octave. This is done using the @code{imfinfo} function which 74provides read access to many of the parameters stored in the header of the 75image file. 76 77@DOCSTRING(imfinfo) 78 79By default, Octave's image IO functions (@code{imread}, @code{imwrite}, 80and @code{imfinfo}) use the @code{GraphicsMagick} library for their 81operations. This means a vast number of image formats is supported 82but considering the large amount of image formats in science and 83its commonly closed nature, it is impossible to have a library 84capable of reading them all. Because of this, the function 85@code{imformats} keeps a configurable list of available formats, 86their extensions, and what functions should the image IO functions 87use. This allows one to expand Octave's image IO capabilities by 88creating functions aimed at acting on specific file formats. 89 90While it would be possible to call the extra functions directly, 91properly configuring Octave with @code{imformats} allows one to keep a 92consistent code that is abstracted from file formats. 93 94It is important to note that a file format is not actually defined by its 95file extension and that @code{GraphicsMagick} is capable to read and write 96more file formats than the ones listed by @code{imformats}. What this 97means is that even with an incorrect or missing extension the image may 98still be read correctly, and that even unlisted formats are not necessarily 99unsupported. 100 101@DOCSTRING(imformats) 102 103@node Displaying Images 104@section Displaying Images 105 106A natural part of image processing is visualization of an image. 107The most basic function for this is the @code{imshow} function that 108shows the image given in the first input argument. 109 110@DOCSTRING(imshow) 111 112@DOCSTRING(image) 113 114@DOCSTRING(imagesc) 115 116@node Representing Images 117@section Representing Images 118 119In general Octave supports four different kinds of images, grayscale 120images, RGB images, binary images, and indexed images. A grayscale 121image is represented with an M-by-N matrix in which each 122element corresponds to the intensity of a pixel. An RGB image is 123represented with an M-by-N-by-3 array where each 1243-vector corresponds to the red, green, and blue intensities of each 125pixel. 126 127The actual meaning of the value of a pixel in a grayscale or RGB 128image depends on the class of the matrix. If the matrix is of class 129@code{double} pixel intensities are between 0 and 1, if it is of class 130@code{uint8} intensities are between 0 and 255, and if it is of class 131@code{uint16} intensities are between 0 and 65535. 132 133A binary image is an M-by-N matrix of class @code{logical}. 134A pixel in a binary image is black if it is @code{false} and white 135if it is @code{true}. 136 137An indexed image consists of an M-by-N matrix of integers 138and a C-by-3 color map. Each integer corresponds to an 139index in the color map, and each row in the color map corresponds to 140an RGB color. The color map must be of class @code{double} with values 141between 0 and 1. 142 143The following convenience functions are available for conversion between image 144formats. 145 146@DOCSTRING(im2double) 147 148@DOCSTRING(gray2ind) 149 150@DOCSTRING(ind2gray) 151 152@DOCSTRING(rgb2ind) 153 154@DOCSTRING(ind2rgb) 155 156Octave also provides tools to produce and work with movie frame structures. 157Those structures encapsulate the image data (@qcode{"cdata"} field) together 158with the corresponding colormap (@qcode{"colormap"} field). 159 160@DOCSTRING(getframe) 161 162@DOCSTRING(movie) 163 164@DOCSTRING(frame2im) 165 166@DOCSTRING(im2frame) 167 168The @code{colormap} function is used to change the colormap of the current 169axes or figure. 170 171@DOCSTRING(colormap) 172 173@DOCSTRING(iscolormap) 174 175The following functions return predefined colormaps, the same that can be 176requested by name using the @code{colormap} function. 177 178@DOCSTRING(rgbplot) 179 180@DOCSTRING(autumn) 181 182@DOCSTRING(bone) 183 184@DOCSTRING(colorcube) 185 186@DOCSTRING(cool) 187 188@DOCSTRING(copper) 189 190@DOCSTRING(cubehelix) 191 192@DOCSTRING(flag) 193 194@DOCSTRING(gray) 195 196@DOCSTRING(hot) 197 198@DOCSTRING(hsv) 199 200@DOCSTRING(jet) 201 202@DOCSTRING(lines) 203 204@DOCSTRING(ocean) 205 206@DOCSTRING(pink) 207 208@DOCSTRING(prism) 209 210@DOCSTRING(rainbow) 211 212@DOCSTRING(spring) 213 214@DOCSTRING(summer) 215 216@DOCSTRING(viridis) 217 218@DOCSTRING(white) 219 220@DOCSTRING(winter) 221 222@DOCSTRING(contrast) 223 224The following three functions modify the existing colormap rather than 225replace it. 226 227@DOCSTRING(brighten) 228 229@DOCSTRING(spinmap) 230 231@DOCSTRING(whitebg) 232 233The following functions can be used to manipulate colormaps. 234 235@DOCSTRING(cmunique) 236 237@DOCSTRING(cmpermute) 238 239@node Plotting on top of Images 240@section Plotting on top of Images 241 242If gnuplot is being used to display images it is possible to plot on 243top of images. Since an image is a matrix it is indexed by row and 244column values. The plotting system is, however, based on the 245traditional @math{(x, y)} system. To minimize the difference between 246the two systems Octave places the origin of the coordinate system in 247the point corresponding to the pixel at @math{(1, 1)}. So, to plot 248points given by row and column values on top of an image, one should 249simply call @code{plot} with the column values as the first argument 250and the row values as the second. As an example the following code 251generates an image with random intensities between 0 and 1, and shows 252the image with red circles over pixels with an intensity above 253@math{0.99}. 254 255@example 256@group 257I = rand (100, 100); 258[row, col] = find (I > 0.99); 259hold ("on"); 260imshow (I); 261plot (col, row, "ro"); 262hold ("off"); 263@end group 264@end example 265 266@node Color Conversion 267@section Color Conversion 268 269Octave supports conversion from the RGB color system to the HSV color system 270and vice versa. It is also possible to convert from a color RGB image to a 271grayscale image. 272 273@DOCSTRING(rgb2hsv) 274 275@DOCSTRING(hsv2rgb) 276 277@DOCSTRING(rgb2gray) 278