Image Processing Toolbox™ Reference R2012b How to Contact MathWorks Web Newsgroup www.mathworks.com/contact_TS.html Technical Support www.mathworks.com comp.soft-sys.matlab [email protected] [email protected] [email protected] [email protected] [email protected] Product enhancement suggestions Bug reports Documentation error reports Order status, license renewals, passcodes Sales, pricing, and general information 508-647-7000 (Phone) 508-647-7001 (Fax) The MathWorks, Inc. 3 Apple Hill Drive Natick, MA 01760-2098 For contact information about worldwide offices, see the MathWorks Web site. Image Processing Toolbox™ Reference © COPYRIGHT 1993–2012 by The MathWorks, Inc. The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form without prior written consent from The MathWorks, Inc. FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through the federal government of the United States. By accepting delivery of the Program or Documentation, the government hereby agrees that this software or documentation qualifies as commercial computer software or commercial computer software documentation as such terms are used or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern the use, modification, reproduction, release, performance, display, and disclosure of the Program and Documentation by the federal government (or other entity acquiring for or through the federal government) and shall supersede any conflicting contractual terms or conditions. If this License fails to meet the government’s needs or is inconsistent in any respect with federal procurement law, the government agrees to return the Program and Documentation, unused, to The MathWorks, Inc. Trademarks MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand names may be trademarks or registered trademarks of their respective holders. Patents MathWorks products are protected by one or more U.S. patents. Please see www.mathworks.com/patents for more information. Revision History August 1993 May 1997 April 2001 June 2001 July 2002 May 2003 September 2003 June 2004 August 2004 October 2004 March 2005 September 2005 March 2006 September 2006 March 2007 September 2007 March 2008 October 2008 March 2009 September 2009 March 2010 September 2010 April 2011 September 2011 March 2012 September 2012 First printing Second printing Third printing Online only Online only Fourth printing Online only Online only Online only Fifth printing Online only Online only Online only Online only Online only Online only Online only Online only Online only Online only Online only Online only Online only Online only Online only Online only Version 1 Version 2 Revised for Version 3.0 Revised for Version 3.1 (Release 12.1) Revised for Version 3.2 (Release 13) Revised for Version 4.0 (Release 13.0.1) Revised for Version 4.1 (Release 13.SP1) Revised for Version 4.2 (Release 14) Revised for Version 5.0 (Release 14+) Revised for Version 5.0.1 (Release 14SP1) Revised for Version 5.0.2 (Release 14SP2) Revised for Version 5.1 (Release 14SP3) Revised for Version 5.2 (Release 2006a) Revised for Version 5.3 (Release 2006b) Revised for Version 5.4 (Release 2007a) Revised for Version 6.0 (Release 2007b) Revised for Version 6.1 (Release 2008a) Revised for Version 6.2 (Release 2008b) Revised for Version 6.3 (Release 2009a) Revised for Version 6.4 (Release 2009b) Revised for Version 7.0 (Release 2010a) Revised for Version 7.1 (Release 2010b) Revised for Version 7.2 (Release 2011a) Revised for Version 7.3 (Release 2011b) Revised for Version 8.0 (Release 2012a) Revised for Version 8.1 (Release 2012b) Contents Function Reference 1 Image Display and Exploration . . . . . . . . . . . . . . . . . . . . . Image Display and Exploration . . . . . . . . . . . . . . . . . . . . . . Image File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Image Types and Type Conversions . . . . . . . . . . . . . . . . . . . 1-2 1-2 1-2 1-3 GUI Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Modular Interactive Tools . . . . . . . . . . . . . . . . . . . . . . . . . . Navigational Tools for Image Scroll Panel . . . . . . . . . . . . . Utilities for Interactive Tools . . . . . . . . . . . . . . . . . . . . . . . . 1-5 1-5 1-5 1-6 Spatial Transformation and Image Registration . . . . . . Spatial Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . Image Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-8 1-8 1-9 Image Analysis and Statistics . . . . . . . . . . . . . . . . . . . . . . . Image Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Texture Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Pixel Values and Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10 1-10 1-11 1-11 Image Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-12 Image Enhancement and Restoration . . . . . . . . . . . . . . . Image Enhancement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Image Restoration (Deblurring) . . . . . . . . . . . . . . . . . . . . . . 1-13 1-13 1-13 Linear Filtering and Transforms . . . . . . . . . . . . . . . . . . . . Linear Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Linear 2-D Filter Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . Image Transforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-15 1-15 1-15 1-15 Morphological Operations . . . . . . . . . . . . . . . . . . . . . . . . . . Intensity and Binary Images . . . . . . . . . . . . . . . . . . . . . . . . Binary Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-17 1-17 1-18 v Structuring Element Creation and Manipulation . . . . . . . . 1-19 ROI-Based, Neighborhood, and Block Processing . . . . . ROI-Based Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Neighborhood and Block Processing . . . . . . . . . . . . . . . . . . 1-20 1-20 1-20 Colormaps and Color Space . . . . . . . . . . . . . . . . . . . . . . . . Color Space Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-22 1-22 Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mouse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Array Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-24 1-24 1-24 1-25 1-25 1-25 1-25 Class Reference 2 vi Contents Image Input and Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . ImageAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 2-2 Image Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . registration.metric.MattesMutualInformation . . . . . . . . . . registration.metric.MeanSquares, . . . . . . . . . . . . . . . . . . . . registration.optimizer.RegularStepGradientDescent . . . . . registration.optimizer.OnePlusOneEvolutionary . . . . . . . . 2-3 2-3 2-3 2-3 2-3 Functions — Alphabetical List 3 Index vii viii Contents 1 Function Reference Image Display and Exploration (p. 1-2) Display, import, and export images GUI Tools (p. 1-5) Modular interactive tools and associated utility functions. Spatial Transformation and Image Registration (p. 1-8) Spatial transformation and image registration Image Analysis and Statistics (p. 1-10) Image analysis, texture analysis, view pixel values, and calculate image statistics Image Arithmetic (p. 1-12) Add, subtract, multiply, and divide images Image Enhancement and Restoration (p. 1-13) Enhance and restore images Linear Filtering and Transforms (p. 1-15) Linear filters, filter design, and image transforms Morphological Operations (p. 1-17) Morphological image processing ROI-Based, Neighborhood, and Block Processing (p. 1-20) ROI-based, neighborhood, and block operations Colormaps and Color Space (p. 1-22) Manipulate image color Utilities (p. 1-24) Array operations, examples, preferences and other toolbox utility functions 1 Function Reference Image Display and Exploration Image Display and Exploration (p. 1-2) Display and explore images Image File I/O (p. 1-2) Import and export images Image Types and Type Conversions (p. 1-3) Convert between the various image types Image Display and Exploration immovie Make movie from multiframe image implay Play movies, videos, or image sequences imshow Display image imtool Image Tool montage Display multiple image frames as rectangular montage subimage Display multiple images in single figure warp Display image as texture-mapped surface Image File I/O 1-2 analyze75info Read metadata from header file of Analyze 7.5 data set analyze75read Read image data from image file of Analyze 7.5 data set dicomanon Anonymize DICOM file dicomdict Get or set active DICOM data dictionary Image Display and Exploration dicominfo Read metadata from DICOM message dicomlookup Find attribute in DICOM data dictionary dicomread Read DICOM image dicomuid Generate DICOM unique identifier dicomwrite Write images as DICOM files hdrread Read high dynamic range (HDR) image hdrwrite Write Radiance high dynamic range (HDR) image file interfileinfo Read metadata from Interfile file interfileread Read images in Interfile format isrset Check if file is R-Set makehdr Create high dynamic range image nitfinfo Read metadata from National Imagery Transmission Format (NITF) file nitfread Read image from NITF file openrset Open R-Set file rsetwrite Create reduced resolution data set from image file tonemap Render high dynamic range image for viewing Image Types and Type Conversions demosaic Convert Bayer pattern encoded image to truecolor image gray2ind Convert grayscale or binary image to indexed image 1-3 1 1-4 Function Reference grayslice Convert grayscale image to indexed image using multilevel thresholding graythresh Global image threshold using Otsu’s method im2bw Convert image to binary image, based on threshold im2double Convert image to double precision im2int16 Convert image to 16-bit signed integers im2java2d Convert image to Java buffered image im2single Convert image to single precision im2uint16 Convert image to 16-bit unsigned integers im2uint8 Convert image to 8-bit unsigned integers ind2gray Convert indexed image to grayscale image ind2rgb Convert indexed image to RGB image label2rgb Convert label matrix into RGB image mat2gray Convert matrix to grayscale image rgb2gray Convert RGB image or colormap to grayscale GUI Tools GUI Tools Modular Interactive Tools (p. 1-5) Modular interactive tool creation functions Navigational Tools for Image Scroll Panel (p. 1-5) Modular interactive navigational tools Utilities for Interactive Tools (p. 1-6) Modular interactive tool utility functions Modular Interactive Tools imageinfo Image Information tool imcontrast Adjust Contrast tool imdisplayrange Display Range tool imdistline Distance tool impixelinfo Pixel Information tool impixelinfoval Pixel Information tool without text label impixelregion Pixel Region tool impixelregionpanel Pixel Region tool panel Navigational Tools for Image Scroll Panel immagbox Magnification box for scroll panel imoverview Overview tool for image displayed in scroll panel imoverviewpanel Overview tool panel for image displayed in scroll panel imscrollpanel Scroll panel for interactive image navigation 1-5 1 Function Reference Utilities for Interactive Tools 1-6 axes2pix Convert axes coordinates to pixel coordinates getimage Image data from axes getimagemodel Image model object from image object imattributes Information about image attributes imellipse Create draggable ellipse imfreehand Create draggable freehand region imgca Get handle to current axes containing image imgcf Get handle to current figure containing image imgetfile Open Image dialog box imhandles Get all image handles imline Create draggable, resizable line impoint Create draggable point impoly Create draggable, resizable polygon imrect Create draggable rectangle imroi Region-of-interest (ROI) base class iptaddcallback Add function handle to callback list iptcheckhandle Check validity of handle iptgetapi Get Application Programmer Interface (API) for handle iptGetPointerBehavior Retrieve pointer behavior from HG object ipticondir Directories containing IPT and MATLAB® icons iptPointerManager Create pointer manager in figure GUI Tools iptremovecallback Delete function handle from callback list iptSetPointerBehavior Store pointer behavior structure in Handle Graphics object iptwindowalign Align figure windows makeConstrainToRectFcn Create rectangularly bounded drag constraint function truesize Adjust display size of image 1-7 1 Function Reference Spatial Transformation and Image Registration Spatial Transformations (p. 1-8) Spatial transformation of images and multidimensional arrays Image Registration (p. 1-9) Align two images using control points Spatial Transformations 1-8 checkerboard Create checkerboard image findbounds Find output bounds for spatial transformation fliptform Flip input and output roles of TFORM structure imcrop Crop image impyramid Image pyramid reduction and expansion imresize Resize image imrotate Rotate image imtransform Apply 2-D spatial transformation to image makeresampler Create resampling structure maketform Create spatial transformation structure (TFORM) tformarray Apply spatial transformation to N-D array tformfwd Apply forward spatial transformation tforminv Apply inverse spatial transformation Spatial Transformation and Image Registration Image Registration cp2tform Infer spatial transformation from control point pairs cpcorr Tune control-point locations using cross correlation cpselect Control Point Selection Tool cpstruct2pairs Convert CPSTRUCT to valid pairs of control points imfuse Composite of two images imregconfig Configurations for intensity-based registration imregister Intensity-based image registration imshowpair Compare differences between images normxcorr2 Normalized 2-D cross-correlation registration.metric.MattesMutualInformation Mattes mutual information metric configuration object registration.metric.MeanSquares Mean square error metric configuration object registration.optimizer.OnePlusOneEvolutionary One-plus-one evolutionary optimizer configuration object Regular step gradient descent registration.optimizer.RegularStepGradientDescent optimizer configuration object 1-9 1 Function Reference Image Analysis and Statistics Image Analysis (p. 1-10) Trace boundaries, detect edges, and perform quadtree decomposition Texture Analysis (p. 1-11) Entropy, range, and standard deviation filtering; gray-level co-occurrence matrix Pixel Values and Statistics (p. 1-11) Create histograms, contour plots, and get statistics on image regions Image Analysis 1-10 bwboundaries Trace region boundaries in binary image bwtraceboundary Trace object in binary image corner Find corner points in image cornermetric Create corner metric matrix from image edge Find edges in grayscale image hough Hough transform houghlines Extract line segments based on Hough transform houghpeaks Identify peaks in Hough transform imfindcircles Find circles using circular Hough transform qtdecomp Quadtree decomposition qtgetblk Block values in quadtree decomposition qtsetblk Set block values in quadtree decomposition viscircles Create circle Image Analysis and Statistics Texture Analysis entropy Entropy of grayscale image entropyfilt Local entropy of grayscale image graycomatrix Create gray-level co-occurrence matrix from image graycoprops Properties of gray-level co-occurrence matrix rangefilt Local range of image stdfilt Local standard deviation of image Pixel Values and Statistics corr2 2-D correlation coefficient imcontour Create contour plot of image data imhist Display histogram of image data imhistmatch Adjust histogram of image to match N-bin histogram of reference image impixel Pixel color values improfile Pixel-value cross-sections along line segments mean2 Average or mean of matrix elements regionprops Measure properties of image regions std2 Standard deviation of matrix elements 1-11 1 Function Reference Image Arithmetic 1-12 imabsdiff Absolute difference of two images imadd Add two images or add constant to image imapplymatrix Linear combination of color channels imcomplement Complement image imdivide Divide one image into another or divide image by constant imlincomb Linear combination of images immultiply Multiply two images or multiply image by constant imsubtract Subtract one image from another or subtract constant from image Image Enhancement and Restoration Image Enhancement and Restoration Image Enhancement (p. 1-13) Histogram equalization, decorrelation stretching, and 2-D filtering Image Restoration (Deblurring) (p. 1-13) Deconvolution for deblurring Image Enhancement adapthisteq Contrast-limited adaptive histogram equalization (CLAHE) decorrstretch Apply decorrelation stretch to multichannel image histeq Enhance contrast using histogram equalization imadjust Adjust image intensity values or colormap imnoise Add noise to image intlut Convert integer values using lookup table medfilt2 2-D median filtering ordfilt2 2-D order-statistic filtering stretchlim Find limits to contrast stretch image wiener2 2-D adaptive noise-removal filtering Image Restoration (Deblurring) deconvblind Deblur image using blind deconvolution deconvlucy Deblur image using Lucy-Richardson method 1-13 1 1-14 Function Reference deconvreg Deblur image using regularized filter deconvwnr Deblur image using Wiener filter edgetaper Taper discontinuities along image edges otf2psf Convert optical transfer function to point-spread function psf2otf Convert point-spread function to optical transfer function Linear Filtering and Transforms Linear Filtering and Transforms Linear Filtering (p. 1-15) Convolution, N-D filtering, and predefined 2-D filters Linear 2-D Filter Design (p. 1-15) 2-D FIR filters Image Transforms (p. 1-15) Fourier, Discrete Cosine, Radon, and Fan-beam transforms Linear Filtering convmtx2 2-D convolution matrix fspecial Create predefined 2-D filter imfilter N-D filtering of multidimensional images Linear 2-D Filter Design freqz2 2-D frequency response fsamp2 2-D FIR filter using frequency sampling ftrans2 2-D FIR filter using frequency transformation fwind1 2-D FIR filter using 1-D window method fwind2 2-D FIR filter using 2-D window method Image Transforms dct2 2-D discrete cosine transform dctmtx Discrete cosine transform matrix 1-15 1 1-16 Function Reference fan2para Convert fan-beam projections to parallel-beam fanbeam Fan-beam transform idct2 2-D inverse discrete cosine transform ifanbeam Inverse fan-beam transform iradon Inverse Radon transform para2fan Convert parallel-beam projections to fan-beam phantom Create head phantom image radon Radon transform Morphological Operations Morphological Operations Intensity and Binary Images (p. 1-17) Dilate, erode, reconstruct, and perform other morphological operations Binary Images (p. 1-18) Label, pack, and perform morphological operations on binary images Structuring Element Creation and Manipulation (p. 1-19) Create and manipulate structuring elements for morphological operations Intensity and Binary Images conndef Create connectivity array imbothat Bottom-hat filtering imclearborder Suppress light structures connected to image border imclose Morphologically close image imdilate Dilate image imerode Erode image imextendedmax Extended-maxima transform imextendedmin Extended-minima transform imfill Fill image regions and holes imhmax H-maxima transform imhmin H-minima transform imimposemin Impose minima imopen Morphologically open image imreconstruct Morphological reconstruction imregionalmax Regional maxima 1-17 1 Function Reference imregionalmin Regional minima imtophat Top-hat filtering watershed Watershed transform Binary Images 1-18 applylut Neighborhood operations on binary images using lookup tables bwarea Area of objects in binary image bwareaopen Remove small objects from binary image bwconncomp Find connected components in binary image bwconvhull Generate convex hull image from binary image bwdist Distance transform of binary image bwdistgeodesic Geodesic distance transform of binary image bweuler Euler number of binary image bwhitmiss Binary hit-miss operation bwlabel Label connected components in 2-D binary image bwlabeln Label connected components in binary image bwmorph Morphological operations on binary images bwpack Pack binary image bwperim Find perimeter of objects in binary image bwselect Select objects in binary image Morphological Operations bwulterode Ultimate erosion bwunpack Unpack binary image graydist Gray-weighted distance transform of grayscale image imtophat Top-hat filtering makelut Create lookup table for use with bwlookup Structuring Element Creation and Manipulation getheight Height of structuring element getneighbors Structuring element neighbor locations and heights getnhood Structuring element neighborhood getsequence Sequence of decomposed structuring elements isflat True for flat structuring element reflect Reflect structuring element strel Create morphological structuring element (STREL) translate Translate structuring element (STREL) 1-19 1 Function Reference ROI-Based, Neighborhood, and Block Processing ROI-Based Processing (p. 1-20) Define regions of interest (ROI) and perform operations on them Neighborhood and Block Processing (p. 1-20) Define neighborhoods and blocks and process them ROI-Based Processing poly2mask Convert region of interest (ROI) polygon to region mask roicolor Select region of interest (ROI) based on color roifill Fill in specified region of interest (ROI) polygon in grayscale image roifilt2 Filter region of interest (ROI) in image roipoly Specify polygonal region of interest (ROI) Neighborhood and Block Processing 1-20 bestblk Determine optimal block size for block processing blockproc Distinct block processing for image close (ImageAdapter) Close ImageAdapter object col2im Rearrange matrix columns into blocks colfilt Columnwise neighborhood operations im2col Rearrange image blocks into columns ImageAdapter Interface for image I/O ROI-Based, Neighborhood, and Block Processing nlfilter General sliding-neighborhood operations readRegion (ImageAdapter) Read region of image writeRegion (ImageAdapter) Write block of data to region of image 1-21 1 Function Reference Colormaps and Color Space Color Space Conversions (p. 1-22) ICC profile-based device independent color space conversions and device-dependent color space conversions Color Space Conversions 1-22 applycform Apply device-independent color space transformation iccfind Search for ICC profiles iccread Read ICC profile iccroot Find system default ICC profile repository iccwrite Write ICC color profile to disk file isicc True for valid ICC color profile lab2double Convert L*a*b* data to double lab2uint16 Convert L*a*b* data to uint16 lab2uint8 Convert L*a*b* data to uint8 makecform Create color transformation structure ntsc2rgb Convert NTSC values to RGB color space rgb2ntsc Convert RGB color values to NTSC color space rgb2ycbcr Convert RGB color values to YCbCr color space whitepoint XYZ color values of standard illuminants xyz2double Convert XYZ color values to double Colormaps and Color Space xyz2uint16 Convert XYZ color values to uint16 ycbcr2rgb Convert YCbCr color values to RGB color space 1-23 1 Function Reference Utilities Preferences (p. 1-24) Set and determine value of toolbox preferences Validation (p. 1-24) Check input arguments and perform other common programming tasks Mouse (p. 1-25) Retrieve values of lines, points, and rectangles defined interactively using mouse Array Operations (p. 1-25) Circularly shift pixel values and pad arrays Examples (p. 1-25) Launch Image Processing Toolbox™ examples Performance (p. 1-25) Check for presence of Intel® Integrated Performance Primitives (Intel IPP) library Preferences iptgetpref Get values of Image Processing Toolbox preferences iptprefs Display Image Processing Preferences dialog box iptsetpref Set Image Processing Toolbox preferences or display valid values Validation 1-24 getrangefromclass Default display range of image based on its class iptcheckconn Check validity of connectivity argument iptcheckinput Check validity of array Utilities iptcheckmap Check validity of colormap iptchecknargin Check number of input arguments iptcheckstrs Check validity of option string iptnum2ordinal Convert positive integer to ordinal string Mouse getline Select polyline with mouse getpts Specify points with mouse getrect Specify rectangle with mouse Array Operations padarray Pad array Examples iptdemos Index of Image Processing Toolbox examples Performance ippl Check for presence of Intel Integrated Performance Primitives (Intel IPP) library 1-25 1 1-26 Function Reference 2 Class Reference • “Image Input and Output” on page 2-2 • “Image Registration” on page 2-3 2 Class Reference Image Input and Output ImageAdapter 2-2 close Close ImageAdapter object ImageAdapter Interface for image I/O readRegion Read region of image writeRegion Write block of data to region of image Image Registration Image Registration registration.metric.MattesMutualInformation registration.metric.MattesMutualInformation Mattes mutual information metric configuration object registration.metric.MeanSquares, registration.metric.MeanSquares Mean square error metric configuration object registration.optimizer.RegularStepGradientDescent Regular step gradient descent registration.optimizer.RegularStepGradientDescent optimizer configuration object registration.optimizer.OnePlusOneEvolutionary registration.optimizer.OnePlusOneEvolutionary One-plus-one evolutionary optimizer configuration object 2-3 2 2-4 Class Reference 3 Functions — Alphabetical List adapthisteq Purpose Contrast-limited adaptive histogram equalization (CLAHE) Syntax J = adapthisteq(I) J = adapthisteq(I,param1,val1,param2,val2...) Description J = adapthisteq(I) enhances the contrast of the grayscale image I by transforming the values using contrast-limited adaptive histogram equalization (CLAHE). CLAHE operates on small regions in the image, called tiles, rather than the entire image. Each tile’s contrast is enhanced, so that the histogram of the output region approximately matches the histogram specified by the 'Distribution' parameter. The neighboring tiles are then combined using bilinear interpolation to eliminate artificially induced boundaries. The contrast, especially in homogeneous areas, can be limited to avoid amplifying any noise that might be present in the image. J = adapthisteq(I,param1,val1,param2,val2...) specifies any of the additional parameter/value pairs listed in the following table. Parameter names can be abbreviated, and case does not matter. Parameter Value 'NumTiles' Two-element vector of positive integers specifying the number of tiles by row and column, [M N]. Both M and N must be at least 2. The total number of tiles is equal to M*N. Default: [8 8] 'ClipLimit' Real scalar in the range [0 1] that specifies a contrast enhancement limit. Higher numbers result in more contrast. Default: 0.01 3-2 adapthisteq Parameter Value 'NBins' Positive integer scalar specifying the number of bins for the histogram used in building a contrast enhancing transformation. Higher values result in greater dynamic range at the cost of slower processing speed. Default: 256 'Range' String specifying the range of the output image data. 'original' — Range is limited to the range of the original image, [min(I(:)) max(I(:))]. 'full' — Full range of the output image class is used. For example, for uint8 data, range is [0 255]. Default: 'full' 'Distribution' String specifying the desired histogram shape for the image tiles. 'uniform' — Flat histogram 'rayleigh' — Bell-shaped histogram 'exponential' — Curved histogram Default: 'uniform' 'Alpha' Nonnegative real scalar specifying a distribution parameter. Default: 0.4 Note Only used when 'Distribution' is set to either 'rayleigh' or 'exponential'. 3-3 adapthisteq Tips • 'NumTiles' specifies the number of rectangular contextual regions (tiles) into which adapthisteq divides the image. adapthisteq calculates the contrast transform function for each of these regions individually. The optimal number of tiles depends on the type of the input image, and it is best determined through experimentation. • 'ClipLimit' is a contrast factor that prevents over-saturation of the image specifically in homogeneous areas. These areas are characterized by a high peak in the histogram of the particular image tile due to many pixels falling inside the same gray level range. Without the clip limit, the adaptive histogram equalization technique could produce results that, in some cases, are worse than the original image. • 'Distribution' specifies the distribution that adapthisteq uses as the basis for creating the contrast transform function. The distribution you select should depend on the type of the input image. For example, underwater imagery appears to look more natural when the Rayleigh distribution is used. Class Support Grayscale image I can be of class uint8, uint16, int16, single, or double. The output image J has the same class as I. Examples Apply Contrast-limited Adaptive Histogram Equalization (CLAHE) to an image and display the results. I = imread('tire.tif'); A = adapthisteq(I,'clipLimit',0.02,'Distribution','rayleigh'); figure, imshow(I); figure, imshow(A); Apply CLAHE to a color image. [X MAP] = imread('shadow.tif'); % Convert indexed image to true-color (RGB) format RGB = ind2rgb(X,MAP); 3-4 adapthisteq % Convert image to L*a*b* color space cform2lab = makecform('srgb2lab'); LAB = applycform(RGB, cform2lab); % Scale values to range from 0 to 1 L = LAB(:,:,1)/100; % Perform CLAHE LAB(:,:,1) = adapthisteq(L,'NumTiles',... [8 8],'ClipLimit',0.005)*100; % Convert back to RGB color space cform2srgb = makecform('lab2srgb'); J = applycform(LAB, cform2srgb); % Display the results figure, imshow(RGB); figure, imshow(J); References [1] Zuiderveld, Karel. “Contrast Limited Adaptive Histograph Equalization.” Graphic Gems IV. San Diego: Academic Press Professional, 1994. 474–485. See Also histeq 3-5 analyze75info Purpose Read metadata from header file of Analyze 7.5 data set Syntax info = analyze75info(filename) info = analyze75info(filename,'ByteOrder', endian) Description info = analyze75info(filename) reads the header file of the Analyze 7.5 data set specified by the string filename. The function returns info, a structure whose fields contain information about the data set. Analyze 7.5 is a 3-D biomedical image visualization and analysis product developed by the Biomedical Imaging Resource of the Mayo Clinic. An Analyze 7.5 data set is made of two files, a header file and an image file. The files have the same name with different file extensions. The header file has the file extension .hdr and the image file has the file extension .img. info = analyze75info(filename,'ByteOrder', endian) reads the Analyze 7.5 header file using the byte ordering specified by endian, where endian can have either of the following values: Value Meaning 'ieee-le' Byte ordering is Little Endian 'ieee-be' Byte ordering is Big Endian If the specified endian value results in a read error, analyze75info issues a warning message and attempts to read the header file with the opposite ByteOrder format. Examples Read an Analyze 7.5 header file. info = analyze75info('brainMRI.hdr'); Specify the byte ordering of the data set. info = analyze75info('brainMRI', 'ByteOrder', 'ieee-le'); See Also 3-6 analyze75read analyze75read Purpose Read image data from image file of Analyze 7.5 data set Syntax X = analyze75read(filename) X = analyze75read(info) Description X = analyze75read(filename) reads the image data from the image file of an Analyze 7.5 format data set specified by the string filename. The function returns the image data in X. For single-frame, grayscale images, X is an m-by-n array. analyze75read uses a data type for X that is consistent with the data type specified in the data set header file. Analyze 7.5 is a 3-D biomedical image visualization and analysis product developed by the Biomedical Imaging Resource of the Mayo Clinic. An Analyze 7.5 data set is made of two files, a header file and an image file. The files have the same name with different file extensions. The header file has the file extension .hdr and the image file has the file extension .img. X = analyze75read(info) reads the image data from the image file specified in the metadata structure info. info must be a valid metadata structure returned by the analyze75info function. Note analyze75read returns image data in radiological orientation (LAS). This is the default used by the Analyze 7.5 format. Examples Example 1 Read image data from an Analyze 7.5 image file. X = analyze75read('brainMRI'); Because Analyze 7.5 format uses radiological orientation (LAS), flip the data for correct image display in MATLAB. X = flipdim(X,1); Select frames 12 to 17 and use reshape to create an array for montage. 3-7 analyze75read Y = reshape(X(:,:,12:17),[size(X,1) size(X,2) 1 6]); montage(Y); Example 2 Call analyze75read with the metadata obtained from the header file using analyze75info. info = analyze75info('brainMRI.hdr'); X = analyze75read(info); 3-8 Class Support X can be logical, uint8, int16, int32, single, or double. Complex See Also analyze75info and RGB data types are not supported. applycform Purpose Apply device-independent color space transformation Syntax B = applycform(A,C) Description B = applycform(A,C) converts the color values in A to the color space specified in the color transformation structure C. The color transformation structure specifies various parameters of the transformation. See makecform for details. If A is two-dimensional, each row is interpreted as a color unless the color transformation structure contains a grayscale ICC profile. (See Note for this case.) A can have 1 or more columns, depending on the input color space. B has the same number of rows and 1 or more columns, depending on the output color space. (The ICC spec currently supports up to 15-channel device spaces.) If A is three-dimensional, each row-column location is interpreted as a color, and size(A,3) is typically 1 or more, depending on the input color space. B has the same number of rows and columns as A, and size(B,3) is 1 or more, depending on the output color space. Class Support A is a real, nonsparse array of class uint8, uint16, or double or a string. A is only a string if C was created with the following syntax: C = makecform('named', profile, space) The output array B has the same class as A, unless the output space is XYZ. If the input is XYZ data of class uint8, the output is of class uint16, because there is no standard 8-bit encoding defined for XYZ color values. Note If the color transformation structure C contains a grayscale ICC profile, applycform interprets each pixel in A as a color. A can have any number of columns. B has the same size as A. 3-9 applycform Examples Read in a color image that uses the sRGB color space. rgb = imread('peppers.png'); Create a color transformation structure that defines an sRGB to L*a*b* conversion. C = makecform('srgb2lab'); Perform the transformation with applycform. lab = applycform(rgb,C); 3-10 See Also lab2double | lab2uint8 | lab2uint16 | makecform | whitepoint | xyz2double | xyz2uint16 How To • “Converting Color Data Between Color Spaces” applylut Purpose Neighborhood operations on binary images using lookup tables Syntax A = applylut(BW,LUT) Description A = applylut(BW,LUT) performs a 2-by-2 or 3-by-3 neighborhood operation on binary image BW by using a lookup table (LUT). LUT is either a 16-element or 512-element vector returned by makelut. The vector consists of the output values for all possible 2-by-2 or 3-by-3 neighborhoods. Class Support BW can be numeric or logical, and it must be real, two-dimensional, and nonsparse. LUT can be numeric or logical, and it must be a real vector with 16 or 512 elements. If all the elements of LUT are 0 or 1, then A is logical. If all the elements of LUT are integers between 0 and 255, then A is uint8. For all other cases, A is double. Algorithms applylut performs a neighborhood operation on a binary image by producing a matrix of indices into lut, and then replacing the indices with the actual values in lut. The specific algorithm used depends on whether you use 2-by-2 or 3-by-3 neighborhoods. 2-by-2 Neighborhoods For 2-by-2 neighborhoods, length(lut) is 16. There are four pixels in each neighborhood, and two possible states for each pixel, so the total number of permutations is 24 = 16. To produce the matrix of indices, applylut convolves the binary image BW with this matrix. 8 4 2 1 The resulting convolution contains integer values in the range [0,15]. applylut uses the central part of the convolution, of the same size as BW, and adds 1 to each value to shift the range to [1,16]. It then constructs A by replacing the values in the cells of the index matrix with the values in lut that the indices point to. 3-11 applylut 3-by-3 Neighborhoods For 3-by-3 neighborhoods, length(lut) is 512. There are nine pixels in each neighborhood, and two possible states for each pixel, so the total number of permutations is 29 = 512. To produce the matrix of indices, applylut convolves the binary image BW with this matrix. 256 128 64 32 16 8 4 2 1 The resulting convolution contains integer values in the range [0,511]. applylut uses the central part of the convolution, of the same size as BW, and adds 1 to each value to shift the range to [1,512]. It then constructs A by replacing the values in the cells of the index matrix with the values in lut that the indices point to. Examples Perform erosion using a 2-by-2 neighborhood. An output pixel is on only if all four of the input pixel’s neighborhood pixels are on. lut = makelut('sum(x(:)) == 4',2); BW = imread('text.png'); BW2 = applylut(BW,lut); imshow(BW), figure, imshow(BW2) 3-12 applylut See Also makelut 3-13 axes2pix Purpose Convert axes coordinates to pixel coordinates Syntax pixelx = axes2pix(dim, XDATA, AXESX) Description pixelx = axes2pix(dim, XDATA, AXESX) converts an axes coordinate into an intrinsic (“pixel”) coordinate. For example, if pt = get(gca,'CurrentPoint') then AXESX could be pt(1,1) or pt(1,2). AXESX must be in intrinsic coordinates. XDATA is a two-element vector returned by get(image_handle, 'XData') or get(image_handle,'YData'). dim is the number of image columns for the x coordinate, or the number of image rows for the y coordinate. Class Support dim, XDATA, and AXESX can be double. The output is double. Note axes2pix performs minimal checking on the validity of AXESX, DIM, or XDATA. For example, axes2pix returns a negative coordinate if AXESX is less than XDATA(1). The function calling axes2pix bears responsibility for error checking. Examples Example with default XData and YData. h = imshow('pout.tif'); [nrows,ncols] = size(get(h,'CData')); xdata = get(h,'XData') ydata = get(h,'YData') px = axes2pix(ncols,xdata,30) py = axes2pix(nrows,ydata,30) Example with non-default XData and YData. xdata = [10 100] ydata = [20 90] px = axes2pix(ncols,xdata,30) py = axes2pix(nrows,ydata,30) See Also 3-14 impixelinfo | bwselect | imfill | impixel | improfile | roipoly bestblk Purpose Determine optimal block size for block processing Syntax siz = bestblk([m n],k) [mb,nb] = bestblk([m n],k) Description siz = bestblk([m n],k) returns, for an m-by-n image, the optimal block size for block processing. k is a scalar specifying the maximum row and column dimensions for the block; if the argument is omitted, it defaults to 100. The return value siz is a 1-by-2 vector containing the row and column dimensions for the block. [mb,nb] = bestblk([m n],k) returns the row and column dimensions for the block in mb and nb, respectively. Algorithms bestblk returns the optimal block size given m, n, and k. The algorithm for determining siz is • If m is less than or equal to k, return m. • If m is greater than k, consider all values between min(m/10,k/2) and k. Return the value that minimizes the padding required. The same algorithm is then repeated for n. Examples siz = bestblk([640 800],72) siz = 64 See Also 50 blockproc 3-15 blockproc Purpose Distinct block processing for image Syntax B = blockproc(A,[M N],fun) B = blockproc(src_filename,[M N],fun) B = blockproc(adapter,[M N],fun) blockproc(...,Name,Value,...) Description B = blockproc(A,[M N],fun) processes the image A by applying the function fun to each distinct M-by-N block of A and concatenating the results into B, the output matrix. fun is a function handle to a function that accepts a block struct as input and returns a matrix, vector, or scalar Y. For example, Y = fun(block_struct). (For more information about a block struct, see the Definition section below.) For each block of data in the input image, A, blockproc passes the block in a block struct to the user function, fun, to produce Y, the corresponding block in the output image. If Y is empty, blockproc does not generate any output and returns empty after processing all blocks. Choosing an appropriate block size can significantly improve performance. For more information, see “Choosing Block Size” in the Image Processing Toolbox documentation. B = blockproc(src_filename,[M N],fun) processes the image src_filename, reading and processing one block at a time. This syntax is useful for processing very large images since only one block of the image is read into memory at a time. If the output matrix B is too large to fit into memory, omit the output argument and instead use the 'Destination' parameter/value pair to write the output to a file. B = blockproc(adapter,[M N],fun) processes the source image specified by adapter, an ImageAdapter object. An ImageAdapter is a user-defined class that provides blockproc with a common API for reading and writing to a particular image file format. For more information, see “Working with Data in Unsupported Formats” in the Image Processing Toolbox documentation. blockproc(...,Name,Value,...) processes the input image, specifying parameters and corresponding values that control various aspects of the block behavior. Parameter names are not case sensitive. 3-16 blockproc Input Arguments A Input image. [M N] Block size of A. fun Function handle to a function that accepts a block struct as input and returns a matrix, vector, or scalar. src_filename Input image. adapter A user-defined class that provides blockproc with a common API for reading and writing to a particular image file format. Name-Value Pair Arguments Specify optional comma-separated pairs of Name,Value arguments, where Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN. BorderSize A two-element vector, [V H], specifying the amount of border pixels to add to each block. The function adds V rows above and below each block and H columns left and right of each block. The size of each resulting block will be: [M + 2*V, N + 2*H] By default, the function automatically removes the border from the result of fun. See the 'TrimBorder' parameter for more information. 3-17 blockproc The function pads blocks with borders extending beyond the image edges with zeros. Default: [0 0] (no border) Destination The destination for the output of blockproc. When you specify the 'Destination' parameter, blockproc does not return the processed image as an output argument, but instead writes the output to the 'Destination'. (You cannot request an output argument when the 'Destination' parameter is specified.) Valid 'Destination' parameters are: • TIFF filename: A string filename ending with '.tif'. If a file with this name already exists, it will be overwritten. • ImageAdapter object: An instance of an ImageAdapter class. ImageAdapters provide an interface for reading and writing to arbitrary image file formats. The 'Destination' parameter is useful when you expect your output to be too large to practically fit into memory. It provides a workflow for file-to-file image processing for arbitrarily large images. PadPartialBlocks A logical scalar. When set to true, blockproc pads partial blocks to make them full-sized (M-by-N) blocks. Partial blocks arise when the image size is not exactly divisible by the block size. If they exist, partial blocks lie along the right and bottom edge of the image. The default is false, meaning that the function does not pad the partial blocks, but processes them as-is. blockproc uses zeros to pad partial blocks when necessary. Default: false PadMethod 3-18 blockproc The 'PadMethod' determines how blockproc will pad the image boundary. Options are: • X: Pads the image with a scalar (X) pad value. By default X == 0. • 'replicate': Repeats border elements of image A. • 'symmetric': Pads image A with mirror reflections of itself. TrimBorder A logical scalar. When set to true, the blockproc function trims off border pixels from the output of the user function, fun. The function removes V rows from the top and bottom of the output of fun, and H columns from the left and right edges. The 'BorderSize' parameter defines V and H. The default is true, meaning that the blockproc function automatically removes borders from the fun output. Default: true UseParallel A logical scalar. Enabling this mode of image processing requires the Parallel Computing Toolbox™. When set to true, blockproc will attempt to run in parallel mode, distributing the processing across multiple workers (MATLAB sessions) in an open MATLAB pool. In parallel mode, the input image cannot be an ImageAdapter object. See the documentation for matlabpool for information on configuring your parallel environment. Default: false File Format Support: Input and output files for blockproc (as specified by src_filename and the 'Destination' parameter) must have one of the following file types and must be named with one of the listed file extensions: • Read/Write File Formats: TIFF (*.tif, *.tiff), JPEG2000 (*.jp2, *.j2c, *.j2k) 3-19 blockproc • Read-Only File Formats: JPEG2000 (*.jpf, *.jpx) Output Arguments B Definitions A block struct is a MATLAB structure that contains the block data as well as other information about the block. Fields in the block struct are: Output matrix. • block_struct.border: A two-element vector, [V H], that specifies the size of the vertical and horizontal padding around the block of data. (See the 'BorderSize' parameter in the Inputs section.) • block_struct.blockSize: A two-element vector, [rows cols], that specifies the size of the block data. If a border has been specified, the size does not include the border pixels. • block_struct.data: M-by-N or M-by-N-by-P matrix of block data • block_struct.imageSize: A two-element vector, [rows cols], that specifies the full size of the input image. • block_struct.location: A two-element vector, [row col], that specifies the position of the first pixel (minimum-row, minimum-column) of the block data in the input image. If a border has been specified, the location refers to the first pixel of the discrete block data, not the added border pixels. Examples Generate an image thumbnail: fun = @(block_struct) imresize(block_struct.data,0.15); I = imread('pears.png'); I2 = blockproc(I,[100 100],fun); figure; imshow(I); figure; imshow(I2); 3-20 blockproc Set the pixels in each 32-by-32 block to the standard deviation of the elements in that block: fun = @(block_struct) ... std2(block_struct.data) * ones(size(block_struct.data)); I2 = blockproc('moon.tif',[32 32],fun); figure; imshow('moon.tif'); figure; imshow(I2,[]); Original Image Standard Deviation Image Switch the red and green bands of an RGB image and write the results to a new TIFF file: 3-21 blockproc I = imread('peppers.png'); fun = @(block_struct) block_struct.data(:,:,[2 1 3]); blockproc(I,[200 200],fun,'Destination','grb_peppers.tif'); figure; imshow('peppers.png'); figure; imshow('grb_peppers.tif'); Original Image of Peppers Recolored Image of Peppers Convert a TIFF image into a new JPEG2000 image. Replace 'largeImage.tif' in the example below with the name of your file: 3-22 blockproc fun = @(block_struct) block_struct.data; blockproc('largeImage.tif',[1024 1024],fun,... 'Destination','New.jp2'); See Also colfilt | function_handle | “ImageAdapter” on page 2-2 | nlfilter How To • “Anonymous Functions” • “Parameterizing Functions” • “Performing Distinct Block Operations” 3-23 bwarea Purpose Area of objects in binary image Syntax total = bwarea(BW) Description total = bwarea(BW) estimates the area of the objects in binary image BW. total is a scalar whose value corresponds roughly to the total number of on pixels in the image, but might not be exactly the same because different patterns of pixels are weighted differently. Class Support BW can be numeric or logical. For numeric input, any nonzero pixels are considered to be on. The return value total is of class double. Algorithms bwarea estimates the area of all of the on pixels in an image by summing the areas of each pixel in the image. The area of an individual pixel is determined by looking at its 2-by-2 neighborhood. There are six different patterns, each representing a different area: • Patterns with zero on pixels (area = 0) • Patterns with one on pixel (area = 1/4) • Patterns with two adjacent on pixels (area = 1/2) • Patterns with two diagonal on pixels (area = 3/4) • Patterns with three on pixels (area = 7/8) • Patterns with all four on pixels (area = 1) Keep in mind that each pixel is part of four different 2-by-2 neighborhoods. This means, for example, that a single on pixel surrounded by off pixels has a total area of 1. Examples Compute the area in the objects of a 256-by-256 binary image. BW = imread('circles.png'); imshow(BW); 3-24 bwarea bwarea(BW) ans = 1.4187e+004 References [1] Pratt, William K., Digital Image Processing, New York, John Wiley & Sons, Inc., 1991, p. 634. See Also bweuler | bwperim 3-25 bwareaopen Purpose Remove small objects from binary image Syntax BW2 = bwareaopen(BW, P) BW2 = bwareaopen(BW, P, conn) Description BW2 = bwareaopen(BW, P) removes from a binary image all connected components (objects) that have fewer than P pixels, producing another binary image, BW2. This operation is known as an area opening. The default connectivity is 8 for two dimensions, 26 for three dimensions, and conndef(ndims(BW), 'maximal') for higher dimensions. BW2 = bwareaopen(BW, P, conn) specifies the desired connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by-...-by-3 matrix of 0s and 1s. The 1-valued elements define neighborhood locations relative to the central element of conn. Note that conn must be symmetric about its central element. Class Support 3-26 BW can be a logical or numeric array of any dimension, and it must be nonsparse. The return value BW2 is of class logical. bwareaopen Algorithms The basic steps are 1 Determine the connected components: CC = bwconncomp(BW, conn); 2 Compute the area of each component: S = regionprops(CC, 'Area'); 3 Remove small objects: L = labelmatrix(CC); BW2 = ismember(L, find([S.Area] >= P)); Examples Remove all objects in the image text.png containing fewer than 50 pixels: BW = imread('text.png'); BW2 = bwareaopen(BW, 50); imshow(BW); figure, imshow(BW2) 3-27 bwareaopen See Also 3-28 bwconncomp | conndef bwboundaries Purpose Trace region boundaries in binary image Syntax B = bwboundaries(BW) B = bwboundaries(BW,conn) B = bwboundaries(BW,conn,options) [B,L] = bwboundaries(...) [B,L,N,A] = bwboundaries(...) Description B = bwboundaries(BW) traces the exterior boundaries of objects, as well as boundaries of holes inside these objects, in the binary image BW. bwboundaries also descends into the outermost objects (parents) and traces their children (objects completely enclosed by the parents). BW must be a binary image where nonzero pixels belong to an object and 0 pixels constitute the background. The following figure illustrates these components. bwboundaries returns B, a P-by-1 cell array, where P is the number of objects and holes. Each cell in the cell array contains a Q-by-2 matrix. Each row in the matrix contains the row and column coordinates of a boundary pixel. Q is the number of boundary pixels for the corresponding region. B = bwboundaries(BW,conn) specifies the connectivity to use when tracing parent and child boundaries. conn can have either of the following scalar values. 3-29 bwboundaries Value Meaning 4 4-connected neighborhood 8 8-connected neighborhood. This is the default. B = bwboundaries(BW,conn,options) specifies an optional argument, where options can have either of the following values: Value Meaning 'holes' Search for both object and hole boundaries. This is the default. 'noholes' Search only for object (parent and child) boundaries. This can provide better performance. [B,L] = bwboundaries(...) returns the label matrix L as the second output argument. Objects and holes are labeled. L is a two-dimensional array of nonnegative integers that represent contiguous regions. The kth region includes all elements in L that have value k. The number of objects and holes represented by L is equal to max(L(:)). The zero-valued elements of L make up the background. [B,L,N,A] = bwboundaries(...) returns N, the number of objects found, and A, an adjacency matrix. The first N cells in B are object boundaries. A represents the parent-child-hole dependencies. A is a square, sparse, logical matrix with side of length max(L(:)), whose rows and columns correspond to the positions of boundaries stored in B. The boundaries enclosed by a B{m} as well as the boundary enclosing B{m} can both be found using A as follows: enclosing_boundary = find(A(m,:)); enclosed_boundaries = find(A(:,m)); Class Support 3-30 BW can be logical or numeric and it must be real, two-dimensional, and nonsparse. L and N are double. A is sparse logical. bwboundaries Examples Example 1 Read in and threshold an intensity image. Display the labeled objects using the jet colormap, on a gray background, with region boundaries outlined in white. I = imread('rice.png'); BW = im2bw(I, graythresh(I)); [B,L] = bwboundaries(BW,'noholes'); imshow(label2rgb(L, @jet, [.5 .5 .5])) hold on for k = 1:length(B) boundary = B{k}; plot(boundary(:,2), boundary(:,1), 'w', 'LineWidth', 2) end Example 2 Read in and display a binary image. Overlay the region boundaries on the image. Display text showing the region number (based on the label matrix) next to every boundary. Additionally, display the adjacency matrix using the MATLAB spy function. After the image is displayed, use the zoom tool to read individual labels. BW = imread('blobs.png'); [B,L,N,A] = bwboundaries(BW); figure, imshow(BW); hold on; colors=['b' 'g' 'r' 'c' 'm' 'y']; for k=1:length(B) boundary = B{k}; cidx = mod(k,length(colors))+1; plot(boundary(:,2), boundary(:,1),... colors(cidx),'LineWidth',2); %randomize text position for better visibility rndRow = ceil(length(boundary)/(mod(rand*k,7)+1)); col = boundary(rndRow,2); row = boundary(rndRow,1); h = text(col+1, row-1, num2str(L(row,col))); set(h,'Color',colors(cidx),... 'FontSize',14,'FontWeight','bold'); 3-31 bwboundaries end figure; spy(A); Example 3 Display object boundaries in red and hole boundaries in green. BW = imread('blobs.png'); [B,L,N] = bwboundaries(BW); figure; imshow(BW); hold on; for k=1:length(B), boundary = B{k}; if(k > N) plot(boundary(:,2),... boundary(:,1),'g','LineWidth',2); else plot(boundary(:,2),... boundary(:,1),'r','LineWidth',2); end end Example 4 Display parent boundaries in red (any empty row of the adjacency matrix belongs to a parent) and their holes in green. BW = imread('blobs.png'); [B,L,N,A] = bwboundaries(BW); figure; imshow(BW); hold on; for k=1:length(B), if(~sum(A(k,:))) boundary = B{k}; plot(boundary(:,2),... boundary(:,1),'r','LineWidth',2); for l=find(A(:,k))' boundary = B{l}; plot(boundary(:,2),... boundary(:,1),'g','LineWidth',2); end 3-32 bwboundaries end end Algorithms The bwboundaries function implements the Moore-Neighbor tracing algorithm modified by Jacob’s stopping criteria. This function is based on the boundaries function presented in the first edition of Digital Image Processing Using MATLAB[1]. References [1] Gonzalez, R. C., R. E. Woods, and S. L. Eddins, Digital Image Processing Using MATLAB, New Jersey, Pearson Prentice Hall, 2004. See Also bwlabel | bwlabeln | bwperim | bwtraceboundary 3-33 bwconncomp Purpose Find connected components in binary image Syntax CC = bwconncomp(BW) CC = bwconncomp(BW,conn) Description CC = bwconncomp(BW) returns the connected components CC found in BW. The binary image BW can have any dimension. CC is a structure with four fields. Field Description Connectivity Connectivity of the connected components (objects) ImageSize Size of BW NumObjects Number of connected components (objects) in BW PixelIdxList 1-by-NumObjects cell array where the kth element in the cell array is a vector containing the linear indices of the pixels in the kth object. bwconncomp uses a default connectivity of 8 for two dimensions, 26 for three dimensions, and conndef(ndims(BW),'maximal') for higher dimensions. CC = bwconncomp(BW,conn) specifies the desired connectivity for the connected components. conn can have the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 3-34 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood bwconncomp Connectivity can be defined in a more general way for any dimension using a 3-by-3-by- ... -by-3 matrix of 0s and 1s. conn must be symmetric about its center element. The 1-valued elements define neighborhood locations relative to conn. The functions bwlabel, bwlabeln, and bwconncomp all compute connected components for binary images. bwconncomp replaces the use of bwlabel and bwlabeln. It uses significantly less memory and is sometimes faster than the other functions. Function Input Dimension Output Form Memory Use Connectivity bwlabel 2-D Label matrix with double-precision High 4 or 8 bwlabeln N-D Double-precision label matrix High Any bwconncomp N-D CC struct Low Any Tips To extract features from a binary image using regionprops with default connectivity, just pass BW directly into regionprops (i.e., regionprops(BW)). To compute a label matrix having more memory-efficient data type (e.g., uint8 versus double), use the labelmatrix function on the output of bwconncomp. See the documentation for each function for more information. Class Support BW can be a logical or numeric array of any dimension, and it must be real and nonsparse. CC is a structure. Examples Example 1 Calculate the centroids of the 3-D objects. BW = cat(3, [1 1 0; 0 0 0; 1 0 0],... [0 1 0; 0 0 0; 0 1 0],... 3-35 bwconncomp [0 1 1; 0 0 0; 0 0 1]); CC = bwconncomp(BW); S = regionprops(CC,'Centroid'); Example 2 Erase the largest letter from the image. BW = imread('text.png'); imshow(BW); CC = bwconncomp(BW); numPixels = cellfun(@numel,CC.PixelIdxList); [biggest,idx] = max(numPixels); BW(CC.PixelIdxList{idx}) = 0; figure, imshow(BW); 3-36 bwconncomp Algorithms The basic steps in finding the connected components are: 1 Search for the next unlabeled pixel, p. 2 Use a flood-fill algorithm to label all the pixels in the connected component containing p. 3 Repeat steps 1 and 2 until all the pixels are labelled. See Also bwlabel | bwlabeln | labelmatrix | regionprops 3-37 bwconvhull Purpose Generate convex hull image from binary image Syntax CH = bwconvhull(BW) CH = bwconvhull(BW, method) CH = bwconvhull(BW, 'objects', conn) Description CH = bwconvhull(BW) computes the convex hull of all objects in BW and returns CH, a binary convex hull image. CH = bwconvhull(BW, method) specifies the desired method for computing the convex hull image. CH = bwconvhull(BW, 'objects', conn) specifies the desired connectivity used when defining individual foreground objects. The conn parameter is only valid when the method is 'objects'. Input Arguments BW A logical 2-D image method A string that can have the following values: • 'union': Compute the convex hull of all foreground objects, treating them as a single object. • 'objects': Compute the convex hull of each connected component of BW individually. CH contains the convex hulls of each connected component. Default: 'union' conn Connectivity. Can have the following scalar values: • 4: Two-dimensional, four-connected neighborhood. • 8: Two-dimensional, eight-connected neighborhood. 3-38 bwconvhull Additionally, conn may be defined in a more general way, using a 3-by-3 matrix of 0s and 1s. The 1-valued elements define neighborhood locations relative to conn’s center element. conn must be symmetric about its center element. Default: 8 Output Arguments CH Examples Display the binary convex hull of an image: A logical, convex hull image, containing the binary mask of the convex hull of all foreground objects in BW. subplot(2,2,1); I = imread('coins.png'); imshow(I); title('Original'); subplot(2,2,2); BW = I > 100; imshow(BW); title('Binary'); subplot(2,2,3); CH = bwconvhull(BW); imshow(CH); title('Union Convex Hull'); subplot(2,2,4); CH_objects = bwconvhull(BW,'objects'); imshow(CH_objects); title('Objects Convex Hull'); 3-39 bwconvhull See Also 3-40 bwconncomp | bwlabel | labelmatrix | regionprops bwdist Purpose Distance transform of binary image Syntax D = bwdist(BW) [D,IDX] = bwdist(BW) [D,IDX] = bwdist(BW,method) Description D = bwdist(BW) computes the Euclidean distance transform of the binary image BW. For each pixel in BW, the distance transform assigns a number that is the distance between that pixel and the nearest nonzero pixel of BW. bwdist uses the Euclidean distance metric by default. BW can have any dimension. D is the same size as BW. [D,IDX] = bwdist(BW) also computes the closest-pixel map in the form of an index array, IDX. (The closest-pixel map is also called the feature map, feature transform, or nearest-neighbor transform.) IDX has the same size as BW and D. Each element of IDX contains the linear index of the nearest nonzero pixel of BW. [D,IDX] = bwdist(BW,method) computes the distance transform, where method specifies an alternate distance metric. method can take any of the following values. The method string can be abbreviated. Method Description 'chessboard' In 2-D, the chessboard distance between (x1,y1) and (x2,y2) is max(│x1 – x2│,│y1 – y2│). 'cityblock' In 2-D, the cityblock distance between (x1,y1) and (x2,y2) is │x1 – x2│ + │y1 – y2│. 3-41 bwdist Method Description 'euclidean' In 2-D, the Euclidean distance between (x1,y1) and (x2,y2) is ( x1 − x2 )2 + ( y1 − y2 )2 . This is the default method. 'quasi-euclidean' In 2-D, the quasi-Euclidean distance between (x1,y1) and (x2,y2) is x1 x2 ( 2 1) y1 y2 , x1 x2 y1 y2 ( 2 − 1) x1 − x2 + y1 − y2 , otherwise. Tips bwdist uses fast algorithms to compute the true Euclidean distance transform, especially in the 2-D case. The other methods are provided primarily for pedagogical reasons. However, the alternative distance transforms are sometimes significantly faster for multidimensional input images, particularly those that have many nonzero elements. The function bwdist changed in version 6.4 (R2009b). Previous versions of the Image Processing Toolbox used different algorithms for computing the Euclidean distance transform and the associated label matrix. If you need the same results produced by the previous implementation, use the function bwdist_old. Class Support 3-42 BW can be numeric or logical, and it must be nonsparse. D is a single matrix with the same size as BW. The class of IDX depends on the number of elements in the input image, and is determined using the following table. bwdist Examples Class Range 'uint32' numel(BW) <= 232 − 1 'uint64' numel(BW) >= 232 Compute the Euclidean distance transform. bw = zeros(5,5); bw = 0 0 0 1 0 0 0 0 0 0 bw(2,2) = 1; bw(4,4) = 1 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 [D,IDX] = bwdist(bw) D = 1.4142 1.0000 1.4142 2.2361 3.1623 1.0000 0 1.0000 2.0000 2.2361 1.4142 1.0000 1.4142 1.0000 1.4142 2.2361 2.0000 1.0000 0 1.0000 3.1623 2.2361 1.4142 1.0000 1.4142 IDX = 7 7 7 7 7 7 7 7 7 19 7 7 7 19 19 7 7 19 19 19 7 19 19 19 19 In the nearest-neighbor matrix IDX the values 7 and 19 represent the position of the nonzero elements using linear matrix indexing. If a pixel contains a 7, its closest nonzero neighbor is at linear position 7. Compare the 2-D distance transforms for each of the supported distance methods. In the figure, note how the quasi-Euclidean distance 3-43 bwdist transform best approximates the circular shape achieved by the Euclidean distance method. bw = zeros(200,200); bw(50,50) = 1; bw(50,150) = 1; bw(150,100) = 1; D1 = bwdist(bw,'euclidean'); D2 = bwdist(bw,'cityblock'); D3 = bwdist(bw,'chessboard'); D4 = bwdist(bw,'quasi-euclidean'); figure subplot(2,2,1), subimage(mat2gray(D1)), title('Euclidean') hold on, imcontour(D1) subplot(2,2,2), subimage(mat2gray(D2)), title('City block') hold on, imcontour(D2) subplot(2,2,3), subimage(mat2gray(D3)), title('Chessboard') hold on, imcontour(D3) subplot(2,2,4), subimage(mat2gray(D4)), title('Quasi-Euclidean') hold on, imcontour(D4) Compare isosurface plots for the distance transforms of a 3-D image containing a single nonzero pixel in the center. 3-44 bwdist bw = zeros(50,50,50); bw(25,25,25) = 1; D1 = bwdist(bw); D2 = bwdist(bw,'cityblock'); D3 = bwdist(bw,'chessboard'); D4 = bwdist(bw,'quasi-euclidean'); figure subplot(2,2,1), isosurface(D1,15), axis equal, view(3) camlight, lighting gouraud, title('Euclidean') subplot(2,2,2), isosurface(D2,15), axis equal, view(3) camlight, lighting gouraud, title('City block') subplot(2,2,3), isosurface(D3,15), axis equal, view(3) camlight, lighting gouraud, title('Chessboard') subplot(2,2,4), isosurface(D4,15), axis equal, view(3) camlight, lighting gouraud, title('Quasi-Euclidean') Algorithms For Euclidean distance transforms, bwdist uses the fast algorithm described in [1] Maurer, Calvin, Rensheng Qi, and Vijay Raghavan, "A Linear Time Algorithm for Computing Exact Euclidean Distance Transforms 3-45 bwdist of Binary Images in Arbitrary Dimensions," IEEE Transactions on Pattern Analysis and Machine Intelligence, Vol. 25, No. 2, February 2003, pp. 265-270. For cityblock, chessboard, and quasi-Euclidean distance transforms, bwdist uses the two-pass, sequential scanning algorithm described in [2] Rosenfeld, Azriel and John Pfaltz, "Sequential operations in digital picture processing," Journal of the Association for Computing Machinery, Vol. 13, No. 4, 1966, pp. 471-494. The different distance measures are achieved by using different sets of weights in the scans, as described in [3] Paglieroni, David, "Distance Transforms: Properties and Machine Vision Applications," Computer Vision, Graphics, and Image Processing: Graphical Models and Image Processing, Vol. 54, No. 1, January 1992, pp. 57-58. 3-46 See Also bwulterode | watershed How To • “Distance Transform” bwdistgeodesic Purpose Geodesic distance transform of binary image Syntax D D D D Description D = bwdistgeodesic(BW,mask) computes the geodesic distance transform, given the binary image BW and the seed locations specified by mask. Regions where BW is true represent valid regions that can be traversed in the computation of the distance transform. Regions where BW is false represent constrained regions that cannot be traversed in the distance computation. For each true pixel in BW, the geodesic distance transform assigns a number that is the constrained distance between that pixel and the nearest true pixel in mask. Output matrix D contains geodesic distances. = = = = bwdistgeodesic(BW,mask) bwdistgeodesic(BW,C,R) bwdistgeodesic(BW,ind) bwdistgeodesic(...,method) D = bwdistgeodesic(BW,C,R) computes the geodesic distance transform of the binary image BW. Vectors C and R contain the column and row coordinates of the seed locations. D = bwdistgeodesic(BW,ind) computes the geodesic distance transform of the binary image BW. ind is a vector of linear indices of seed locations. D = bwdistgeodesic(...,method) specifies an alternate distance metric. Input Arguments BW Binary image. mask Logical image the same size as BW that specifies seed locations. C,R 3-47 bwdistgeodesic Numeric vectors that contain the positive integer column and row coordinates of the seed locations. Coordinate values are valid C,R subscripts in BW. ind Numeric vector of positive integer, linear indices of seed locations. method Type of distance metric. method can have any of these values. Method Description 'cityblock' In 2-D, the cityblock distance between (x1,y1) and (x2,y2) is │x1 – x2│ + │y1 – y2│. 'chessboard' The chessboard distance is max(│x1 – x2│,│y1 – y2│). 'quasieuclidean' The quasi-Euclidean distance is x1 x2 ( 2 1) y1 y2 , x1 x2 y1 y2 ( 2 − 1) x1 − x2 + y1 − y2 , otherwise. Default: 'chessboard' Output Arguments Class Support 3-48 D Numeric array of class single, with the same size as input BW, that contains geodesic distances. BW is a logical matrix. C, R, and ind are numeric vectors that contain positive integer values. D is a numeric array of class single that has the same size as the input BW. bwdistgeodesic Examples Compute the geodesic distance transformation of BW based on the seed locations specified by vectors C and R. Output pixels for which BW is false have undefined geodesic distance and contain NaN values. Because there is no connected path from the seed locations to element BW(10,5), the output D(10,5) has a value of Inf. BW = [1 1 1 1 1 1 1 1 1 1;... 1 1 1 1 1 1 0 0 1 1;... 1 1 1 1 1 1 0 0 1 1;... 1 1 1 1 1 1 0 0 1 1;... 0 0 0 0 0 1 0 0 1 0;... 0 0 0 0 1 1 0 1 1 0;... 0 1 0 0 1 1 0 0 0 0;... 0 1 1 1 1 1 1 0 1 0;... 0 1 1 0 0 0 1 1 1 0;... 0 0 0 0 1 0 0 0 0 0]; BW = logical(BW); C = [1 2 3 3 3]; R = [3 3 3 1 2]; D = bwdistgeodesic(BW,C,R); Algorithms bwdistgeodesic uses the geodesic distance algorithm described in See Also bwdist | graydist Soille, P., Morphological Image Analysis: Principles and Applications, 2nd Edition, Secaucus, NJ, Springer-Verlag, 2003, pp. 219–221. 3-49 bweuler Purpose Euler number of binary image Syntax eul = bweuler(BW,n) Description eul = bweuler(BW,n) returns the Euler number for the binary image BW. The return value eul is a scalar whose value is the total number of objects in the image minus the total number of holes in those objects. The argument n can have a value of either 4 or 8, where 4 specifies 4-connected objects and 8 specifies 8-connected objects; if the argument is omitted, it defaults to 8. Class Support BW can be numeric or logical and it must be real, nonsparse, and two-dimensional. The return value eul is of class double. Examples BW = imread('circles.png'); imshow(BW); bweuler(BW) ans = -3 3-50 bweuler Algorithms bweuler computes the Euler number by considering patterns of References [1] Horn, Berthold P. K., Robot Vision, New York, McGraw-Hill, 1986, pp. 73-77. convexity and concavity in local 2-by-2 neighborhoods. See [2] for a discussion of the algorithm used. [2] Pratt, William K., Digital Image Processing, New York, John Wiley & Sons, Inc., 1991, p. 633. See Also bwmorph | bwperim 3-51 bwhitmiss Purpose Binary hit-miss operation Syntax BW2 = bwhitmiss(BW1,SE1,SE2) BW2 = bwhitmiss(BW1,INTERVAL) Description BW2 = bwhitmiss(BW1,SE1,SE2) performs the hit-miss operation defined by the structuring elements SE1 and SE2. The hit-miss operation preserves pixels whose neighborhoods match the shape of SE1 and don’t match the shape of SE2. SE1 and SE2 can be flat structuring element objects, created by strel, or neighborhood arrays. The neighborhoods of SE1 and SE2 should not have any overlapping elements. The syntax bwhitmiss(BW1,SE1,SE2) is equivalent to imerode(BW1,SE1) & imerode(~BW1,SE2). BW2 = bwhitmiss(BW1,INTERVAL) performs the hit-miss operation defined in terms of a single array, called an interval. An interval is an array whose elements can contain 1, 0, or -1. The 1-valued elements make up the domain of SE1, the -1-valued elements make up the domain of SE2, and the 0-valued elements are ignored. The syntax bwhitmiss(BW1,INTERVAL) is equivalent to bwhitmiss(BW1,INTERVAL == 1, INTERVAL == -1). Class Support BW1 can be a logical or numeric array of any dimension, and it must be nonsparse. BW2 is always a logical array the same size as BW1. SE1 and SE2 must be flat STREL objects or they must be logical or numeric arrays containing 1’s and 0’s. INTERVAL must be an array containing 1's, 0's, and -1's. Examples Perform the hit-miss operation on a binary image using an interval. bw = [0 0 0 0 0 0 3-52 0 0 1 1 0 0 0 1 1 1 1 1 0 1 1 1 1 0 0 0 1 1 0 0 0 0 0 0 0 0] bwhitmiss interval = [0 -1 -1 1 1 -1 0 1 0]; bw2 = bwhitmiss(bw,interval) bw2 = 0 0 0 0 0 0 See Also 0 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 imdilate | imerode | strel 3-53 bwlabel Purpose Label connected components in 2-D binary image Syntax L = bwlabel(BW, n) [L, num] = bwlabel(BW, n) Description L = bwlabel(BW, n) returns a matrix L, of the same size as BW, containing labels for the connected objects in BW. The variable n can have a value of either 4 or 8, where 4 specifies 4-connected objects and 8 specifies 8-connected objects. If the argument is omitted, it defaults to 8. The elements of L are integer values greater than or equal to 0. The pixels labeled 0 are the background. The pixels labeled 1 make up one object; the pixels labeled 2 make up a second object; and so on. [L, num] = bwlabel(BW, n) returns in num the number of connected objects found in BW. The functions bwlabel, bwlabeln, and bwconncomp all compute connected components for binary images. bwconncomp replaces the use of bwlabel and bwlabeln. It uses significantly less memory and is sometimes faster than the other functions. Input Dimension Output Form Memory Use Connectivity bwlabel 2-D Double-precision label matrix High 4 or 8 bwlabeln N-D Double-precision label matrix High Any bwconncomp N-D CC struct Low Any Tips Using find with bwlabel You can use the MATLAB find function in conjunction with bwlabel to return vectors of indices for the pixels that make up a specific object. For example, to return the coordinates for the pixels in object 2, enter the following: 3-54 bwlabel [r, c] = find(bwlabel(BW)==2) You can display the output matrix as a pseudocolor indexed image. Each object appears in a different color, so the objects are easier to distinguish than in the original image. For more information, see label2rgb. Using labelmatrix and regionprops To compute a label matrix having a more memory-efficient data type (e.g., uint8 versus double), use the labelmatrix function on the output of bwconncomp. For more information, see the reference page for each function. To extract features from a binary image using regionprops with default connectivity, just pass BW directly into regionprops, i.e., regionprops(BW). Class Support BW can be logical or numeric, and it must be real, two-dimensional, and nonsparse. L is of class double. Examples Label components using 4-connected objects. Notice objects 2 and 3; with 8-connected labeling, bwlabel would consider these a single object rather than two separate objects. BW = logical ([1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 0 1 1 0 0 0 1 0 0 0 0 1 1 1 1 0 0 0 0 0 0 0 0 0]); L = bwlabel(BW,4) L = 1 1 1 0 0 0 0 0 3-55 bwlabel 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 2 2 0 0 0 0 0 2 2 0 0 0 3 0 0 0 3 3 3 3 0 0 0 0 0 0 0 0 [r, c] = find(L==2); rc = [r c] rc = 2 3 2 3 Algorithms 5 5 6 6 bwlabel uses the general procedure outlined in reference [1], pp. 40-48: 1 Run-length encode the input image. 2 Scan the runs, assigning preliminary labels and recording label equivalences in a local equivalence table. 3 Resolve the equivalence classes. 4 Relabel the runs based on the resolved equivalence classes. 3-56 References [1] Haralick, Robert M., and Linda G. Shapiro, Computer and Robot Vision, Volume I, Addison-Wesley, 1992, pp. 28-48. See Also bwconncomp | bwlabeln | bwselect | labelmatrix | label2rgb | regionprops bwlabeln Purpose Label connected components in binary image Syntax L = bwlabeln(BW) [L, NUM] = bwlabeln(BW) [L, NUM] = bwlabeln(BW, conn) Description L = bwlabeln(BW) returns a label matrix, L, containing labels for the connected components in BW. The input image BW can have any dimension; L is the same size as BW. The elements of L are integer values greater than or equal to 0. The pixels labeled 0 are the background. The pixels labeled 1 make up one object; the pixels labeled 2 make up a second object; and so on. The default connectivity is 8 for two dimensions, 26 for three dimensions, and conndef(ndims(BW), 'maximal') for higher dimensions. [L, NUM] = bwlabeln(BW) returns in NUM the number of connected objects found in BW. [L, NUM] = bwlabeln(BW, conn) specifies the desired connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can also be defined in a more general way for any dimension by using for conn a 3-by-3-by- ...-by-3 matrix of 0s and 1s. The 1-valued elements define neighborhood locations relative to the 3-57 bwlabeln central element of conn. Note that conn must be symmetric about its central element. The functions bwlabel, bwlabeln, and bwconncomp all compute connected components for binary images. bwconncomp replaces the use of bwlabel and bwlabeln. It uses significantly less memory and is sometimes faster than the older functions. Function Input Dimension Output Form Memory Use Connectivity bwlabel 2-D Double-precision label matrix High 4 or 8 bwlabeln N-D Double-precision label matrix High Any bwconncomp N-D CC struct Low Any Tips To extract features from a binary image using regionprops with default connectivity, just pass BW directly into regionprops, i.e., regionprops(BW). To compute a label matrix having a more memory-efficient data type (e.g., uint8 versus double), use the labelmatrix function on the output of bwconncomp: C = bwconncomp(BW); L = labelmatrix(CC); CC = bwconncomp(BW, conn); S = regionprops(CC); Class Support BW can be numeric or logical, and it must be real and nonsparse. L is of class double. Examples Calculate the centroids of the 3-D objects. BW = cat(3, [1 1 0; 0 0 0; 1 0 0],... 3-58 bwlabeln [0 1 0; 0 0 0; 0 1 0],... [0 1 1; 0 0 0; 0 0 1]) bwlabeln(BW) ans(:,:,1) = 1 0 2 1 0 0 0 0 0 ans(:,:,2) = 0 0 0 1 0 2 0 0 0 ans(:,:,3) = 0 0 0 Algorithms 1 0 0 1 0 2 bwlabeln uses the following general procedure: 1 Scan all image pixels, assigning preliminary labels to nonzero pixels and recording label equivalences in a union-find table. 2 Resolve the equivalence classes using the union-find algorithm [1]. 3 Relabel the pixels based on the resolved equivalence classes. References [1] Sedgewick, Robert, Algorithms in C, 3rd Ed., Addison-Wesley, 1998, pp. 11-20. 3-59 bwlabeln See Also 3-60 bwconncomp | bwlabel | labelmatrix | label2rgb | regionprops bwlookup Purpose Nonlinear filtering using lookup tables Syntax A = bwlookup(BW,lut) Description A = bwlookup(BW,lut) performs a 2–by–2 or 3–by–3 nonlinear neighborhood filtering operation on binary or grayscale image BW and returns the results in output image A. The neighborhood processing determines an integer index value used to access values in lookup table lut. The fetched lut value becomes the pixel value in output image A at the targeted position. • A is the same size as BW • A is the same data type as lut bwlookup supports the generation of efficient, production-quality C/C++ code from MATLAB. For best results, specify an input image of class logical. To see a complete list of toolbox functions that support code generation, see “Supported Functions”. Input Arguments BW - Input image binary image | grayscale image Input image transformed by nonlinear neighborhood filtering operation, specified as either a grayscale or binary (logical) image. In the case of numeric values, non-zero pixels are considered true which is equivalent to logical 1. Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical lut - Lookup table of output pixel values 16- or 256-element vector Lookup table of output pixel values, specified as a 16- or 256-element vector. The size of lut determines which of the two neighborhood operations is performed. 3-61 bwlookup • If lut contains 16 data elements, then the neighborhood matrix is 2–by–2. • If lut contains 256 data elements, then the neighborhood matrix is 3–by–3. Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical Output Arguments A - Output image binary image | grayscale image Output image, returned as a grayscale or binary image whose size matches BW, and whose distribution of pixel values are determined by the content of lut. • A is the same size as BW • A is the same data type as lut Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical Examples 2-by-2 Neighborhood Erosion of Binary Image This example performs an erosion along the edges of a binary image. Vector lut is constructed such that the filtering operation places a 1 at the targeted pixel location in image A only when all 4 pixels in the 2-by-2 neighborhood of BW are set to 1. For all other 2-by-2 neighborhood combinations in BW, the targeted pixel location in image A receives a 0. % Construct lut so it is 'true' only % when all 4 2-by2 locations equal 1 lutfun = @(x)(sum(x(:))==4); lut = makelut(lutfun,2); % load binary image BW1 = imread('text.png'); 3-62 bwlookup % Perform 2x2 Neighborhood processing % with 16 element vector lut BW2 = bwlookup(BW1,lut); % show Zoomed before and after images figure; h1 = subplot(1,2,1); imshow(BW1), axis off; title('BW1') h2 = subplot(1,2,2); imshow(BW2); axis off; title('BW2') % do a 16X Zoom to see effects of erosion on text set(h1,'Ylim',[.5 64.5]); set(h1,'Xlim',[.5 64.5]); set(h2,'Ylim',[.5 64.5]); set(h2,'Xlim',[.5 64.5]); lut = 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 3-63 bwlookup Algorithm The first step in each iteration of the filtering operation performed by bwlookup entails computing the index into vector lut based on the binary pixel pattern of the neighborhood matrix on image BW. The value in lut accessed at index, lut(index), is inserted into output image A at the targeted pixel location. This results in image A being the same data type as vector lut. Since there is a 1-to-1 correspondence in targeted pixel locations, image A is the same size as image BW. If the targeted pixel location is on an edge of image BW and if any part of the 2x2 or 3x3 neighborhood matrix extends beyond the image edge, then these non-image locations are padded with 0 in order to perform the filtering operation. Mapping from Neighborhood Matrices to Binary Notation The following figures show the mapping from binary 0 and 1 patterns in the neighborhood matrices to its binary representation. Adding 1 to the binary representation yields index which is used to access lut. For 2-by-2 neighborhoods, length(lut) is 16. There are four pixels in each neighborhood, and two possible states for each pixel, so the total number of permutations is 24 = 16. 3-64 bwlookup 3-65 bwlookup Example: This example demonstrates how the pixel pattern in a 2x2 matrix determines which entry in lut is placed in the targeted pixel location. Create random 16 element lut vector containing uint8 data scurr = rng; % save current seed state rng('default') % always generate same set of random numbers lut = uint8( round( 255*rand(16,1) ) ) % generate 16 uint8 rng(scurr); % restore lut = 208 231 32 233 161 25 71 139 244 246 40 248 244 124 204 36 Create a small 2x2 image; targeted pixel location will be at location BW(1,1). BW = [1 0; 0 1] BW = 1 3-66 0 bwlookup 0 1 By referring to the color coded mapping figure above, the binary representation for this 2x2 neighborhood can be computed as shown in the code snippet below. The logical 1 at BW(1,1) corresponds to blue in the figure which maps to the Least Signficant Bit (LSB) at position 0 in the 4-bit binary representation (,20= 1). The logical 1 at BW(2,2) is red which maps to the Most Significant Bit (MSB) at position 3 in the 4-bit binary representation (23= 8) . % BW(1,1): blue square; sets bit position 0 on right % BW(2,2): red square; sets bit position 3 on left binNot = '1 0 0 1'; % binary representation of 2x2 neighborhood matr X = bin2dec( binNot ); % convert from binary to decimal index = X + 1 % add 1 to compute index value for uint8 vector lut A11 = lut(index) % value at A(1,1) index = 10 A11 = 246 The above calculation predicts that output image A should contain the value 246 at targeted position A(1,1). A = bwlookup(BW,lut) % perform filtering A = 246 161 32 231 A(1,1) does in fact equal 246. 3-67 bwlookup Note For a more robust way to perform image erosion, see function imerode. For 3-by-3 neighborhoods, length(lut) is 512. There are nine pixels in each neighborhood, and two possible states for each pixel, so the total number of permutations is 29 = 512. The process for computing the binary representation of 3x3 neighborhood processing is the same as shown above for 2x2 neighborhoods. 3-68 bwlookup 3-69 bwmorph Purpose Morphological operations on binary images Syntax BW2 = bwmorph(BW,operation) BW2 = bwmorph(BW,operation,n) Description BW2 = bwmorph(BW,operation) applies a specific morphological operation to the binary image BW. BW2 = bwmorph(BW,operation,n) applies the operation n times. n can be Inf, in which case the operation is repeated until the image no longer changes. operation is a string that can have one of the values listed below. Operation Description 'bothat' Performs the morphological “bottom hat” operation, returning the image minus the morphological closing of the image (dilation followed by erosion). 'branchpoints' Find branch points of skeleton. For example: 0 0 1 0 0 'bridge' 1 1 1 1 1 0 0 1 0 0 0 0 1 0 0 becomes 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 Bridges unconnected pixels, that is, sets 0-valued pixels to 1 if they have two nonzero neighbors that are not connected. For example: 1 1 0 3-70 0 0 1 0 0 0 0 0 0 1 1 becomes 1 1 0 1 1 1 0 1 1 bwmorph Operation Description 'clean' Removes isolated pixels (individual 1s that are surrounded by 0s), such as the center pixel in this pattern. 0 0 0 0 1 0 0 0 0 'close' Performs morphological closing (dilation followed by erosion). 'diag' Uses diagonal fill to eliminate 8-connectivity of the background. For example: 0 1 0 1 0 0 0 0 0 becomes 0 1 0 1 1 0 0 0 0 'dilate' Performs dilation using the structuring element ones(3). 'endpoints' Finds end points of skeleton. For example: 1 0 0 0 'erode' 0 1 0 0 0 0 1 0 0 0 0 0 becomes 1 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 Performs erosion using the structuring element ones(3). 3-71 bwmorph Operation Description 'fill' Fills isolated interior pixels (individual 0s that are surrounded by 1s), such as the center pixel in this pattern. 1 1 1 'hbreak' 1 1 1 Removes H-connected pixels. For example: 1 0 1 3-72 1 0 1 1 1 1 1 0 1 becomes 1 0 1 1 0 1 1 0 1 'majority' Sets a pixel to 1 if five or more pixels in its 3-by-3 neighborhood are 1s; otherwise, it sets the pixel to 0. 'open' Performs morphological opening (erosion followed by dilation). 'remove' Removes interior pixels. This option sets a pixel to 0 if all its 4-connected neighbors are 1, thus leaving only the boundary pixels on. 'shrink' With n = Inf, shrinks objects to points. It removes pixels so that objects without holes shrink to a point, and objects with holes shrink to a connected ring halfway between each hole and the outer boundary. This option preserves the Euler number. 'skel' With n = Inf, removes pixels on the boundaries of objects but does not allow objects to break apart. The pixels remaining make up the image skeleton. This option preserves the Euler number. bwmorph Operation Description 'spur' Removes spur pixels. For example: 0 0 0 0 1 0 0 0 1 1 0 0 1 0 0 0 0 0 0 0 becomes 0 0 0 0 1 0 0 0 1 1 0 0 0 0 0 0 0 0 0 0 'thicken' With n = Inf, thickens objects by adding pixels to the exterior of objects until doing so would result in previously unconnected objects being 8-connected. This option preserves the Euler number. 'thin' With n = Inf, thins objects to lines. It removes pixels so that an object without holes shrinks to a minimally connected stroke, and an object with holes shrinks to a connected ring halfway between each hole and the outer boundary. This option preserves the Euler number. See “Algorithms” on page 3-75 for more detail. 'tophat' Performs morphological "top hat" operation, returning the image minus the morphological opening of the image (erosion followed by dilation). bwmorph supports the generation of efficient, production-quality C/C++ code from MATLAB. The text string specifying the operation must be a constant and, for best results, specify an input image of class logical. To see a complete list of toolbox functions that support code generation, see “Supported Functions”. Class Support The input image BW can be numeric or logical. It must be 2-D, real and nonsparse. The output image BW2 is of class logical. Examples BW = imread('circles.png'); imshow(BW); 3-73 bwmorph BW2 = bwmorph(BW,'remove'); figure, imshow(BW2) BW3 = bwmorph(BW,'skel',Inf); figure, imshow(BW3) 3-74 bwmorph References [1] Haralick, Robert M., and Linda G. Shapiro, Computer and Robot Vision, Vol. 1, Addison-Wesley, 1992. [2] Kong, T. Yung and Azriel Rosenfeld, Topological Algorithms for Digital Image Processing, Elsevier Science, Inc., 1996. [3] Lam, L., Seong-Whan Lee, and Ching Y. Suen, "Thinning Methodologies-A Comprehensive Survey," IEEE Transactions on Pattern Analysis and Machine Intelligence, Vol 14, No. 9, September 1992, page 879, bottom of first column through top of second column. [4] Pratt, William K., Digital Image Processing, John Wiley & Sons, Inc., 1991. Algorithms When used with the 'thin' option, bwmorph uses the following algorithm (References [3]): 1 Divide the image into two distinct subfields in a checkerboard pattern. 2 In the first subiteration, delete pixel p from the first subfield if and only if the conditions G1, G2, and G3 are all satisfied. 3 In the second subiteration, delete pixel p from the second subfield if and only if the conditions G1, G2, and G3 ′ are all satisfied. 3-75 bwmorph Condition G1: X H ( p) = 1 where 4 X H ( p) = ∑ bi i=1 ⎧ 1, if x2i−1 = 0 and ( x2i = 1 or x2i+1 = 1) bi = ⎨ ⎩0, otherwise x1, x2, ..., x8 are the values of the eight neighbors of p, starting with the east neighbor and numbered in counter-clockwise order. Condition G2: 2 ≤ min {n1 ( p), n2 ( p)} ≤ 3 where n1 ( p) = 4 ∑ x2k−1 ∨ x2k k=1 n2 ( p) = 4 ∑ x2k ∨ x2k+1 k=1 Condition G3: ( x2 ∨ x3 ∨ x8 ) ∧ x1 = 0 Condition G3’: ( x6 ∨ x7 ∨ x4 ) ∧ x5 = 0 3-76 bwmorph The two subiterations together make up one iteration of the thinning algorithm. When the user specifies an infinite number of iterations (n=Inf), the iterations are repeated until the image stops changing. The conditions are all tested using applylut with precomputed lookup tables. See Also bweuler | bwperim | imdilate | imerode 3-77 bwpack Purpose Pack binary image Syntax BWP = bwpack(BW) Description BWP = bwpack(BW) packs the uint8 binary image BW into the uint32 array BWP, which is known as a packed binary image. Because each 8-bit pixel value in the binary image has only two possible values, 1 and 0, bwpack can map each pixel to a single bit in the packed output image. bwpack processes the image pixels by column, mapping groups of 32 pixels into the bits of a uint32 value. The first pixel in the first row corresponds to the least significant bit of the first uint32 element of the output array. The first pixel in the 32nd input row corresponds to the most significant bit of this same element. The first pixel of the 33rd row corresponds to the least significant bit of the second output element, and so on. If BW is M-by-N, then BWP is ceil(M/32)-by-N. This figure illustrates how bwpack maps the pixels in a binary image to the bits in a packed binary image. 3-78 bwpack Binary image packing is used to accelerate some binary morphological operations, such as dilation and erosion. If the input to imdilate or imerode is a packed binary image, the functions use a specialized routine to perform the operation faster. bwunpack is used to unpack packed binary images. Class Support BW can be logical or numeric, and it must be 2-D, real, and nonsparse. BWP is of class uint32. Examples Pack, dilate, and unpack a binary image: BW = imread('text.png'); BWp = bwpack(BW); BWp_dilated = imdilate(BWp,ones(3,3),'ispacked'); BW_dilated = bwunpack(BWp_dilated, size(BW,1)); 3-79 bwpack See Also 3-80 bwunpack | imdilate | imerode bwperim Purpose Find perimeter of objects in binary image Syntax BW2 = bwperim(BW1) BW2 = bwperim(BW1, conn) Description BW2 = bwperim(BW1) returns a binary image containing only the perimeter pixels of objects in the input image BW1. A pixel is part of the perimeter if it is nonzero and it is connected to at least one zero-valued pixel. The default connectivity is 4 for two dimensions, 6 for three dimensions, and conndef(ndims(BW), 'minimal') for higher dimensions. BW2 = bwperim(BW1, conn) specifies the desired connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can also be defined in a more general way for any dimension by using for conn a 3-by-3-by-...-by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. Class Support BW1 must be logical or numeric, and it must be nonsparse. BW2 is of class logical. 3-81 bwperim Examples Find the perimeter of objects in an image mask. BW1 = imread('circbw.tif'); BW2 = bwperim(BW1,8); imshow(BW1) figure, imshow(BW2) See Also 3-82 bwarea | bwboundaries | bweuler | bwtraceboundary | conndef | imfill bwselect Purpose Select objects in binary image Syntax BW2 = bwselect(BW,c,r,n) BW2 = bwselect(BW,n) [BW2,idx] = bwselect(...) BW2 = bwselect(x,y,BW,xi,yi,n) [x,y,BW2,idx,xi,yi] = bwselect(...) Description BW2 = bwselect(BW,c,r,n) returns a binary image containing the objects that overlap the pixel (r,c). r and c can be scalars or equal-length vectors. If r and c are vectors, BW2 contains the sets of objects overlapping with any of the pixels (r(k),c(k)). n can have a value of either 4 or 8 (the default), where 4 specifies 4-connected objects and 8 specifies 8-connected objects. Objects are connected sets of on pixels (i.e., pixels having a value of 1). BW2 = bwselect(BW,n) displays the image BW on the screen and lets you select the (r,c) coordinates using the mouse. If you omit BW, bwselect operates on the image in the current axes. Use normal button clicks to add points. Pressing Backspace or Delete removes the previously selected point. A shift-click, right-click, or double-click selects the final point; pressing Return finishes the selection without adding a point. [BW2,idx] = bwselect(...) returns the linear indices of the pixels belonging to the selected objects. BW2 = bwselect(x,y,BW,xi,yi,n) uses the vectors x and y to establish a nondefault spatial coordinate system for BW1. xi and yi are scalars or equal-length vectors that specify locations in this coordinate system. [x,y,BW2,idx,xi,yi] = bwselect(...) returns the XData and YData in x and y, the output image in BW2, linear indices of all the pixels belonging to the selected objects in idx, and the specified spatial coordinates in xi and yi. If bwselect is called with no output arguments, the resulting image is displayed in a new figure. 3-83 bwselect 3-84 Class Support The input image BW can be logical or numeric and must be 2-D and nonsparse. The output image BW2 is of class logical. Examples BW1 = imread('text.png'); c = [43 185 212]; r = [38 68 181]; BW2 = bwselect(BW1,c,r,4); imshow(BW1), figure, imshow(BW2) See Also bwlabel | imfill | impixel | roipoly | roifill bwtraceboundary Purpose Trace object in binary image Syntax B = bwtraceboundary(BW,P,fstep) B = bwtraceboundary(BW,P,fstep,conn) B = bwtraceboundary(...,N,dir) Description B = bwtraceboundary(BW, P,fstep) traces the outline of an object in binary image bw. Nonzero pixels belong to an object and 0 pixels constitute the background. P is a two-element vector specifying the row and column coordinates of the point on the object boundary where you want the tracing to begin. fstep is a string specifying the initial search direction for the next object pixel connected to P. You use strings such as 'N' for north, 'NE' for northeast, to specify the direction. The following figure illustrates all the possible values for fstep. bwtraceboundary returns B, a Q-by-2 matrix, where Q is the number of boundary pixels for the region. B holds the row and column coordinates of the boundary pixels. B = bwtraceboundary(bw, P, fstep, conn) specifies the connectivity to use when tracing the boundary. conn can have either of the following scalar values. 3-85 bwtraceboundary Value Meaning 4 4-connected neighborhood Note With this connectivity, fstep is limited to the following values: 'N', 'E', 'S', and 'W'. 8 8-connected neighborhood. This is the default. B = bwtraceboundary(...,N,dir) specifies n, the maximum number of boundary pixels to extract, and dir, the direction in which to trace the boundary. When N is set to Inf, the default value, the algorithm identifies all the pixels on the boundary. dir can have either of the following values: Value Meaning 'clockwise' Search in a clockwise direction. This is the default. 'counterclockwise' Search in counterclockwise direction. BW can be logical or numeric and it must be real, 2-D, and nonsparse. B, P, conn, and N are of class double. dir and fstep are strings. Examples Read in and display a binary image. Starting from the top left, project a beam across the image searching for the first nonzero pixel. Use the location of that pixel as the starting point for the boundary tracing. Including the starting point, extract 50 pixels of the boundary and overlay them on the image. Mark the starting points with a green x. Mark beams that missed their targets with a red x. BW = imread('blobs.png'); imshow(BW,[]); s=size(BW); for row = 2:55:s(1) for col=1:s(2) 3-86 bwtraceboundary if BW(row,col), break; end end contour = bwtraceboundary(BW, [row, col], 'W', 8, 50,... 'counterclockwise'); if(~isempty(contour)) hold on; plot(contour(:,2),contour(:,1),'g','LineWidth',2); hold on; plot(col, row,'gx','LineWidth',2); else hold on; plot(col, row,'rx','LineWidth',2); end end bwboundaries, bwperim 3-87 bwulterode Purpose Ultimate erosion Syntax BW2 = bwulterode(BW) BW2 = bwulterode(BW,method,conn) Description BW2 = bwulterode(BW) computes the ultimate erosion of the binary image BW. The ultimate erosion of BW consists of the regional maxima of the Euclidean distance transform of the complement of BW. The default connectivity for computing the regional maxima is 8 for two dimensions, 26 for three dimensions, and conndef(ndims(BW), 'maximal') for higher dimensions. BW2 = bwulterode(BW,method,conn) specifies the distance transform method and the regional maxima connectivity. method can be one of the strings 'euclidean', 'cityblock', 'chessboard', and 'quasi-euclidean'. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by... - by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. 3-88 bwulterode Class Support BW can be numeric or logical and it must be nonsparse. It can have any dimension. The return value BW2 is always a logical array. Examples originalBW = imread('circles.png'); imshow(originalBW) ultimateErosion = bwulterode(originalBW); figure, imshow(ultimateErosion) See Also bwdist | conndef | imregionalmax 3-89 bwunpack Purpose Unpack binary image Syntax BW = bwunpack(BWP,m) Description BW = bwunpack(BWP,m) unpacks the packed binary image BWP. BWP is a uint32 array. When it unpacks BWP, bwunpack maps the least significant bit of the first row of BWP to the first pixel in the first row of BW. The most significant bit of the first element of BWP maps to the first pixel in the 32nd row of BW, and so on. BW is M-by-N, where N is the number of columns of BWP. If m is omitted, its default value is 32*size(BWP,1). Binary image packing is used to accelerate some binary morphological operations, such as dilation and erosion. If the input to imdilate or imerode is a packed binary image, the functions use a specialized routine to perform the operation faster. bwpack is used to create packed binary images. Class Support BWP is of class uint32 and must be real, 2-D, and nonsparse. The return value BW is of class uint8. Examples Pack, dilate, and unpack a binary image. bw = imread('text.png'); bwp = bwpack(bw); bwp_dilated = imdilate(bwp,ones(3,3),'ispacked'); bw_dilated = bwunpack(bwp_dilated, size(bw,1)); See Also 3-90 bwpack | imdilate | imerode checkerboard Purpose Create checkerboard image Syntax I = checkerboard I = checkerboard(n) I = checkerboard(n,p,q) Description I = checkerboard creates an 8-by-8 square checkerboard image that has four identifiable corners. Each square has 10 pixels per side. The light squares on the left half of the checkerboard are white. The light squares on the right half of the checkerboard are gray. I = checkerboard(n) creates a checkerboard image where each square has n pixels per side. I = checkerboard(n,p,q) creates a rectangular checkerboard where p specifies the number of rows and q specifies the number of columns. If you omit q, it defaults to p and the checkerboard is square. Each row and column is made up of tiles. Each tile contains four squares, n pixels per side, defined as TILE = [DARK LIGHT; LIGHT DARK] The light squares on the left half of the checkerboard are white. The light squares on the right half of the checkerboard are gray. Examples Create a checkerboard where the side of every square is 20 pixels in length. I = checkerboard(20);imshow(I) 3-91 checkerboard Create a rectangular checkerboard that is 2 tiles in height and 3 tiles wide. J = checkerboard(10,2,3); figure, imshow(J) Create a black and white checkerboard. K = (checkerboard > 0.5); figure, imshow(K) See Also 3-92 cp2tform | imtransform | maketform col2im Purpose Rearrange matrix columns into blocks Syntax A = col2im(B,[m n],[mm nn],'distinct') A = col2im(B,[m n],[mm nn],'sliding') Description A = col2im(B,[m n],[mm nn],'distinct') rearranges each column of B into a distinct m-by-n block to create the matrix A of size mm-by-nn. If B = [A11(:) A21(:) A12(:) A22(:)], where each column has length m*n, then A = [A11 A12; A21 A22] where each Aij is m-by-n. A = col2im(B,[m n],[mm nn],'sliding') rearranges the row vector B into a matrix of size (mm-m+1)-by-(nn-n+1). B must be a vector of size 1-by-(mm-m+1)*(nn-n+1). B is usually the result of processing the output of im2col(...,'sliding') using a column compression function (such as sum). col2im(B,[m n],[mm nn]) is the same as col2im(B, [m n], [mm nn],'sliding'). Class Support B can be logical or numeric. The return value A is of the same class as B. Examples B = reshape(uint8(1:25),[5 5])' C = im2col(B,[1 5]) A = col2im(C,[1 5],[5 5],'distinct') See Also blockproc | colfilt | im2col | nlfilter 3-93 colfilt Purpose Columnwise neighborhood operations Syntax B = colfilt(A,[m n],block_type,fun) B = colfilt(A,[m n],[mblock nblock],block_type,fun) B = colfilt(A,'indexed',...) Description B = colfilt(A,[m n],block_type,fun) processes the image A by rearranging each m-by-n block of A into a column of a temporary matrix, and then applying the function fun to this matrix. fun must be a function handle. Parameterizing Functions, in the MATLAB Mathematics documentation, explains how to provide additional parameters to the function fun. The function colfilt zero-pads A, if necessary. Before calling fun, colfilt calls im2col to create the temporary matrix. After calling fun, colfilt rearranges the columns of the matrix back into m-by-n blocks using col2im. block_type is a string that can have one of the values listed in this table. Note colfilt can perform operations similar to blockproc and nlfilter, but often executes much faster. Value Description 'distinct' Rearranges each m-by-n distinct block of A into a column in a temporary matrix, and then applies the function fun to this matrix. fun must return a matrix the same size as the temporary matrix. colfilt then rearranges the columns of the matrix returned by fun into m-by-n distinct blocks. 'sliding' 3-94 Rearranges each m-by-n sliding neighborhood of A into a column in a temporary matrix, and then applies the function fun to this matrix. fun must return a row vector containing a single value for each column in the colfilt Value Description temporary matrix. (Column compression functions such as sum return the appropriate type of output.) colfilt then rearranges the vector returned by fun into a matrix the same size as A. B = colfilt(A,[m n],[mblock nblock],block_type,fun) processes the matrix A as above, but in blocks of size mblock-by-nblock to save memory. Note that using the [mblock nblock] argument does not change the result of the operation. B = colfilt(A,'indexed',...) processes A as an indexed image, padding with 0’s if the class of A is uint8 or uint16, or 1’s if the class of A is double or single. Note To save memory, the colfilt function might divide A into subimages and process one subimage at a time. This implies that fun may be called multiple times, and that the first argument to fun may have a different number of columns each time. Class Support The input image A can be of any class supported by fun. The class of B depends on the class of the output from fun. Examples Set each output pixel to the mean value of the input pixel’s 5-by-5 neighborhood. I = imread('tire.tif'); imshow(I) I2 = uint8(colfilt(I,[5 5],'sliding',@mean)); figure, imshow(I2) See Also blockproc | col2im | function_handle | im2col | nlfilter 3-95 colfilt How To • “Anonymous Functions” • “Parameterizing Functions” 3-96 conndef Purpose Create connectivity array Syntax conn = conndef(num_dims,type) Description conn = conndef(num_dims,type) returns the connectivity array defined by type for num_dims dimensions. type can have either of the values listed in this table. Value Description 'minimal' Defines a neighborhood whose neighbors are touching the central element on an (N-1)-dimensional surface, for the N-dimensional case. 'maximal' Defines a neighborhood including neighbors that touch the central element in any way; it is ones(repmat(3,1,NUM_DIMS)). Several Image Processing Toolbox functions use conndef to create the default connectivity input argument. Examples The minimal connectivity array for two dimensions includes the neighbors touching the central element along a line. conn1 = conndef(2,'minimal') conn1 = 0 1 0 1 1 1 0 1 0 The minimal connectivity array for three dimensions includes all the neighbors touching the central element along a face. conndef(3,'minimal') ans(:,:,1) = 0 0 0 3-97 conndef 0 0 1 0 0 0 ans(:,:,2) 0 1 0 = 1 1 1 0 1 0 ans(:,:,3) 0 0 0 = 0 1 0 0 0 0 The maximal connectivity array for two dimensions includes all the neighbors touching the central element in any way. conn2 = conndef(2,'maximal') conn2 = 1 1 1 3-98 1 1 1 1 1 1 convmtx2 Purpose 2-D convolution matrix Syntax T = convmtx2(H,m,n) T = convmtx2(H,[m n]) Description T = convmtx2(H,m,n) returns the convolution matrix T for the matrix H. If X is an m-by-n matrix, then reshape(T*X(:),size(H)+[m n]-1) is the same as conv2(X,H). T = convmtx2(H,[m n]) returns the convolution matrix, where the dimensions m and n are a two-element vector. Class Support The inputs are all of class double. The output matrix T is of class sparse. The number of nonzero elements in T is no larger than prod(size(H))*m*n. See Also conv2 | convmtx 3-99 corner Purpose Find corner points in image Syntax C C C C C Description C = corner(I) detects corners in image I and returns them in matrix C. = = = = = corner(I) corner(I, method) corner(I, N) corner(I, method, N) corner(..., Name,Value) C = corner(I, method) detects corners in image I using the specified method. C = corner(I, N) detects corners in image I and returns a maximum of N corners. C = corner(I, method, N) detects corners using the specified method and maximum number of corners. C = corner(..., Name,Value) specifies parameters and corresponding values that control various aspects of the corner detection algorithm. Tips The corner and cornermetric functions both detect corners in images. For most applications, use the streamlined corner function to find corners in one step. If you want greater control over corner selection, use the cornermetric function to compute a corner metric matrix and then write your own algorithm to find peak values. Input Arguments I A grayscale or binary image. method The algorithm used to detect corners. Supported methods are: • 'Harris': The Harris corner detector. • 'MinimumEigenvalue': Shi & Tomasi’s minimum eigenvalue method. 3-100 corner Default: 'Harris' N The maximum number of corners the corner function can return. Default: 200 Name-Value Pair Arguments Specify optional comma-separated pairs of Name,Value arguments, where Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN. FilterCoefficients A vector, V, of filter coefficients for the separable smoothing filter. The outer product, V*V', gives the full filter kernel. Default: fspecial('gaussian',[5 1],1.5) QualityLevel A scalar value, Q, where 0 < Q < 1, specifying the minimum accepted quality of corners. When candidate corners have corner metric values less than Q * max(corner metric), the toolbox rejects them. Use larger values of Q to remove erroneous corners. Default: 0.01 SensitivityFactor A scalar value, K, where 0 < K < 0.25, specifying the sensitivity factor used in the Harris detection algorithm. The smaller the value of K, the more likely the algorithm is to detect sharp corners. Use this parameter with the 'Harris' method only. Default: 0.04 3-101 corner Output Arguments C Class Support I is a nonsparse numeric array. C is a matrix of class double. Examples Find and plot corner points in a checkerboard image. An M-by-2 matrix containing the X and Y coordinates of the corner points detected in I. I = checkerboard(50,2,2); C = corner(I); imshow(I); hold on plot(C(:,1), C(:,2), 'r*'); Algorithms 3-102 The corner function performs nonmaxima suppression on candidate corners, and corners are at least two pixels apart. corner See Also cornermetric How To • “Detecting Corners Using the corner Function” 3-103 cornermetric Purpose Create corner metric matrix from image Description CM = cornermetric(I) generates a corner metric matrix for the grayscale or logical image I. The corner metric, CM, is used to detect corner features in I and is the same size as I. Larger values in CM correspond to pixels in I with a higher likelihood of being a corner feature. CM = cornermetric(I, method) generates a corner metric matrix for the grayscale or logical image I using the specified method. Valid values for method are: Value Description 'Harris' The Harris corner detector. This is the default method. 'MinimumEigenvalue' Shi and Tomasi’s minimum eigenvalue method. CM = cornermetric(..., param1, val1, param2, val2, ...) generates a corner metric matrix for I, specifying parameters and corresponding values that control various aspects of the corner metric calculation algorithm. Parameters include: 3-104 Parameter Description 'FilterCoefficients' A vector, V, of filter coefficients for the separable smoothing filter. This parameter is valid with the 'Harris' and 'MinimumEigenvalue' methods. The outer product, V*V', gives the full filter kernel. The default is fspecial('gaussian',[5 1],1.5). 'SensitivityFactor' A scalar k, 0 < k < 0.25, specifying the sensitivity factor used in the Harris detection algorithm. For smaller values of k, the algorithm is more likely to cornermetric Parameter Description detect sharper corners. This parameter is only valid with the 'Harris' method. Default value: 0.04 Tips The corner and cornermetric functions both detect corners in images. For most applications, use the streamlined corner function to find corners in one step. If you want greater control over corner selection, use the cornermetric function to compute a corner metric matrix and then write your own algorithm to find peak values. Class Support I is a nonsparse numeric array. CM is a matrix of class double. Examples Find corner features in grayscale image. First generate a corner metric matrix. I = imread('pout.tif'); I = I(1:150,1:120); subplot(1,3,1); imshow(I); title('Original Image'); CM = cornermetric(I); Adjust corner metric for viewing. CM_adjusted = imadjust(CM); subplot(1,3,2); imshow(CM_adjusted); title('Corner Metric'); Find and display some corner features. corner_peaks = imregionalmax(CM); corner_idx = find(corner_peaks == true); [r g b] = deal(I); 3-105 cornermetric r(corner_idx) = 255; g(corner_idx) = 255; b(corner_idx) = 0; RGB = cat(3,r,g,b); subplot(1,3,3); imshow(RGB); title('Corner Points'); The following figure shows the output of these operations. See Also 3-106 corner | edge | immovie | imshow corr2 Purpose 2-D correlation coefficient Syntax r = corr2(A,B) Description r = corr2(A,B) computes the correlation coefficient between A and B, where A and B are matrices or vectors of the same size. Class Support A and B can be numeric or logical. The return value r is a scalar double. Examples Compute the correlation coefficient between an image and the same image processed with a median filter. I = imread('pout.tif'); J = medfilt2(I); R = corr2(I,J) R = 0.9959 Algorithms corr2 computes the correlation coefficient using r= ∑ ∑ ( Amn − A)( Bmn − B) m n ⎛ ⎜ ∑ ∑ Amn − A ⎜ ⎝m n ( 2 ⎞⎛ ) ⎟⎟ ⎜⎜ ∑ ∑ ( Bmn − B) ⎠⎝ m n 2⎞ ⎟ ⎟ ⎠ where A = mean2(A), and B = mean2(B). See Also std2 | corrcoef 3-107 cp2tform Purpose Infer spatial transformation from control point pairs Syntax TFORM = cp2tform(input_points, base_points, transformtype) TFORM = cp2tform(CPSTRUCT, transformtype) [TFORM, input_points, base_points] = cp2tform(CPSTRUCT, ...) TFORM = cp2tform(input_points, base_points, 'polynomial', order) TFORM = cp2tform(CPSTRUCT, 'polynomial',order) TFORM = cp2tform(input_points, base_points, 'piecewise linear') TFORM = cp2tform(CPSTRUCT, 'piecewise linear') TFORM = cp2tform(input_points, base_points, 'lwm', N) TFORM = cp2tform(CPSTRUCT, 'lwm', N) [TFORM, input_points, base_points, input_points_bad, base_points_bad] = cp2tform(input_points, base_points, 'piecewise linear') [TFORM, input_points, base_points, input_points_bad, base_points_bad] = cp2tform(CPSTRUCT, 'piecewise linear') Description TFORM = cp2tform(input_points, base_points, transformtype) infers a spatial transformation from control point pairs and returns this transformation as a TFORM structure. TFORM = cp2tform(CPSTRUCT, transformtype) works on a CPSTRUCT structure that contains the control point matrices for the input and base images. The Control Point Selection Tool, cpselect, creates the CPSTRUCT. [TFORM, input_points, base_points] = cp2tform(CPSTRUCT, ...) returns the control points that were used in input_points and base_points. Unmatched and predicted points are not used. See cpstruct2pairs. TFORM = cp2tform(input_points, base_points, 'polynomial', order) lets you specify the order of the polynomials to use. 3-108 cp2tform TFORM = cp2tform(CPSTRUCT, 'polynomial',order) works on a CPSTRUCT structure. TFORM = cp2tform(input_points, base_points, 'piecewise linear') creates a Delaunay triangulation of the base control points, and maps corresponding input control points to the base control points. The mapping is linear (affine) for each triangle and continuous across the control points but not continuously differentiable as each triangle has its own mapping. TFORM = cp2tform(CPSTRUCT, 'piecewise linear') works on a CPSTRUCT structure. TFORM = cp2tform(input_points, base_points, 'lwm', N) creates a mapping by inferring a polynomial at each control point using neighboring control points. The mapping at any location depends on a weighted average of these polynomials. You can optionally specify the number of points, N, used to infer each polynomial. The N closest points are used to infer a polynomial of order 2 for each control point pair. If you omit N, it defaults to 12. N can be as small as 6, but making N small risks generating ill-conditioned polynomials. TFORM = cp2tform(CPSTRUCT, 'lwm', N) works on a CPSTRUCT structure. [TFORM, input_points, base_points, input_points_bad, base_points_bad] = cp2tform(input_points, base_points, 'piecewise linear') returns the control points that were used in input_points and base_points and the control points that were eliminated because they were middle vertices of degenerate fold-over triangles in input_points_bad and base_points_bad. [TFORM, input_points, base_points, input_points_bad, base_points_bad] = cp2tform(CPSTRUCT, 'piecewise linear') works on a CPSTRUCT structure. Tips • When transformtype is 'nonreflective similarity', 'similarity', 'affine', 'projective', or 'polynomial', and input_points and base_points (or CPSTRUCT) have the minimum 3-109 cp2tform number of control points needed for a particular transformation, cp2tform finds the coefficients exactly. • If input_points and base_points have more than the minimum number of control points, a least-squares solution is found. See mldivide. • When either input_points or base_points has a large offset with respect to their origin (relative to range of values that it spans), cp2tform shifts the points to center their bounding box on the origin before fitting a TFORM structure. This enhances numerical stability and is handled transparently by wrapping the origin-centered TFORM within a custom TFORM that automatically applies and undoes the coordinate shift as needed. As a result, fields(T) can give different results for different coordinate inputs, even for the same transformation type. Input Arguments input_points m-by-2, double matrix containing the x- and y-coordinates of control points in the image you want to transform. base_points m-by-2, double matrix containing the x- and y-coordinates of control points in the base image. transformtype Specifies the type of spatial transformation to infer. The cp2tform function requires a minimum number of control point pairs to infer a structure of each transform type. The following table lists all the transformation types supported by cp2tform in order of complexity. The 'lwm' and 'polynomial' transform types can each take an optional, additional parameter. 3-110 cp2tform Transformation Types Transformation Type Description Minimum Number of Control Point Pairs 'nonreflective similarity' Use this transformation when shapes in the input image are unchanged, but the image is distorted by some combination of translation, rotation, and scaling. Straight lines remain straight, and parallel lines are still parallel. 2 'similarity' Same as 'nonreflective similarity' with the addition of optional reflection. 3 'affine' Use this transformation when shapes in the input image exhibit shearing. Straight lines remain straight, and parallel lines remain parallel, but rectangles become parallelograms. 3 'projective' Use this transformation when the scene appears tilted. Straight lines remain straight, but parallel lines converge toward vanishing points that might or might not fall within the image. 4 'polynomial' Use this transformation when objects in the image are curved. The higher the order of the polynomial, the better the fit, but the result can contain more curves than the base image. 6 (order 2) Example 10 (order 3) 15 (order 4) 3-111 cp2tform Transformation Type Description Minimum Number of Control Point Pairs 'piecewise linear' Use this transformation when parts of the image appear distorted differently. 4 'lwm' Use this transformation (local weighted mean), when the distortion varies locally and piecewise linear is not sufficient. 6 (12 recommended) Example CPSTRUCT Structure containing control point matrices for the input and base images. Use the Control Point Selection Tool (cpselect) to create the CPSTRUCT. ’polynomial’,order Specifies the order of polynomials to use. order can be 2, 3, or 4. Default: 3 ’piecewise linear’ Linear for each piece and continuous, not continuously differentiable. ’lwm’ Local weighted mean. N Number of points. Output Arguments 3-112 TFORM Structure containing the spatial transformation. cp2tform input_points Input control points that were used to infer the spatial transformation. Unmatched and predicted points are not used. base_points Base control points that were used to infer the spatial transformation. Unmatched and predicted points are not used. input_points_bad Input control points that were eliminated because they were determined to be outliers. base_points_bad Base control points that were eliminated because they were determined to be outliers. Examples Transform an image, use the cp2tform function to return the transformation, and compare the angle and scale of the TFORM to the angle and scale of the original transformation: I = checkerboard; J = imrotate(I,30); base_points = [11 11; 41 71]; input_points = [14 44; 70 81]; cpselect(J,I,input_points,base_points); t = cp2tform(input_points,base_points,'nonreflective similarity'); % Recover angle and scale by checking how a unit vector % parallel to the x-axis is rotated and stretched. u = [0 1]; v = [0 0]; [x, y] = tformfwd(t, u, v); dx = x(2) - x(1); dy = y(2) - y(1); 3-113 cp2tform angle = (180/pi) * atan2(dy, dx) scale = 1 / sqrt(dx^2 + dy^2) Algorithms cp2tform uses the following general procedure: 1 Use valid pairs of control points to infer a spatial transformation or an inverse mapping from output space (x,y) to input space (x,y) according to transformtype. 2 Return the TFORM structure containing spatial transformation. The procedure varies depending on the transformtype. Nonreflective Similarity Nonreflective similarity transformations can include a rotation, a scaling, and a translation. Shapes and angles are preserved. Parallel lines remain parallel. Straight lines remain straight. Let sc = scale*cos(angle) ss = scale*sin(angle) [u v] = [x y 1] * [ sc -ss ss sc tx ty] Solve for sc, ss, tx, and ty. Similarity Similarity transformations can include rotation, scaling, translation, and reflection. Shapes and angles are preserved. Parallel lines remain parallel. Straight lines remain straight. Let sc = s*cos(theta) ss = s*sin(theta) 3-114 cp2tform [u v] = [x y 1] * [ sc -a*-ss ss a*sc tx ty] Solve for sc, ss, tx, ty, and a. If a = -1, reflection is included in the transformation. If a = 1, reflection is not included in the transformation. Affine In an affine transformation, the x and y dimensions can be scaled or sheared independently and there can be a translation. Parallel lines remain parallel. Straight lines remain straight. Nonreflective similarity transformations are a subset of affine transformations. For an affine transformation, [u v] = [x y 1] * Tinv Tinv is a 3-by-2 matrix. Solve for the six elements of Tinv: t_affine = cp2tform(input_points,base_points,'affine'); The coefficients of the inverse mapping are stored in t_affine.tdata.Tinv. At least three control-point pairs are needed to solve for the six unknown coefficients. Projective In a projective transformation, quadrilaterals map to quadrilaterals. Straight lines remain straight. Affine transformations are a subset of projective transformations. For a projective transformation, [up vp wp] = [x y w] * Tinv where u = up/wp 3-115 cp2tform v = vp/wp Tinv is a 3-by-3 matrix. Assuming Tinv = [ A D B E C F u = (Ax + By v = (Dx + Ey G; H; I ]; + C)/(Gx + Hy + I) + F)/(Gx + Hy + I) Solve for the nine elements of Tinv: t_proj = cp2tform(input_points,base_points,'projective'); The coefficients of the inverse mapping are stored in t_proj.tdata.Tinv. At least four control-point pairs are needed to solve for the nine unknown coefficients. Note An affine or projective transformation can also be expressed like this, for a 3-by-2 Tinv: [u v]' = Tinv' * [x y 1]' Or, like this, for a 3-by-3 Tinv: [u v 1]' = Tinv' * [x y 1]' Polynomial In a polynomial transformation, polynomial functions of x and y determine the mapping. 3-116 cp2tform Second-Order Polynomials For a second-order polynomial transformation, [u v] = [1 x y x*y x^2 y^2] * Tinv Both u and v are second-order polynomials of x and y. Each second-order polynomial has six terms. To specify all coefficients, Tinv has size 6-by-2. t_poly_ord2 = cp2tform(input_points, base_points,'polynomial'); The coefficients of the inverse mapping are stored in t_poly_ord2.tdata. At least six control-point pairs are needed to solve for the 12 unknown coefficients. Third-Order Polynomials For a third-order polynomial transformation: [u v] = [1 x y x*y x^2 y^2 y*x^2 x*y^2 x^3 y^3] * Tinv Both u and v are third-order polynomials of x and y. Each third-order polynomial has 10 terms. To specify all coefficients, Tinv has size 10-by-2. t_poly_ord3 = cp2tform(input_points, base_points,'polynomial',3); The coefficients of the inverse mapping are stored in t_poly_ord3.tdata. At least ten control-point pairs are needed to solve for the 20 unknown coefficients. 3-117 cp2tform Fourth-Order Polynomials For a fourth-order polynomial transformation: [u v] = [1 x y x*y x^2 y^2 y*x^2 x*y^2 x^3 y^3 x^3*y x^2*y^2 x*y^3 x^4 y^4] * Tinv Both u and v are fourth-order polynomials of x and y. Each fourth-order polynomial has 15 terms. To specify all coefficients, Tinv has size 15-by-2. t_poly_ord4 = cp2tform(input_points, base_points,'polynomial',4); The coefficients of the inverse mapping are stored in t_poly_ord4.tdata. At least 15 control-point pairs are needed to solve for the 30 unknown coefficients. Piecewise Linear In a piecewise linear transformation, linear (affine) transformations are applied separately to each triangular region of the image[1]. 1 Find a Delaunay triangulation of the base control points. 2 Using the three vertices of each triangle, infer an affine mapping from base to input coordinates. Note At least four control-point pairs are needed. Four pairs result in two triangles with distinct mappings. Local Weighted Mean For each control point in base_points: 1 Find the N closest control points. 2 Use these N points and their corresponding points in input_points to infer a second-order polynomial. 3-118 cp2tform 3 Calculate the radius of influence of this polynomial as the distance from the center control point to the farthest point used to infer the polynomial (using base_points)[2]. Note At least six control-point pairs are needed to solve for the second-order polynomial. Ill-conditioned polynomials might result if too few pairs are used. References [1] Goshtasby, Ardeshir, "Piecewise linear mapping functions for image registration," Pattern Recognition, Vol. 19, 1986, pp. 459-466. [2] Goshtasby, Ardeshir, "Image registration by local approximation methods," Image and Vision Computing, Vol. 6, 1988, pp. 255-261. See Also cpcorr | cpselect | cpstruct2pairs | imtransform | tformfwd | tforminv 3-119 cpcorr Purpose Tune control-point locations using cross correlation Syntax input_points = cpcorr(input_points_in, base_points_in, input, base) Description input_points = cpcorr(input_points_in, base_points_in, input,base) uses normalized cross-correlation to adjust each pair of control points specified in input_points_in and base_points_in. input_points_in must be an M-by-2 double matrix containing the coordinates of control points in the input image. base_points_in is an M-by-2 double matrix containing the coordinates of control points in the base image. cpcorr returns the adjusted control points in input_points, a double matrix the same size as input_points_in. If cpcorr cannot correlate a pair of control points, input_points contains the same coordinates as input_points_in for that pair. cpcorr only moves the position of a control point by up to four pixels. Adjusted coordinates are accurate to one-tenth of a pixel. cpcorr is designed to get subpixel accuracy from the image content and coarse control-point selection. Note input and base images must have the same scale for cpcorr to be effective. cpcorr cannot adjust a point if any of the following occur: • Points are too near the edge of either image. • Regions of images around points contain Inf or NaN. • Region around a point in input image has zero standard deviation. • Regions of images around points are poorly correlated. 3-120 cpcorr Class Support The images input and base can be numeric and must contain finite values. The control-point pairs are of class double. Algorithms cpcorr uses the following general procedure. For each control-point pair, 1 Extract an 11-by-11 template around the input control point and a 21-by-21 region around the base control point. 2 Calculate the normalized cross-correlation of the template with the region. 3 Find the absolute peak of the cross-correlation matrix. 4 Use the position of the peak to adjust the coordinates of the input control point. Examples Use cpcorr to fine-tune control points selected in an image. Note the difference in the values of the input_points matrix and the input_points_adj matrix. input = imread('onion.png'); base = imread('peppers.png'); input_points = [127 93; 74 59]; base_points = [323 195; 269 161]; input_points_adj = cpcorr(input_points,base_points,... input(:,:,1),base(:,:,1)) input_points_adj = 127.0000 71.0000 See Also 93.0000 59.6000 cp2tform | cpselect | imtransform | normxcorr2 3-121 cpselect Purpose Control Point Selection Tool Syntax cpselect(input, base) cpselect(input, base, CPSTRUCT_IN) cpselect(input, base, xyinput_in, xybase_in) h = cpselect(input, base,...) cpselect(...,param1, val1,...) Description cpselect(input, base) starts the Control Point Selection Tool, a graphical user interface that enables you to select control points in two related images. input is the image that needs to be warped to bring it into the coordinate system of the base image. input and base can be either variables that contain grayscale, truecolor, or binary images, or strings that identify files containing these images. The Control Point Selection Tool returns the control points in a CPSTRUCT structure. (For more information, see “Specifying Control Points Using the Control Point Selection Tool”.) cpselect(input, base, CPSTRUCT_IN) starts cpselect with an initial set of control points that are stored in CPSTRUCT_IN. This syntax allows you to restart cpselect with the state of control points previously saved in CPSTRUCT_IN. cpselect(input, base, xyinput_in, xybase_in) starts cpselect with a set of initial pairs of control points. xyinput_in and xybase_in are m-by-2 matrices that store the input and base coordinates, respectively. h = cpselect(input, base,...) returns a handle h to the tool. You can use the close(h) syntax to close the tool from the command line. cpselect(...,param1, val1,...) starts cpselect, specifying parameters and corresponding values that control various aspects of the tool. Parameter names can be abbreviated, and case does not matter. Parameters include: 3-122 cpselect Parameter Description 'Wait' Logical scalar that controls whether cpselect waits for the user to finish the task of selecting points. If set to false (the default), you can run cpselect at the same time as you run other programs in MATLAB. If set to true, you must finish the task of selecting points before doing anything else in MATLAB. Note When 'Wait' is set to true, cpselect returns the selected pairs of points, not a handle to the tool: [xyinput_out, xybase_out] = cpselect(...,'Wait', true) xyinput_out and xybase_out are P-by-2 matrices that store the input and base image coordinates, respectively. Class Support The images can be grayscale, truecolor, or binary. A grayscale image can be uint8, uint16, int16, single, or double. A truecolor image can be uint8, uint16, single, or double. A binary image is of class logical. Algorithms cpselect uses the following general procedure for control-point prediction. 1 Find all valid pairs of control points. 2 Infer a spatial transformation between input and base control points using method that depends on the number of valid pairs, as follows: 3-123 cpselect 2 pairs Nonreflective similarity 3 pairs Affine 4 or more pairs Projective 3 Apply spatial transformation to the new point to generate the predicted point. 4 Display predicted point. Examples Start Control Point Selection tool with saved images. cpselect('westconcordaerial.png','westconcordorthophoto.png') Start Control Point Selection tool with images and control points stored in variables in the workspace. I = checkerboard; J = imrotate(I,30); base_points = [11 11; 41 71]; input_points = [14 44; 70 81]; cpselect(J, I, input_points, base_points); Use cpselect in a script, specifying the 'wait' parameter to block until control point selection is complete. aerial = imread('westconcordaerial.png'); figure, imshow(aerial) figure, imshow('westconcordorthophoto.png') load westconcordpoints % load preselected control points % Block the tool until you pick some more control points [aerial_points,ortho_points] = ... cpselect(aerial,'westconcordorthophoto.png',... input_points,base_points,... 'Wait',true); 3-124 cpselect t_concord = cp2tform(aerial_points,ortho_points,'projective'); info = imfinfo('westconcordorthophoto.png'); aerial_registered = imtransform(aerial, t_concord,... 'XData',[1 info.Width],... 'YData',[1 info.Height]); figure, imshow(aerial_registered) See Also cpcorr | cp2tform | cpstruct2pairs | imtransform How To • “Geometric Transformation and Image Registration” 3-125 cpstruct2pairs Purpose Convert CPSTRUCT to valid pairs of control points Syntax [input_points, base_points] = cpstruct2pairs(CPSTRUCT) Description [input_points, base_points] = cpstruct2pairs(CPSTRUCT) takes a CPSTRUCT (produced by cpselect) and returns the arrays of coordinates of valid control point pairs in input_points and base_points. cpstruct2pairs eliminates unmatched points and predicted points. Examples Start the Control Point Selection Tool, cpselect. aerial = imread('westconcordaerial.png'); cpselect(aerial(:,:,1),'westconcordorthophoto.png') Using cpselect, pick control points in the images. Select Export Points to Workspace from the File menu to save the points to the workspace. On the Export Points to Workspace dialog box, check the Structure with all points check box and clear Input points of valid pairs and Base points of valid pairs. Click OK. Use cpstruct2pairs to extract the input and base points from the CPSTRUCT. [input_points,base_points] = cpstruct2pairs(cpstruct); See Also 3-126 cp2tform | cpselect | imtransform dct2 Purpose 2-D discrete cosine transform Syntax B = dct2(A) B = dct2(A,m,n) B = dct2(A,[m n]) Description B = dct2(A) returns the two-dimensional discrete cosine transform of A. The matrix B is the same size as A and contains the discrete cosine transform coefficients B(k1,k2). B = dct2(A,m,n) pads the matrix A with 0’s to size m-by-n before transforming. If m or n is smaller than the corresponding dimension of A, dct2 truncates A. B = dct2(A,[m n]) same as above. Class Support A can be numeric or logical. The returned matrix B is of class double. Algorithms The discrete cosine transform (DCT) is closely related to the discrete Fourier transform. It is a separable linear transformation; that is, the two-dimensional transform is equivalent to a one-dimensional DCT performed along a single dimension followed by a one-dimensional DCT in the other dimension. The definition of the two-dimensional DCT for an input image A and output image B is B pq = p q M −1 N −1 ∑ ∑ Amn cos m =0 n =0 (2m + 1) p (2n + 1) q 0 ≤ p ≤ M − 1 cos , 0 ≤ q ≤ N −1 2M 2N where ⎧ 1 ⎪ M, p=0 ⎪ p = ⎨ ⎪ 2 , 1 ≤ p ≤ M -1 ⎪⎩ M 3-127 dct2 and ⎧ 1 ⎪ N , q=0 ⎪ q = ⎨ ⎪ 2 , 1 ≤ q ≤ N-1 ⎪⎩ N M and N are the row and column size of A, respectively. If you apply the DCT to real data, the result is also real. The DCT tends to concentrate information, making it useful for image compression applications. This transform can be inverted using idct2. Examples The commands below compute the discrete cosine transform for the autumn image. Notice that most of the energy is in the upper left corner. RGB = imread('autumn.tif'); I = rgb2gray(RGB); J = dct2(I); imshow(log(abs(J)),[]), colormap(jet(64)), colorbar 3-128 dct2 Now set values less than magnitude 10 in the DCT matrix to zero, and then reconstruct the image using the inverse DCT function idct2. J(abs(J) < 10) = 0; K = idct2(J); imshow(I) figure, imshow(K,[0 255]) References [1] Jain, Anil K., Fundamentals of Digital Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1989, pp. 150-153. [2] Pennebaker, William B., and Joan L. Mitchell, JPEG: Still Image Data Compression Standard, Van Nostrand Reinhold, 1993. See Also fft2 | idct2 | ifft2 3-129 dctmtx Purpose Discrete cosine transform matrix Syntax D = dctmtx(n) Description D = dctmtx(n) returns the n-by-n DCT (discrete cosine transform) matrix. D*A is the DCT of the columns of A and D'*A is the inverse DCT of the columns of A (when A is n-by-n). Class Support n is an integer scalar of class double. D is returned as a matrix of class double. Tips If A is square, the two-dimensional DCT of A can be computed as D*A*D'. This computation is sometimes faster than using dct2, especially if you are computing a large number of small DCTs, because D needs to be determined only once. For example, in JPEG compression, the DCT of each 8-by-8 block is computed. To perform this computation, use dctmtx to determine D, and then calculate each DCT using D*A*D' (where A is each 8-by-8 block). This is faster than calling dct2 for each individual block. Examples A = im2double(imread('rice.png')); D = dctmtx(size(A,1)); dct = D*A*D'; figure, imshow(dct) See Also dct2 3-130 deconvblind Purpose Deblur image using blind deconvolution Syntax [J,PSF] = deconvblind(I, INITPSF) [J,PSF] = deconvblind(I, INITPSF, NUMIT) [J,PSF] = deconvblind(I, INITPSF, NUMIT, DAMPAR) [J,PSF] = deconvblind(I, INITPSF, NUMIT, DAMPAR, WEIGHT) [J,PSF] = deconvblind(I, INITPSF, NUMIT, DAMPAR, WEIGHT, READOUT) [J,PSF] = deconvblind(..., FUN, P1, P2,...,PN) Description [J,PSF] = deconvblind(I, INITPSF) deconvolves image I using the maximum likelihood algorithm, returning both the deblurred image J and a restored point-spread function PSF. The restored PSF is a positive array that is the same size as INITPSF, normalized so its sum adds up to 1. The PSF restoration is affected strongly by the size of the initial guess INITPSF and less by the values it contains. For this reason, specify an array of 1’s as your INITPSF. I can be a N-dimensional array. To improve the restoration, deconvblind supports several optional parameters, described below. Use [] as a placeholder if you do not specify an intermediate parameter. [J,PSF] = deconvblind(I, INITPSF, NUMIT) specifies the number of iterations (default is 10). [J,PSF] = deconvblind(I, INITPSF, NUMIT, DAMPAR) specifies the threshold deviation of the resulting image from the input image I (in terms of the standard deviation of Poisson noise) below which damping occurs. The iterations are suppressed for the pixels that deviate within the DAMPAR value from their original value. This suppresses the noise generation in such pixels, preserving necessary image details elsewhere. The default value is 0 (no damping). [J,PSF] = deconvblind(I, INITPSF, NUMIT, DAMPAR, WEIGHT) specifies which pixels in the input image I are considered in the restoration. By default, WEIGHT is a unit array, the same size as the input image. You can assign a value between 0.0 and 1.0 to elements 3-131 deconvblind in the WEIGHT array. The value of an element in the WEIGHT array determines how much the pixel at the corresponding position in the input image is considered. For example, to exclude a pixel from consideration, assign it a value of 0 in the WEIGHT array. You can adjust the weight value assigned to each pixel according to the amount of flat-field correction. [J,PSF] = deconvblind(I, INITPSF, NUMIT, DAMPAR, WEIGHT, READOUT), where READOUT is an array (or a value) corresponding to the additive noise (e.g., background, foreground noise) and the variance of the read-out camera noise. READOUT has to be in the units of the image. The default value is 0. [J,PSF] = deconvblind(..., FUN, P1, P2,...,PN), where FUN is a function describing additional constraints on the PSF. FUN must be a function handle. FUN is called at the end of each iteration. FUN must accept the PSF as its first argument and can accept additional parameters P1, P2,..., PN. The FUN function should return one argument, PSF, that is the same size as the original PSF and that satisfies the positivity and normalization constraints. Parameterizing Functions, in the MATLAB Mathematics documentation, explains how to provide additional parameters to the function fun. Note The output image J could exhibit ringing introduced by the discrete Fourier transform used in the algorithm. To reduce the ringing, use I = edgetaper(I,PSF) before calling deconvblind. Resuming You can use deconvblind to perform a deconvolution that starts where Deconvolution a previous deconvolution stopped. To use this feature, pass the input image I and the initial guess at the PSF, INITPSF, as cell arrays: {I} and {INITPSF}. When you do, the deconvblind function returns the output image J and the restored point-spread function, PSF, as cell 3-132 deconvblind arrays, which can then be passed as the input arrays into the next deconvblind call. The output cell array J contains four elements: J{1} contains I, the original image. J{2} contains the result of the last iteration. J{3} contains the result of the next-to-last iteration. J{4} is an array generated by the iterative algorithm. I and INITPSF can be uint8, uint16, int16, single, or double. DAMPAR and READOUT must have the same class as the input image. Other inputs have to be double. The output image J (or the first array of the output cell) has the same class as the input image I. The output PSF is double. Examples I = checkerboard(8); PSF = fspecial('gaussian',7,10); V = .0001; BlurredNoisy = imnoise(imfilter(I,PSF),'gaussian',0,V); WT = zeros(size(I)); WT(5:end-4,5:end-4) = 1; INITPSF = ones(size(PSF)); [J P] = deconvblind(BlurredNoisy,INITPSF,20,10*sqrt(V),WT); subplot(221);imshow(BlurredNoisy); title('A = Blurred and Noisy'); subplot(222);imshow(PSF,[]); title('True PSF'); subplot(223);imshow(J); title('Deblurred Image'); subplot(224);imshow(P,[]); title('Recovered PSF'); See Also deconvlucy | deconvreg | deconvwnr | edgetaper | function_handle | imnoise | otf2psf | padarray | psf2otf How To • “Anonymous Functions” • “Parameterizing Functions” 3-133 deconvlucy Purpose Deblur image using Lucy-Richardson method Syntax J J J J J J Description = = = = = = deconvlucy(I, deconvlucy(I, deconvlucy(I, deconvlucy(I, deconvlucy(I, deconvlucy(I, SUBSMPL) PSF) PSF, PSF, PSF, PSF, PSF, NUMIT) NUMIT, NUMIT, NUMIT, NUMIT, DAMPAR) DAMPAR, WEIGHT) DAMPAR, WEIGHT, READOUT) DAMPAR, WEIGHT, READOUT, J = deconvlucy(I, PSF) restores image I that was degraded by convolution with a point-spread function PSF and possibly by additive noise. The algorithm is based on maximizing the likelihood of the resulting image J’s being an instance of the original image I under Poisson statistics. I can be a N-dimensional array. To improve the restoration, deconvlucy supports several optional parameters. Use [] as a placeholder if you do not specify an intermediate parameter. J = deconvlucy(I, PSF, NUMIT) specifies the number of iterations the deconvlucy function performs. If this value is not specified, the default is 10. J = deconvlucy(I, PSF, NUMIT, DAMPAR) specifies the threshold deviation of the resulting image from the image I (in terms of the standard deviation of Poisson noise) below which damping occurs. Iterations are suppressed for pixels that deviate beyond the DAMPAR value from their original value. This suppresses the noise generation in such pixels, preserving necessary image details elsewhere. The default value is 0 (no damping). J = deconvlucy(I, PSF, NUMIT, DAMPAR, WEIGHT) specifies the weight to be assigned to each pixel to reflect its recording quality in the camera. A bad pixel is excluded from the solution by assigning it zero weight value. Instead of giving a weight of unity for good pixels, you 3-134 deconvlucy can adjust their weight according to the amount of flat-field correction. The default is a unit array of the same size as input image I. J = deconvlucy(I, PSF, NUMIT, DAMPAR, WEIGHT, READOUT) specifies a value corresponding to the additive noise (e.g., background, foreground noise) and the variance of the readout camera noise. READOUT has to be in the units of the image. The default value is 0. J = deconvlucy(I, PSF, NUMIT, DAMPAR, WEIGHT, READOUT, SUBSMPL), where SUBSMPL denotes subsampling and is used when the PSF is given on a grid that is SUBSMPL times finer than the image. The default value is 1. Note The output image J could exhibit ringing introduced by the discrete Fourier transform used in the algorithm. To reduce the ringing, use I = edgetaper(I,PSF) before calling deconvlucy. Resuming If I is a cell array, it can contain a single numerical array (the blurred Deconvolution image) or it can be the output from a previous run of deconvlucy. When you pass a cell array to deconvlucy as input, it returns a 1-by-4 cell array J, where J{1} contains I, the original image. J{2} contains the result of the last iteration. J{3} contains the result of the next-to-last iteration. J{4} is an array generated by the iterative algorithm. I and PSF can be uint8, uint16, int16, double, or single. DAMPAR and READOUT must have the same class as the input image. Other inputs have to be double. The output image J (or the first array of the output cell) has the same class as the input image I. Examples I = checkerboard(8); PSF = fspecial('gaussian',7,10); V = .0001; 3-135 deconvlucy BlurredNoisy = imnoise(imfilter(I,PSF),'gaussian',0,V); WT = zeros(size(I)); WT(5:end-4,5:end-4) = 1; J1 = deconvlucy(BlurredNoisy,PSF); J2 = deconvlucy(BlurredNoisy,PSF,20,sqrt(V)); J3 = deconvlucy(BlurredNoisy,PSF,20,sqrt(V),WT); subplot(221);imshow(BlurredNoisy); title('A = Blurred and Noisy'); subplot(222);imshow(J1); title('deconvlucy(A,PSF)'); subplot(223);imshow(J2); title('deconvlucy(A,PSF,NI,DP)'); subplot(224);imshow(J3); title('deconvlucy(A,PSF,NI,DP,WT)'); References [1] Biggs, D.S.C. “Acceleration of Iterative Image Restoration Algorithms.” Applied Optics. Vol. 36. Number 8, 1997, pp. 1766–1775. [2] Hanisch, R.J., R.L. White, and R.L. Gilliland. “Deconvolution of Hubble Space Telescope Images and Spectra.” Deconvolution of Images and Spectra (P.A. Jansson, ed.). Boston, MA: Academic Press, 1997, pp. 310–356. See Also 3-136 deconvblind | deconvreg | deconvwnr | otf2psf | padarray | psf2otf deconvreg Purpose Deblur image using regularized filter Syntax J = J = J = J = [J, Description J = deconvreg(I, PSF) deconvolves image I using the regularized filter algorithm, returning deblurred image J. The assumption is that the image I was created by convolving a true image with a point-spread function PSF and possibly by adding noise. The algorithm is a constrained optimum in the sense of least square error between the estimated and the true images under requirement of preserving image smoothness. deconvreg(I, PSF) deconvreg(I, PSF, NOISEPOWER) deconvreg(I, PSF, NOISEPOWER, LRANGE) deconvreg(I, PSF, NOISEPOWER, LRANGE, REGOP) LAGRA] = deconvreg(I, PSF,...) I can be a N-dimensional array. J = deconvreg(I, PSF, NOISEPOWER) where NOISEPOWER is the additive noise power. The default value is 0. J = deconvreg(I, PSF, NOISEPOWER, LRANGE) where LRANGE is a vector specifying range where the search for the optimal solution is performed. The algorithm finds an optimal Lagrange multiplier LAGRA within the LRANGE range. If LRANGE is a scalar, the algorithm assumes that LAGRA is given and equal to LRANGE; the NP value is then ignored. The default range is between [1e-9 and 1e9]. J = deconvreg(I, PSF, NOISEPOWER, LRANGE, REGOP) where REGOP is the regularization operator to constrain the deconvolution. The default regularization operator is the Laplacian operator, to retain the image smoothness. The REGOP array dimensions must not exceed the image dimensions; any nonsingleton dimensions must correspond to the nonsingleton dimensions of PSF. [J, LAGRA] = deconvreg(I, PSF,...) outputs the value of the Lagrange multiplier LAGRA in addition to the restored image J. 3-137 deconvreg Note The output image J could exhibit ringing introduced by the discrete Fourier transform used in the algorithm. To reduce the ringing, process the image with the edgetaper function prior to calling the deconvreg function. For example, I = edgetaper(I,PSF). Class Support I can be of class uint8, uint16, int16, single, or double. Other inputs have to be of class double. J has the same class as I. Examples I = checkerboard(8); PSF = fspecial('gaussian',7,10); V = .01; BlurredNoisy = imnoise(imfilter(I,PSF),'gaussian',0,V); NOISEPOWER = V*prod(size(I)); [J LAGRA] = deconvreg(BlurredNoisy,PSF,NOISEPOWER); subplot(221); imshow(BlurredNoisy); title('A = Blurred and Noisy'); subplot(222); imshow(J); title('[J LAGRA] = deconvreg(A,PSF,NP)'); subplot(223); imshow(deconvreg(BlurredNoisy,PSF,[],LAGRA/10)); title('deconvreg(A,PSF,[],0.1*LAGRA)'); subplot(224); imshow(deconvreg(BlurredNoisy,PSF,[],LAGRA*10)); title('deconvreg(A,PSF,[],10*LAGRA)'); See Also 3-138 deconvblind | deconvlucy | deconvwnr | otf2psf | padarray | psf2otf deconvwnr Purpose Deblur image using Wiener filter Syntax J = deconvwnr(I,PSF,NSR) J = deconvwnr(I,PSF,NCORR,ICORR) Description J = deconvwnr(I,PSF,NSR) deconvolves image I using the Wiener filter algorithm, returning deblurred image J. Image I can be an N-dimensional array. PSF is the point-spread function with which I was convolved. NSR is the noise-to-signal power ratio of the additive noise. NSR can be a scalar or a spectral-domain array of the same size as I. Specifying 0 for the NSR is equivalent to creating an ideal inverse filter. The algorithm is optimal in a sense of least mean square error between the estimated and the true images. J = deconvwnr(I,PSF,NCORR,ICORR) deconvolves image I, where NCORR is the autocorrelation function of the noise and ICORR is the autocorrelation function of the original image. NCORR and ICORR can be of any size or dimension, not exceeding the original image. If NCORR or ICORR are N-dimensional arrays, the values correspond to the autocorrelation within each dimension. If NCORR or ICORR are vectors, and PSF is also a vector, the values represent the autocorrelation function in the first dimension. If PSF is an array, the 1-D autocorrelation function is extrapolated by symmetry to all non-singleton dimensions of PSF. If NCORR or ICORR is a scalar, this value represents the power of the noise of the image. Note The output image J could exhibit ringing introduced by the discrete Fourier transform used in the algorithm. To reduce the ringing, use I = edgetaper(I,PSF) prior to calling deconvwnr. 3-139 deconvwnr Class Support I can be of class uint8, uint16, int16, single, or double. Other inputs have to be of class double. J has the same class as I. Examples Use deconvwnr to Restore an Image Create a noisy, blurry image and then apply the deconvwnr filter to deblur it. Display the original image. I = im2double(imread('cameraman.tif')); imshow(I); title('Original Image (courtesy of MIT)'); Simulate a motion blur. LEN = 21; THETA = 11; PSF = fspecial('motion', LEN, THETA); 3-140 deconvwnr blurred = imfilter(I, PSF, 'conv', 'circular'); figure, imshow(blurred) Simulate additive noise. noise_mean = 0; noise_var = 0.0001; blurred_noisy = imnoise(blurred, 'gaussian', ... noise_mean, noise_var); figure, imshow(blurred_noisy) title('Simulate Blur and Noise') 3-141 deconvwnr Try restoration assuming no noise. estimated_nsr = 0; wnr2 = deconvwnr(blurred_noisy, PSF, estimated_nsr); figure, imshow(wnr2) title('Restoration of Blurred, Noisy Image Using NSR = 0') 3-142 deconvwnr Try restoration using a better estimate of the noise-to-signal-power ratio. estimated_nsr = noise_var / var(I(:)); wnr3 = deconvwnr(blurred_noisy, PSF, estimated_nsr); figure, imshow(wnr3) title('Restoration of Blurred, Noisy Image Using Estimated NSR'); References "Digital Image Processing", R. C. Gonzalez & R. E. Woods, Addison-Wesley Publishing Company, Inc., 1992. See Also deconvblind | deconvlucy | deconvreg | edgetaper | otf2psf | padarray | psf2otf 3-143 decorrstretch Purpose Apply decorrelation stretch to multichannel image Syntax S = decorrstretch(I) S = decorrstretch(I, TOL) Description S = decorrstretch(I) applies a decorrelation stretch to a multichannel image I and returns the result in S. S has the same size and class as I. The mean and variance in each band are the same as in I. S = decorrstretch(I, TOL) applies a contrast following the decorrelation stretch. The contrast stretch is controlled by TOL: • TOL = [LOW_FRACT HIGH_FRACT] specifies the fraction of the image to saturate at low and high intensities. • If TOL is a scalar, LOW_FRACT = TOL, and HIGH_FRACT = 1 - TOL, which saturates equal fractions at low and high intensities. Notes The decorrelation stretch is normally applied to three band images (ordinary RGB images or RGB multispectral composite images), but decorrstretch works on an arbitrary number of bands. The primary purpose of decorrelation stretch is visual enhancement. Small adjustments to TOL can strongly affect the visual appearance of the output. Class Support The input image must be of class uint8, uint16, int16, single, or double. Examples [X, map] = imread('forest.tif'); S = decorrstretch(ind2rgb(X, map),'tol',0.01); figure, imshow(X,map) figure, imshow(S) See Also imadjust | stretchlim 3-144 demosaic Purpose Convert Bayer pattern encoded image to truecolor image Syntax RGB = demosaic(I, sensorAlignment) Description RGB = demosaic(I, sensorAlignment) converts a Bayer pattern encoded image to a truecolor image using gradient-corrected linear interpolation. I is an M-by-N array of intensity values that are Bayer pattern encoded. I must have at least 5 rows and 5 columns. A Bayer filter mosaic, or color filter array, refers to the arrangement of color filters that let each sensor in a single-sensor digital camera record only red, green, or blue data. The patterns emphasize the number of green sensors to mimic the human eye’s greater sensitivity to green light. The demosaic function uses interpolation to convert the two-dimensional Bayer-encoded image into the truecolor image, RGB, which is an M-by-N-by-3 array. sensorAlignment is one of the following text strings that specifies the Bayer pattern. Each string represents the order of the red, green, and blue sensors by describing the four pixels in the upper-left corner of the image (left-to-right, top-to-bottom). 3-145 demosaic Value 2–by-2 Sensor Alignment 'gbrg' Green Blue Red Green Green Red Blue Green Blue Green Green Red Red Green Green Blue 'grbg' 'bggr' 'rggb' 3-146 demosaic Class Support I can be uint8 or uint16, and it must be real. RGB has the same class as I. Examples Convert a Bayer pattern encoded image that was photographed by a camera with a sensor alignment of 'bggr'. I = imread('mandi.tif'); J = demosaic(I,'bggr'); imshow(I); figure, imshow(J); Bayer Pattern Encoded Image 3-147 demosaic Truecolor Image 3-148 dicomanon Purpose Anonymize DICOM file Syntax dicomanon(file_in, file_out) dicomanon(..., 'keep', FIELDS) dicomanon(..., 'update', ATTRS) Description dicomanon(file_in, file_out) removes confidential medical information from the DICOM file file_in and creates a new file file_out with the modified values. Image data and other attributes are unmodified. dicomanon(..., 'keep', FIELDS) modifies all of the confidential data except for those listed in FIELDS, which is a cell array of field names. This syntax is useful for keeping metadata that does not uniquely identify the patient but is useful for diagnostic purposes (e.g., PatientAge, PatientSex, etc.). Note Keeping certain fields might compromise patient confidentiality. dicomanon(..., 'update', ATTRS) modifies the confidential data and updates particular confidential data. ATTRS is a structure whose fields are the names of the attributes to preserve. The structure values are the attribute values. Use this syntax to preserve the Study/Series/Image hierarchy or to replace a specific value with a more generic property (e.g., remove PatientBirthDate but keep a computed PatientAge). For information about the fields that will be modified or removed, see DICOM Supplement 55 from http://medical.nema.org/. Examples Remove all confidential metadata from a file. dicomanon('patient.dcm', 'anonymized.dcm') Create a training file. dicomanon('tumor.dcm', 'tumor_anon.dcm', 'keep',... 3-149 dicomanon {'PatientAge', 'PatientSex', 'StudyDescription'}) Anonymize a series of images, keeping the hierarchy. values.StudyInstanceUID = dicomuid; values.SeriesInstanceUID = dicomuid; d = dir('*.dcm'); for p = 1:numel(d) dicomanon(d(p).name, sprintf('anon%d.dcm', p), ... 'update', values) end See Also 3-150 dicominfo | dicomwrite dicomdict Purpose Get or set active DICOM data dictionary Syntax dicomdict('set',dictionary) dictionary = dicomdict('get') dicomdict('factory') Description dicomdict('set',dictionary) sets the Digital Imaging and Communications in Medicine (DICOM) data dictionary to the value stored in dictionary, a string containing the filename of the dictionary. DICOM-related functions use this dictionary by default, unless a different dictionary is provided at the command line. dictionary = dicomdict('get') returns a string containing the filename of the stored DICOM data dictionary. dicomdict('factory') resets the DICOM data dictionary to its default startup value. Note The default data dictionary is a MAT-file, dicom-dict.mat. The toolbox also includes a text version of this default data dictionary, dicom-dict.txt. If you want to create your own DICOM data dictionary, open the dicom-dict.txt file in a text editor, modify it, and save it under another name. Examples dictionary = dicomdict('get') dictionary = dicom-dict.mat See Also dicominfo | dicomread | dicomwrite 3-151 dicominfo Purpose Read metadata from DICOM message Syntax info = dicominfo(filename) info = dicominfo(filename, 'dictionary', D) Description info = dicominfo(filename) reads the metadata from the compliant Digital Imaging and Communications in Medicine (DICOM) file specified in the string filename. info = dicominfo(filename, 'dictionary', D) uses the data dictionary file given in the string D to read the DICOM message. The file in D must be on the MATLAB search path. The default file is dicom-dict.mat. Examples info = dicominfo('CT-MONO2-16-ankle.dcm') info = Filename: FileModDate: FileSize: Format: FormatVersion: Width: Height: BitDepth: ColorType: SelectedFrames: FileStruct: StartOfPixelData: FileMetaInformationGroupLength: FileMetaInformationVersion: MediaStorageSOPClassUID: . . . 3-152 [1x62 char] '18-Dec-2000 11:06:43' 525436 'DICOM' 3 512 512 16 'grayscale' [] [1x1 struct] 1140 192 [2x1 uint8] '1.2.840.10008.5.1.4.1.1.7' dicominfo See Also dicomdict | dicomread | dicomwrite | dicomuid 3-153 dicomlookup Purpose Find attribute in DICOM data dictionary Syntax name = dicomlookup(group, element) [group, element] = dicomlookup(name) Description name = dicomlookup(group, element) looks into the current DICOM data dictionary for the attribute with the specified group and element tag and returns a string containing the name of the attribute. group and element can contain either a decimal value or hexadecimal string. [group, element] = dicomlookup(name) looks into the current DICOM data dictionary for the attribute specified byname and returns the group and element tags associated with the attribute. The values are returned as decimal values. Examples Find the names of DICOM attributes using their tags. name1 = dicomlookup('7FE0', '0010') name2 = dicomlookup(40, 4) Look up a DICOM attribute’s tag (GROUP and ELEMENT) using its name. [group, element] = dicomlookup('TransferSyntaxUID') Examine the metadata of a DICOM file. This returns the same value even if the data dictionary changes. metadata = dicominfo('CT-MONO2-16-ankle.dcm'); metadata.(dicomlookup('0028', '0004')) See Also 3-154 dicomdict | dicominfo dicomread Purpose Read DICOM image Syntax X = dicomread(filename) X = dicomread(info) [X,map] = dicomread(...) [X,map,alpha] = dicomread(...) [X,map,alpha,overlays] = dicomread(...) [...] = dicomread(filename, 'frames', v) Description X = dicomread(filename) reads the image data from the compliant Digital Imaging and Communications in Medicine (DICOM) file filename. For single-frame grayscale images, X is an M-by-N array. For single-frame true-color images, X is an M-by-N-by-3 array. Multiframe images are always 4-D arrays. X = dicomread(info) reads the image data from the message referenced in the DICOM metadata structure info. The info structure is produced by the dicominfo function. [X,map] = dicomread(...) returns the image X and the colormap map. If X is a grayscale or true-color image, map is empty. [X,map,alpha] = dicomread(...) returns the image X, the colormap map, and an alpha channel matrix for X. The values of alpha are 0 if the pixel is opaque; otherwise they are row indices into map. The RGB value in map should be substituted for the value in X to use alpha. alpha has the same height and width as X and is 4-D for a multiframe image. [X,map,alpha,overlays] = dicomread(...) returns the image X, the colormap map, an alpha channel matrix for X, and any overlays from the DICOM file. Each overlay is a 1-bit black and white image with the same height and width as X. If multiple overlays are present in the file, overlays is a 4-D multiframe image. If no overlays are in the file, overlays is empty. = dicomread(filename, 'frames', v) reads only the frames in the vector v from the image. v must be an integer scalar, a vector of integers, or the string 'all'. The default value is 'all'. [...] 3-155 dicomread Tips The dicomread function supports both reversible (lossless) and irreversible (lossy) JPEG-2000 compression in DICOM files. Class Support X can be uint8, int8, uint16, or int16. map must be double. alpha has the same size and type as X. overlays is a logical array. Examples Use dicomread to retrieve the data array, X, and colormap matrix, map, needed to create a montage. [X, map] = dicomread('US-PAL-8-10x-echo.dcm'); montage(X, map, 'Size', [2 5]); Call dicomread with the information retrieved from the DICOM file using dicominfo and display the image using imshow. Adjust the contrast of the image using imcontrast. info = dicominfo('CT-MONO2-16-ankle.dcm'); Y = dicomread(info); figure, imshow(Y); imcontrast; See Also 3-156 dicomdict | dicominfo | dicomwrite dicomuid Purpose Generate DICOM unique identifier Syntax UID = dicomuid Description UID = dicomuid creates a string UID containing a new DICOM unique identifier. Multiple calls to dicomuid produce globally unique values. Two calls to dicomuid always return different values. See Also dicominfo | dicomwrite 3-157 dicomwrite Purpose Write images as DICOM files Syntax dicomwrite(X, filename) dicomwrite(X, map, filename) dicomwrite(..., param1, value1, param2, value2, ...) dicomwrite(..., 'ObjectType', IOD,...) dicomwrite(..., 'SOPClassUID', UID,...) dicomwrite(..., meta_struct,...) dicomwrite(..., info,...) status = dicomwrite(...) Description dicomwrite(X, filename) writes the binary, grayscale, or truecolor image X to the file filename, where filename is a string specifying the name of the Digital Imaging and Communications in Medicine (DICOM) file to create. dicomwrite(X, map, filename) writes the indexed image X with colormap map. dicomwrite(..., param1, value1, param2, value2, ...) specifies optional metadata to write to the DICOM file or parameters that affect how the file is written. param1 is a string containing the metadata attribute name or a dicomwrite-specific option. value1 is the corresponding value for the attribute or option. To find a list of the DICOM attributes that you can specify, see the data dictionary file, dicom-dict.txt, included with the Image Processing Toolbox software. The following table lists the options that you can specify, in alphabetical order. Default values are enclosed in braces ({}). 3-158 dicomwrite Option Name Description 'CompressionMode' String specifying the type of compression to use when storing the image. Possible values: {'None'} 'JPEG lossless' 'JPEG lossy' 'JPEG2000 lossy' 'JPEG2000 lossless' 'RLE' 'CreateMode' Specifies the method used for creating the data to put in the new file. Possible values: {'Create'} — Verify input values and generate missing data values. 'Copy' — Copy all values from the input and do not generate missing values. 'Dictionary' String specifying the name of a DICOM data dictionary. 'Endian' String specifying the byte ordering of the file. 'Big' {'Little'} Note If VR is set to 'Explicit', 'Endian' must be 'Big'. dicomwrite ignores this value if 'CompressionMode' or 'TransferSyntax' is set. 3-159 dicomwrite Option Name Description 'MultiframeSingleFile'Logical value indicating whether multiframe imagery should be written to one file. When true (default), one file is created regardless of how many frames X contains. When false, one file is written for each frame in the image. 'TransferSyntax' A DICOM UID specifying the 'Endian', 'VR', and 'CompressionMode' options. Note If specified, dicomwrite ignores any values specified for the 'Endian', 'VR', and 'CompressionMode' options. The TransferSyntax value encodes values for these options. 'VR' String specifying whether the two-letter value representation (VR) code should be written to the file. 'explicit' — Write VR to file. {'implicit'} — Infer from data dictionary. Note If you specify the 'Endian' value 'Big', you must specify 'Explicit'. 'WritePrivate' Logical value indicating whether private data should be written to the file. Possible values: true — Write private data to file. {false} — Do not write private data. 3-160 dicomwrite dicomwrite(..., 'ObjectType', IOD,...) writes a file containing the necessary metadata for a particular type of DICOM Information Object (IOD). Supported IODs are • 'Secondary Capture Image Storage' (default) • 'CT Image Storage' • 'MR Image Storage' dicomwrite(..., 'SOPClassUID', UID,...) provides an alternate method for specifying the IOD to create. UID is the DICOM unique identifier corresponding to one of the IODs listed above. dicomwrite(..., meta_struct,...) specifies optional metadata or file options in structure meta_struct. The names of fields in meta_struct must be the names of DICOM file attributes or options. The value of a field is the value you want to assign to the attribute or option. dicomwrite(..., info,...) specifies metadata in the metadata structure info, which is produced by the dicominfo function. For more information about this structure, see dicominfo. status = dicomwrite(...) returns information about the metadata and the descriptions used to generate the DICOM file. This syntax can be useful when you specify an info structure that was created by dicominfo to the dicomwrite function. An info structure can contain many fields. If no metadata was specified, dicomwrite returns an empty matrix ([]). The structure returned by dicomwrite contains these fields: Field Description 'BadAttribute' The attribute’s internal description is bad. It might be missing from the data dictionary or have incorrect data in its description. 'MissingCondition' The attribute is conditional but no condition has been provided for when to use it. 3-161 dicomwrite Tips Field Description 'MissingData' No data was provided for an attribute that must appear in the file. 'SuspectAttribute' Data in the attribute does not match a list of enumerated values in the DICOM specification. The DICOM format specification lists several Information Object Definitions (IODs) that can be created. These IODs correspond to images and metadata produced by different real-world modalities (e.g., MR, X-ray, Ultrasound, etc.). For each type of IOD, the DICOM specification defines the set of metadata that must be present and possible values for other metadata. dicomwrite fully implements a limited number of these IODs, listed above in the ObjectType syntax. For these IODs, dicomwrite verifies that all required metadata attributes are present, creates missing attributes if necessary, and specifies default values where possible. Using these supported IODs is the best way to ensure that the files you create conform to the DICOM specification. This is dicomwrite default behavior and corresponds to the CreateMode option value of 'Create'. To write DICOM files for IODs that dicomwrite doesn’t implement, use the 'Copy' value for the CreateMode option. In this mode, dicomwrite writes the image data to a file including the metadata that you specify as a parameter, shown above in the info syntax. The purpose of this option is to take metadata from an existing file of the same modality or IOD and use it to create a new DICOM file with different image pixel data. 3-162 dicomwrite Note Because dicomwrite copies metadata to the file without verification in 'copy' mode, it is possible to create a DICOM file that does not conform to the DICOM standard. For example, the file may be missing required metadata, contain superfluous metadata, or the metadata may no longer correspond to the modality settings used to generate the original image. When using 'Copy' mode, make sure that the metadata you use is from the same modality and IOD. If the copy you make is unrelated to the original image, use dicomuid to create new unique identifiers for series and study metadata. See the IOD descriptions in Part 3 of the DICOM specification for more information on appropriate IOD values. Examples Read a CT image from the sample DICOM file included with the toolbox and then write the CT image to a file, creating a secondary capture image. X = dicomread('CT-MONO2-16-ankle.dcm'); dicomwrite(X, 'sc_file.dcm'); Write the CT image, X, to a DICOM file along with its metadata. Use the dicominfo function to retrieve metadata from a DICOM file. metadata = dicominfo('CT-MONO2-16-ankle.dcm'); dicomwrite(X, 'ct_file.dcm', metadata); Copy all metadata from one file to another. In this mode, dicomwrite does not verify the metadata written to the file. dicomwrite(X, 'ct_copy.dcm', metadata, 'CreateMode', 'copy'); See Also dicomdict | dicominfo | dicomread | dicomuid 3-163 edge Purpose Find edges in grayscale image Note • The syntax BW = edge(... ,K) has been removed. Use the BW = edge(... ,direction) syntax instead. • The syntax edge(I,'marr-hildreth',...) has been removed. Use the edge(I,'log',...) syntax instead. Syntax BW = edge(I) BW = edge(I,'sobel') BW = edge(I,'sobel',thresh) BW = edge(I,'sobel',thresh,direction) [BW,thresh] = edge(I,'sobel',...) BW = edge(I,'prewitt') BW = edge(I,'prewitt',thresh) BW = edge(I,'prewitt',thresh,direction) [BW,thresh] = edge(I,'prewitt',...) BW = edge(I,'roberts') BW = edge(I,'roberts',thresh) [BW,thresh] = edge(I,'roberts',...) BW = edge(I,'log') BW = edge(I,'log',thresh) BW = edge(I,'log',thresh,sigma) [BW,threshold] = edge(I,'log',...) BW = edge(I,'zerocross',thresh,h) [BW,thresh] = edge(I,'zerocross',...) BW = edge(I,'canny') BW = edge(I,'canny',thresh) 3-164 edge BW = edge(I,'canny',thresh,sigma) [BW,threshold] = edge(I,'canny',...) Description BW = edge(I) takes a grayscale or a binary image I as its input, and returns a binary image BW of the same size as I, with 1’s where the function finds edges in I and 0’s elsewhere. By default, edge uses the Sobel method to detect edges but the following provides a complete list of all the edge-finding methods supported by this function: • The Sobel method finds edges using the Sobel approximation to the derivative. It returns edges at those points where the gradient of I is maximum. • The Prewitt method finds edges using the Prewitt approximation to the derivative. It returns edges at those points where the gradient of I is maximum. • The Roberts method finds edges using the Roberts approximation to the derivative. It returns edges at those points where the gradient of I is maximum. • The Laplacian of Gaussian method finds edges by looking for zero crossings after filtering I with a Laplacian of Gaussian filter. • The zero-cross method finds edges by looking for zero crossings after filtering I with a filter you specify. • The Canny method finds edges by looking for local maxima of the gradient of I. The gradient is calculated using the derivative of a Gaussian filter. The method uses two thresholds, to detect strong and weak edges, and includes the weak edges in the output only if they are connected to strong edges. This method is therefore less likely than the others to be fooled by noise, and more likely to detect true weak edges. The parameters you can supply differ depending on the method you specify. If you do not specify a method, edge uses the Sobel method. 3-165 edge Sobel Method BW = edge(I,'sobel') specifies the Sobel method. BW = edge(I,'sobel',thresh) specifies the sensitivity threshold for the Sobel method. edge ignores all edges that are not stronger than thresh. If you do not specify thresh, or if thresh is empty ([]), edge chooses the value automatically. BW = edge(I,'sobel',thresh,direction) specifies the direction of detection for the Sobel method. direction is a string specifying whether to look for 'horizontal' or 'vertical' edges or 'both' (the default). BW = edge(I,'sobel',...,options) provides an optional string input. String 'nothinning' speeds up the operation of the algorithm by skipping the additional edge thinning stage. By default, or when 'thinning' string is specified, the algorithm applies edge thinning. [BW,thresh] = edge(I,'sobel',...) returns the threshold value. Prewitt Method BW = edge(I,'prewitt') specifies the Prewitt method. BW = edge(I,'prewitt',thresh) specifies the sensitivity threshold for the Prewitt method. edge ignores all edges that are not stronger than thresh. If you do not specify thresh, or if thresh is empty ([]), edge chooses the value automatically. BW = edge(I,'prewitt',thresh,direction) specifies the direction of detection for the Prewitt method. direction is a string specifying whether to look for 'horizontal' or 'vertical' edges or 'both' (default). [BW,thresh] = edge(I,'prewitt',...) returns the threshold value. Roberts Method BW = edge(I,'roberts') specifies the Roberts method. BW = edge(I,'roberts',thresh) specifies the sensitivity threshold for the Roberts method. edge ignores all edges that are not stronger 3-166 edge than thresh. If you do not specify thresh, or if thresh is empty ([]), edge chooses the value automatically. BW = edge(I,'roberts',...,options) where options can be the text string 'thinning' or 'nothinning'. When you specify 'thinning', or don’t specify a value, the algorithm applies edge thinning. Specifying the 'nothinning' option can speed up the operation of the algorithm by skipping the additional edge thinning stage. [BW,thresh] = edge(I,'roberts',...) returns the threshold value. Laplacian of Gaussian Method BW = edge(I,'log') specifies the Laplacian of Gaussian method. BW = edge(I,'log',thresh) specifies the sensitivity threshold for the Laplacian of Gaussian method. edge ignores all edges that are not stronger than thresh. If you do not specify thresh, or if thresh is empty ([]), edge chooses the value automatically. If you specify a threshold of 0, the output image has closed contours, because it includes all the zero crossings in the input image. BW = edge(I,'log',thresh,sigma) specifies the Laplacian of Gaussian method, using sigma as the standard deviation of the LoG filter. The default sigma is 2; the size of the filter is n-by-n, where n = ceil(sigma*3)*2+1. [BW,thresh] = edge(I,'log',...) returns the threshold value. Zero-Cross Method BW = edge(I,'zerocross',thresh,h) specifies the zero-cross method, using the filter h. thresh is the sensitivity threshold; if the argument is empty ([]), edge chooses the sensitivity threshold automatically. If you specify a threshold of 0, the output image has closed contours, because it includes all the zero crossings in the input image. [BW,thresh] = edge(I,'zerocross',...) returns the threshold value. Canny Method BW = edge(I,'canny') specifies the Canny method. 3-167 edge BW = edge(I,'canny',thresh) specifies sensitivity thresholds for the Canny method. thresh is a two-element vector in which the first element is the low threshold, and the second element is the high threshold. If you specify a scalar for thresh, this scalar value is used for the high threshold and 0.4*thresh is used for the low threshold. If you do not specify thresh, or if thresh is empty ([]), edge chooses low and high values automatically. The value for thresh is relative to the highest value of the gradient magnitude of the image. BW = edge(I,'canny',thresh,sigma) specifies the Canny method, using sigma as the standard deviation of the Gaussian filter. The default sigma is sqrt(2); the size of the filter is chosen automatically, based on sigma. [BW,thresh] = edge(I,'canny',...) returns the threshold values as a two-element vector. Class Support I is a nonsparse numeric array. BW is of class logical. Tips For the gradient-magnitude methods (Sobel, Prewitt, Roberts), thresh is used to threshold the calculated gradient magnitude. For the zero-crossing methods, including Lap, thresh is used as a threshold for the zero-crossings; in other words, a large jump across zero is an edge, while a small jump isn’t. The Canny method applies two thresholds to the gradient: a high threshold for low edge sensitivity and a low threshold for high edge sensitivity. edge starts with the low sensitivity result and then grows it to include connected edge pixels from the high sensitivity result. This helps fill in gaps in the detected edges. In all cases, the default threshold is chosen heuristically in a way that depends on the input data. The best way to vary the threshold is to run edge once, capturing the calculated threshold as the second output argument. Then, starting from the value calculated by edge, adjust the threshold higher (fewer edge pixels) or lower (more edge pixels). 3-168 edge The function edge changed in Version 7.2 (R2011a). Previous versions of the Image Processing Toolbox used a different algorithm for computing the Canny method. If you need the same results produced by the previous implementation, use the following syntax: BW = edge(I,'canny_old',...) Examples Find the edges of an image using the Prewitt and Canny methods. I = imread('circuit.tif'); BW1 = edge(I,'prewitt'); BW2 = edge(I,'canny'); imshow(BW1); Prewitt Method figure, imshow(BW2) 3-169 edge Canny Method References [1] Canny, John, "A Computational Approach to Edge Detection," IEEE Transactions on Pattern Analysis and Machine Intelligence,Vol. PAMI-8, No. 6, 1986, pp. 679-698. [2] Lim, Jae S., Two-Dimensional Signal and Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1990, pp. 478-488. [3] Parker, James R., Algorithms for Image Processing and Computer Vision, New York, John Wiley & Sons, Inc., 1997, pp. 23-29. See Also 3-170 fspecial | imgradient | imgradientxy edgetaper Purpose Taper discontinuities along image edges Syntax J = edgetaper(I,PSF) Description J = edgetaper(I,PSF) blurs the edges of the input image I using the point spread function PSF. The size of the PSF cannot exceed half of the image size in any dimension. The output image J is the weighted sum of the original image I and its blurred version. The weighting array, determined by the autocorrelation function of PSF, makes J equal to I in its central region, and equal to the blurred version of I near the edges. The edgetaper function reduces the ringing effect in image deblurring methods that use the discrete Fourier transform, such as deconvwnr, deconvreg, and deconvlucy. Class Support I and PSF can be of class uint8, uint16, int16, single, or double. J is of the same class as I. Examples original = imread('cameraman.tif'); PSF = fspecial('gaussian',60,10); edgesTapered = edgetaper(original,PSF); figure, imshow(original,[]); figure, imshow(edgesTapered,[]); See Also deconvlucy | deconvreg | deconvwnr | otf2psf | padarray | psf2otf 3-171 entropy Purpose Entropy of grayscale image Syntax E = entropy(I) Description E = entropy(I) returns E, a scalar value representing the entropy of grayscale image I. Entropy is a statistical measure of randomness that can be used to characterize the texture of the input image. Entropy is defined as -sum(p.*log2(p)) where p contains the histogram counts returned from imhist. By default, entropy uses two bins for logical arrays and 256 bins for uint8, uint16, or double arrays. I can be a multidimensional image. If I has more than two dimensions, the entropy function treats it as a multidimensional grayscale image and not as an RGB image. Class Support I can be logical, uint8, uint16, or double and must be real, nonempty, and nonsparse. E is double. Notes entropy converts any class other than logical to uint8 for the histogram count calculation so that the pixel values are discrete and directly correspond to a bin value. Examples I = imread('circuit.tif'); J = entropy(I) References [1] Gonzalez, R.C., R.E. Woods, S.L. Eddins, Digital Image Processing Using MATLAB, New Jersey, Prentice Hall, 2003, Chapter 11. See Also imhist | entropyfilt 3-172 entropyfilt Purpose Local entropy of grayscale image Syntax J = entropyfilt(I) J = entropyfilt(I,NHOOD) Description J = entropyfilt(I) returns the array J, where each output pixel contains the entropy value of the 9-by-9 neighborhood around the corresponding pixel in the input image I. I can have any dimension. If I has more than two dimensions, entropyfilt treats it as a multidimensional grayscale image and not as a truecolor (RGB) image. The output image J is the same size as the input image I. For pixels on the borders of I, entropyfilt uses symmetric padding. In symmetric padding, the values of padding pixels are a mirror reflection of the border pixels in I. J = entropyfilt(I,NHOOD) performs entropy filtering of the input image I where you specify the neighborhood in NHOOD. NHOOD is a multidimensional array of zeros and ones where the nonzero elements specify the neighbors. NHOOD’s size must be odd in each dimension. By default, entropyfilt uses the neighborhood true(9). entropyfilt determines the center element of the neighborhood by floor((size(NHOOD) + 1)/2). To specify neighborhoods of various shapes, such as a disk, use the strel function to create a structuring element object and then use the getnhood function to extract the neighborhood from the structuring element object. Class Support I can be logical, uint8, uint16, or double, and must be real and nonsparse. NHOOD can be logical or numeric and must contain zeros or ones. The output array J is of class double. entropyfilt converts any class other than logical to uint8 for the histogram count calculation so that the pixel values are discrete and directly correspond to a bin value. Examples I = imread('circuit.tif'); J = entropyfilt(I); 3-173 entropyfilt imshow(I), figure, imshow(J,[]); References [1] Gonzalez, R.C., R.E. Woods, S.L. Eddins, Digital Image Processing Using MATLAB, New Jersey, Prentice Hall, 2003, Chapter 11. See Also entropy | imhist | rangefilt | stdfilt 3-174 fan2para Purpose Convert fan-beam projections to parallel-beam Syntax P = fan2para(F,D) P = fan2para(..., param1, val1, param2, val2,...) [P ,parallel_locations, parallel_rotation_angles] = fan2para(...) Description P = fan2para(F,D) converts the fan-beam data F to the parallel-beam data P. D is the distance in pixels from the fan-beam vertex to the center of rotation that was used to obtain the projections. P = fan2para(..., param1, val1, param2, val2,...) specifies parameters that control various aspects of the fan2para conversion, listed in the following table. Parameter names can be abbreviated, and case does not matter. Parameter Description 'FanCoverage' String specifying the range through which the beams are rotated. 'cycle' — Rotate through the full range [0,360). This is the default. 'minimal' — Rotate the minimum range necessary to represent the object. 'FanRotationIncrement' Positive real scalar specifying the increment of the rotation angle of the fan-beam projections, measured in degrees. Default value is 1. 3-175 fan2para Parameter Description 'FanSensorGeometry' String specifying how sensors are positioned. 'arc' — Sensors are spaced equally along a circular arc at distance D from the center of rotation. Default value is 'arc' 'line' — Sensors are spaced equally along a line, the closest point of which is distance D from the center of rotation. See fanbeam for details. 'FanSensorSpacing' Positive real scalar specifying the spacing of the fan-beam sensors. Interpretation of the value depends on the setting of 'FanSensorGeometry'. If 'FanSensorGeometry' is set to 'arc' (the default), the value defines the angular spacing in degrees. Default value is 1. If 'FanSensorGeometry' is 'line', the value specifies the linear spacing. Default value is 1. See fanbeam for details. Note This linear spacing is measured on the x’ axis. The x’ axis for each column, col, of F is oriented at fan_rotation_angles(col) degrees counterclockwise from the x-axis. The origin of both axes is the center pixel of the image. 3-176 fan2para Parameter Description 'Interpolation' Text string specifying the type of interpolation used between the parallel-beam and fan-beam data. 'nearest' — Nearest-neighbor {'linear'} — Linear 'spline' — Piecewise cubic spline 'pchip' — Piecewise cubic Hermite (PCHIP) 'cubic' — Same as 'pchip' 'ParallelCoverage' Text string specifying the range of rotation. 'cycle' — Parallel data covers 360 degrees {'halfcycle'} — Parallel data covers 180 degrees 'ParallelRotationIncrement' Positive real scalar specifying the parallel-beam rotation angle increment, measured in degrees. Parallel beam angles are calculated to cover [0,180) degrees with increment PAR_ROT_INC, where PAR_ROT_INC is the value of 'ParallelRotationIncrement'. 180/PAR_ROT_INC must be an integer. If 'ParallelRotationIncrement' is not specified, the increment is assumed to be the same as the increment of the fan-beam rotation angles. 'ParallelSensorSpacing' Positive real scalar specifying the spacing of the parallel-beam sensors in pixels. The range of sensor locations is implied by the range of fan angles and is given by [D*tan(min(FAN_ANGLES)),... D*tan(max(FAN_ANGLES))] 3-177 fan2para Parameter Description If 'ParallelSensorSpacing' is not specified, the spacing is assumed to be uniform and is set to the minimum spacing implied by the fan angles and sampled over the range implied by the fan angles. [P ,parallel_locations, parallel_rotation_angles] = fan2para(...) returns the parallel-beam sensor locations in parallel_locations and rotation angles in parallel_rotation_angles. Class Support The input arguments, F and D, can be double or single, and they must be nonsparse. All other numeric inputs are double. The output P is double. Examples Create synthetic parallel-beam data, derive fan-beam data, and then use the fan-beam data to recover the parallel-beam data. ph = phantom(128); theta = 0:179; [Psynthetic,xp] = radon(ph,theta); imshow(Psynthetic,[],... 'XData',theta,'YData',xp,'InitialMagnification','fit') axis normal title('Synthetic Parallel-Beam Data') xlabel('\theta (degrees)') ylabel('x''') colormap(hot), colorbar Fsynthetic = para2fan(Psynthetic,100,'FanSensorSpacing',1); Recover original parallel-beam data. [Precovered,Ploc,Pangles] = fan2para(Fsynthetic,100,... 'FanSensorSpacing',1,... 'ParallelSensorSpacing',1); figure imshow(Precovered,[],'XData',Pangles,... 3-178 fan2para 'YData',Ploc,'InitialMagnification','fit') axis normal title('Recovered Parallel-Beam Data') xlabel('Rotation Angles (degrees)') ylabel('Parallel Sensor Locations (pixels)') colormap(hot), colorbar See Also fanbeam | ifanbeam | iradon | para2fan | phantom | radon 3-179 fanbeam Purpose Fan-beam transform Syntax F = fanbeam(I,D) F = fanbeam(..., param1, val1, param1, val2,...) [F, fan_sensor_positions, fan_rotation_angles] = fanbeam(...) Description F = fanbeam(I,D) computes the fan-beam data (sinogram) F from the image I. A sinogram is a special x-ray procedure that is done with contrast media (x-ray dye) to visualize any abnormal opening (sinus) in the body. D is the distance in pixels from the fan-beam vertex to the center of rotation. The center of rotation is the center pixel of the image, defined as floor((size(I)+1)/2). D must be large enough to ensure that the fan-beam vertex is outside of the image at all rotation angles. See “Tips” on page 3-183 for guidelines on specifying D. The following figure illustrates D in relation to the fan-beam vertex for one fan-beam geometry. See the FanSensorGeometry parameter for more information. Each column of F contains the fan-beam sensor samples at one rotation angle. The number of columns in F is determined by the fan rotation increment. By default, the fan rotation increment is 1 degree so F has 360 columns. 3-180 fanbeam The number of rows in F is determined by the number of sensors. fanbeam determines the number of sensors by calculating how many beams are required to cover the entire image for any rotation angle. For information about how to specify the rotation increment and sensor spacing, see the documentation for the FanRotationIncrement and FanSensorSpacing parameters, below. F = fanbeam(..., param1, val1, param1, val2,...) specifies parameters, listed below, that control various aspects of the fan-beam projections. Parameter names can be abbreviated, and case does not matter. 'FanRotationIncrement' -- Positive real scalar specifying the increment of the rotation angle of the fan-beam projections. Measured in degrees. Default value is 1. 'FanSensorGeometry' -- Text string specifying how sensors are positioned. Valid values are 'arc' or 'line'. In the 'arc' geometry, sensors are spaced equally along a circular arc, as shown below. This is the default value. In 'line' geometry, sensors are spaced equally along a line, as shown below. 3-181 fanbeam 'FanSensorSpacing' -- Positive real scalar specifying the spacing of the fan-beam sensors. Interpretation of the value depends on the setting of 'FanSensorGeometry'. If 'FanSensorGeometry' is set to 'arc' (the default), the value defines the angular spacing in degrees. Default value is 1. If 'FanSensorGeometry' is 'line', the value specifies the linear spacing. Default value is 1. Note This linear spacing is measured on the x’ axis. The x’ axis for each column, col, of F is oriented at fan_rotation_angles(col) degrees counterclockwise from the x-axis. The origin of both axes is the center pixel of the image. [F, fan_sensor_positions, fan_rotation_angles] = fanbeam(...) returns the location of fan-beam sensors in fan_sensor_positions and the rotation angles where the fan-beam projections are calculated in fan_rotation_angles. If 'FanSensorGeometry' is 'arc' (the default), fan_sensor_positions contains the fan-beam spread angles. If 'FanSensorGeometry' is 'line', fan_sensor_positions contains the fan-beam sensor positions along the x’ axis. See 'FanSensorSpacing' for more information. 3-182 fanbeam Class Support I can be logical or numeric. All other numeric inputs and outputs can be double. None of the inputs can be sparse. Tips As a guideline, try making D a few pixels larger than half the image diagonal dimension, calculated as follows sqrt(size(I,1)^2 + size(I,2)^2) The values returned in F are a numerical approximation of the fan-beam projections. The algorithm depends on the Radon transform, interpolated to the fan-beam geometry. The results vary depending on the parameters used. You can expect more accurate results when the image is larger, D is larger, and for points closer to the middle of the image, away from the edges. Examples The following example computes the fan-beam projections for rotation angles that cover the entire image. iptsetpref('ImshowAxesVisible','on') ph = phantom(128); imshow(ph) [F,Fpos,Fangles] = fanbeam(ph,250); figure imshow(F,[],'XData',Fangles,'YData',Fpos,... 'InitialMagnification','fit') axis normal xlabel('Rotation Angles (degrees)') ylabel('Sensor Positions (degrees)') colormap(hot), colorbar The following example computes the Radon and fan-beam projections and compares the results at a particular rotation angle. I = ones(100); D = 200; dtheta = 45; 3-183 fanbeam % Compute fan-beam projections for 'arc' geometry [Farc,FposArcDeg,Fangles] = fanbeam(I,D,... 'FanSensorGeometry','arc',... 'FanRotationIncrement',dtheta); % Convert angular positions to linear distance % along x-prime axis FposArc = D*tan(FposArcDeg*pi/180); % Compute fan-beam projections for 'line' geometry [Fline,FposLine] = fanbeam(I,D,... 'FanSensorGeometry','line',... 'FanRotationIncrement',dtheta); % Compute the corresponding Radon transform [R,Rpos]=radon(I,Fangles); % Display the three projections at one particular rotation % angle. Note the three are very similar. Differences are % due to the geometry of the sampling, and the numerical % approximations used in the calculations. figure idx = find(Fangles==45); plot(Rpos,R(:,idx),... FposArc,Farc(:,idx),... FposLine,Fline(:,idx)) legend('Radon','Arc','Line') References [1] Kak, A.C., & Slaney, M., Principles of Computerized Tomographic Imaging, IEEE Press, NY, 1988, pp. 92-93. See Also fan2para | ifanbeam | iradon | para2fan | phantom | radon 3-184 findbounds Purpose Find output bounds for spatial transformation Syntax outbounds = findbounds(TFORM,inbounds) Description outbounds = findbounds(TFORM,inbounds) estimates the output bounds corresponding to a given spatial transformation and a set of input bounds. TFORM, as returned by maketform, is a spatial transformation structure. inbounds is a 2-by-num_dims matrix. The first row of inbounds specifies the lower bounds for each dimension, and the second row specifies the upper bounds. num_dims has to be consistent with the ndims_in field of TFORM. outbounds has the same form as inbounds. It is an estimate of the smallest rectangular region completely containing the transformed rectangle represented by the input bounds. Since outbounds is only an estimate, it might not completely contain the transformed input rectangle. Tips findbounds gets called by imtransform if 'XData' and 'YData', the parameters that control the output-space bounding box in imtransform, are not specified. findbounds computes the output-space bounding box. Algorithms 1 findbounds first creates a grid of input-space points. These points are located at the center, corners, and middle of each edge in the image. I = imread('rice.png'); h = imshow(I); set(h,'AlphaData',0.3); axis on, grid on in_points = [ ... 0.5000 0.5000 0.5000 256.5000 256.5000 0.5000 256.5000 256.5000 0.5000 128.5000 128.5000 0.5000 3-185 findbounds 128.5000 128.5000 128.5000 256.5000 256.5000 128.5000]; hold on plot(in_points(:,1),in_points(:,2),'.','MarkerSize',18) hold off Grid of Input-Space Points 2 Next, findbounds transforms the grid of input-space points to output space. If tform contains a forward transformation (a nonempty forward_fcn field), then findbounds transforms the input-space points using tformfwd. For example: tform = maketform('affine', ... [1.1067 -0.2341 0; 0.5872 1.1769 0; 1000 -300 1]); out_points = tformfwd(tform, in_points) The output appears below: out_points = 1.0e+003 * 3-186 findbounds 1.0008 1.1512 1.2842 1.4345 1.0760 1.1425 1.2177 1.2928 1.3593 -0.2995 0.0018 -0.3595 -0.0582 -0.1489 -0.3295 -0.1789 -0.0282 -0.2088 If TFORM does not contain a forward transformation, then findbounds estimates the output bounds using the Nelder-Mead optimization function fminsearch. 3 Finally, findbounds computes the bounding box of the transformed grid of points. See Also cp2tform | imtransform | maketform | tformarray | tformfwd | tforminv 3-187 fliptform Purpose Flip input and output roles of TFORM structure Syntax TFLIP = fliptform(T) Description TFLIP = fliptform(T) creates a new spatial transformation structure, a TFORM struct, by flipping the roles of the inputs and outputs in an existing TFORM struct. Examples T = maketform('affine', [.5 0 0; .5 2 0; 0 0 1]); T2 = fliptform(T) The following are equivalent: x = tformfwd([-3 7],T) x = tforminv([-3 7],T2) See Also 3-188 maketform | tformfwd | tforminv freqz2 Purpose 2-D frequency response Syntax [H, f1, f2] = freqz2(h, n1, n2) [H, f1, f2] = freqz2(h, [n2 n1]) [H, f1, f2] = freqz2(h) [H, f1, f2] = freqz2(h, f1, f2) [...] = freqz2(h,...,[dx dy]) [...] = freqz2(h,...,dx) freqz2(...) Description [H, f1, f2] = freqz2(h, n1, n2) returns H, the n2-by-n1 frequency response of h, and the frequency vectors f1 (of length n1) and f2 (of length n2). h is a two-dimensional FIR filter, in the form of a computational molecule. f1 and f2 are returned as normalized frequencies in the range -1.0 to 1.0, where 1.0 corresponds to half the sampling frequency, or π radians. [H, f1, f2] = freqz2(h, [n2 n1]) returns the same result returned by [H,f1,f2] = freqz2(h,n1,n2). [H, f1, f2] = freqz2(h) uses [n2 n1] = [64 64]. [H, f1, f2] = freqz2(h, f1, f2) returns the frequency response for the FIR filter h at frequency values in f1 and f2. These frequency values must be in the range -1.0 to 1.0, where 1.0 corresponds to half the sampling frequency, or π radians. [...] = freqz2(h,...,[dx dy]) uses [dx dy] to override the intersample spacing in h. dx determines the spacing for the x dimension and dy determines the spacing for the y dimension. The default spacing is 0.5, which corresponds to a sampling frequency of 2.0. [...] = freqz2(h,...,dx) uses dx to determine the intersample spacing in both dimensions. freqz2(...)produces a mesh plot of the two-dimensional magnitude frequency response when no output arguments are specified. 3-189 freqz2 Class Support The input matrix h can be of class double or of any integer class. All other inputs to freqz2 must be of class double. All outputs are of class double. Examples Use the window method to create a 16-by-16 filter, then view its frequency response using freqz2. Hd = zeros(16,16); Hd(5:12,5:12) = 1; Hd(7:10,7:10) = 0; h = fwind1(Hd,bartlett(16)); colormap(jet(64)) freqz2(h,[32 32]); axis ([-1 1 -1 1 0 1]) 1 Magnitude 0.8 0.6 0.4 0.2 0 1 0.5 1 0.5 0 0 −0.5 Fy See Also 3-190 freqz −0.5 −1 −1 Fx fsamp2 Purpose 2-D FIR filter using frequency sampling Syntax h = fsamp2(Hd) h = fsamp2(f1, f2, Hd,[m n]) Description h = fsamp2(Hd) designs a two-dimensional FIR filter with frequency response Hd, and returns the filter coefficients in matrix h. (fsamp2 returns h as a computational molecule, which is the appropriate form to use with filter2.) The filter h has a frequency response that passes through points in Hd. If Hd is m-by-n, then h is also m-by-n. fsamp2 designs two-dimensional FIR filters based on a desired two-dimensional frequency response sampled at points on the Cartesian plane. Hd is a matrix containing the desired frequency response sampled at equally spaced points between -1.0 and 1.0 along the x and y frequency axes, where 1.0 corresponds to half the sampling frequency, or π radians. H d ( f1 , f2 ) = H d (1 , 2 ) = f , = f 1 1 2 1 For accurate results, use frequency points returned by freqspace to create Hd. h = fsamp2(f1, f2, Hd,[m n]) produces an m-by-n FIR filter by matching the filter response at the points in the vectors f1 and f2. The frequency vectors f1 and f2 are in normalized frequency, where 1.0 corresponds to half the sampling frequency, or π radians. The resulting filter fits the desired response as closely as possible in the least squares sense. For best results, there must be at least m*n desired frequency points. fsamp2 issues a warning if you specify fewer than m*n points. Class Support The input matrix Hd can be of class double or of any integer class. All other inputs to fsamp2 must be of class double. All outputs are of class double. Examples Use fsamp2 to design an approximately symmetric two-dimensional bandpass filter with passband between 0.1 and 0.5 (normalized 3-191 fsamp2 frequency, where 1.0 corresponds to half the sampling frequency, or π radians): 1 Create a matrix Hd that contains the desired bandpass response. Use freqspace to create the frequency range vectors f1 and f2. [f1,f2] = freqspace(21,'meshgrid'); Hd = ones(21); r = sqrt(f1.^2 + f2.^2); Hd((r<0.1)|(r>0.5)) = 0; colormap(jet(64)) mesh(f1,f2,Hd) 1 0.8 0.6 0.4 0.2 0 1 0.5 1 0.5 0 0 −0.5 −0.5 −1 −1 2 Design the filter that passes through this response. h = fsamp2(Hd); freqz2(h) 3-192 fsamp2 Magnitude 1.5 1 0.5 0 1 0.5 1 0.5 0 0 −0.5 Fy −0.5 −1 −1 Fx Algorithms fsamp2 computes the filter h by taking the inverse discrete Fourier transform of the desired frequency response. If the desired frequency response is real and symmetric (zero phase), the resulting filter is also zero phase. References [1] Lim, Jae S., Two-Dimensional Signal and Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1990, pp. 213-217. See Also conv2 | filter2 | freqspace | ftrans2 | fwind1 | fwind2 3-193 fspecial Purpose Create predefined 2-D filter Syntax h = fspecial(type) h = fspecial(type, parameters) Description h = fspecial(type) creates a two-dimensional filter h of the specified type. fspecial returns h as a correlation kernel, which is the appropriate form to use with imfilter. type is a string having one of these values. Value Description average Averaging filter disk Circular averaging filter (pillbox) gaussian Gaussian lowpass filter laplacian Approximates the two-dimensional Laplacian operator log Laplacian of Gaussian filter motion Approximates the linear motion of a camera prewitt Prewitt horizontal edge-emphasizing filter sobel Sobel horizontal edge-emphasizing filter unsharp Unsharp contrast enhancement filter h = fspecial(type, parameters) accepts the filter specified by type plus additional modifying parameters particular to the type of filter chosen. If you omit these arguments, fspecial uses default values for the parameters. The following list shows the syntax for each filter type. Where applicable, additional parameters are also shown. • h = fspecial('average', hsize) returns an averaging filter h of size hsize. The argument hsize can be a vector specifying the 3-194 fspecial number of rows and columns in h, or it can be a scalar, in which case h is a square matrix. The default value for hsize is [3 3]. • h = fspecial('disk', radius) returns a circular averaging filter (pillbox) within the square matrix of side 2*radius+1. The default radius is 5. • h = fspecial('gaussian', hsize, sigma) returns a rotationally symmetric Gaussian lowpass filter of size hsize with standard deviation sigma (positive). hsize can be a vector specifying the number of rows and columns in h, or it can be a scalar, in which case h is a square matrix. The default value for hsize is [3 3]; the default value for sigma is 0.5. • h = fspecial('laplacian', alpha) returns a 3-by-3 filter approximating the shape of the two-dimensional Laplacian operator. The parameter alpha controls the shape of the Laplacian and must be in the range 0.0 to 1.0. The default value for alpha is 0.2. • h = fspecial('log', hsize, sigma) returns a rotationally symmetric Laplacian of Gaussian filter of size hsize with standard deviation sigma (positive). hsize can be a vector specifying the number of rows and columns in h, or it can be a scalar, in which case h is a square matrix. The default value for hsize is [5 5] and 0.5 for sigma. • h = fspecial('motion', len, theta) returns a filter to approximate, once convolved with an image, the linear motion of a camera by len pixels, with an angle of theta degrees in a counterclockwise direction. The filter becomes a vector for horizontal and vertical motions. The default len is 9 and the default theta is 0, which corresponds to a horizontal motion of nine pixels. To compute the filter coefficients, h, for 'motion': 1 Construct an ideal line segment with the desired length and angle, centered at the center coefficient of h. 2 For each coefficient location (i,j), compute the nearest distance between that location and the ideal line segment. 3-195 fspecial 3 h = max(1 - nearest_distance, 0); 4 Normalize h:h = h/(sum(h(:)) • h = fspecial('prewitt') returns the 3-by-3 filter h (shown below) that emphasizes horizontal edges by approximating a vertical gradient. If you need to emphasize vertical edges, transpose the filter h'. [ 1 1 1 0 0 0 -1 -1 -1 ] To find vertical edges, or for x-derivatives, use h'. • h = fspecial('sobel') returns a 3-by-3 filter h (shown below) that emphasizes horizontal edges using the smoothing effect by approximating a vertical gradient. If you need to emphasize vertical edges, transpose the filter h'. [ 1 2 1 0 0 0 -1 -2 -1 ] • h = fspecial('unsharp', alpha) returns a 3-by-3 unsharp contrast enhancement filter. fspecial creates the unsharp filter from the negative of the Laplacian filter with parameter alpha. alpha controls the shape of the Laplacian and must be in the range 0.0 to 1.0. The default value for alpha is 0.2. Note Do not be confused by the name of this filter: an unsharp filter is an operator used to sharpen images. The name comes from a publishing industry process in which an image is sharpened by subtracting a blurred (unsharp) version of the image from itself. 3-196 fspecial fspecial supports the generation of efficient, production-quality C/C++ code from MATLAB. For best results, all inputs must be constants at compilation time. Expressions or variables are allowed if their values do not change. To see a complete list of toolbox functions that support code generation, see “Supported Functions”. Class Support h is of class double. Examples I = imread('cameraman.tif'); subplot(2,2,1); imshow(I); title('Original Image'); H = fspecial('motion',20,45); MotionBlur = imfilter(I,H,'replicate'); subplot(2,2,2); imshow(MotionBlur);title('Motion Blurred Image'); H = fspecial('disk',10); blurred = imfilter(I,H,'replicate'); subplot(2,2,3); imshow(blurred); title('Blurred Image'); H = fspecial('unsharp'); sharpened = imfilter(I,H,'replicate'); subplot(2,2,4); imshow(sharpened); title('Sharpened Image'); 3-197 fspecial Algorithms fspecial creates Gaussian filters using hg (n1 , n2 ) = h(n1 , n2 ) = −( n12 + n22 ) 2 e 2 hg (n1 , n2 ) ∑ ∑ hg n1 n2 fspecial creates Laplacian filters using 3-198 fspecial ∇2 = ∂2 ∂x2 + ∂2 ∂y2 ⎡ ⎢ 4 ⎢ 4 ⎢1 − 2 ∇ = ( + 1) ⎢ 4 ⎢ ⎢ ⎢⎣ 4 1− 4 −1 1− 4 ⎤ 4 ⎥ ⎥ 1− ⎥ 4 ⎥ ⎥⎥ 4 ⎥⎦ fspecial creates Laplacian of Gaussian (LoG) filters using hg (n1 , n2 ) = h(n1 , n2 ) = −( n12 + n22 ) 2 e 2 (n12 + n22 − 2 2 )hg (n1 , n2 ) 2 6 ∑ ∑ hg n1 n2 fspecial creates averaging filters using ones(n(1),n(2))/(n(1)*n(2)) fspecial creates unsharp filters using ⎡ − − 1 − ⎤ 1 ⎢ − 1 + 5 − 1⎥⎥ ( + 1) ⎢ ⎢⎣ − − 1 − ⎥⎦ See Also conv2 | edge | filter2 | fsamp2 | fwind1 | fwind2 | imfilter | del2 3-199 ftrans2 Purpose 2-D FIR filter using frequency transformation Syntax h = ftrans2(b, t) h = ftrans2(b) Description h = ftrans2(b, t) produces the two-dimensional FIR filter h that corresponds to the one-dimensional FIR filter b using the transform t. (ftrans2 returns h as a computational molecule, which is the appropriate form to use with filter2.) b must be a one-dimensional, Type I (even symmetric, odd-length) filter such as can be returned by fir1, fir2, or remez in the Signal Processing Toolbox software. The transform matrix t contains coefficients that define the frequency transformation to use. If t is m-by-n and b has length Q, then h is size ((m-1)*(Q-1)/2+1)-by-((n-1)*(Q-1)/2+1). h = ftrans2(b) uses the McClellan transform matrix t. t = [1 2 1; 2 -4 2; 1 2 1]/8; All inputs and outputs should be of class double. Tips The transformation below defines the frequency response of the two-dimensional filter returned by ftrans2. H(1 ,2 ) = B( ) cos =T (1 ,2 ) , where B(ω) is the Fourier transform of the one-dimensional filter b: B( ) = N ∑ b(n) e− j n n=− N and T(ω1,ω2) is the Fourier transform of the transformation matrix t: T (1 , 2 ) = ∑ ∑ t(n1 , n2 ) e− j1n1 e− j2 n2 . n2 n1 The returned filter h is the inverse Fourier transform of H(ω1,ω2): 3-200 ftrans2 h(n1 , n2 ) = Examples 1 ( 2 ) ∫ ∫ 2 − − H (1 , 2 ) e j1n1 e j2 n2 d1 d2 . Use ftrans2 to design an approximately circularly symmetric two-dimensional bandpass filter with passband between 0.1 and 0.6 (normalized frequency, where 1.0 corresponds to half the sampling frequency, or π radians): 1 Since ftrans2 transforms a one-dimensional FIR filter to create a two-dimensional filter, first design a one-dimensional FIR bandpass filter using the Signal Processing Toolbox function remez. colormap(jet(64)) b = remez(10,[0 0.05 0.15 0.55 0.65 1],[0 0 1 1 0 0]); [H,w] = freqz(b,1,128,'whole'); plot(w/pi-1,fftshift(abs(H))) 1.4 1.2 1 0.8 0.6 0.4 0.2 0 −1 −0.8 −0.6 −0.4 −0.2 0 0.2 0.4 0.6 0.8 1 3-201 ftrans2 2 Use ftrans2 with the default McClellan transformation to create the desired approximately circularly symmetric filter. h = ftrans2(b); freqz2(h) Magnitude 1.5 1 0.5 0 1 0.5 1 0.5 0 0 −0.5 Fy −0.5 −1 −1 Fx References [1] Lim, Jae S., Two-Dimensional Signal and Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1990, pp. 218-237. See Also conv2 | filter2 | fsamp2 | fwind1 | fwind2 3-202 fwind1 Purpose 2-D FIR filter using 1-D window method Syntax h = fwind1(Hd, win) h = fwind1(Hd, win1, win2) h = fwind1(f1, f2, Hd,...) Description fwind1 designs two-dimensional FIR filters using the window method. fwind1 uses a one-dimensional window specification to design a two-dimensional FIR filter based on the desired frequency response Hd. fwind1 works with one-dimensional windows only; use fwind2 to work with two-dimensional windows. h = fwind1(Hd, win) designs a two-dimensional FIR filter h with frequency response Hd. (fwind1 returns h as a computational molecule, which is the appropriate form to use with filter2.) fwind1 uses the one-dimensional window win to form an approximately circularly symmetric two-dimensional window using Huang’s method. You can specify win using windows from the Signal Processing Toolbox software, such as boxcar, hamming, hanning, bartlett, blackman, kaiser, or chebwin. If length(win) is n, then h is n-by-n. Hd is a matrix containing the desired frequency response sampled at equally spaced points between -1.0 and 1.0 (in normalized frequency, where 1.0 corresponds to half the sampling frequency, or π radians) along the x and y frequency axes. For accurate results, use frequency points returned by freqspace to create Hd. (See the entry for freqspace for more information.) h = fwind1(Hd, win1, win2) uses the two one-dimensional windows win1 and win2 to create a separable two-dimensional window. If length(win1) is n and length(win2) is m, then h is m-by-n. h = fwind1(f1, f2, Hd,...) lets you specify the desired frequency response Hd at arbitrary frequencies (f1 and f2) along the x- and y-axes. The frequency vectors f1 and f2 should be in the range -1.0 to 1.0, where 1.0 corresponds to half the sampling frequency, or π radians. The length of the windows controls the size of the resulting filter, as above. 3-203 fwind1 Class Support The input matrix Hd can be of class double or of any integer class. All other inputs to fwind1 must be of class double. All outputs are of class double. Examples Use fwind1 to design an approximately circularly symmetric two-dimensional bandpass filter with passband between 0.1 and 0.5 (normalized frequency, where 1.0 corresponds to half the sampling frequency, or π radians): 1 Create a matrix Hd that contains the desired bandpass response. Use freqspace to create the frequency range vectors f1 and f2. [f1,f2] = freqspace(21,'meshgrid'); Hd = ones(21); r = sqrt(f1.^2 + f2.^2); Hd((r<0.1)|(r>0.5)) = 0; colormap(jet(64)) mesh(f1,f2,Hd) 1 0.8 0.6 0.4 0.2 0 1 0.5 1 0.5 0 0 −0.5 −0.5 −1 3-204 −1 fwind1 2 Design the filter using a one-dimensional Hamming window. h = fwind1(Hd,hamming(21)); freqz2(h) Magnitude 1.5 1 0.5 0 1 0.5 1 0.5 0 0 −0.5 −0.5 −1 Fy Algorithms −1 Fx fwind1 takes a one-dimensional window specification and forms an approximately circularly symmetric two-dimensional window using Huang’s method, w(n1 , n2 ) = w(t) t = n12 + n22 , where w(t) is the one-dimensional window and w(n1,n2) is the resulting two-dimensional window. Given two windows, fwind1 forms a separable two-dimensional window: w(n1 , n2 ) = w1 (n1 )w2 (n2 ). 3-205 fwind1 fwind1 calls fwind2 with Hd and the two-dimensional window. fwind2 computes h using an inverse Fourier transform and multiplication by the two-dimensional window: hd (n1 , n2 ) = 1 ( 2 ) ∫ ∫ 2 − − H d (1 , 2 ) e j1n1 e j2 n2 d1 d2 h(n1 , n2 ) = hd (n1 , n2 )w(n2 , n2 ). References [1] Lim, Jae S., Two-Dimensional Signal and Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1990. See Also conv2 | filter2 | fsamp2 | freqspace | ftrans2 | fwind2 3-206 fwind2 Purpose 2-D FIR filter using 2-D window method Syntax h = fwind2(Hd, win) h = fwind2(f1, f2, Hd, win) Description Use fwind2 to design two-dimensional FIR filters using the window method. fwind2 uses a two-dimensional window specification to design a two-dimensional FIR filter based on the desired frequency response Hd. fwind2 works with two-dimensional windows; use fwind1 to work with one-dimensional windows. h = fwind2(Hd, win) produces the two-dimensional FIR filter h using an inverse Fourier transform of the desired frequency response Hd and multiplication by the window win. Hd is a matrix containing the desired frequency response at equally spaced points in the Cartesian plane. fwind2 returns h as a computational molecule, which is the appropriate form to use with filter2. h is the same size as win. For accurate results, use frequency points returned by freqspace to create Hd. (See the entry for freqspace for more information.) h = fwind2(f1, f2, Hd, win) lets you specify the desired frequency response Hd at arbitrary frequencies (f1 and f2) along the x- and y-axes. The frequency vectors f1 and f2 should be in the range -1.0 to 1.0, where 1.0 corresponds to half the sampling frequency, or π radians. h is the same size as win. Class Support The input matrix Hd can be of class double or of any integer class. All other inputs to fwind2 must be of class double. All outputs are of class double. Examples Use fwind2 to design an approximately circularly symmetric two-dimensional bandpass filter with passband between 0.1 and 0.5 (normalized frequency, where 1.0 corresponds to half the sampling frequency, or π radians): 1 Create a matrix Hd that contains the desired bandpass response. Use freqspace to create the frequency range vectors f1 and f2. 3-207 fwind2 [f1,f2] = freqspace(21,'meshgrid'); Hd = ones(21); r = sqrt(f1.^2 + f2.^2); Hd((r<0.1)|(r>0.5)) = 0; colormap(jet(64)) mesh(f1,f2,Hd) 1 0.8 0.6 0.4 0.2 0 1 0.5 1 0.5 0 0 −0.5 −0.5 −1 −1 2 Create a two-dimensional Gaussian window using fspecial. win = fspecial('gaussian',21,2); win = win ./ max(win(:)); mesh(win) 3-208 % Make the maximum window value be 1. fwind2 1 0.8 0.6 0.4 0.2 0 30 20 10 0 0 5 10 15 20 25 3 Design the filter using the window from step 2. h = fwind2(Hd,win); freqz2(h) 3-209 fwind2 1 Magnitude 0.8 0.6 0.4 0.2 0 1 0.5 1 0.5 0 0 −0.5 −0.5 −1 Fy Algorithms −1 Fx fwind2 computes h using an inverse Fourier transform and multiplication by the two-dimensional window win. hd (n1 , n2 ) = 1 ( 2 ) ∫ ∫ 2 − − H d (1 , 2 ) e j1n1 e j2 n2 d1 d2 h(n1 , n2 ) = hd (n1 , n2 )w(n1 , n2 ) References [1] Lim, Jae S., Two-Dimensional Signal and Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1990, pp. 202-213. See Also conv2 | filter2 | fsamp2 | freqspace | ftrans2 | fwind1 3-210 getheight Purpose Height of structuring element Syntax H = getheight(SE) Description H = getheight(SE) returns an array the same size as getnhood(SE) Class Support SE is a STREL object. H is of class double. Examples se = strel(ones(3,3),magic(3)); getheight(se) See Also strel | getnhood containing the height associated with each of the structuring element neighbors. H is all zeros for a flat structuring element. 3-211 getimage Purpose Image data from axes Syntax A = getimage(h) [x, y, A] = getimage(h) [..., A, flag] = getimage(h) [...] = getimage Description A = getimage(h) returns the first image data contained in the Handle Graphics object h. h can be a figure, axes, or image. A is identical to the image CData; it contains the same values and is of the same class (uint8, uint16, double, or logical) as the image CData. If h is not an image or does not contain an image, A is empty. [x, y, A] = getimage(h) returns the image XData in x and the YData in y. XData and YData are two-element vectors that indicate the range of the x-axis and y-axis. [..., A, flag] = getimage(h) returns an integer flag that indicates the type of image h contains. This table summarizes the possible values for flag. Flag Type of Image 0 Not an image; A is returned as an empty matrix 1 Indexed image 2 Intensity image with values in standard range ([0,1] for single and double arrays, [0,255] for uint8 arrays, [0,65535] for uint16 arrays) 3 Intensity data, but not in standard range 4 RGB image 5 Binary image = getimage returns information for the current axes object. It is equivalent to [...] = getimage(gca). [...] 3-212 getimage Class Support The output array A is of the same class as the image CData. All other inputs and outputs are of class double. Note For int16 and single images, the image data returned by getimage is of class double, not int16 or single. This is because the getimage function gets the data from the image object’s CData property and image objects store int16 and single image data as class double. For example, create an image object of class int16. If you retrieve the CData from the object and check its class, it returns double. h = imshow(ones(10,'int16')); class(get(h,'CData')) Therefore, if you get the image data using the getimage function, the data it returns is also of class double. The flag return value is set to 3. [img,flag] = getimage(h); class(img) The same is true for an image of class single. Getting the CData directly from the image object or by using getimage, the class of the returned data is double. h = imshow(ones(10,'single')); class(get(h,'CData')) [img,flag] = getimage(h); class(img) For images of class single, the flag return value is set to 2 because single and double share the same dynamic range. Examples After using imshow or imtool to display an image directly from a file, use getimage to get the image data into the workspace. imshow rice.png I = getimage; 3-213 getimage imtool cameraman.tif I = getimage(imgca); See Also 3-214 imshow | imtool getimagemodel Purpose Image model object from image object Syntax imgmodel = getimagemodel(himage) Description imgmodel = getimagemodel(himage) returns the image model object associated with himage. himage must be a handle to an image object or an array of handles to image objects. The return value imgmodel is an image model object. If himage is an array of handles to image objects, imgmodel is an array of image models. If himage does not have an associated image model object, getimagemodel creates one. Examples h = imshow('bag.png'); imgmodel = getimagemodel(h); See Also imagemodel 3-215 getline Purpose Select polyline with mouse Syntax [x, [x, [x, [x, Description [x, y] = getline(fig) lets you select a polyline in the current axes of figure fig using the mouse. Coordinates of the polyline are returned in X and Y. Use normal button clicks to add points to the polyline. A shift-, y] y] y] y] = = = = getline(fig) getline(ax) getline getline(...,'closed') right-, or double-click adds a final point and ends the polyline selection. Pressing Return or Enter ends the polyline selection without adding a final point. Pressing Backspace or Delete removes the previously selected point from the polyline. [x, y] = getline(ax) lets you select a polyline in the axes specified by the handle ax. [x, y] = getline is the same as [x,y] = getline(gcf). [x, y] = getline(...,'closed') animates and returns a closed polygon. See Also 3-216 getpts | getrect getneighbors Purpose Structuring element neighbor locations and heights Syntax [offsets, heights] = getneighbors(SE) Description [offsets, heights] = getneighbors(SE) returns the relative locations and corresponding heights for each of the neighbors in the structuring element object SE. offsets is a P-by-N array where P is the number of neighbors in the structuring element and N is the dimensionality of the structuring element. Each row of offsets contains the location of the corresponding neighbor, relative to the center of the structuring element. heights is a P-element column vector containing the height of each structuring element neighbor. Class Support SE is a STREL object. The return values offsets and heights are arrays Examples se = strel([1 0 1],[5 0 -5]) [offsets,heights] = getneighbors(se) se = Nonflat STREL object containing 2 neighbors. of double-precision values. Neighborhood: 1 0 Height: 5 0 1 -5 offsets = 0 -1 0 1 heights = 5 -5 See Also strel | getnhood | getheight 3-217 getnhood Purpose Structuring element neighborhood Syntax NHOOD = getnhood(SE) Description NHOOD = getnhood(SE) returns the neighborhood associated with the structuring element SE. Class Support SE is a STREL object. NHOOD is a logical array. Examples se = strel(eye(5)); NHOOD = getnhood(se) See Also strel | getneighbors 3-218 getpts Purpose Specify points with mouse Syntax [x, y] = getpts(fig) [x, y] = getpts(ax) [x, y] = getpts Description [x, y] = getpts(fig) lets you choose a set of points in the current axes of figure fig using the mouse. Coordinates of the selected points are returned in X and Y. Use normal button clicks to add points. A shift-, right-, or double-click adds a final point and ends the selection. Pressing Return or Enter ends the selection without adding a final point. Pressing Backspace or Delete removes the previously selected point. [x, y] = getpts(ax) lets you choose points in the axes specified by the handle ax. [x, y] = getpts is the same as [x,y] = getpts(gcf). See Also getline | getrect 3-219 getrangefromclass Purpose Default display range of image based on its class Syntax range = getrangefromclass(I) Description range = getrangefromclass(I) returns the default display range of the image I, based on its class type. The function returns range, a two-element vector specifying the display range in the form [min max]. Class Support I can be uint8, uint16, int16, logical, single, or double. range is of class double. Note For single and double data, getrangefromclass returns the range [0 1] to be consistent with the way double and single images are interpreted in MATLAB. For integer data, getrangefromclass returns the default display range of the class. For example, if the class is uint8, the dynamic range is [0 255]. Examples Read in the 16-bit DICOM image and get the default display range. CT = dicomread('CT-MONO2-16-ankle.dcm'); r = getrangefromclass(CT) r = -32768 See Also 3-220 intmin | intmax 32767 getrect Purpose Specify rectangle with mouse Syntax rect = getrect rect = getrect(fig) rect = getrect(ax) Description rect = getrect lets you select a rectangle in the current axes using the mouse. Use the mouse to click and drag the desired rectangle. rect is a four-element vector with the form [xmin ymin width height]. To constrain the rectangle to be a square, use a shift- or right-click to begin the drag. rect = getrect(fig) lets you select a rectangle in the current axes of figure fig using the mouse. rect = getrect(ax) lets you select a rectangle in the axes specified by the handle ax. Examples Select a rectangle in an image of the moon: imshow('moon.tif') rect = getrect See Also getline | getpts 3-221 getsequence Purpose Sequence of decomposed structuring elements Syntax SEQ = getsequence(SE) Description SEQ = getsequence(SE) returns the array of structuring elements SEQ, containing the individual structuring elements that form the decomposition of SE. SE can be an array of structuring elements. SEQ is equivalent to SE, but the elements of SEQ have no decomposition. Class Support SE and SEQ are arrays of STREL objects. Examples The strel function uses decomposition for square structuring elements larger than 3-by-3. Use getsequence to extract the decomposed structuring elements. se = strel('square',5) se = Flat STREL object containing 25 neighbors. Decomposition: 2 STREL objects containing a total of 10 neighbors Neighborhood: 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 seq = getsequence(se) seq = 2x1 array of STREL objects Use imdilate with the 'full' option to see that dilating sequentially with the decomposed structuring elements really does form a 5-by-5 square: imdilate(1,seq,'full') 3-222 getsequence See Also imdilate | imerode | strel 3-223 gray2ind Purpose Convert grayscale or binary image to indexed image Syntax [X, map] = gray2ind(I,n) [X, map] = gray2ind(BW,n) Description [X, map] = gray2ind(I,n) converts the grayscale image I to an indexed image X. n specifies the size of the colormap, gray(n). n must be an integer between 1 and 65536. If n is omitted, it defaults to 64. [X, map] = gray2ind(BW,n) converts the binary image BW to an indexed image X. n specifies the size of the colormap, gray(n). If n is omitted, it defaults to 2. gray2ind scales and then rounds the intensity image to produce an equivalent indexed image. Class Support The input image I can be logical, uint8, uint16, int16, single, or double and must be a real and nonsparse. The image I can have any dimension. The class of the output image X is uint8 if the colormap length is less than or equal to 256; otherwise it is uint16. Examples Convert a grayscale image into an indexed image and then view the result. I = imread('cameraman.tif'); [X, map] = gray2ind(I, 16); imshow(X, map); See Also 3-224 grayslice | ind2gray | mat2gray graycomatrix Purpose Create gray-level co-occurrence matrix from image Syntax glcm = graycomatrix(I) glcms = graycomatrix(I, param1, val1, param2, val2,...) [glcm, SI] = graycomatrix(...) Description glcm = graycomatrix(I) creates a gray-level co-occurrence matrix (GLCM) from image I. graycomatrix creates the GLCM by calculating how often a pixel with gray-level (grayscale intensity) value i occurs horizontally adjacent to a pixel with the value j. (You can specify other pixel spatial relationships using the 'Offsets' parameter -- see Parameters.) Each element (i,j) in glcm specifies the number of times that the pixel with value i occurred horizontally adjacent to a pixel with value j. graycomatrix calculates the GLCM from a scaled version of the image. By default, if I is a binary image, graycomatrix scales the image to two gray-levels. If I is an intensity image, graycomatrix scales the image to eight gray-levels. You can specify the number of gray-levels graycomatrix uses to scale the image by using the 'NumLevels' parameter, and the way that graycomatrix scales the values using the 'GrayLimits' parameter — see Parameters. The following figure shows how graycomatrix calculates several values in the GLCM of the 4-by-5 image I. Element (1,1) in the GLCM contains the value 1 because there is only one instance in the image where two, horizontally adjacent pixels have the values 1 and 1. Element (1,2) in the GLCM contains the value 2 because there are two instances in the image where two, horizontally adjacent pixels have the values 1 and 2. graycomatrix continues this processing to fill in all the values in the GLCM. 3-225 graycomatrix glcms = graycomatrix(I, param1, val1, param2, val2,...) returns one or more gray-level co-occurrence matrices, depending on the values of the optional parameter/value pairs. Parameter names can be abbreviated, and case does not matter. Parameters Parameter Description Default 'GrayLimits' Two-element vector, [low high], that specifies how the grayscale values in I are linearly scaled into gray levels. Grayscale values less than or equal to low are scaled to 1. Grayscale values greater than or equal to high are scaled to NumLevels. If graylimits is set to [], graycomatrix uses the minimum and maximum grayscale values in the image as limits, [min(I(:)) max(I(:))]. Minimum and maximum specified by class, e.g. Integer specifying the number of gray-levels to use when scaling the grayscale values in I. For example, if NumLevels is 8, graycomatrix scales 8 (numeric) 2 (binary) 'NumLevels' 3-226 The following table lists these parameters in alphabetical order. double [0 1] int16 [-32768 32767] graycomatrix Parameter Description Default the values in I so they are integers between 1 and 8. The number of gray-levels determines the size of the gray-level co-occurrence matrix (glcm). 'Offset' p-by-2 array of integers specifying the distance between the pixel of interest and its neighbor. Each row in the array is a two-element vector, [row_offset, col_offset], that specifies the relationship, or offset, of a pair of pixels. row_offset is the number of rows between the pixel-of-interest and its neighbor. col_offset is the number of columns between the pixel-of-interest and its neighbor. Because the offset is often expressed as an angle, the following table lists the offset values that specify common angles, given the pixel distance D. Angle Offset 0 [0 D] 45 [-D D] 90 [-D 0] 135 [0 1] [-D -D] The figure illustrates the array: offset = [0 1; -1 1; -1 0; -1 -1] 'Symmetric' Boolean that creates a GLCM where the ordering of values in the pixel pairs is not considered. For example, when 'Symmetric' is set to true, false 3-227 graycomatrix Parameter Description Default graycomatrix counts both 1,2 and 2,1 pairings when calculating the number of times the value 1 is adjacent to the value 2. When 'Symmetric' is set to false, graycomatrix only counts 1,2 or 2,1, depending on the value of 'offset'. See “Notes” on page 3-228. [glcm, SI] = graycomatrix(...) returns the scaled image, SI, used to calculate the gray-level co-occurrence matrix. The values in SI are between 1 and NumLevels. Class Support I can be numeric or logical but must be two-dimensional, real, and nonsparse. SI is a double matrix having the same size as I. glcms is a 'NumLevels'-by-'NumLevels'-by-P double array where P is the number of offsets in 'Offset'. Notes Another name for a gray-level co-occurrence matrix is a gray-level spatial dependence matrix. Also, the word co-occurrence is frequently used in the literature without a hyphen, cooccurrence. graycomatrix ignores pixel pairs if either of the pixels contains a NaN. graycomatrix replaces positive Infs with the value NumLevels and replaces negative Infs with the value 1. graycomatrix ignores border pixels, if the corresponding neighbor pixel falls outside the image boundaries. The GLCM created when 'Symmetric' is set to true is symmetric across its diagonal, and is equivalent to the GLCM described by Haralick (1973). The GLCM produced by the following syntax, with 'Symmetric' set to true graycomatrix(I, 'offset', [0 1], 'Symmetric', true) is equivalent to the sum of the two GLCMs produced by the following statements where'Symmetric' is set to false. 3-228 graycomatrix graycomatrix(I, 'offset', [0 1], 'Symmetric', false) graycomatrix(I, 'offset', [0 -1], 'Symmetric', false) Examples Calculate the gray-level co-occurrence matrix for a grayscale image. I = imread('circuit.tif'); glcm = graycomatrix(I,'Offset',[2 0]); Calculate the gray-level co-occurrence matrix and return the scaled version of the image, SI, used by graycomatrix to generate the GLCM. I = [ 1 1 5 6 8 8; 2 3 5 7 0 2; 0 2 3 5 6 7]; [glcm,SI] = graycomatrix(I,'NumLevels',9,'G',[]) References Haralick, R.M., K. Shanmugan, and I. Dinstein, "Textural Features for Image Classification", IEEE Transactions on Systems, Man, and Cybernetics, Vol. SMC-3, 1973, pp. 610-621. Haralick, R.M., and L.G. Shapiro. Computer and Robot Vision: Vol. 1, Addison-Wesley, 1992, p. 459. See Also graycoprops 3-229 graycoprops Purpose Properties of gray-level co-occurrence matrix Syntax stats = graycoprops(glcm, properties) Description stats = graycoprops(glcm, properties) calculates the statistics specified in properties from the gray-level co-occurence matrix glcm. glcm is an m-by-n-by-p array of valid gray-level co-occurrence matrices. If glcm is an array of GLCMs, stats is an array of statistics for each glcm. graycoprops normalizes the gray-level co-occurrence matrix (GLCM) so that the sum of its elements is equal to 1. Each element (r,c) in the normalized GLCM is the joint probability occurrence of pixel pairs with a defined spatial relationship having gray level values r and c in the image. graycoprops uses the normalized GLCM to calculate properties. properties can be a comma-separated list of strings, a cell array containing strings, the string 'all', or a space separated string. The property names can be abbreviated and are not case sensitive. Property Description 'Contrast' Returns a measure of the intensity contrast between a pixel and its neighbor over the whole image. Formula ∑ i− j 2 p(i, j) i, j Range = [0 (size(GLCM,1)-1)^2] Contrast is 0 for a constant image. 'Correlation' Returns a measure of how correlated a pixel is to its neighbor over the whole image. ∑ i, j Range = [-1 1] Correlation is 1 or -1 for a perfectly positively or negatively correlated image. Correlation is NaN for a constant image. 3-230 (i − i)( j − j) p(i, j) i j graycoprops Property Description 'Energy' Returns the sum of squared elements in the GLCM. Formula Range = [0 1] ∑ p(i, j)2 i, j Energy is 1 for a constant image. 'Homogeneity' Returns a value that measures the closeness of the distribution of elements in the GLCM to the GLCM diagonal. p(i, j) ∑1 + i − j i, j Range = [0 1] Homogeneity is 1 for a diagonal GLCM. stats is a structure with fields that are specified by properties. Each field contains a 1 x p array, where p is the number of gray-level co-occurrence matrices in GLCM. For example, if GLCM is an 8 x 8 x 3 array and properties is 'Energy', then stats is a structure containing the field Energy, which contains a 1 x 3 array. Notes Energy is also known as uniformity, uniformity of energy, and angular second moment. Contrast is also known as variance and inertia. Class Support glcm can be logical or numeric, and it must contain real, non-negative, finite, integers. stats is a structure. Examples GLCM = [0 1 2 3;1 1 2 3;1 0 2 0;0 0 0 3]; stats = graycoprops(GLCM) I = imread('circuit.tif'); GLCM2 = graycomatrix(I,'Offset',[2 0;0 2]); stats = graycoprops(GLCM2,{'contrast','homogeneity'}) 3-231 graycoprops See Also 3-232 graycomatrix graydist Purpose Gray-weighted distance transform of grayscale image Syntax T T T T Description T = graydist(A,mask) computes the gray-weighted distance transform of the grayscale image A. Locations where mask is true are seed locations. = = = = graydist(A,mask) graydist(A,C,R) graydist(A,ind) graydist(...,method) T = graydist(A,C,R) uses vectors C and R to specify the row and column coordinates of seed locations. T = graydist(A,ind) specifies the linear indices of seed locations using the vector ind. T = graydist(...,method) specifies an alternate distance metric. method determines the chamfer weights that are assigned to the local neighborhood during outward propagation. Each pixel’s contribution to the geodesic time is based on the chamfer weight in a particular direction multiplied by the pixel intensity. Input Arguments A Grayscale image. mask Logical image the same size as A that specifies seed locations. C,R Numeric vectors that contain the positive integer row and column coordinates of the seed locations. Coordinate values are valid C,R subscripts in A. ind Numeric vector of positive integer, linear indices of seed locations. 3-233 graydist method Type of distance metric. method can have any of these values. Method Description 'cityblock' In 2-D, the cityblock distance between (x1,y1) and (x2,y2) is │x1 – x2│ + │y1 – y2│. 'chessboard' The chessboard distance is max(│x1 – x2│,│y1 – y2│). 'quasieuclidean' The quasi-Euclidean distance is x1 x2 ( 2 1) y1 y2 , x1 x2 y1 y2 ( 2 − 1) x1 − x2 + y1 − y2 , otherwise. Default: 'chessboard' Output Arguments Class Support T Array the same size as A that specifies the gray-weighted distance transform. If the input numeric type of A is double, the output numeric type of T is double. If the input is any other numeric type, the output T is single. A can be numeric or logical, and it must be nonsparse. mask is a logical array of the same size as A. C, R, and ind are numeric vectors that contain positive integer values. The output T is an array of the same size as A. If the input numeric type of A is double, the output T is double. If the input is any other numeric type, the output T is single. Examples 3-234 Matrices generated by the magic function have equal row, column and diagonal sums. The minimum path between the upper left and lower graydist right corner is along the diagonal. The following example demonstrates how the graydist function computes this path: A T1 T2 T = = = = magic(3) graydist(A,1,1); graydist(A,3,3); T1 + T2 A = 8 3 4 1 5 9 6 7 2 10 13 17 11 10 17 17 13 10 T = As expected, there is a constant-value minimum path along the diagonal. Algorithms graydist uses the geodesic time algorithm described in Soille, P., Generalized geodesy via geodesic time,, Pattern Recognition Letters, vol.15, December 1994; pp. 1235–1240 The basic equation for geodesic time along a path is: f P f po 2 f pl 2 l 1 f pi i 1 3-235 graydist See Also 3-236 bwdist | bwdistgeodesic | watershed grayslice Purpose Convert grayscale image to indexed image using multilevel thresholding Syntax X = grayslice(I, n) Description X = grayslice(I, n) thresholds the intensity image I returning an indexed image in X. grayslice uses the threshold values: X = grayslice(I, v) thresholds the intensity image I using the values of v, where v is a vector of values between 0 and 1, returning an indexed image in X. You can view the thresholded image using imshow(X,map) with a colormap of appropriate length. Class Support The input image I can be of class uint8, uint16, int16, single, or double, and must be nonsparse. Note that the threshold values are always between 0 and 1, even if I is of class uint8 or uint16. In this case, each threshold value is multiplied by 255 or 65535 to determine the actual threshold to use. The class of the output image X depends on the number of threshold values, as specified by n or length(v). If the number of threshold values is less than 256, then X is of class uint8, and the values in X range from 0 to n or length(v). If the number of threshold values is 256 or greater, X is of class double, and the values in X range from 1 to n+1 or length(v)+1. Examples I = imread('snowflakes.png'); X = grayslice(I,16); imshow(I) figure, imshow(X,jet(16)) 3-237 grayslice See Also 3-238 gray2ind graythresh Purpose Global image threshold using Otsu’s method Syntax level = graythresh(I) [level EM] = graythresh(I) Description level = graythresh(I) computes a global threshold (level) that can be used to convert an intensity image to a binary image with im2bw. level is a normalized intensity value that lies in the range [0, 1]. The graythresh function uses Otsu’s method, which chooses the threshold to minimize the intraclass variance of the black and white pixels. Multidimensional arrays are converted automatically to 2-D arrays using reshape. The graythresh function ignores any nonzero imaginary part of I. [level EM] = graythresh(I) returns the effectiveness metric, EM, as the second output argument. The effectiveness metric is a value in the range [0 1] that indicates the effectiveness of the thresholding of the input image. The lower bound is attainable only by images having a single gray level, and the upper bound is attainable only by two-valued images. Class Support The input image I can be of class uint8, uint16, int16, single,or double and it must be nonsparse. The return value level is a double scalar. The effectiveness metric EM is a double scalar. Examples I = imread('coins.png'); level = graythresh(I); BW = im2bw(I,level); imshow(BW) References [1] Otsu, N., "A Threshold Selection Method from Gray-Level Histograms," IEEE Transactions on Systems, Man, and Cybernetics, Vol. 9, No. 1, 1979, pp. 62-66. See Also im2bw 3-239 hdrread Purpose Read high dynamic range (HDR) image Syntax hdr = hdrread(filename) Description hdr = hdrread(filename) reads the high dynamic range (HDR) image from the file specified by filename. hdr is an m-by-n-by-3 RGB array in the range [0,inf) of type single. For scene-referred data sets, these values usually are scene illumination in radiance units. To display these images, use an appropriate tone-mapping operator. Class Support The output image hdr is an m-by-n-by-3 image of type single. Examples hdr = hdrread('office.hdr'); rgb = tonemap(hdr); imshow(rgb); References [1] Larson, Greg W. “Radiance File Formats"http://radsite.lbl.gov/radiance/refer/filefmts.pdf See Also hdrwrite | makehdr | tonemap 3-240 hdrwrite Purpose Write Radiance high dynamic range (HDR) image file Syntax hdrwrite(hdr, filename) Description hdrwrite(hdr, filename) creates a Radiance high dynamic range (HDR) image file from HDR, a single- or double-precision high dynamic range RGB image. The HDR file with the name filename uses run-length encoding to minimize file size. See Also hdrread | makehdr | tonemap 3-241 histeq Purpose Enhance contrast using histogram equalization Syntax J = histeq(I, hgram) J = histeq(I, n) [J, T] = histeq(I,...) newmap = histeq(X, map, hgram) newmap = histeq(X, map) [newmap, T] = histeq(X,...) Description histeq enhances the contrast of images by transforming the values in an intensity image, or the values in the colormap of an indexed image, so that the histogram of the output image approximately matches a specified histogram. J = histeq(I, hgram) transforms the intensity image I so that the histogram of the output intensity image J with length(hgram) bins approximately matches hgram. The vector hgram should contain integer counts for equally spaced bins with intensity values in the appropriate range: [0, 1] for images of class double, [0, 255] for images of class uint8, and [0, 65535] for images of class uint16. histeq automatically scales hgram so that sum(hgram) = prod(size(I)). The histogram of J will better match hgram when length(hgram) is much smaller than the number of discrete levels in I. J = histeq(I, n) transforms the intensity image I, returning in J an intensity image with n discrete gray levels. A roughly equal number of pixels is mapped to each of the n levels in J, so that the histogram of J is approximately flat. (The histogram of J is flatter when n is much smaller than the number of discrete levels in I.) The default value for n is 64. [J, T] = histeq(I,...) returns the grayscale transformation that maps gray levels in the image I to gray levels in J. newmap = histeq(X, map, hgram) transforms the colormap associated with the indexed image X so that the histogram of the gray component of the indexed image (X,newmap) approximately matches hgram. The histeq function returns the transformed colormap in newmap. length(hgram) must be the same as size(map,1). 3-242 histeq newmap = histeq(X, map) transforms the values in the colormap so that the histogram of the gray component of the indexed image X is approximately flat. It returns the transformed colormap in newmap. [newmap, T] = histeq(X,...) returns the grayscale transformation T that maps the gray component of map to the gray component of newmap. Class Support For syntax that include an intensity image I as input, I can be of class uint8, uint16, int16, single, or double. The output image J has the same class as I. For syntax that include an indexed image X as input, X can be of class uint8, single, or double; the output colormap is always of class double. The optional output T (the gray-level transform) is always of class double. Examples Enhance the contrast of an intensity image using histogram equalization. I = imread('tire.tif'); J = histeq(I); imshow(I) figure, imshow(J) Display a histogram of the original image. figure; imhist(I,64) 3-243 histeq 3000 2500 2000 1500 1000 500 0 0 50 100 150 200 Compare it to a histogram of the processed image. figure; imhist(J,64) 3-244 250 histeq 2000 1800 1600 1400 1200 1000 800 600 400 200 0 0 Algorithms 50 100 150 200 250 When you supply a desired histogram hgram, histeq chooses the grayscale transformation T to minimize c1 (T (k)) − c0 (k) , where c0 is the cumulative histogram of A, c1 is the cumulative sum of hgram for all intensities k. This minimization is subject to the constraints that T must be monotonic and c1(T(a)) cannot overshoot c0(a) by more than half the distance between the histogram counts at a. histeq uses the transformation b = T(a) to map the gray levels in X (or the colormap) to their new values. If you do not specify hgram, histeq creates a flat hgram, hgram = ones(1,n)*prod(size(A))/n; and then applies the previous algorithm. 3-245 histeq See Also 3-246 brighten | imadjust | imhist hough Purpose Hough transform Syntax [H, theta, rho] = hough(BW) [H, theta, rho] = hough(BW, ParameterName, ParameterValue) Description [H, theta, rho] = hough(BW) computes the Standard Hough Transform (SHT) of the binary image BW. Use the hough function to detect lines in an image. The function returns H, the Hough transform matrix. theta (in degrees) and rho are the arrays of rho and theta values over which hough generates the Hough transform matrix. BW can be logical or numeric, and it must be real, 2-D, and nonsparse. [H, theta, rho] = hough(BW, ParameterName, ParameterValue) computes the SHT using parameter name/value pairs. When ParameterName is 'RhoResolution', specify a real scalar value between 0 and norm(size(BW)), exclusive, to determine the spacing of the Hough transform bins along the rho axis. The default value is 1. When ParameterName is 'Theta', specify a vector of Hough transform theta values. Each element of the vector determines the theta value for the corresponding column of the output matrix H. The acceptable range of theta values is −90° ≤ < 90° , and the default is -90:89. Examples Compute and display the Hough transform of a gantrycrane image. RGB = imread('gantrycrane.png'); % Convert to intensity. I = rgb2gray(RGB); % Extract edges. BW = edge(I,'canny'); [H,T,R] = hough(BW,'RhoResolution',0.5,'Theta',-90:0.5:89.5); % Display the original image. subplot(2,1,1); imshow(RGB); 3-247 hough title('Gantrycrane Image'); % Display the Hough matrix. subplot(2,1,2); imshow(imadjust(mat2gray(H)),'XData',T,'YData',R,... 'InitialMagnification','fit'); title('Hough Transform of Gantrycrane Image'); xlabel('\theta'), ylabel('\rho'); axis on, axis normal, hold on; colormap(hot); Compute the Hough transform over a limited theta range for the gantrycrane image. RGB = imread('gantrycrane.png'); I = rgb2gray(RGB); BW = edge(I,'canny'); [H,T,R] = hough(BW, 'Theta', 44:0.5:46); figure 3-248 hough imshow(imadjust(mat2gray(H)),'XData',T,'YData',R,... 'InitialMagnification','fit'); title('Limited Theta Range Hough Transform of Gantrycrane Image'); xlabel('\theta'), ylabel('\rho'); axis on, axis normal; colormap(hot) Algorithms The hough function implements the Standard Hough Transform (SHT). The SHT uses the parametric representation of a line: rho = x*cos(theta) + y*sin(theta) The variable rho is the distance from the origin to the line along a vector perpendicular to the line. theta is the angle of the perpendicular projection from the origin to the line measured in degrees clockwise from the positive x-axis. The range of theta is −90° ≤ < 90° . The angle of the line itself is + 90° , also measured clockwise with respect to the positive x-axis. 3-249 hough x y The SHT is a parameter space matrix whose rows and columns correspond to rho and theta values respectively. The elements in the SHT represent accumulator cells. Initially, the value in each cell is zero. Then, for every non-background point in the image, rho is calculated for every theta. rho is rounded off to the nearest allowed row in SHT. That accumulator cell is incremented. At the end of this procedure, a value of Q in SHT(r,c) means that Q points in the xy-plane lie on the line specified by theta(c) and rho(r). Peak values in the SHT represent potential lines in the input image. The Hough transform matrix, H, is nrho-by-ntheta. Values of nrho and ntheta nrho = 2*(ceil(D/RhoResolution)) + 1, where D = sqrt((numRowsInBW - 1)^2 + (numColsInBW - 1)^2). rho values range from -diagonal to diagonal, where diagonal = RhoResolution*ceil(D/RhoResolution). ntheta = length(theta) See Also 3-250 houghlines | houghpeaks hough How To • “Detecting Lines Using the Hough Transform” 3-251 houghlines Purpose Extract line segments based on Hough transform Syntax lines = houghlines(BW, theta, rho, peaks) lines = houghlines(..., param1, val1, param2, val2) Description lines = houghlines(BW, theta, rho, peaks) extracts line segments in the image BW associated with particular bins in a Hough transform. theta and rho are vectors returned by function hough. peaks is a matrix returned by the houghpeaks function that contains the row and column coordinates of the Hough transform bins to use in searching for line segments. The houghlines function returns lines, a structure array whose length equals the number of merged line segments found. Each element of the structure array has these fields: Field Description point1 Two element vector [X Y] specifying the coordinates of the end-point of the line segment point2 Two element vector [X Y] specifying the coordinates of the end-point of the line segment theta Angle in degrees of the Hough transform bin rho rho axis position of the Hough transform bin lines = houghlines(..., param1, val1, param2, val2) specifies parameter/value pairs, listed in the following table. Parameter names can be abbreviated, and case does not matter. 3-252 houghlines Parameter Description 'FillGap' Positive real scalar value that specifies the distance between two line segments associated with the same Hough transform bin. When the distance between the line segments is less the value specified, the houghlines function merges the line segments into a single line segment. Default: 20 'MinLength' Positive real scalar value that specifies whether merged lines should be kept or discarded. Lines shorter than the value specified are discarded. Default: 40 Class Support BW can be logical or numeric and it must be real, 2-D, and nonsparse. Examples Search for line segments in an image and highlight the longest segment. I = imread('circuit.tif'); rotI = imrotate(I,33,'crop'); BW = edge(rotI,'canny'); [H,T,R] = hough(BW); imshow(H,[],'XData',T,'YData',R,... 'InitialMagnification','fit'); xlabel('\theta'), ylabel('\rho'); axis on, axis normal, hold on; P = houghpeaks(H,5,'threshold',ceil(0.3*max(H(:)))); x = T(P(:,2)); y = R(P(:,1)); plot(x,y,'s','color','white'); % Find lines and plot them lines = houghlines(BW,T,R,P,'FillGap',5,'MinLength',7); figure, imshow(rotI), hold on max_len = 0; for k = 1:length(lines) xy = [lines(k).point1; lines(k).point2]; plot(xy(:,1),xy(:,2),'LineWidth',2,'Color','green'); 3-253 houghlines % Plot beginnings and ends of lines plot(xy(1,1),xy(1,2),'x','LineWidth',2,'Color','yellow'); plot(xy(2,1),xy(2,2),'x','LineWidth',2,'Color','red'); % Determine the endpoints of the longest line segment len = norm(lines(k).point1 - lines(k).point2); if ( len > max_len) max_len = len; xy_long = xy; end end % highlight the longest line segment plot(xy_long(:,1),xy_long(:,2),'LineWidth',2,'Color','blue'); See Also 3-254 hough | houghpeaks houghpeaks Purpose Identify peaks in Hough transform Syntax peaks = houghpeaks(H, numpeaks) peaks = houghpeaks(..., param1, val1, param2, val2) Description peaks = houghpeaks(H, numpeaks) locates peaks in the Hough transform matrix, H, generated by the hough function. numpeaks is a scalar value that specifies the maximum number of peaks to identify. If you omit numpeaks, it defaults to 1. The function returns peaks, a Q-by-2 matrix, where Q can range from 0 to numpeaks. Q holds the row and column coordinates of the peaks. peaks = houghpeaks(..., param1, val1, param2, val2) specifies parameter/value pairs, listed in the following table. Parameter names can be abbreviated, and case does not matter. Parameter Description 'Threshold' Nonnegative scalar value that specifies the threshold at which values of H are considered to be peaks. Threshold can vary from 0 to Inf. Default is 0.5*max(H(:)). 'NHoodSize' Two-element vector of positive odd integers: [M N]. 'NHoodSize' specifies the size of the suppression neighborhood. This is the neighborhood around each peak that is set to zero after the peak is identified. Default: smallest odd values greater than or equal to size(H)/50. Class Support H is the output of the hough function. numpeaks is a positive integer Examples Locate and display two peaks in the Hough transform of a rotated image. scalar. I = imread('circuit.tif'); BW = edge(imrotate(I,50,'crop'),'canny'); 3-255 houghpeaks [H,T,R] = hough(BW); P = houghpeaks(H,2); imshow(H,[],'XData',T,'YData',R,'InitialMagnification','fit'); xlabel('\theta'), ylabel('\rho'); axis on, axis normal, hold on; plot(T(P(:,2)),R(P(:,1)),'s','color','white'); See Also 3-256 hough | houghlines iccfind Purpose Search for ICC profiles Syntax P = iccfind(directory) [P, descriptions] = iccfind(directory) [...] = iccfind(directory, pattern) Description P = iccfind(directory) searches for all of the ICC profiles in the directory specified by directory. The function returns P, a cell array of structures containing profile information. [P, descriptions] = iccfind(directory) searches for all of the ICC profiles in the specified directory and returns P, a cell array of structures containing profile information, and descriptions, a cell array of text strings, where each string describes the corresponding profile in P. Each text string is the value of the Description.String field in the profile information structure. = iccfind(directory, pattern) returns all of the ICC profiles in the specified directory with the given pattern in their Description.String fields. iccfind performs case-insensitive pattern matching. [...] Note To improve performance, iccfind caches copies of the ICC profiles in memory. Adding or modifying profiles might not change the results of iccfind. To clear the cache, use the clear functions command. Examples Get all the ICC profiles in the default system directory where profiles are stored. profiles = iccfind(iccroot); Get a listing of all the ICC profiles with text strings that describe each profile. [profiles, descriptions ] = iccfind(iccroot); 3-257 iccfind Find the profiles whose descriptions contain the text string RGB. [profiles, descriptions] = iccfind(iccroot, 'rgb'); See Also 3-258 iccread | iccroot | iccwrite iccread Purpose Read ICC profile Syntax P = iccread(filename) Description P = iccread(filename) reads the International Color Consortium (ICC) color profile information from the file specified by filename. The file can be either an ICC profile file or a TIFF file containing an embedded ICC profile. To determine if a TIFF file contains an embedded ICC profile, use the imfinfo function to get information about the file and look for the ICCProfileOffset field. iccread looks for the file in the current directory, a directory on the MATLAB path, or in the directory returned by iccroot, in that order. iccread returns the profile information in the structure P, a 1-by-1 structure array whose fields contain the data structures (called tags) defined in the ICC specification. iccread can read profiles that conform with either Version 2 (ICC.1:2001-04) or Version 4 (ICC.1:2001-12) of the ICC specification. For more information about ICC profiles, visit the ICC web site, www.color.org. ICC profiles provide color management systems with the information necessary to convert color data between native device color spaces and device independent color spaces, called the Profile Connection Space (PCS). You can use the profile as the source or destination profile with the makecform function to compute color space transformations. The number of fields in P depends on the profile class and the choices made by the profile creator. iccread returns all the tags for a given profile, both public and private. Private tags and certain public tags are left as encoded uint8 data. The following table lists fields that are found in any profile structure generated by iccread, in the order they appear in the structure. 3-259 iccread Field Data Type Description Header 1-by-1 struct array Profile header fields TagTable n-by-3 cell array Profile tag table Copyright Text string Profile copyright notice Description 1-by-1 struct array The String field in this structure contains a text string describing the profile. double XYZ tristimulus values of the device’s media white point MediaWhitepoint array PrivateTags m-by-2 cell array Contents of all the private tags or tags not defined in the ICC specifications. The tag signatures are in the first column, and the contents of the tags are in the second column. Note that iccread leaves the contents of these tags in unsigned 8-bit encoding. Filename Text string Name of the file containing the profile Additionally, P might contain one or more of the following transforms: • Three-component, matrix-based transform: A simple transform that is often used to transform between the RGB and XYZ color spaces. If this transform is present, P contains a field called MatTRC. • N-component LUT-based transform: A transform that is used for transforming between color spaces that have a more complex relationship. This type of transform is found in any of the following fields in P: 3-260 iccread Examples AToB0 BToA0 Preview0 AToB1 BToA1 Preview1 AToB2 BToA2 Preview2 AToB3 BToA3 Gamut The example reads the ICC profile that describes a typical PC computer monitor. P = iccread('sRGB.icm') P = Header: [1x1 struct] TagTable: {17x3 cell} Copyright: 'Copyright (c) 1999 Hewlett-Packard Company' Description: [1x1 struct] MediaWhitePoint: [0.9505 1 1.0891] MediaBlackPoint: [0 0 0] DeviceMfgDesc: [1x1 struct] DeviceModelDesc: [1x1 struct] ViewingCondDesc: [1x1 struct] ViewingConditions: [1x1 struct] Luminance: [76.0365 80 87.1246] Measurement: [1x36 uint8] Technology: [115 105 103 32 0 0 0 0 67 82 84 32] MatTRC: [1x1 struct] PrivateTags: {} Filename: 'sRGB.icm' The profile header provides general information about the profile, such as its class, color space, and PCS. For example, to determine the source color space, view the ColorSpace field in the Header structure. P.Header.ColorSpace ans = 3-261 iccread RGB See Also 3-262 applycform | iccfind | iccroot | iccwrite | isicc | makecform iccroot Purpose Find system default ICC profile repository Syntax rootdir = iccroot Description rootdir = iccroot returns the system directory containing ICC profiles. Additional profiles can be stored in other directories, but this is the default location used by the color management system. Note Only Windows and Mac OS X platforms are supported. Examples Return information on all the profiles in the root directory. iccfind(iccroot) See Also iccfind | iccread | iccwrite 3-263 iccwrite Purpose Write ICC color profile to disk file Syntax P_new = iccwrite(P, filename) Description P_new = iccwrite(P, filename) writes the International Color Consortium (ICC) color profile data in structure P to the file specified by filename. P is a structure representing an ICC profile in the data format returned by iccread and used by makecform and applycform to compute color-space transformations. P must contain all the tags and fields required by the ICC profile specification. Some fields may be inconsistent, however, because of interactive changes to the structure. For instance, the tag table may not be correct because tags may have been added, deleted, or modified since the tag table was constructed. iccwrite makes any necessary corrections to the profile structure before writing it to the file and returns this corrected structure in P_new. Note Because some applications use the profile description string in the ICC profile to present choices to users, the ICC recommends modifying the profile description string in the ICC profile data before writing the data to a file. Each profile should have a unique description string. For more information, see the example. iccwrite can write the color profile data using either Version 2 (ICC.1:2001-04) or Version 4 (ICC.1:2001-12) of the ICC specification, depending on the value of the Version field in the file profile header. If any required fields are missing, iccwrite errors. For more information about ICC profiles, visit the ICC web site, www.color.org. 3-264 iccwrite Note iccwrite does not perform automatic conversions from one version of the ICC specification to another. Such conversions have to be done manually, by adding fields or modifying fields. Use isicc to validate a profile. Examples Read a profile into the MATLAB workspace and export the profile data to a new file. The example changes the profile description string in the profile data before writing the data to a file. P = iccread('monitor.icm'); P.Description.String ans = sgC4_050102_d50.pf P.Description.String = 'my new description'; pmon = iccwrite(P, 'monitor2.icm'); See Also applycform | iccread | isicc | makecform 3-265 idct2 Purpose 2-D inverse discrete cosine transform Syntax B = idct2(A) B = idct2(A,m,n) B = idct2(A,[m n]) Description B = idct2(A) returns the two-dimensional inverse discrete cosine transform (DCT) of A. B = idct2(A,m,n) pads A with 0’s to size m-by-n before transforming. If [m n] < size(A), idct2 crops A before transforming. B = idct2(A,[m n]) same as above. For any A, idct2(dct2(A)) equals A to within roundoff error. Class Support The input matrix A can be of class double or of any numeric class. The output matrix B is of class double. Algorithms idct2 computes the two-dimensional inverse DCT using: Amn = M −1 N −1 ∑ ∑ p q Bpq cos p= 0 q = 0 where ⎧ 1 ⎪ M, p=0 ⎪ p = ⎨ ⎪ 2 , 1 ≤ p ≤ M −1 ⎪⎩ M and ⎧ 1 ⎪ N , q=0 ⎪ q = ⎨ . ⎪ 2 , 1 ≤ q ≤ N −1 ⎪⎩ N 3-266 (2m + 1) p (2n + 1) q 0 ≤ m ≤ M − 1 cos , , 0 ≤ n ≤ N −1 2M 2N idct2 Examples Create a DCT matrix. RGB = imread('autumn.tif'); I = rgb2gray(RGB); J = dct2(I); imshow(log(abs(J)),[]), colormap(jet), colorbar Set values less than magnitude 10 in the DCT matrix to zero, then reconstruct the image using the inverse DCT function idct2. J(abs(J)<10) = 0; K = idct2(J); figure, imshow(I) figure, imshow(K,[0 255]) References [1] Jain, A. K., Fundamentals of Digital Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1989, pp. 150-153. [2] Pennebaker, W. B., and J. L. Mitchell, JPEG: Still Image Data Compression Standard, New York, Van Nostrand Reinhold, 1993. See Also dct2 | dctmtx | fft2 | ifft2 3-267 ifanbeam Purpose Inverse fan-beam transform Syntax I = ifanbeam(F,D) I = ifanbeam(...,param1,val1,param2,val2,...) [I,H] = ifanbeam(...) Description I = ifanbeam(F,D) reconstructs the image I from projection data in the two-dimensional array F. Each column of F contains fan-beam projection data at one rotation angle. ifanbeam assumes that the center of rotation is the center point of the projections, which is defined as ceil(size(F,1)/2). The fan-beam spread angles are assumed to be the same increments as the input rotation angles split equally on either side of zero. The input rotation angles are assumed to be stepped in equal increments to cover [0:359] degrees. D is the distance from the fan-beam vertex to the center of rotation. I = ifanbeam(...,param1,val1,param2,val2,...) specifies parameters that control various aspects of the ifanbeam reconstruction, described in the following table. Parameter names can be abbreviated, and case does not matter. Default values are in braces ({}). 3-268 Parameter Description 'FanCoverage' String specifying the range through which the beams are rotated. {'cycle'} — Rotate through the full range [0,360). 'minimal' — Rotate the minimum range necessary to represent the object. 'FanRotationIncrement' Positive real scalar specifying the increment of the rotation angle of the fan-beam projections, measured in degrees. See fanbeam for details. ifanbeam Parameter Description 'FanSensorGeometry' String specifying how sensors are positioned. 'arc' — Sensors are spaced equally along a circular arc at distance D from the center of rotation. Default value is 'arc' 'line' — Sensors are spaced equally along a line, the closest point of which is distance D from the center of rotation. See fanbeam for details. 'FanSensorSpacing' Positive real scalar specifying the spacing of the fan-beam sensors. Interpretation of the value depends on the setting of 'FanSensorGeometry'. If 'FanSensorGeometry' is set to 'arc' (the default), the value defines the angular spacing in degrees. Default value is 1. If 'FanSensorGeometry' is 'line', the value specifies the linear spacing. Default value is 1. See fanbeam for details. 'Filter' String specifying the name of a filter. See iradon for details. 'FrequencyScaling' Scalar in the range (0,1] that modifies the filter by rescaling its frequency axis. See iradon for details. 3-269 ifanbeam Parameter Description 'Interpolation' Text string specifying the type of interpolation used between the parallel-beam and fan-beam data. 'nearest' — Nearest-neighbor {'linear'} — Linear 'spline' — Piecewise cubic spline 'pchip' —- Piecewise cubic Hermite (PCHIP) 'cubic' — Same as 'pchip' 'OutputSize' Positive scalar specifying the number of rows and columns in the reconstructed image. If 'OutputSize' is not specified, ifanbeam determines the size automatically. If you specify 'OutputSize', ifanbeam reconstructs a smaller or larger portion of the image, but does not change the scaling of the data. Note If the projections were calculated with the fanbeam function, the reconstructed image might not be the same size as the original image. [I,H] = ifanbeam(...) returns the frequency response of the filter in the vector H. 3-270 ifanbeam Notes ifanbeam converts the fan-beam data to parallel beam projections and then uses the filtered back projection algorithm to perform the inverse Radon transform. The filter is designed directly in the frequency domain and then multiplied by the FFT of the projections. The projections are zero-padded to a power of 2 before filtering to prevent spatial domain aliasing and to speed up the FFT. Class Support The input arguments, F and D, can be double or single. All other numeric input arguments must be double. The output arguments are double. Examples Example 1 This example creates a fan-beam transformation of the phantom head image and then calls the ifanbeam function to recreate the phantom image from the fan-beam transformation. ph = phantom(128); d = 100; F = fanbeam(ph,d); I = ifanbeam(F,d); imshow(ph), figure, imshow(I); Example 2 This example illustrates use of the ifanbeam function with the 'fancoverage' option set to 'minimal' . ph = phantom(128); P = radon(ph); [F,obeta,otheta] = para2fan(P,100,... 'FanSensorSpacing',0.5,... 'FanCoverage','minimal',... 'FanRotationIncrement',1); phReconstructed = ifanbeam(F,100,... 'FanSensorSpacing',0.5,... 'Filter','Shepp-Logan',... 'OutputSize',128,... 'FanCoverage','minimal',... 3-271 ifanbeam 'FanRotationIncrement',1); imshow(ph), figure, imshow(phReconstructed) References [1] Kak, A. C., and M. Slaney, Principles of Computerized Tomographic Imaging, New York, NY, IEEE Press, 1988. See Also fan2para | fanbeam | iradon | para2fan | phantom | radon 3-272 im2bw Purpose Convert image to binary image, based on threshold Syntax BW = im2bw(I, level) BW = im2bw(X, map, level) BW = im2bw(RGB, level) Description BW = im2bw(I, level) converts the grayscale image I to a binary image. The output image BW replaces all pixels in the input image with luminance greater than level with the value 1 (white) and replaces all other pixels with the value 0 (black). Specify level in the range [0,1]. This range is relative to the signal levels possible for the image’s class. Therefore, a level value of 0.5 is midway between black and white, regardless of class. To compute the level argument, you can use the function graythresh. If you do not specify level, im2bw uses the value 0.5. BW = im2bw(X, map, level) converts the indexed image X with colormap map to a binary image. BW = im2bw(RGB, level) converts the truecolor image RGB to a binary image. If the input image is not a grayscale image, im2bw converts the input image to grayscale, and then converts this grayscale image to binary by thresholding. Class Support The input image can be of class uint8, uint16, single, int16, or double, and must be nonsparse. The output image BW is of class logical. I and X must be 2-D. RGB images are M-by-N-by-3. Examples load trees BW = im2bw(X,map,0.4); imshow(X,map), figure, imshow(BW) 3-273 im2bw See Also 3-274 graythresh | ind2gray | rgb2gray im2col Purpose Rearrange image blocks into columns Syntax B = im2col(A,[m n],block_type) B = im2col(A,'indexed',...) Description B = im2col(A,[m n],block_type) rearranges image blocks into columns. block_type is a string that can have one of these values. The default value is enclosed in braces ({}). Value Description 'distinct' Rearranges each distinct m-by-n block in the image A into a column of B. im2col pads A with 0’s, if necessary, so its size is an integer multiple of m-by-n. If A = [A11 A12; A21 A22], where each Aij is m-by-n, then B = [A11(:) A12(:) A21(:) A22(:)]. {'sliding'} Converts each sliding m-by-n block of A into a column of B, with no zero padding. B has m*n rows and contains as many columns as there are m-by-n neighborhoods of A. If the size of A is [mm nn], then the size of B is (m*n)-by-((mm-m+1)*(nn-n+1)). For the sliding block case, each column of B contains the neighborhoods of A reshaped as NHOOD(:) where NHOOD is a matrix containing an m-by-n neighborhood of A. im2col orders the columns of B so that they can be reshaped to form a matrix in the normal way. For Examples, suppose you use a function, such as sum(B), that returns a scalar for each column of B. You can directly store the result in a matrix of size (mm-m+1)-by-(nn-n+1), using these calls. B = im2col(A,[m n],'sliding'); C = reshape(sum(B),mm-m+1,nn-n+1); B = im2col(A,'indexed',...) processes A as an indexed image, padding with 0’s if the class of A is uint8, or 1’s if the class of A is double. 3-275 im2col Class Support The input image A can be numeric or logical. The output matrix B is of the same class as the input image. Examples Calculate the local mean using a [2 2] neighborhood with zero padding: A = reshape(linspace(0,1,16),[4 4])' B = im2col(A,[2 2]) M = mean(B) newA = col2im(M,[1 1],[3 3]) The output appears like this: newA = 0.1667 0.4333 0.7000 See Also 3-276 0.2333 0.5000 0.7667 0.3000 0.5667 0.8333 blockproc | col2im | colfilt | nlfilter im2double Purpose Convert image to double precision Syntax I2 = im2double(I) RGB2 = im2double(RGB) I = im2double(BW) X2 = im2double(X,'indexed') Description I2 = im2double(I) converts the intensity image I to double precision, rescaling the data if necessary. If the input image is of class double, the output image is identical. RGB2 = im2double(RGB) converts the truecolor image RGB to double precision, rescaling the data if necessary. I = im2double(BW) converts the binary image BW to a double-precision intensity image. X2 = im2double(X,'indexed') converts the indexed image X to double precision, offsetting the data if necessary. Class Support Intensity and truecolor images can be uint8, uint16, double, logical, single, or int16. Indexed images can be uint8, uint16, double or logical. Binary input images must be logical. The output image is double. Examples I1 = reshape(uint8(linspace(1,255,25)),[5 5]) I2 = im2double(I1) See Also double | im2single | im2int16 | im2uint8 | im2uint16 3-277 im2int16 Purpose Convert image to 16-bit signed integers Syntax I2 = im2int16(I) RGB2 = im2int16(RGB) I = im2int16(BW) Description I2 = im2int16(I) converts the intensity image I to int16, rescaling the data if necessary. If the input image is of class int16, the output image is identical to it. RGB2 = im2int16(RGB) converts the truecolor image RGB to int16, rescaling the data if necessary. I = im2int16(BW) converts the binary image BW to an int16 intensity image, changing false-valued elements to -32768 and true-valued elements to 32767. Class Support Intensity and truecolor images can be uint8, uint16, int16, single, double, or logical. Binary input images must be logical. The output image is int16. Examples I = reshape(linspace(0,1,20),[5 4]) I2 = im2int16(I) See Also im2double | im2single | im2uint8 | im2uint16 | int16 3-278 im2java2d Purpose Convert image to Java buffered image Syntax jimage = im2java2d(I) jimage = im2java2d(X,MAP) Description jimage = im2java2d(I) converts the image I to an instance of the Java image class java.awt.image.BufferedImage. The image I can be an intensity (grayscale), RGB, or binary image. jimage = im2java2d(X,MAP) converts the indexed image X with colormap MAP to an instance of the Java class java.awt.image.BufferedImage. Note The im2java2d function works with the Java 2D API. The im2java function works with the Java Abstract Windowing Toolkit (AWT). Class Support Intensity, indexed, and RGB input images can be of class uint8, uint16, or double. Binary input images must be of class logical. Examples Read an image into the MATLAB workspace and then use im2java2d to convert it into an instance of the Java class java.awt.image.BufferedImage. I = imread('moon.tif'); javaImage = im2java2d(I); frame = javax.swing.JFrame; icon = javax.swing.ImageIcon(javaImage); label = javax.swing.JLabel(icon); frame.getContentPane.add(label); frame.pack frame.show 3-279 im2single Purpose Convert image to single precision Syntax I2 = im2single(I) RGB2 = im2single(RGB) I = im2single(BW) X2 = im2single(X,'indexed') Description I2 = im2single(I) converts the intensity image I to single, rescaling the data if necessary. If the input image is of class single, the output image is identical to it. RGB2 = im2single(RGB) converts the truecolor image RGB to single, rescaling the data if necessary. I = im2single(BW) converts the binary image BW to a single-precision intensity image. X2 = im2single(X,'indexed') converts the indexed image X to single precision, offsetting the data if necessary. Class Support Intensity and truecolor images can be uint8, uint16, int16, single, double, or logical. Indexed images can be uint8, uint16, double or logical. Binary input images must be logical. The output image is single. Examples I = reshape(uint8(linspace(1,255,25)),[5 5]) I2 = im2single(I) See Also im2double | im2int16 | im2uint8 | im2uint16 | single 3-280 im2uint16 Purpose Convert image to 16-bit unsigned integers Syntax I2 = im2uint16(I) RGB2 = im2uint16(RGB) I = im2uint16(BW) X2 = im2uint16(X,'indexed') Description I2 = im2uint16(I) converts the intensity image I to uint16, rescaling the data if necessary. If the input image is of class uint16, the output image is identical to it. RGB2 = im2uint16(RGB) converts the truecolor image RGB to uint16, rescaling the data if necessary. I = im2uint16(BW) converts the binary image BW to a uint16 intensity image, changing 1-valued elements to 65535. X2 = im2uint16(X,'indexed') converts the indexed image X to uint16, offsetting the data if necessary. If X is of class double, max(X(:)) must be 65536 or less. Class Support Intensity and truecolor images can be uint8, uint16, double, logical, single, or int16. Indexed images can be uint8, uint16, double, or logical. Binary input images must be logical. The output image is uint16. Examples I = reshape(linspace(0,1,20),[5 4]) I2 = im2uint16(I) See Also im2uint8 | double | im2double | uint8 | uint16 | imapprox 3-281 im2uint8 Purpose Convert image to 8-bit unsigned integers Syntax I2 = im2uint8(I1) RGB2 = im2uint8(RGB1) I = im2uint8(BW) X2 = im2uint8(X1,'indexed') Description im2uint8 takes an image as input and returns an image of class uint8. If the input image is of class uint8, the output image is identical to the input image. If the input image is not uint8, im2uint8 returns the equivalent image of class uint8, rescaling or offsetting the data as necessary. I2 = im2uint8(I1) converts the grayscale image I1 to uint8, rescaling the data if necessary. RGB2 = im2uint8(RGB1) converts the truecolor image RGB1 to uint8, rescaling the data if necessary. I = im2uint8(BW) converts the binary image BW to a uint8 grayscale image, changing 1-valued elements to 255. X2 = im2uint8(X1,'indexed') converts the indexed image X1 to uint8, offsetting the data if necessary. Note that it is not always possible to convert an indexed image to uint8. If X1 is of class double, the maximum value of X1 must be 256 or less; if X1 is of class uint16, the maximum value of X1 must be 255 or less. Class Support Grayscale and truecolor images can be uint8, uint16, int16, single, double, or logical. Indexed images can be uint8, uint16, double, or logical. Binary input images must be logical. The output image is uint8. Examples I1 = reshape(uint16(linspace(0,65535,25)),[5 5]) I2 = im2uint8(I1) See Also im2double | im2int16 | im2single | im2uint16 | uint8 3-282 imabsdiff Purpose Absolute difference of two images Syntax Z = imabsdiff(X,Y) Description Z = imabsdiff(X,Y) subtracts each element in array Y from the corresponding element in array X and returns the absolute difference in the corresponding element of the output array Z. X and Y are real, nonsparse numeric arrays with the same class and size. Z has the same class and size as X and Y. If X and Y are integer arrays, elements in the output that exceed the range of the integer type are truncated. If X and Y are double arrays, you can use the expression abs(X-Y) instead of this function. Note This function may take advantage of hardware optimization for data types uint8, int16, and single to run faster. Hardware optimization requires that arrays X and Y are of the same size and class. Examples Calculate the absolute difference between two uint8 arrays. Note that the absolute value prevents negative values from being rounded to zero in the result, as they are with imsubtract. X = uint8([ 255 10 75; 44 225 100]); Y = uint8([ 50 50 50; 50 50 50 ]); Z = imabsdiff(X,Y) Z = 205 6 40 175 25 50 Display the absolute difference between a filtered image and the original. I = imread('cameraman.tif'); J = uint8(filter2(fspecial('gaussian'), I)); K = imabsdiff(I,J); 3-283 imabsdiff imshow(K,[]) % [] = scale data automatically See Also 3-284 imadd | imcomplement | imdivide | imlincomb | immultiply | imsubtract | ippl imadd Purpose Add two images or add constant to image Syntax Z = imadd(X,Y) Description Z = imadd(X,Y) adds each element in array X with the corresponding element in array Y and returns the sum in the corresponding element of the output array Z. X and Y are real, nonsparse numeric arrays with the same size and class, or Y is a scalar double. Z has the same size and class as X, unless X is logical, in which case Z is double. If X and Y are integer arrays, elements in the output that exceed the range of the integer type are truncated, and fractional values are rounded. Note On Intel architecture processors, imadd can take advantage of the Intel Integrated Performance Primitives (Intel IPP) library, thus accelerating its execution time. The Intel IPP library is activated if arrays X, Y, and Z are of class logical, uint8, or single and are of the same class. The Intel IPP library is also activated if Y is a double scalar and arrays X and Z are uint8, int16, or single and are of the same class. Examples Add two uint8 arrays. Note the truncation that occurs when the values exceed 255. X Y Z Z = uint8([ 255 0 75; 44 225 100]); = uint8([ 50 50 50; 50 50 50 ]); = imadd(X,Y) = 255 94 50 255 125 150 Add two images together and specify an output class. I = imread('rice.png'); 3-285 imadd J = imread('cameraman.tif'); K = imadd(I,J,'uint16'); imshow(K,[]) Add a constant to an image. I = imread('rice.png'); J = imadd(I,50); subplot(1,2,1), imshow(I) subplot(1,2,2), imshow(J) See Also 3-286 imabsdiff | imcomplement | imdivide | imlincomb | immultiply | imsubtract | ippl imadjust Purpose Adjust image intensity values or colormap Syntax J = imadjust(I) J = imadjust(I,[low_in; high_in],[low_out; high_out]) J = imadjust(I,[low_in; high_in],[low_out; high_out],gamma) newmap = imadjust(map,[low_in; high_in],[low_out; high_out], gamma) RGB2 = imadjust(RGB1,...) Description J = imadjust(I) maps the intensity values in grayscale image I to new values in J such that 1% of data is saturated at low and high intensities of I. This increases the contrast of the output image J. This syntax is equivalent to imadjust(I,stretchlim(I)). J = imadjust(I,[low_in; high_in],[low_out; high_out]) maps the values in I to new values in J such that values between low_in and high_in map to values between low_out and high_out. Values for low_in, high_in, low_out, and high_out must be between 0 and 1. Values below low_in and above high_in are clipped; that is, values below low_in map to low_out, and those above high_in map to high_out. You can use an empty matrix ([]) for [low_in high_in] or for [low_out high_out] to specify the default of [0 1]. J = imadjust(I,[low_in; high_in],[low_out; high_out],gamma) maps the values in I to new values in J, where gamma specifies the shape of the curve describing the relationship between the values in I and J. If gamma is less than 1, the mapping is weighted toward higher (brighter) output values. If gamma is greater than 1, the mapping is weighted toward lower (darker) output values. If you omit the argument, gamma defaults to 1 (linear mapping). newmap = imadjust(map,[low_in; high_in],[low_out; high_out],gamma) transforms the colormap associated with an indexed image. If low_in, high_in, low_out, high_out, and gamma are scalars, then the same mapping applies to red, green, and blue components. Unique mappings for each color component are possible when low_in and high_in are both 1-by-3 vectors. 3-287 imadjust low_out and high_out are both 1-by-3 vectors, or gamma is a 1-by-3 vector. The rescaled colormap newmap is the same size as map. RGB2 = imadjust(RGB1,...) performs the adjustment on each image plane (red, green, and blue) of the RGB image RGB1. As with the colormap adjustment, you can apply unique mappings to each plane. Note If high_out < low_out, the output image is reversed, as in a photographic negative. Class Support For syntax variations that include an input image (rather than a colormap), the input image can be of class uint8, uint16, int16, single, or double. The output image has the same class as the input image. For syntax variations that include a colormap, the input and output colormaps are of class double. Examples Adjust a low-contrast grayscale image. I = imread('pout.tif'); J = imadjust(I); imshow(I), figure, imshow(J) 3-288 imadjust Adjust the grayscale image, specifying the contrast limits. K = imadjust(I,[0.3 0.7],[]); figure, imshow(K) Adjust an RGB image. RGB1 = imread('football.jpg'); RGB2 = imadjust(RGB1,[.2 .3 0; .6 .7 1],[]); imshow(RGB1), figure, imshow(RGB2) See Also brighten | histeq | stretchlim 3-289 ImageAdapter Purpose Interface for image I/O Description ImageAdapter, an abstract class, specifies the Image Processing Toolbox interface for region-based reading and writing of image files. You can use classes that inherit from the ImageAdapter interface with the blockproc function for file-based processing of arbitrary image file formats. Construction adapter = ClassName(...) handles object initialization, manages file Properties Colormap opening or creation, and sets the initial values of class properties. The class constructor can take any number of arguments. Specifies a colormap. Use the Colormap property when working with indexed images. Data Type: 2-D, real, M-by-3 matrix Default: Empty ([]), indicating either a grayscale, logical, or truecolor image ImageSize Holds the size of the entire image. When you construct a new class that inherits from ImageAdapter, set the ImageSize property in your class constructor. Data Type: 2- or 3-element vector specified as [rows cols] or [rows cols bands], where rows indicates height and cols indicates width Methods 3-290 Classes that inherit from ImageAdapter must implement the readRegion and close methods to support basic region-based reading of images. The writeRegion method allows for incremental, region-based writing of images and is optional. Image Adapter classes that do not implement the writeRegion method are read-only. ImageAdapter close Close ImageAdapter object readRegion Read region of image writeRegion Write block of data to region of image See Also blockproc Tutorials • Computing Statistics for Large Images How To • “Defining Abstract Classes” • “Working with Data in Unsupported Formats” 3-291 ImageAdapter.close Purpose Close ImageAdapter object Syntax adapter.close Description adapter.close closes the ImageAdapter object and performs any necessary clean-up, such as closing file handles. When you construct a class that inherits from the ImageAdapter class, implement this method. 3-292 ImageAdapter.readRegion Purpose Read region of image Syntax data = adapter.readRegion(region_start, region_size) Description data = adapter.readRegion(region_start, region_size) reads a region of the image. region_start and region_size define a rectangular region in the image. region_start, a two-element vector, specifies the [row col] of the first pixel (minimum-row, minimum-column) of the region. region_size, a two-element vector, specifies the size of the requested region in [rows cols]. When you construct a class that inherits from the ImageAdapter class, implement this method. 3-293 ImageAdapter.writeRegion Purpose Write block of data to region of image Syntax adapter.writeRegion(region_start, region_data) Description adapter.writeRegion(region_start, region_data) writes a contiguous block of data to a region of the image. The method writes the block of data specified by the region_data argument. The two-element vector, region_start, specifies the [row col] location of the first pixel (minimum-row, minimum-column) of the target region in the image. When you construct a class that inherits from the ImageAdapter class, implement this method if you need to write data. 3-294 imageinfo Purpose Image Information tool Syntax imageinfo imageinfo(h) imageinfo(filename) imageinfo(info) imageinfo(himage,filename) imageinfo(himage,info) hfig = imageinfo(...) Description imageinfo creates an Image Information tool associated with the image in the current figure. The tool displays information about the basic attributes of the target image in a separate figure. imageinfo gets information about image attributes by querying the image object’s CData. The following table lists the basic image information included in the Image Information tool display. Note that the tool contains either four or six fields, depending on the type of image. Attribute Name Value Width (columns) Number of columns in the image Height (rows) Number of rows in the image Class Data type used by the image, such as uint8. Note For single or int16 images, imageinfo returns a class value of double, because image objects convert the CData of these images to double. Image type One of the image types identified by the Image Processing Toolbox software: 'intensity' 'truecolor', 'binary', or 'indexed'. 3-295 imageinfo Attribute Name Minimum intensity or index Value For grayscale images, this value represents the lowest intensity value of any pixel. For indexed images, this value represents the lowest index value into a color map. Not included for 'binary' or 'truecolor' images. Maximum intensity or index For grayscale images, this value represents the highest intensity value of any pixel. For indexed images, this value represents the highest index value into a color map. Not included for 'binary' or 'truecolor' images. imageinfo(h) creates an Image Information tool associated with h, where h is a handle to a figure, axes, or image object. imageinfo(filename) creates an Image Information tool containing image metadata from the graphics file filename. The image does not have to be displayed in a figure window. filename can be any file type that has been registered with an information function in the file formats registry, imformats, so its information can be read by imfinfo. filename can also be a DICOM, NITF, Interfile, or Analyze file. imageinfo(info) creates an Image Information tool containing the image metadata in the structure info. info is a structure returned by the functions imfinfo, dicominfo, nitfinfo interfileinfo, or analyze75info. info can also be a user-created structure. imageinfo(himage,filename) creates an Image Information tool containing information about the basic attributes of the image specified by the handle himage and the image metadata from the graphics file filename. imageinfo(himage,info) creates an Image Information tool containing information about the basic attributes of the image specified by the handle himage and the image metadata in the structure info. 3-296 imageinfo hfig = imageinfo(...) returns a handle to the Image Information tool figure. Examples imageinfo('peppers.png') h = imshow('bag.png'); info = imfinfo('bag.png'); imageinfo(h,info); imshow('canoe.tif'); imageinfo; See Also analyze75info | dicominfo | imattributes | imfinfo | imformats | imtool | interfileinfo | nitfinfo 3-297 imagemodel Purpose Image Model object Syntax imgmodel = imagemodel(himage) Description imgmodel = imagemodel(himage) creates an image model object associated with a target image. The target image himage is a handle to an image object or an array of handles to image objects. imagemodel returns an image model object or, if himage is an array of image objects, an array of image model objects. imagemodel works by querying the image object’s CData. For a single or int16 image, the image object converts its CData to double. For example, in the case of h = imshow(int16(ones(10))), class(get(h,'CData')) returns 'double'. Therefore, getClassType(imgmodel) returns 'double'. API Functions An image model object stores information about an image such as class, type, display range, width, height, minimum intensity value, and maximum intensity value. The image model object supports methods that you can use to access this information, get information about the pixels in an image, and perform special text formatting. Brief descriptions of these methods follow. Methods imagemodel supports the following methods. Type methods imagemodel to see a list of methods, or type help imagemodel/methodname for more information about a specific method. getClassType — Return class of image str = getClassType(imgmodel) returns a string indicating the class of the image, where imgmodel is a valid image model and str is a text string, such as 'uint8'. getDisplayRange — Return display range of intensity image disp_range = getDisplayRange(imgmodel), where imgmodel is a valid image model and disp_range is an array of doubles such as [0 255], returns a double array containing the minimum and maximum 3-298 imagemodel values of the display range for an intensity image. For image types other than intensity, the value returned is an empty array. getImageHeight — Return number of rows height = getImageHeight(imgmodel), where imgmodel is a valid image model and height is a double scalar, returns a double scalar containing the number of rows. getImageType — Return image type str = getImageType(imgmodel), where imgmodel is a valid image model and str is one of the text strings ('intensity', 'truecolor', 'binary', or 'indexed'), returns a text string indicating the image type. getImageWidth — Return number of columns width = getImageWidth(imgmodel), where imgmodel is a valid image model and width is a double scalar, returns a double scalar containing the number of columns. getMinIntensity — Return minimum value in image minval = getMinIntensity(imgmodel), where imgmodel is a valid image model and minval is a numeric value, returns the minimum value in the image calculated as min(Image(:)). For an intensity image, the value returned is the minimum intensity. For an indexed image, the value returned is the minimum index. For any other image type, the value returned is an empty array. The class of minval depends on the class of the target image. getMaxIntensity — Return maximum value in image maxval = getMaxIntensity(imgmodel), where imgmodel is a valid image model and maxval is a numeric value, returns the maximum value in the image calculated as max(Image(:)). For an intensity image, the value returned is the maximum intensity. For an indexed image, the value returned is the maximum index. For any other image type, the value returned is an empty array. The class of maxval depends on the class of the target image. 3-299 imagemodel getNumberFormatFcn — Return handle to function that converts numeric value into string fun = getNumberFormatFcn(imgmodel), where imgmodel is a valid image model, returns the handle to a function that converts a numeric value into a string. For example, str = fun(getPixelValue(imgmodel, 100, 100)) converts the numeric return value of the getPixelValue method into a text string. getPixelInfoString — Return value of specific pixel as text string str = getPixelInfoString(imgmodel, row, column), where str is a character array, imgmodel is a valid image model, and row and column are numeric scalar values, returns a text string containing the value of the pixel at the location specified by row and column. For example, for an RGB image, the method returns a text string such as '[66 35 60]'. getPixelRegionFormatFcn — Return handle to function that formats value of pixel into text string fun = getPixelRegionFormatFcn(imgmodel), takes a valid image model, imgmodel, and returns fun, a handle to a function that accepts the location (row, column) of a pixel in the target image and returns the value of the pixel as a specially formatted text string. For example, when used with an RGB image, this function returns a text string of the form 'R:000 G:000 B:000' where 000 is the actual pixel value. str = fun(100,100) getPixelValue — Return value of specific pixel as numeric array val = getPixelValue(imgmodel, row, column), where imgmodel is a valid image model and row and column are numeric scalar values, returns the value of the pixel at the location specified by row and column as a numeric array. The class of val depends on the class of the target image. getDefaultPixelInfoString — Return pixel information type as text string str = getDefaultPixelInfoString(imgmodel), where imgmodel is a valid image model, returns a text string indicating the pixel information type. This string can be used in place of actual pixel information 3-300 imagemodel values. Depending on the image type, str can be the text string 'Intensity','[R G B]','BW', or '<Index> [R G B]'. getDefaultPixelRegionString — Return type of information displayed in Pixel Region tool str = getDefaultPixelRegionString(imgmodel), where imgmodel is a valid image model, returns a text string indicating the type of information displayed in the Pixel Region tool for each image type. This string can be used in place of actual pixel values. Depending on the image type, str can be the text string '000','R:000 G:000 B:000]', '0', or '<000> R:0.00 G:0.00 B:0.00'. getScreenPixelRGBValue — Return screen display value of specific pixel val = getScreenPixelRGBValue(imgmodel, row, col) returns the screen display value of the pixel at the location specified by row and col as a double array. imgmodel is a valid image model, row and col are numeric scalar values, and val is an array of doubles, such as [0.2 0.5 0.3]. Examples Create an image model. h = imshow('peppers.png'); im = imagemodel(h); figure,subplot(1,2,1) h1 = imshow('hestain.png'); subplot(1,2,2) h2 = imshow('coins.png'); im = imagemodel([h1 h2]); See Also getimagemodel 3-301 imapplymatrix Purpose Linear combination of color channels Syntax Y = imapplymatrix(M,X) Y = imapplymatrix(M,X,C) Y = imapplymatrix(..., output_type) Description Y = imapplymatrix(M,X) computes the linear combination of the rows of M with the color channels of X. The output data type is the same as the type of X. Y = imapplymatrix(M,X,C) computes the linear combination of the rows of M with the color channels of X, adding the corresponding constant value from C to each combination. The output data type is the same as the type of X. Y = imapplymatrix(..., output_type) returns the result of the linear combination in an array of type output_type. Input Arguments M Matrix that contains the coefficients of the weighting matrix. If X is m-by-n-by-p, M must be q-by-p, where q is in the range [1,p]. X An image. C A vector with the same number of elements as the number of rows in M, or a scalar applied to every channel. output_type A string that describes the output type. Possible values include uint8, int8, uint16, int16, uint32, int32, single, or double. 3-302 imapplymatrix Output Arguments Y Examples Convert RGB values to grayscale: Array that contains the linear combination of the rows of M with the color channels of X. RGB = imread('peppers.png'); M = [0.30, 0.59, 0.11]; gray = imapplymatrix(M, RGB); figure subplot(1,2,1), imshow(RGB), title('Original RGB') subplot(1,2,2), imshow(gray), title('Grayscale Conversion') See Also imlincomb | immultiply 3-303 imattributes Purpose Information about image attributes Syntax attrs = imattributes attrs = imattributes(himage) attrs = imattributes(imgmodel) Description attrs = imattributes returns information about an image in the current figure. If the current figure does not contain an image, imattributes returns an empty array. attrs = imattributes(himage) returns information about the image specified by himage, a handle to an image object. imattributes gets the image attributes by querying the image object’s CData. imattributes returns image attribute information in attrs, a 4-by-2 or 6-by-2 cell array, depending on the image type. The first column of the cell array contains the name of the attribute as a text string. The second column contains the value of the attribute, also represented as a text string. The following table lists these attributes in the order they appear in the cell array. Attribute Name Value Width (columns) Number of columns in the image Height (rows) Number of rows in the image Class Data type used by the image, such as uint8. Note For single or int16 images, imageinfo returns a class value of double, because image objects convert CData of these classes to double. 3-304 imattributes Attribute Name Value Image type One of the image types identified by the Image Processing Toolbox software: 'intensity, 'truecolor', 'binary', or 'indexed'. Minimum intensity For intensity images, this value represents the lowest intensity value of any pixel. For indexed images, this value represents the lowest index value into a color map. Not included for 'binary' or 'truecolor' images. Maximum intensity For intensity images, this value represents the highest intensity value of any pixel. For indexed images, this value represents the highest index value into a color map. Not included for 'binary' or 'truecolor' images. attrs = imattributes(imgmodel) returns information about the image represented by the image model object, imgmodel. Examples Retrieve the attributes of a grayscale image. h = imshow('liftingbody.png'); attrs = imattributes(h) attrs = 'Width (columns)' 'Height (rows)' 'Class' 'Image type' 'Minimum intensity' 'Maximum intensity' '512' '512' 'uint8' 'intensity' '0' '255' Retrieve the attributes of a truecolor image. 3-305 imattributes h = imshow('gantrycrane.png'); im = imagemodel(h); attrs = imattributes(im) attrs = 'Width (columns)' 'Height (rows)' 'Class' 'Image type' See Also 3-306 imagemodel '400' '264' 'uint8' 'truecolor' imbothat Purpose Bottom-hat filtering Syntax IM2 = imbothat(IM,SE) IM2 = imbothat(IM,NHOOD) Description IM2 = imbothat(IM,SE) performs morphological bottom-hat filtering on the grayscale or binary input image, IM, returning the filtered image, IM2. The argument SE is a structuring element returned by the strel function. SE must be a single structuring element object, not an array containing multiple structuring element objects. IM2 = imbothat(IM,NHOOD) performs morphological bottom-hat filtering where NHOOD is an array of 0’s and 1’s that specifies the size and shape of the structuring element. This is equivalent to imbothat(IM,strel(NHOOD)). Class Support IM can be numeric or logical and must be nonsparse. The output image has the same class as the input image. If the input is binary (logical), then the structuring element must be flat. Examples Top-hat filtering and bottom-hat filtering can be used together to enhance contrast in an image. 1 Read the image into the MATLAB workspace. I = imread('pout.tif'); imshow(I) 3-307 imbothat 2 Create disk-shaped structuring element, needed for morphological processing. se = strel('disk',3); 3 Add the original image I to the top-hat filtered image, and then subtract the bottom-hat filtered image. J = imsubtract(imadd(I,imtophat(I,se)), imbothat(I,se)); figure, imshow(J) 3-308 imbothat See Also imtophat | strel 3-309 imclearborder Purpose Suppress light structures connected to image border Syntax IM2 = imclearborder(IM) IM2 = imclearborder(IM,conn) Description IM2 = imclearborder(IM) suppresses structures that are lighter than their surroundings and that are connected to the image border. (In other words, use this function to clear the image border.) IM can be a grayscale or binary image. The output image, IM2, is grayscale or binary, respectively. The default connectivity is 8 for two dimensions, 26 for three dimensions, and conndef(ndims(BW),'maximal') for higher dimensions. Note For grayscale images, imclearborder tends to reduce the overall intensity level in addition to suppressing border structures. IM2 = imclearborder(IM,conn) specifies the desired connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can also be defined in a more general way for any dimension by using for conn a 3-by-3-by- ... -by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the 3-310 imclearborder center element of conn. Note that conn must be symmetric about its center element. Note A pixel on the edge of the input image might not be considered to be a border pixel if a nondefault connectivity is specified. For example, if conn = [0 0 0; 1 1 1; 0 0 0], elements on the first and last row are not considered to be border pixels because, according to that connectivity definition, they are not connected to the region outside the image. Class Support IM can be a numeric or logical array of any dimension, and it must be nonsparse and real. IM2 has the same class as IM. Examples The following examples use this simple binary image to illustrate the effect of imclearborder when you specify different connectivities. BW = 0 0 0 1 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Using a 4-connected neighborhood, the pixel at (5,2) is not considered connected to the border pixel (4,1), so it is not cleared. BWc1 = imclearborder(BW,4) BWc1 = 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3-311 imclearborder 0 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 0 1 1 1 0 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Using an 8-connected neighborhood, pixel (5,2) is considered connected to pixel (4,1) so both are cleared. BWc2 = imclearborder(BW,8) BWc2 = 0 0 0 0 0 0 0 0 0 Algorithms 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 imclearborder uses morphological reconstruction where • Mask image is the input image. • Marker image is zero everywhere except along the border, where it equals the mask image. References [1] Soille, P., Morphological Image Analysis: Principles and Applications, Springer, 1999, pp. 164-165. See Also conndef 3-312 imclose Purpose Morphologically close image Syntax IM2 = imclose(IM,SE) IM2 = imclose(IM,NHOOD) Description IM2 = imclose(IM,SE) performs morphological closing on the grayscale or binary image IM, returning the closed image, IM2. The structuring element, SE, must be a single structuring element object, as opposed to an array of objects. The morphological close operation is a dilation followed by an erosion, using the same structuring element for both operations. IM2 = imclose(IM,NHOOD) performs closing with the structuring element strel(NHOOD), where NHOOD is an array of 0’s and 1’s that specifies the structuring element neighborhood. Class Support IM can be any numeric or logical class and any dimension, and must be nonsparse. If IM is logical, then SE must be flat. IM2 has the same class as IM. Examples Use imclose to join the circles in the image together by filling in the gaps between them and by smoothing their outer edges. 1 Read the image into the MATLAB workspace and view it. originalBW = imread('circles.png'); imshow(originalBW); 3-313 imclose 2 Create a disk-shaped structuring element. Use a disk structuring element to preserve the circular nature of the object. Specify a radius of 10 pixels so that the largest gap gets filled. se = strel('disk',10); 3 Perform a morphological close operation on the image. closeBW = imclose(originalBW,se); figure, imshow(closeBW) See Also 3-314 imdilate | imerode | imopen | strel imcolormaptool Purpose Choose Colormap tool Syntax imcolormaptool imcolormaptool(hclientfig) hfig = imcolormaptool(...) Description The Choose Colormap tool is an interactive colormap selection tool that allows you to change the colormap of the target (current) figure by selecting a colormap from a list of MATLAB colormap functions or workspace variables, or by entering a custom MATLAB expression. imcolormaptool launches the Choose Colormap tool in a separate figure, which is associated with the target figure. imcolormaptool(hclientfig) launches the Choose Colormap tool using hclientfig as the target figure. hclientfig must contain either a grayscale or an indexed image. hfig = imcolormaptool(...) returns a handle to the Choose Colormap tool, hfig. Examples h = figure; imshow('cameraman.tif'); imcolormaptool(h); 3-315 imcolormaptool Choose Colormap Tool See Also 3-316 colormap | imshow | imtool imcomplement Purpose Complement image Syntax IM2 = imcomplement(IM) Description IM2 = imcomplement(IM) computes the complement of the image IM. IM can be a binary, grayscale, or RGB image. IM2 has the same class and size as IM. In the complement of a binary image, zeros become ones and ones become zeros; black and white are reversed. In the complement of an intensity or RGB image, each pixel value is subtracted from the maximum pixel value supported by the class (or 1.0 for double-precision images) and the difference is used as the pixel value in the output image. In the output image, dark areas become lighter and light areas become darker. If IM is an grayscale or RGB image of class double, you can use the expression 1-IM instead of this function. If IM is a binary image, you can use the expression ~IM instead of this function. Examples Create the complement of a uint8 array. X = uint8([ 255 10 75; 44 225 100]); X2 = imcomplement(X) X2 = 0 245 180 211 30 155 Reverse black and white in a binary image. bw = imread('text.png'); bw2 = imcomplement(bw); subplot(1,2,1),imshow(bw) subplot(1,2,2),imshow(bw2) Create the complement of an intensity image. I = imread('glass.png'); J = imcomplement(I); 3-317 imcomplement imshow(I), figure, imshow(J) See Also 3-318 imabsdiff | imadd | imdivide | imlincomb | immultiply | imsubtract imcontour Purpose Create contour plot of image data Syntax imcontour(I) imcontour(I,n) imcontour(I,v) imcontour(x,y,...) imcontour(...,LineSpec) [C,handle] = imcontour(...) Description imcontour(I) draws a contour plot of the grayscale image I, automatically setting up the axes so their orientation and aspect ratio match the image. imcontour(I,n) draws a contour plot of the grayscale image I, automatically setting up the axes so their orientation and aspect ratio match the image. n is the number of equally spaced contour levels in the plot; if you omit the argument, the number of levels and the values of the levels are chosen automatically. imcontour(I,v) draws a contour plot of I with contour lines at the data values specified in vector v. The number of contour levels is equal to length(v). imcontour(x,y,...) uses the vectors x and y to specify the x- and y-axis limits. imcontour(...,LineSpec) draws the contours using the line type and color specified by LineSpec. Marker symbols are ignored. [C,handle] = imcontour(...) returns the contour matrix C and a handle to an hggroup object. Class Support The input image can be of class uint8, uint16, int16, single, double, or logical. Examples I = imread('circuit.tif'); imcontour(I,3) 3-319 imcontour See Also 3-320 clabel | contour | LineSpec imcontrast Purpose Adjust Contrast tool Syntax imcontrast imcontrast(h) hfigure = imcontrast(...) Description imcontrast creates an Adjust Contrast tool in a separate figure that is associated with the grayscale image in the current figure, called the target image. The Adjust Contrast tool is an interactive contrast and brightness adjustment tool, shown in the following figure, that you can use to adjust the black-to-white mapping used to display the image. When you use the tool, imcontrast adjusts the contrast of the displayed image by modifying the axes CLim property. To modify the actual pixel values in the target image, click the Adjust Data button. (This button is unavailable until you make a change to the contrast of the image.) For more information about using the tool, see “Tips” on page 3-322. 3-321 imcontrast Note The Adjust Contrast tool can handle grayscale images of class double and single with data ranges beyond the default display range, which is [0 1]. For these images, imcontrast sets the histogram limits to fit the image data range, with padding at the upper and lower bounds. imcontrast(h) creates the Adjust Contrast tool associated with the image specified by the handle h. h can be a handle to a figure, axes, uipanel, or image object. If h is an axes or figure handle, imcontrast uses the first image returned by findobj(H,'Type','image'). hfigure = imcontrast(...) returns a handle to the Adjust Contrast tool figure. Tips The Adjust Contrast tool presents a scaled histogram of pixel values (overly represented pixel values are truncated for clarity). Dragging on the left red bar in the histogram display changes the minimum value. The minimum value (and any value less than the minimum) displays as black. Dragging on the right red bar in the histogram changes the maximum value. The maximum value (and any value greater than the maximum) displays as white. Values in between the red bars display as intermediate shades of gray. Together the minimum and maximum values create a "window". Stretching the window reduces contrast. Shrinking the window increases contrast. Changing the center of the window changes the brightness of the image. It is possible to manually enter the minimum, maximum, width, and center values for the window. Changing one value automatically updates the other values and the image. For more information about using the Adjust Contrast tool, see “Adjusting Image Contrast Using the Adjust Contrast Tool”. Window/Level Interactivity Clicking and dragging the mouse within the target image interactively changes the image’s window values. Dragging the mouse horizontally from left to right changes the window width (i.e., contrast). Dragging 3-322 imcontrast the mouse vertically up and down changes the window center (i.e., brightness). Holding down the Ctrl key before clicking and dragging the mouse accelerates the rate of change; holding down the Shift key before clicking and dragging the mouse slows the rate of change. Keys must be pressed before clicking and dragging. Examples imshow('pout.tif') imcontrast(gca) See Also imadjust | imtool | stretchlim 3-323 imcrop Purpose Crop image Syntax I = imcrop I2 = imcrop(I) X2 = imcrop(X, map) I = imcrop(h) I2 = imcrop(I, rect) X2 = imcrop(X, map, rect) [...] = imcrop(x, y,...) [I2 rect] = imcrop( ) [X,Y,I2,rect] = imcrop( ) Description I = imcrop creates an interactive Crop Image tool associated with the image displayed in the current figure, called the target image. The Crop Image tool is a moveable, resizable rectangle that you can position interactively using the mouse. When the Crop Image tool is active, the pointer changes to cross hairs when you move it over the target image. Using the mouse, you specify the crop rectangle by clicking and dragging the mouse. You can move or resize the crop rectangle using the mouse. When you are finished sizing and positioning the crop rectangle, create the cropped image by double-clicking the left mouse button or by choosing Crop Image from the context menu. imcrop returns the cropped image, I. The following figure illustrates the Crop Image tool with the context menu displayed. For more information about the interactive capabilities of the tool, see the table that follows. 3-324 imcrop Resize handle Crop rectangle Crop Image tool context menu Interactive Behavior Description Deleting the Crop Image tool. Press Backspace, Escape or Delete, or right-click inside the crop rectangle and select Cancel from the context menu. Note: If you delete the ROI, the function returns empty values. Resizing the Crop Image tool. Select any of the resize handles on the crop rectangle. The pointer changes to a . Click and drag the double-headed arrow mouse to resize the crop rectangle. 3-325 imcrop Interactive Behavior Description Moving the Crop Image tool. Move the pointer inside the boundary of the crop rectangle. The pointer changes to a fleur shape . Click and drag the mouse to move the rectangle over the image. Changing the color used to display the crop rectangle. Right-click inside the boundary of the crop rectangle and select Set Color from the context menu. Cropping the image. Double-click the left mouse button or right-click inside the boundary of the crop rectangle and select Crop Image from the context menu. Retrieving the coordinates of the crop rectangle. Right-click inside the boundary of the crop rectangle and select Copy Position from the context menu. imcrop copies a four-element position vector ([xmin ymin width height]) to the clipboard. I2 = imcrop(I) displays the image I in a figure window and creates a cropping tool associated with that image. I can be a grayscale image, a truecolor image, or a logical array. The cropped image returned, I2, is of the same type as I. X2 = imcrop(X, map) displays the indexed image X in a figure using the colormap map, and creates a cropping tool associated with that image. I = imcrop(h) creates a cropping tool associated with the image specified by handle h. h may be an image, axes, uipanel, or figure handle. If h is an axes, uipanel, or figure handle, the cropping tool acts on the first image found in the container object. 3-326 imcrop Note With these interactive syntaxes, the cropping tool blocks the MATLAB command line until you complete the operation. I2 = imcrop(I, rect) crops the image I. rect is a four-element position vector[xmin ymin width height] that specifies the size and position of the crop rectangle. X2 = imcrop(X, map, rect) crops the indexed image X. map specifies the colormap used with X. rect is a four-element position vector [xmin ymin width height] that specifies the size and position of the cropping rectangle. = imcrop(x, y,...) specifies a non-default spatial coordinate system for the target image. x and y are two-element vectors specifying XData and YData. [...] [I2 rect] = imcrop( ) returns the cropping rectangle in rect, a four-element position vector. [X,Y,I2,rect] = imcrop( ) returns x and y, two-element vectors that specify the XData and YData of the target image. Class Support If you specify rect as an input argument, the input image can be logical or numeric, and must be real and nonsparse. rect is of class double. If you do not specify rect as an input argument, imcrop calls imshow. imshow expects I to be logical, uint8, uint16, int16, single, or double. A truecolor image can be uint8, int16, uint16, single, or double. X can be logical, uint8, uint16, single, or double. The input image must be real and nonsparse. If you specify an image as an input argument, the output image has the same class as the input image. If you don’t specify an image as an input argument, i.e., you call imcrop with no input arguments or a handle, the output image has the same class as the input image except for int16 or single. If the input image is int16 or single, the output image is double. 3-327 imcrop Tips Because rect is specified in terms of spatial coordinates, the width and height elements of rect do not always correspond exactly with the size of the output image. For example, suppose rect is [20 20 40 30], using the default spatial coordinate system. The upper-left corner of the specified rectangle is the center of the pixel (20,20) and the lower-right corner is the center of the pixel (50,60). The resulting output image is 31-by-41, not 30-by-40, because the output image includes all pixels in the input image that are completely or partially enclosed by the rectangle. Examples I = imread('circuit.tif'); I2 = imcrop(I,[75 68 130 112]); imshow(I), figure, imshow(I2) See Also imrect | zoom 3-328 imdilate Purpose Dilate image Syntax IM2 IM2 IM2 IM2 Description IM2 = imdilate(IM,SE) dilates the grayscale, binary, or packed binary image IM, returning the dilated image, IM2. The argument SE is a structuring element object, or array of structuring element objects, returned by the strel function. = = = = imdilate(IM,SE) imdilate(IM,NHOOD) imdilate(IM,SE,PACKOPT) imdilate(...,SHAPE) If IM is logical and the structuring element is flat, imdilate performs binary dilation; otherwise, it performs grayscale dilation. If SE is an array of structuring element objects, imdilate performs multiple dilations of the input image, using each structuring element in SE in succession. IM2 = imdilate(IM,NHOOD) dilates the image IM, where NHOOD is a matrix of 0’s and 1’s that specifies the structuring element neighborhood. This is equivalent to the syntax imdilate(IM,strel(NHOOD)). The imdilate function determines the center element of the neighborhood by floor((size(NHOOD)+1)/2). IM2 = imdilate(IM,SE,PACKOPT) or imdilate(IM,NHOOD,PACKOPT) specifies whether IM is a packed binary image. PACKOPT can have either of the following values. Default value is enclosed in braces ({}). Value Description 'ispacked' IM is treated as a packed binary image as produced by bwpack. IM must be a 2-D uint32 array and SE must be a flat 2-D structuring element. If the value of PACKOPT is 'ispacked', PADOPT must be 'same'. {'notpacked'} IM is treated as a normal array. 3-329 imdilate IM2 = imdilate(...,SHAPE) specifies the size of the output image. SHAPE can have either of the following values. Default value is enclosed in braces ({}). Definitions Value Description {'same'} Make the output image the same size as the input image. If the value of PACKOPT is 'ispacked', PADOPT must be 'same'. 'full' Compute the full dilation. The binary dilation of A by B, denoted A ⊕ B , is defined as the set operation: {( A ⊕ B = z Bˆ )z ∩ A ≠ ∅}, where B̂ is the reflection of the structuring element B. In other words, it is the set of pixel locations z, where the reflected structuring element overlaps with foreground pixels in A when translated to z. Note that some people use a definition of dilation in which the structuring element is not reflected. In the general form of gray-scale dilation, the structuring element has a height. The gray-scale dilation of A(x,y) by B(x,y) is defined as: ( A ⊕ B )( x, y ) = max { A( x − x′, y − y′) + B( x′, y′) ( x′, y′ ) ∈ DB } , where DB is the domain of the structuring element B and A(x,y) is assumed to be −∞ outside the domain of the image. To create a structuring element with nonzero height values, use the syntax strel(nhood,height), where height gives the height values and nhood corresponds to the structuring element domain, DB. Most commonly, gray-scale dilation is performed with a flat structuring element (B(x,y) = 0). Gray-scale dilation using such a structuring element is equivalent to a local-maximum operator: 3-330 imdilate ( A ⊕ B )( x, y ) = max { A( x − x′, y − y′) ( x′, y′) ∈ DB }. All of the strel syntaxes except for strel(nhood,height), strel('arbitrary',nhood,height), and strel('ball', ...) produce flat structuring elements. For more information about binary dilation, see [1]. Class Support Examples IM can be logical or numeric and must be real and nonsparse. It can have any dimension. If IM is logical, SE must be flat. The output has the same class as the input. If the input is packed binary, then the output is also packed binary. Dilate a binary image with a vertical line structuring element. bw = imread('text.png'); se = strel('line',11,90); bw2 = imdilate(bw,se); imshow(bw), title('Original') figure, imshow(bw2), title('Dilated') Dilate a grayscale image with a rolling ball structuring element. I = imread('cameraman.tif'); se = strel('ball',5,5); I2 = imdilate(I,se); imshow(I), title('Original') 3-331 imdilate figure, imshow(I2), title('Dilated') To determine the domain of the composition of two flat structuring elements, dilate the scalar value 1 with both structuring elements in sequence, using the 'full' option. se1 = strel('line',3,0) se1 = Flat STREL object containing 3 neighbors. Neighborhood: 1 1 1 se2 = strel('line',3,90) se2 = Flat STREL object containing 3 neighbors. Neighborhood: 1 1 1 composition = imdilate(1,[se1 se2],'full') composition = 1 1 1 1 1 1 3-332 imdilate 1 Algorithms 1 1 imdilate automatically takes advantage of the decomposition of a structuring element object (if it exists). Also, when performing binary dilation with a structuring element object that has a decomposition, imdilate automatically uses binary image packing to speed up the dilation. Dilation using bit packing is described in [3]. References [1] Gonzalez, R. C., R. E. Woods, and S. L. Eddins, Digital Image Processing Using MATLAB, Gatesmark Publishing, 2009. [2] Haralick, R. M., and L. G. Shapiro, Computer and Robot Vision, Vol. I, Addison-Wesley, 1992, pp. 158-205. [3] van den Boomgard, R, and R. van Balen, "Methods for Fast Morphological Image Transforms Using Bitmapped Images," Computer Vision, Graphics, and Image Processing: Graphical Models and Image Processing, Vol. 54, Number 3, pp. 254-258, May 1992. See Also bwpack | bwunpack | conv2 | filter2 | imclose | imerode | imopen | strel 3-333 imdisplayrange Purpose Display Range tool Syntax imdisplayrange imdisplayrange(h) imdisplayrange(hparent,himage) hpanel = imdisplayrange(...) Description imdisplayrange creates a Display Range tool in the current figure. The Display Range tool shows the display range of the intensity image or images in the figure. The tool is a uipanel object, positioned in the lower-right corner of the figure. It contains the text string Display range: followed by the display range values for the image, as shown in the following figure. For an indexed, truecolor, or binary image, the display range is not applicable and is set to empty ([]). imdisplayrange(h) creates a Display Range tool in the figure specified by the handle h, where h is a handle to an image, axes, uipanel, or figure object. Axes, uipanel, or figure objects must contain at least one image object. imdisplayrange(hparent,himage) creates a Display Range tool in hparent that shows the display range of himage. himage is a handle to an image or an array of image handles. hparent is a handle to the figure or uipanel object that contains the display range tool. hpanel = imdisplayrange(...) returns a handle to the Display Range tool uipanel. Note 3-334 The Display Range tool can work with multiple images in a figure. When the pointer is not in an image in a figure, the Display Range tool displays the text string [black white]. imdisplayrange Examples Display an image and include the Display Range tool. imshow('bag.png'); imdisplayrange; Import a 16-bit DICOM image and display it with its default range and scaled range in the same figure. dcm = dicomread('CT-MONO2-16-ankle.dcm'); subplot(1,2,1), imshow(dcm); subplot(1,2,2), imshow(dcm,[]); imdisplayrange; See also imtool 3-335 imdistline Purpose Distance tool Syntax h = imdistline h = imdistline(hparent) h = imdistline(..., x, y) Description h = imdistline creates a Distance tool on the current axes. The function returns h, a handle to an imdistline object. The Distance tool is a draggable, resizable line, superimposed on an axes, that measures the distance between the two endpoints of the line. The Distance tool displays the distance in a text label superimposed over the line. The tools specifies the distance in data units determined by the XData and YData properties, which is pixels, by default. The following figure shows a Distance tool on an axes. To move the Distance tool, position the pointer over the line, the . Click and drag the line using the shape changes to the fleur, mouse. To resize the Distance tool, move the pointer over either of the endpoints of the line, the shape changes to the pointing finger, . Click and drag the endpoint of the line using the mouse. The line also supports a context menu that allows you to control various aspects of its functioning and appearance. See Context Menu for more information. Right-click the line to access the context menu. 3-336 imdistline h = imdistline(hparent) creates a draggable Distance tool on the object specified by hparent. hparent specifies the Distance tool’s parent, which is typically an axes object, but can also be any other object that can be the parent of an hggroup object. h = imdistline(..., x, y) creates a Distance tool with endpoints located at the locations specified by the vectors x and y, where x = [x1 x2] and y =[y1 y2]. Context Menu API Functions Distance Tool Behavior Context Menu Item Export endpoint and distance data to the workspace Select Export to Workspace from the context menu. Toggle the distance label on/off. Select Show Distance Label from the context menu. Specify horizontal and vertical drag constraints Select Constrain Drag from the context menu. Change the color used to display the line. Select Set Color from the context menu. Delete the Distance tool object Select Delete from the context menu. The Distance tool contains a structure of function handles, called an API, that can be used to retrieve distance information and control other aspects of Distance tool behavior. To retrieve this structure from the Distance tool, use the iptgetapi function, where h is a handle to the Distance tool. api = iptgetapi(h) 3-337 imdistline The following table lists the functions in the API, with their syntax and brief descriptions. Function Description getDistance Returns the distance between the endpoints of the Distance tool. dist = getDistance() The value returned is in data units determined by the XData and YData properties, which is pixels, by default. getAngleFromHorizontal Returns the angle in degrees between the line defined by the Distance tool and the horizontal axis. The angle returned is between 0 and 180 degrees. (For information about how this angle is calculated, see “Tips” on page 3-341.) angle = getAngleFromHorizontal() setLabelTextFormatter Sets the format string used in displaying the distance label. setLabelTextFormatter(str) str is a character array specifying a format string in the form expected by sprintf. getLabelTextFormatter Returns a character array specifying the format string used to display the distance label. str = getLabelTextFormatter() str is a character array specifying a format string in the form expected by sprintf. 3-338 imdistline Function Description setLabelVisible Sets visibility of Distance tool text label. setLabelVisible(h,TF) h is the Distance tool. TF is a logical scalar. When the distance label is visible, TF is true. When the distance label is invisible, TF is false. getLabelVisible Gets visibility of Distance tool text label. TF = getLabelVisible(h) h is the Distance tool. TF is a logical scalar. When TF is true, the distance label is visible. When TF is false, the distance label is invisible. setPosition Sets the endpoint positions of the Distance tool. setPosition(X,Y) setPosition([X1 Y1; X2 Y2]) getPosition Returns the endpoint positions of the Distance tool. pos = getPosition() pos is a 2-by-2 array [X1 Y1; X2 Y2]. delete Deletes the Distance tool associated with the API. delete() 3-339 imdistline Function Description setColor Sets the color used to draw the Distance tool. setColor(new_color) new_color can be a three-element vector specifying an RGB triplet, or a text string specifying the long or short names of a predefined color, such as 'white' or 'w'. For a complete list of these predefined colors and their short names, see ColorSpec. getColor Gets the color used to draw the ROI object h. color = getColor(h) color is a three-element vector that specifies an RGB triplet. addNewPositionCallback Adds the function handle fcn to the list of new-position callback functions. id = addNewPositionCallback(fcn) Whenever the Distance tool changes its position, each function in the list is called with the following syntax. fcn(pos) pos is a 2-by-2 array [X1 Y1; X2 Y2]. The return value, id, is used only with removeNewPositionCallback. 3-340 imdistline Function Description removeNewPositionCallback Removes the corresponding function from the new-position callback list. removeNewPositionCallback(id) id is the identifier returned by addNewPositionCallback. setPositionConstraintFcn Sets the position constraint function to be the specified function handle, fcn. Use this function to control where the Distance tool can be moved and resized. setPositionConstraintFcn(fcn) Whenever the Distance tool is moved or resized because of a mouse drag, the constraint function is called using the following syntax. constrained_position = fcn(new_position) new_position is a 2-by-2 array [X1 Y1; X2 Y2]. getPositionConstraintFcn Returns the function handle of the current drag constraint function. fcn = getDragConstraintFcn() Tips If you use imdistline with an axes that contains an image object, and do not specify a drag constraint function, users can drag the line outside the extent of the image. When used with an axes created by the plot function, the axes limits automatically expand to accommodate the movement of the line. To understand how imdistline calculates the angle returned by getAngleToHorizontal, draw an imaginary horizontal vector from the bottom endpoint of the distance line, extending to the right. The value 3-341 imdistline returned by getAngleToHorizontal is the angle from this horizontal vector to the distance line, which can range from 0 to 180 degrees. Examples Example 1 Insert a Distance tool into an image. Use makeConstrainToRectFcn to specify a drag constraint function that prevents the Distance tool from being dragged outside the extent of the image. Right-click the Distance tool and explore the context menu options. figure, imshow('pout.tif'); h = imdistline(gca); api = iptgetapi(h); fcn = makeConstrainToRectFcn('imline',... get(gca,'XLim'),get(gca,'YLim')); api.setDragConstraintFcn(fcn); Example 2 Position endpoints of the Distance tool at the specified locations. close all, imshow('pout.tif'); h = imdistline(gca,[10 100],[10 100]); Delete the Distance tool. api = iptgetapi(h); api.delete(); Example 3 Use the Distance tool with XData and YData of associated image in non-pixel units. This example requires the boston.tif image from the Mapping Toolbox software, which includes material copyrighted by GeoEye™, all rights reserved. start_row = 1478; end_row = 2246; meters_per_pixel = 1; rows = [start_row meters_per_pixel end_row]; 3-342 imdistline start_col = 349; end_col = 1117; cols = [start_col meters_per_pixel end_col]; img = imread('boston.tif','PixelRegion',{rows,cols}); figure; hImg = imshow(img); title('1 meter per pixel'); % Specify initial position of distance tool on Harvard Bridge. hline = imdistline(gca,[271 471],[108 650]); api = iptgetapi(hline); api.setLabelTextFormatter('%02.0f meters'); % Repeat process but work with a 2 meter per pixel sampled image. Verify % that the same distance is obtained. meters_per_pixel = 2; rows = [start_row meters_per_pixel end_row]; cols = [start_col meters_per_pixel end_col]; img = imread('boston.tif','PixelRegion',{rows,cols}); figure; hImg = imshow(img); title('2 meters per pixel'); % Convert XData and YData to meters using conversion factor. XDataInMeters = get(hImg,'XData')*meters_per_pixel; YDataInMeters = get(hImg,'YData')*meters_per_pixel; % Set XData and YData of image to reflect desired units. set(hImg,'XData',XDataInMeters,'YData',YDataInMeters); set(gca,'XLim',XDataInMeters,'YLim',YDataInMeters); % Specify initial position of distance tool on Harvard Bridge. hline = imdistline(gca,[271 471],[108 650]); api = iptgetapi(hline); api.setLabelTextFormatter('%02.0f meters'); See Also iptgetapi | makeConstrainToRectFcn 3-343 imdivide Purpose Divide one image into another or divide image by constant Syntax Z = imdivide(X,Y) Description Z = imdivide(X,Y) divides each element in the array X by the corresponding element in array Y and returns the result in the corresponding element of the output array Z. X and Y are real, nonsparse numeric arrays with the same size and class, or Y can be a scalar double. Z has the same size and class as X and Y. If X is an integer array, elements in the output that exceed the range of integer type are truncated, and fractional values are rounded. Note On Intel architecture processors, imdivide can take advantage of the Intel Integrated Performance Primitives (Intel IPP) library, thus accelerating its execution time. The Intel IPP library is activated only if arrays X and Y are of class uint8, int16, or single and are of the same size and class. Examples Divide two uint8 arrays. Note that fractional values greater than or equal to 0.5 are rounded up to the nearest integer. X Y Z Z = uint8([ 255 10 75; 44 225 100]); = uint8([ 50 20 50; 50 50 50 ]); = imdivide(X,Y) = 5 1 2 1 5 2 Estimate and divide out the background of the rice image. I = imread('rice.png'); background = imopen(I,strel('disk',15)); Ip = imdivide(I,background); imshow(Ip,[]) 3-344 imdivide Divide an image by a constant factor. I = imread('rice.png'); J = imdivide(I,2); subplot(1,2,1), imshow(I) subplot(1,2,2), imshow(J) See Also imabsdiff | imadd | imcomplement | imlincomb | immultiply | imsubtract | ippl 3-345 imellipse Purpose Create draggable ellipse Syntax h h h H Description h = imellipse begins interactive placement of an ellipse on the current axes. The function returns h, a handle to an imellipse object. The = = = = imellipse imellipse(hparent) imellipse(hparent, position) imellipse(...,param1, val1, ...) ellipse has a context menu associated with it that controls aspects of its appearance and behavior—see “Interactive Behavior” on page 3-347. Right-click on the line to access this context menu. h = imellipse(hparent) begins interactive placement of an ellipse on the object specified by hparent. hparent specifies the HG parent of the ellipse graphics, which is typically an axes but can also be any other object that can be the parent of an hggroup. h = imellipse(hparent, position) creates a draggable ellipse on the object specified by hparent. position is a four-element vector that specifies the initial location of the ellipse in terms of a bounding rectangle. position has the form [xmin ymin width height]. H = imellipse(...,param1, val1, ...) creates a draggable ellipse, specifying parameters and corresponding values that control the behavior of the ellipse. The following table lists the parameter available. Parameter names can be abbreviated, and case does not matter. Parameter Value 'PositionConstraintFcn' Function handle that is called whenever the mouse is dragged. You can use this to control where the ellipse may be dragged. See the help for the setPositionConstraintFcn method for information about valid function handles. 3-346 imellipse Interactive Behavior When you call imellipse with an interactive syntax, the pointer when over an image. Click and drag the changes to a cross hairs mouse to specify the size and position of the ellipse. The ellipse also supports a context menu that you can use to control aspects of its appearance and behavior. The following figure illustrates the ellipse with its context menu. Ellipse Resize handles Ellipse tool context menu The following table lists the interactive behavior supported by imellipse. Interactive Behavior Description Moving the entire ellipse. Move the pointer inside the ellipse. The Resizing the ellipse. . Click pointer changes to a fleur shape and drag the mouse to move the ellipse. Move the pointer over a resizing handle on the ellipse. The pointer changes to a double-ended . Click and drag the mouse arrow shape to resize the ellipse. 3-347 imellipse Interactive Behavior Description Changing the color used to display the ellipse. Move the pointer inside the ellipse. Right-click and select Set Color from the context menu. Retrieving the current position of the ellipse. Move the pointer inside the ellipse. Right-click and select Copy Position from the context menu. imellipse copies a four-element position vector [xmin ymin width height] to the clipboard. Preserving the current aspect ratio of the ellipse during resizing. Move the pointer inside the ellipse. Right-click and select Fix Aspect Ratio from the context menu. Methods Each imellipse object supports a number of methods. Type methods imellipse to see a complete list. addNewPositionCallback — Add new-position callback to ROI object See imroi for information. createMask — Create mask within image See imroi for information. delete — Delete ROI object See imroi for information. getColor — Get color used to draw ROI object See imroi for information. getPosition — Return current position of ellipse See imrect for information. getPositionConstraintFcn — Return function handle to current position constraint function See imroi for information. 3-348 imellipse getVertices — Return vertices on perimeter of ellipse vert = getVertices(h) returns a set of vertices which lie along the perimeter of the ellipse h. vert is a N-by-2 array. removeNewPositionCallback — Remove new-position callback from ROI object. See imroi for information. resume — Resume execution of MATLAB command line See imroi for information. setColor — Set color used to draw ROI object See imroi for information. setConstrainedPosition — Set ROI object to new position See imroi for information. setFixedAspectRatioMode — Control whether aspect ratio preserved during resize See imrect for information. setPosition — Set ellipse to new position See imrect for information. setPositionConstraintFcn — Set position constraint function of ROI object. See imroi for information. setResizable — Set resize behavior of ellipse See imrect for information. wait — Block MATLAB command line until ROI creation is finished vert = wait(h) blocks execution of the MATLAB command line until you finish positioning the ROI object h. You indicate completion by double-clicking on the ROI object. The returned vertices, vert, is of the form returned by the getVertices method. Tips If you use imellipse with an axes that contains an image object, and do not specify a position constraint function, users can drag the ellipse outside the extent of the image and lose the ellipse. When used with an axes created by the plot function, the axes limits automatically expand to accommodate the movement of the ellipse. 3-349 imellipse Examples Example 1 Create an ellipse, using callbacks to display the updated position in the title of the figure. The example illustrates using the makeConstrainToRectFcn to keep the ellipse inside the original xlim and ylim ranges. figure, imshow('cameraman.tif'); h = imellipse(gca, [10 10 100 100]); addNewPositionCallback(h,@(p) title(mat2str(p,3))); fcn = makeConstrainToRectFcn('imellipse',get(gca,'XLim'),get(gca,'YLim')); setPositionConstraintFcn(h,fcn); Example 2 Interactively place an ellipse by clicking and dragging. Use wait to block the MATLAB command line. Double-click on the ellipse to resume execution of the MATLAB command line. figure, imshow('pout.tif'); h = imellipse; position = wait(h); See Also 3-350 imfreehand | imline | impoint | impoly | imrect | imroi | iptgetapi | makeConstrainToRectFcn imerode Purpose Erode image Syntax IM2 IM2 IM2 IM2 Description IM2 = imerode(IM,SE) erodes the grayscale, binary, or packed binary image IM, returning the eroded image IM2. The argument SE is a = = = = imerode(IM,SE) imerode(IM,NHOOD) imerode(...,PACKOPT,M) imerode(...,SHAPE) structuring element object or array of structuring element objects returned by the strel function. If IM is logical and the structuring element is flat, imerode performs binary erosion; otherwise it performs grayscale erosion. If SE is an array of structuring element objects, imerode performs multiple erosions of the input image, using each structuring element in SE in succession. IM2 = imerode(IM,NHOOD) erodes the image IM, where NHOOD is an array of 0’s and 1’s that specifies the structuring element neighborhood. This is equivalent to the syntax imerode(IM,strel(NHOOD)). The imerode function determines the center element of the neighborhood by floor((size(NHOOD)+1)/2). IM2 = imerode(...,PACKOPT,M) specifies whether IM is a packed binary image and, if it is, provides the row dimension M of the original unpacked image. PACKOPT can have either of the following values. Default value is enclosed in braces ({}). Value Description 'ispacked' IM is treated as a packed binary image as produced by bwpack. IM must be a 2-D uint32 array and SE must be a flat 2-D structuring element. {'notpacked'} IM is treated as a normal array. If PACKOPT is 'ispacked', you must specify a value for M. 3-351 imerode IM2 = imerode(...,SHAPE) specifies the size of the output image. SHAPE can have either of the following values. Default value is enclosed in braces ({}). Definitions Value Description {'same'} Make the output image the same size as the input image. If the value of PACKOPT is 'ispacked', SHAPE must be 'same'. 'full' Compute the full erosion. The binary erosion of A by B, denoted A B, is defined as the set operation A B = {z|(Bz ⊆ A}. In other words, it is the set of pixel locations z, where the structuring element translated to location z overlaps only with foreground pixels in A. In the general form of gray-scale erosion, the structuring element has a height. The gray-scale erosion of A(x, y) by B(x, y) is defined as: (A B)(x, y) = min {A(x + x′, y + y′) − B(x′, y′) | (x′, y′) DB}, where DB is the domain of the structuring element B and A(x,y) is assumed to be +∞ outside the domain of the image. To create a structuring element with nonzero height values, use the syntax strel(nhood,height), where height gives the height values and nhood corresponds to the structuring element domain, DB. Most commonly, gray-scale erosion is performed with a flat structuring element (B(x,y) = 0). Gray-scale erosion using such a structuring element is equivalent to a local-minimum operator: (A B)(x, y) = min {A(x + x′, y + y′) | (x′, y′) DB}. All of the strel syntaxes except for strel(nhood,height), strel('arbitrary',nhood,height), and strel('ball', ...) produce flat structuring elements. For more information on binary erosion, see [1]. 3-352 imerode Class Support IM can be numeric or logical and it can be of any dimension. If IM is logical and the structuring element is flat, the output image is logical; otherwise the output image has the same class as the input. If the input is packed binary, then the output is also packed binary. Examples Erode a binary image with a disk structuring element. originalBW = imread('circles.png'); se = strel('disk',11); erodedBW = imerode(originalBW,se); imshow(originalBW), figure, imshow(erodedBW) Erode a grayscale image with a rolling ball. I = imread('cameraman.tif'); se = strel('ball',5,5); I2 = imerode(I,se); imshow(I), title('Original') figure, imshow(I2), title('Eroded') 3-353 imerode Algorithms imerode automatically takes advantage of the decomposition of a structuring element object (if a decomposition exists). Also, when performing binary dilation with a structuring element object that has a decomposition, imerode automatically uses binary image packing to speed up the dilation. Erosion using bit packing is described in [3]. References [1] Gonzalez, R. C., R. E. Woods, and S. L. Eddins, Digital Image Processing Using MATLAB, Gatesmark Publishing, 2009. [2] Haralick, Robert M., and Linda G. Shapiro, Computer and Robot Vision, Vol. I, Addison-Wesley, 1992, pp. 158-205. [3] van den Boomgard, R, and R. van Balen, "Methods for Fast Morphological Image Transforms Using Bitmapped Images," Computer Vision, Graphics, and Image Processing: Graphical Models and Image Processing, Vol. 54, Number 3, pp. 254-258, May 1992. See Also 3-354 bwpack | bwunpack | conv2 | filter2 | imclose | imdilate | imopen | strel imextendedmax Purpose Extended-maxima transform Syntax BW = imextendedmax(I,H) BW = imextendedmax(I,H,conn) Description BW = imextendedmax(I,H) computes the extended-maxima transform, which is the regional maxima of the H-maxima transform. H is a nonnegative scalar. Regional maxima are connected components of pixels with a constant intensity value, and whose external boundary pixels all have a lower value. By default, imextendedmax uses 8-connected neighborhoods for 2-D images and 26-connected neighborhoods for 3-D images. For higher dimensions, imextendedmax uses conndef(ndims(I),'maximal'). BW = imextendedmax(I,H,conn) computes the extended-maxima transform, where conn specifies the connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by- ...-by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. 3-355 imextendedmax Class Support I can be of any nonsparse numeric class and any dimension. BW has the same size as I and is always logical. Examples I = imread('glass.png'); BW = imextendedmax(I,80); imshow(I), figure, imshow(BW) References [1] Soille, P., Morphological Image Analysis: Principles and Applications, Springer-Verlag, 1999, pp. 170-171. See Also conndef | imextendedmin | imhmax | imreconstruct | imregionalmax 3-356 imextendedmin Purpose Extended-minima transform Syntax BW = imextendedmin(I,h) BW = imextendedmin(I,h,conn) Description BW = imextendedmin(I,h) computes the extended-minima transform, which is the regional minima of the H-minima transform. h is a nonnegative scalar. Regional minima are connected components of pixels with a constant intensity value, and whose external boundary pixels all have a higher value. By default, imextendedmin uses 8-connected neighborhoods for 2-D images, and 26-connected neighborhoods for 3-D images. For higher dimensions, imextendedmin uses conndef(ndims(I),'maximal'). BW = imextendedmin(I,h,conn) computes the extended-minima transform, where conn specifies the connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by-...-by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. 3-357 imextendedmin Class Support I can be of any nonsparse numeric class and any dimension. BW has the same size as I and is always logical. Examples I = imread('glass.png'); BW = imextendedmin(I,50); imshow(I), figure, imshow(BW) References [1] Soille, P., Morphological Image Analysis: Principles and Applications, Springer-Verlag, 1999, pp. 170-171. See Also conndef | imextendedmax | imhmin | imreconstruct | imregionalmin 3-358 imfill Purpose Fill image regions and holes Syntax BW2 = imfill(BW) [BW2,locations] = imfill(BW) BW2 = imfill(BW,locations) BW2 = imfill(BW,'holes') I2 = imfill(I) BW2 = imfill(BW,locations,conn) Description BW2 = imfill(BW) displays the binary image BW on the screen and lets you define the region to fill by selecting points interactively by using the mouse. To use this interactive syntax, BW must be a 2-D image. Press Backspace or Delete to remove the previously selected point. A shift-click, right-click, or double-click selects a final point and starts the fill operation. Pressing Return finishes the selection without adding a point. [BW2,locations] = imfill(BW) returns the locations of points selected interactively in locations. locations is a vector of linear indices into the input image. To use this interactive syntax, BW must be a 2-D image. BW2 = imfill(BW,locations) performs a flood-fill operation on background pixels of the binary image BW, starting from the points specified in locations. If locations is a P-by-1 vector, it contains the linear indices of the starting locations. If locations is a P-by-ndims(BW) matrix, each row contains the array indices of one of the starting locations. BW2 = imfill(BW,'holes') fills holes in the binary image BW. A hole is a set of background pixels that cannot be reached by filling in the background from the edge of the image. I2 = imfill(I) fills holes in the grayscale image I. In this syntax, a hole is defined as an area of dark pixels surrounded by lighter pixels. BW2 = imfill(BW,locations,conn) fills the area defined by locations, where conn specifies the connectivity. conn can have any of the following scalar values. 3-359 imfill Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by- ... -by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. Specifying Connectivity By default, imfill uses 4-connected background neighbors for 2-D inputs and 6-connected background neighbors for 3-D inputs. For higher dimensions the default background connectivity is determined by using conndef(NUM_DIMS,'minimal'). You can override the default connectivity with these syntaxes: BW2 = imfill(BW,locations,conn) BW2 = imfill(BW,conn,'holes') I2 = imfill(I,conn) To override the default connectivity and interactively specify the starting locations, use this syntax: BW2 = imfill(BW,0,conn) Class Support 3-360 The input image can be numeric or logical, and it must be real and nonsparse. It can have any dimension. The output image has the same class as the input image. imfill Examples Fill in the background of a binary image from a specified starting location. BW1 = logical([1 1 1 1 1 1 1 1 0 1 0 0 1 0 0 0 0 1 0 0 1 0 0 0 0 1 0 0 1 1 0 0 0 1 1 1 0 1 1 1 0 0 0 1 1 0 0 1 0 0 1 1 1 1 1 1 0 0 0 0 1 0 0 0]); BW2 = imfill(BW1,[3 3],8) Fill in the holes of a binary image. BW4 = im2bw(imread('coins.png')); BW5 = imfill(BW4,'holes'); imshow(BW4), figure, imshow(BW5) Fill in the holes of a grayscale image. I = imread('tire.tif'); I2 = imfill(I,'holes'); figure, imshow(I), figure, imshow(I2) 3-361 imfill Algorithms imfill uses an algorithm based on morphological reconstruction [1]. References [1] Soille, P., Morphological Image Analysis: Principles and Applications, Springer-Verlag, 1999, pp. 173-174. See Also bwselect | imreconstruct | roifill 3-362 imfilter Purpose N-D filtering of multidimensional images Syntax B = imfilter(A, H) B = imfilter(A, H, option1, option2,...) Description B = imfilter(A, H) filters the multidimensional array A with the multidimensional filter H. The array A can be logical or a nonsparse numeric array of any class and dimension. The result B has the same size and class as A. Each element of the output B is computed using double-precision floating point. If A is an integer or logical array, then output elements that exceed the range of the integer type are truncated, and fractional values are rounded. B = imfilter(A, H, option1, option2,...) performs multidimensional filtering according to the specified options. Option arguments can have the following values. Boundary Options Option Description X Input array values outside the bounds of the array are implicitly assumed to have the value X. When no boundary option is specified, imfilter uses X = 0. 'symmetric' Input array values outside the bounds of the array are computed by mirror-reflecting the array across the array border. 'replicate' Input array values outside the bounds of the array are assumed to equal the nearest array border value. 'circular' Input array values outside the bounds of the array are computed by implicitly assuming the input array is periodic. 3-363 imfilter Output Size Options Option Description 'same' The output array is the same size as the input array. This is the default behavior when no output size options are specified. 'full' The output array is the full filtered result, and so is larger than the input array. Correlation and Convolution Options Option Description 'corr' imfilter performs multidimensional filtering using correlation, which is the same way that filter2 performs filtering. When no correlation or convolution option is specified, imfilter uses correlation. 'conv' imfilter performs multidimensional filtering using convolution. N-D convolution is related to N-D correlation by a reflection of the filter matrix. Tips On Intel architecture processors, imfilter can take advantage of the Intel Integrated Performance Primitives (Intel IPP) library, thus accelerating its execution time. The Intel IPP library is activated only if A and H are both two-dimensional and A is of class uint8, uint16, int16, single, or double. When the Intel IPP library is used, imfilter has different rounding behavior on some processors. Normally, when A is an integer class, filter outputs such as 1.5, 4.5, etc are rounded away from zero. However, when the Intel IPP library is used, these values are rounded toward zero. 3-364 imfilter Also, a special case exists if A is of class single or double, your input image contains NaN values, and your filtering kernel contains zero values. In this situation, you will receive different results if the Intel IPP library is enabled versus if it is not enabled. If you write code that depends on output values in the same neighborhood as NaN values in an input image, be aware that your code may behave differently on different machines, depending on the availability of the Intel IPP library. To disable the Intel IPP library, use this command: iptsetpref('UseIPPL', false) Example This example shows the different results obtained with the Intel IPP library enabled versus not enabled in the special case when you are filtering an array containing NaN elements with a filter containing zero values. First, consider the case in which the Intel IPP library is enabled (the default case). A = [2 2 2 2; 2 NaN 2 2; 2 2 2 2; 2 2 2 2]; h = [1 0; 0 1]; imfilter(A, h) ans = NaN NaN 4 2 NaN NaN 4 2 4 4 4 2 2 2 2 2 Now, compare this result to that obtained when you disable the Intel IPP library. iptsetpref('UseIPPL', false); imfilter(A, h) 3-365 imfilter ans = NaN 4 4 2 4 NaN 4 2 4 4 4 2 2 2 2 2 As you can see, your output is not the same. Examples Read a color image into the workspace and view it. originalRGB = imread('peppers.png'); imshow(originalRGB) Original Image Create a filter, h, that can be used to approximate linear camera motion. h = fspecial('motion', 50, 45); Apply the filter, using imfilter, to the image originalRGB to create a new image, filteredRGB. filteredRGB = imfilter(originalRGB, h); 3-366 imfilter figure, imshow(filteredRGB) Filtered Image Note that imfilter is more memory efficient than some other filtering operations in that it outputs an array of the same data type as the input image array. In this example, the output is an array of uint8. whos Name filteredRGB h originalRGB Size 384x512x3 37x37 384x512x3 Bytes 589824 10952 589824 Class Attributes uint8 double uint8 Specify the replicate boundary option. boundaryReplicateRGB = imfilter(originalRGB, h, 'replicate'); figure, imshow(boundaryReplicateRGB) 3-367 imfilter Image with Replicate Boundary See Also 3-368 conv2 | convn | filter2 | fspecial | ippl imfindcircles Purpose Find circles using circular Hough transform Syntax centers = imfindcircles(A,radius) [centers,radii] = imfindcircles(A,radiusRange) [centers,radii,metric] = imfindcircles(A,radiusRange) [centers,radii,metric] = imfindcircles( ___ ,Name,Value) Description centers = imfindcircles(A,radius) finds the circles in image A whose radii are approximately equal to radius. The output, centers, is a two-column matrix containing the x,y coordinates of the circles centers in the image. [centers,radii] = imfindcircles(A,radiusRange) finds circles with radii in the range specified by radiusRange. The additional output argument, radii, contains the estimated radii corresponding to each circle center in centers. [centers,radii,metric] = imfindcircles(A,radiusRange) also returns a column vector, metric, containing the magnitudes of the accumulator array peaks for each circle (in descending order). The rows of centers and radii correspond to the rows of metric. [centers,radii,metric] = imfindcircles( ___ ,Name,Value) specifies additional options with one or more Name,Value pair arguments, using any of the previous syntaxes. Input Arguments A - Input image grayscale image | truecolor image | binary image Input image is the image in which to detect circular objects, specified as a grayscale, truecolor, or binary image. Data Types single | double | int16 | uint8 | uint16 | logical radius - Circle radius 3-369 imfindcircles scalar integer Circle radius is the approximate radius of the circular objects you want to detect, specified as a scalar integer of any numeric type. Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 radiusRange - Range of radii two-element vector of integers Range of radii for the circular objects you want to detect, specified as a two-element vector, [rmin rmax], of integers of any numeric type. Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 Name-Value Pair Arguments Specify optional comma-separated pairs of Name,Value arguments, where Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN. Example: 'ObjectPolarity','bright' specifies bright circular objects on a dark background. ObjectPolarity - Object polarity 'bright' (default) | 'dark' Object polarity indicates whether the circular objects are brighter or darker than the background, specified as the comma-separated pair consisting of 'ObjectPolarity' and either of the text strings in the following table. 3-370 imfindcircles 'bright' The circular objects are brighter than the background. 'dark' The circular objects are darker than the background. Example: 'ObjectPolarity','bright' specifies bright circular objects on a dark background. Method - Computation method 'PhaseCode' (default) | 'TwoStage' Computation method is the technique used to compute the accumulator array, specified as the comma-separated pair consisting of 'Method' and either of the text strings in the following table. 'PhaseCode' Atherton and Kerbyson’s [1] phase coding method . This is the default. 'TwoStage' The method used in two-stage circular Hough transform [2], [3]. Example: 'Method','PhaseCode' specifies the Atherton and Kerbyson’s phase coding method. Sensitivity - Sensitivity factor nonnegative scalar between 0 and 1 | 0.85 (default) Sensitivity factor is the sensitivity for the circular Hough transform accumulator array, specified as the comma-separated pair consisting of 'Sensitivity' and a nonnegative scalar value in the range [0,1]. As you increase the sensitivity factor, imfindcircles detects more circular objects, including weak and partially obscured circles. Higher sensitivity values also increase the risk of false detection. Example: 'Sensitivity',0.3 sets the sensitivity factor to 0.3. EdgeThreshold - Edge gradient threshold nonnegative scalar between 0 and 1 3-371 imfindcircles Edge gradient threshold sets the gradient threshold for determining edge pixels in the image, specified as the comma-separated pair consisting of 'EdgeThreshold' and a nonnegative scalar value in the range [0,1]. Specify 0 to set the threshold to zero-gradient magnitude. Specify 1 to set the threshold to the maximum gradient magnitude. imfindcircles detects more circular objects (with both weak and strong edges) when you set the threshold to a lower value. It detects fewer circles with weak edges as you increase the value of the threshold. By default, imfindcircles chooses the edge gradient threshold automatically using the function graythresh. Example: 'EdgeThreshold',0.5 sets the edge gradient threshold to 0.5. Output Arguments centers - Coordinates of circle centers two-column matrix Coordinates of the circle centers, returned as a P-by-2 matrix containing the x-coordinates of the circle centers in the first column and the y-coordinates in the second column. The number of rows, P, is the number of circles detected. centers is sorted based on the strength of the circles. radii - Estimated radii column vector The estimated radii for the circle centers, returned as a column vector. The radius value at radii(j) corresponds to the circle centered at centers(j,:). metric - Circle strengths column vector Circle strengths is the relative strengths for the circle centers, returned as a vector. The value at metric(j) corresponds to the circle with radius radii(j) centered at centers(j,:). 3-372 imfindcircles Tips • Specify a relatively small radiusRange for better accuracy. A good rule of thumb is to choose radiusRange such that rmax < 3*rmin and (rmax-rmin) < 100. • The accuracy of imfindcircles is limited when the value of radius (or rmin) is less than 10. • The radius estimation step is typically faster if you use the (default) 'PhaseCode' method instead of 'TwoStage'. • Both computation methods, 'PhaseCode' and 'TwoStage' are limited in their ability to detect concentric circles. The results for concentric circles can vary depending on the input image. • imfindcircles does not find circles with centers outside the domain of the image. • imfindcircles preprocesses binary (logical) images to improve the accuracy of the result. It converts truecolor images to grayscale using the function rgb2gray before processing them. Examples Detection of Five Strongest Circles in an Image Read the image into the workspace and display it. A = imread('coins.png'); imshow(A) 3-373 imfindcircles Find all the circles with radius r such that 15 ≤ r ≤ 30. [centers, radii, metric] = imfindcircles(A,[15 30]); Retain the five strongest circles according to the metric values. centersStrong5 = centers(1:5,:); radiiStrong5 = radii(1:5); metricStrong5 = metric(1:5); Draw the five strongest circle perimeters. viscircles(centersStrong5, radiiStrong5,'EdgeColor','b'); 3-374 imfindcircles Detection of Bright and Dark Circles in an Image Read the image into the workspace and display it. A = imread('circlesBrightDark.png'); imshow(A) 3-375 imfindcircles Define the radius range. Rmin = 30; Rmax = 65; Find all the bright circles in the image within the radius range. [centersBright, radiiBright] = imfindcircles(A,[Rmin Rmax],'ObjectPolarit Find all the dark circles in the image within the radius range. [centersDark, radiiDark] = imfindcircles(A,[Rmin Rmax],'ObjectPolarity',' Plot bright circles in blue. 3-376 imfindcircles viscircles(centersBright, radiiBright,'EdgeColor','b'); Plot dark circles in dashed red boundaries. viscircles(centersDark, radiiDark,'LineStyle','--'); 3-377 imfindcircles Algorithm Function imfindcircles uses a Circular Hough Transform (CHT) based algorithm for finding circles in images. This approach is used because of its robustness in the presence of noise, occlusion and varying illumination. The CHT is not a rigorously specified algorithm, rather there are a number of different approaches that can be taken in its implementation. However, by and large, there are three essential steps which are common to all. 1 Accumulator Array Computation. 3-378 imfindcircles Foreground pixels of high gradient are designated as being candidate pixels and are allowed to cast ‘votes’ in the accumulator array. In a classical CHT implementation, the candidate pixels vote in pattern around them that forms a full circle of a fixed radius. Figure 1a shows an example of a candidate pixel lying on an actual circle (solid circle) and the classical CHT voting pattern (dashed circles) for the candidate pixel. 3-379 imfindcircles Figure 1: classical CHT voting pattern 3-380 imfindcircles 2 Center Estimation The votes of candidate pixels belonging to an image circle tend to accumulate at the accumulator array bin corresponding to the circle’s center. Therefore, the circle centers are estimated by detecting the peaks in the accumulator array. Figure 1b shows an example of the candidate pixels (solid dots) lying on an actual circle (solid circle), and their voting patterns (dashed circles) which coincide at the center of the actual circle. 3 Radius Estimation If the same accumulator array is used for more than one radius value, as is commonly done in CHT algorithms, radii of the detected circles have to be estimated as a separate step. Function imfindcircles provides two algorithms for finding circles in images: Phase-Coding (default) and Two-Stage. Both share some common computational steps, but each has its own unique aspects as well. The common computational features shared by both algorithms are as follow: • Use of 2-D Accumulator Array: The classical Hough Transform requires a 3-D array for storing votes for multiple radii, which results in large storage requirements and long processing times. Both the Phase-Coding and Two-Stage methods solve this problem by using a single 2-D accumulator array for all the radii. Although this approach requires an additional step of radius estimation, the overall computational load is typically lower, especially when working over large radius range. This is a widely adopted practice in modern CHT implementations. • Use of Edge Pixels 3-381 imfindcircles Overall memory requirements and speed is strongly governed by the number of candidate pixels. To limit their number, the gradient magnitude of the input image is threshold so that only pixels of high gradient are included in tallying votes. • Use of Edge Orientation Information: Another way to optimize performance is to restrict the number of bins available to candidate pixels. This is accomplished by utilizing locally available edge information to only permit voting in a limited interval along direction of the gradient (Figure 2). Figure 2: Voting mode: multiple radii, along direction of the gradient 3-382 imfindcircles rmin Minimum search radius rmax Maximum search radius ractual Radius of the circle that the candidate pixel belongs to Center of the circle of radius rmin cmin cmax cactual Center of the circle of radius rmax Center of the circle of radius ractual The two CHT methods employed by function imfindcircles fundamentally differ in the manner by which the circle radii are computed. • Two-Stage Radii are explicitly estimated utilizing the estimated circle centers along with image information. The technique is based on computing radial histograms; see references 1 & 2 for a detailed explanation. • Phase-Coding The key idea in Phase Coding is the use of complex values in the accumulator array with the radius information encoded in the phase of the array entries. The votes cast by the edge pixels contain information not only about the possible center locations but also about the radius of the circle associated with the center location. Unlike the Two-Stage method where radius has to be estimated explicitly using radial histograms, in Phase Coding the radius can be estimated by simply decoding the phase information from the estimated center location in the accumulator array. (see reference 3). References [1] T.J Atherton, D.J. Kerbyson. "Size invariant circle detection." Image and Vision Computing. Volume 17, Number 11, 1999, pp. 795-803. [2] H.K Yuen, .J. Princen, J. Illingworth, and J. Kittler. "Comparative study of Hough transform methods for circle finding." Image and Vision Computing. Volume 8, Number 1, 1990, pp. 71–77. 3-383 imfindcircles [3] E.R. Davies, Machine Vision: Theory, Algorithms, Practicalities. Chapter 10. 3rd Edition. Morgan Kauffman Publishers, 2005, See Also 3-384 hough | houghpeaks | houghlines | viscircles imfreehand Purpose Create draggable freehand region Syntax h = imfreehand h = imfreehand(hparent) h = imfreehand(...,param1, val1,...) Description h = imfreehand begins interactive placement of a freehand region of interest on the current axes. The function returns h, a handle to an imfreehand object. A freehand region of interest can be dragged interactively using the mouse and supports a context menu that controls aspects of its appearance and behavior. See “Interactive Behavior” on page 3-386. h = imfreehand(hparent) begins interactive placement of a freehand region of interest on the object specified by hparent. hparent specifies the HG parent of the freehand region graphics, which is typically an axes, but can also be any other object that can be the parent of an hggroup. h = imfreehand(...,param1, val1,...) creates a freehand ROI, specifying parameters and corresponding values that control the behavior of the tool. The following table lists the parameters available. Parameter names can be abbreviated, and case does not matter. Parameter Description 'Closed' Scalar logical that controls whether the freehand region is closed. When set to true (the default), imfreehand draws a straight line to connect the endpoints of the freehand line to create a closed region. If set to false, imfreehand leaves the region open. 'PositionConstraintFcn'Function handle specifying the function that is called whenever the freehand region is dragged using the mouse. Use this parameter to control where the freehand region can be dragged. See the help for 3-385 imfreehand Parameter Description the setPositionConstraintFcn method for information about valid function handles. Interactive Behavior When you call imfreehand with an interactive syntax, the pointer when positioned over an image. Click and changes to a cross hairs drag the mouse to draw the freehand region. By default, imfreehand draws a straight line connecting the last point you drew with the first point, but you can control this behavior using the 'Closed' parameter. The following figure illustrates a freehand region with its context menu. Freehand region Freehand tool context menu The following table lists the interactive features supported by imfreehand. 3-386 imfreehand Interactive Behavior Description Moving the region. Move the pointer inside the freehand region. The pointer changes to a fleur shape . Click and hold the left mouse button to move the region. Changing the color used to draw the region. Move the pointer inside the freehand region. Right-click and select Set Color from the context menu. Retrieving the current position of the freehand region. Move the pointer inside the freehand region. Right-click and select Copy Position from the context menu. imfreehand copies an n-by-2 array of coordinates on the boundary of the ROI to the clipboard.. Methods The imfreehand object supports the following methods. Type methods imfreehand to see a complete list of all methods. addNewPositionCallback — Add new-position callback to ROI object See imroi for information. createMask — Create mask within image See imroi for information. delete — Delete ROI object See imroi for information. getColor — Get color used to draw ROI object See imroi for information. getPosition — Return current position of freehand region pos = getPosition(h) returns the current position of the freehand region h. The returned position, pos, is an N-by-2 array [X1 Y1;...;XN YN]. 3-387 imfreehand getPositionConstraintFcn — Return function handle to current position constraint function See imroi for information. removeNewPositionCallback — Remove new-position callback from ROI object. See imroi for information. resume — Resume execution of MATLAB command line See imroi for information. setClosed — Set geometry of freehand region setClosed(h,TF) sets the geometry of the freehand region h. TF is a logical scalar. True means that the freehand region is closed. False means that the freehand region is open. setColor — Set color used to draw ROI object See imroi for information. setConstrainedPosition — Set ROI object to new position See imroi for information. setPositionConstraintFcn — Set position constraint function of ROI object. See imroi for information. wait — Block MATLAB command line until ROI creation is finished See imroi for information. Tips If you use imfreehand with an axes that contains an image object, and do not specify a position constraint function, users can drag the freehand region outside the extent of the image and lose the freehand region. When used with an axes created by the plot function, the axes limits automatically expand to accommodate the movement of the freehand region. Examples Interactively place a closed freehand region of interest by clicking and dragging over an image. figure, imshow('pout.tif'); h = imfreehand(gca); 3-388 imfreehand Interactively place a freehand region by clicking and dragging. Use the wait method to block the MATLAB command line. Double-click on the freehand region to resume execution of the MATLAB command line. figure, imshow('pout.tif'); h = imfreehand; position = wait(h); See Also imellipse | imline | impoint | impoly | imrect | iptgetapi | makeConstrainToRectFcn 3-389 imfuse Purpose Composite of two images Syntax C = imfuse(A,B) C = imfuse(A,B,method) C = imfuse( ___ ,Name,Value) Description C = imfuse(A,B) creates a composite image from two images, A and B. If A and B are different sizes, the smaller dimensions are padded with zeros so that both images are the same size before creating the composite. C = imfuse(A,B,method) uses the visualization method specified by method. C = imfuse( ___ ,Name,Value) specifies additional options with one or more Name,Value pair arguments, using any of the previous syntaxes. Input Arguments A,B - Input images grayscale images | truecolor images | binary images Input images to be combined into a composite image, specified as any combination of grayscale, truecolor, or binary images. Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical method - Visualization method 'falsecolor' (default) | 'blend' | 'diff' | 'montage' Visualization method for creating the composite image, specified as one of the text strings in the following table. 3-390 imfuse Method Description 'falsecolor' Creates a composite RGB image showing A and B overlaid in different color bands. Gray regions in the composite image show where the two images have the same intensities. Magenta and green regions show where the intensities are different. This is the default method. 'blend' Overlays A and B using alpha blending. 'diff' Creates a difference image from A and B. 'montage' Places A and B next to each other in the same image. Example: C = imfuse(A,B,'montage') places A and B next to each other in the output image. Name-Value Pair Arguments Specify optional comma-separated pairs of Name,Value arguments, where Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN. Example: 'Scaling','joint' scales the intensity values of A and B together as a single data set. Scaling - Image data scaling option 'independent' (default) | 'joint' | 'none' Image data scaling option that controls the intensity scaling of the pixels representing the input images in the output image, specified as a comma-separated pair consisting of 'Scaling' and 'independent', 'joint', or 'none'. These options are described in the table below. 3-391 imfuse 'independent' Scales the intensity values of A and B independently when C is created. 'joint' Scales the intensity values in the images jointly as if they were together in the same image. This option is useful when you want to visualize registrations of monomodal images, where one image contains fill values that are outside the dynamic range of the other image. 'none' No additional scaling. ColorChannels - Output color channel for each input image [R G B] | `red-cyan' | `green-magenta' (default) Output color channel for each input image, specified as the comma-separated pair consisting of `ColorChannels' and one of the text strings in the following table. `ColorChannels' can only be used with the 'falsecolor' visualization method. 3-392 [R G B] A three element vector that specifies which image to assign to the red, green, and blue channels. The R, G, and B values must be 1 (for the first input image), 2 (for the second input image), and 0 (for neither image). 'red-cyan' A shortcut for the vector [1 2 2], which is suitable for red/cyan stereo anaglyphs. 'green-magenta' A shortcut for the vector [1 2 2], which is a high contrast option, ideal for people with many kinds of color blindness. imfuse Output Arguments C - Fused image grayscale image | truecolor image | binary image Fused image that is a composite of the input images, returned as a grayscale, truecolor, or binary image. Tips • Use imfuse to create composite visualizations that you can save to a file. Use imshowpair to display composite visualizations to the screen. Examples Create Overlay Image of Two Images Load an image into the workspace. Create a copy and apply a rotation and offset. A = imread('cameraman.tif'); B = imrotate(A,5,'bicubic','crop'); Create blended overlay image, scaling the intensities of A and B jointly as a single data set. C = imfuse(A,B,'blend','Scaling','joint'); Save the resulting image as a .png file. imwrite(C,'my_blend_overlay.png'); See Also imregister | imshowpair | imtransform 3-393 imgca Purpose Get handle to current axes containing image Syntax h = imgca h = imgca(hfig) Description h = imgca returns the handle of the current axes that contains an image. The current axes can be in a regular figure window or in an Image Tool window. If no figure contains an axes that contains an image, imgca creates a new axes. h = imgca(hfig) returns the handle to the current axes that contains an image in the specified figure. (It need not be the current figure.) Note imgca can be useful in returning the handle to the Image Tool axes. Because the Image Tool turns graphics object handle visibility off, you cannot retrieve a handle to the tool figure using gca. Examples Compute the centroid of each coin, and superimpose its location on the image. View the results using imtool and imgca: I = imread('coins.png'); figure, imshow(I) Original Image bw = im2bw(I, graythresh(getimage)); 3-394 imgca figure, imshow(bw) Binary Image bw2 = imfill(bw,'holes'); s = regionprops(bw2, 'centroid'); centroids = cat(1, s.Centroid); Display original image I and superimpose centroids: imtool(I) hold(imgca,'on') plot(imgca,centroids(:,1), centroids(:,2), 'r*') hold(imgca,'off') Centroids of Coins See also gca, gcf, imgcf, imhandles 3-395 imgcf Purpose Get handle to current figure containing image Syntax hfig = imgcf Description hfig = imgcf returns the handle of the current figure that contains an image. The figure may be a regular figure window that contains at least one image or an Image Tool window. If none of the figures currently open contains an image, imgcf creates a new figure. Note imgcf can be useful in getting the handle to the Image Tool figure window. Because the Image Tool turns graphics object handle visibility off, you cannot retrieve a handle to the tool figure using gcf. Examples imtool rice.png cmap = copper(256); set(imgcf,'Colormap',cmap) See also gca, gcf, imgca, imhandles 3-396 imgetfile Purpose Open Image dialog box Syntax [filename, user_canceled] = imgetfile Description [filename, user_canceled] = imgetfile displays the Open Image dialog box. You can use this dialog box in imaging applications to get the name of the image file a user wants to open. The Open Image dialog box includes only files using supported image file formats (listed in imformats) and DICOM files. When the user selects a file and clicks Open, imgetfile returns the full path of the file in the return value filename and sets the user_canceled return value to FALSE. If the user clicks Cancel, imgetfile returns an empty string in filename and sets the user_canceled return value to TRUE. Note The Open Image dialog box is modal; it blocks the MATLAB command line until the user responds. See Also imformats | imtool | uigetfile 3-397 imgradient Purpose Gradient magnitude and direction of an image Syntax [Gmag,Gdir] = imgradient(I) [Gmag,Gdir] = imgradient(I,method) [Gmag,Gdir] = imgradient(Gx,Gy) Description [Gmag,Gdir] = imgradient(I) returns the gradient magnitude, Gmag, and the gradient direction, Gdir, for input image I. • Gmag and Gdir are the same size as input image I • Gdir contains angles in degrees within the range [-180 180] [Gmag,Gdir] = imgradient(I,method) returns the gradient magnitude and direction using specified method. [Gmag,Gdir] = imgradient(Gx,Gy) returns the gradient magnitude and direction using directional gradients. Input Arguments I - Input image grayscale image | binary image Input image, specified as a grayscale or binary image. Data Types single | double | int8 | int32 | uint8 | uint16 | uint32 | logical method - Gradient operator `Sobel' (default) | `Prewitt' | 'CentralDifference' | 'IntermediateDifference' | `Roberts' Gradient operator, specified as one of the text strings `Sobel', `Prewitt', 'CentralDifference', 'IntermediateDifference', or `Roberts'. • Central difference gradient (dI/dx = (I(x+1) - I(x-1))/ 2 ) • Intermediate difference gradient (dI/dx = I(x+1) - I(x)) 3-398 imgradient Data Types char Gx, Gy - Directional gradients along x-axis (horizontal) and y-axis (vertical) matrix Directional gradients along x-axis (horizontal) and y-axis (vertical), specified as non-sparse matrices equal in size to image I. Typically they are obtained from function imgradientxy which returns them as output arguments. Data Types single | double | int8 | int32 | uint8 | uint16 | uint32 Output Arguments Gmag - Gradient magnitude matrix Gradient magnitude, returned as a non-sparse matrix the same size as image I. Gmag is of class double, unless the input image I to function imgradientxy is of class single, in which case it is of class single. Data Types double | single Gdir - Gradient direction matrix Gradient direction, returned as a non-sparse matrix the same size as image I. Gdir contains angles in degrees within the range [-180 180] measured counterclockwise from the positive x-axis (horizontal). Gdir is of class double, unless the input image I to function gradientxy is of class single, in which case it is of class single. Data Types double | single 3-399 imgradient Examples Display gradient magnitude and gradient direction Read image and compute gradient magnitude and gradient direction using Prewitt’s gradient operator. I = imread('coins.png'); [Gmag, Gdir] = imgradient(I,'prewitt'); figure imshowpair(Gmag, Gdir, 'montage'); title('Gradient Magnitude, Gmag (left), and Gradient Direction, Gdir (rig axis off; 3-400 imgradient Display directional gradients in addition to gradient magnitude and direction Read in image and return directional gradients, Gx and Gx, as well as gradient magnitude and direction, Gmag and Gdir, utilizing default Sobel gradient operator. I = imread('coins.png'); [Gx, Gy] = imgradientxy(I); [Gmag, Gdir] = imgradient(Gx, Gy); figure; imshowpair(Gmag, Gdir, 'montage'); axis off; title('Gradient Magnitude (Gmag) and Gradient Direction (Gdir) using S figure; imshowpair(Gx, Gy, 'montage'); axis off; title('Directional Gradients, Gx and Gy, using Sobel method') 3-401 imgradient Tips • When applying the gradient operator at the boundaries of the image, values outside the bounds of the image are assumed to equal the nearest image border value. • Algorithms The algorithmic approach taken in imgradient for each of the listed gradient methods is to first compute directional gradients,Gx and Gy, with respect to the x-axis and y-axis. The x-axis is defined along the columns going right and the y-axis is defined along the rows going down. The gradient magnitude and direction are then computed from their orthogonal components Gx and Gy. See Also imgradientxy | edge | fspecial 3-402 imgradientxy Purpose Directional gradients of an image Syntax [Gx,Gy] = imgradientxy(I) [Gx,Gy] = imgradientxy(I,method) Description [Gx,Gy] = imgradientxy(I) returns the directional gradients, Gx and Gy. • Gx and Gy. are the same size as input image I • When applying the gradient operator at the boundaries of the image, values outside the bounds of the image are assumed to equal the nearest image border value. [Gx,Gy] = imgradientxy(I,method) returns the directional gradients using specified method Input Arguments I - Input image grayscale image | binary image Input image, specified as a grayscale or binary image. Data Types single | double | int8 | int32 | uint8 | uint16 | uint32 | logical method - Gradient operator `Sobel' (default) | `Prewitt' | 'CentralDifference' | 'IntermediateDifference' Gradient operator, specified as one of the text strings `Sobel', `Prewitt', 'CentralDifference', or 'IntermediateDifference'. • Central difference gradient (dI/dx = (I(x+1) - I(x-1))/ 2 ) • Intermediate difference gradient (dI/dx = I(x+1) - I(x)) Data Types char 3-403 imgradientxy Output Arguments Gx, Gy - Directional gradients along x-axis (horizontal) and y-axis (vertical) matrix Directional gradients along x-axis (horizontal) and y-axis (vertical), returned as non-sparse matrices equal in size to image I. The output matrices are of class double, unless the input image is of class single, in which case they are of class single. Data Types single | double Examples Display directional gradients Read image and compute gradient magnitude and gradient direction using Prewitt’s gradient operator. I = imread('coins.png'); [Gx, Gy] = imgradientxy(I,'prewitt'); figure imshowpair(Gx, Gy, 'montage'); title('Directional Gradients: x-direction, Gx (left), y-direction, Gy (r axis off; 3-404 imgradientxy Display gradient magnitude and direction in addition to directional gradients Read in image and return directional gradients, Gx and Gx, as well as gradient magnitude and direction, Gmag and Gdir, utilizing default Sobel gradient operator. I = imread('coins.png'); [Gx, Gy] = imgradientxy(I); [Gmag, Gdir] = imgradient(Gx, Gy); figure; imshowpair(Gmag, Gdir, 'montage'); axis off; title('Gradient Magnitude, Gmag (left), and Gradient Direction, Gdir ( figure; imshowpair(Gx, Gy, 'montage'); axis off; title('Directional Gradients, Gx and Gy, using Sobel method') 3-405 imgradientxy 3-406 imgradientxy Tips • When applying the gradient operator at the boundaries of the image, values outside the bounds of the image are assumed to equal the nearest image border value. Algorithms The algorithmic approach is to compute directional gradients,Gx and Gy, with respect to the x-axis and y-axis. The x-axis is defined along the columns going right and the y-axis is defined along the rows going down. See Also edge | fspecial | imgradient 3-407 imhandles Purpose Get all image handles Syntax himage = imhandles(h) Description himage = imhandles(h) takes a graphics handle h as an input and returns all of the image handles whose ancestor is h. h can be an array of valid figure, axes, image, or uipanel handles. himage is an array of image handles. imhandles ignores colorbars in h and does not include its handle in himage. Note imhandles errors if the image objects in himage do not have the same Examples Return the handle to the image object in the current axes. figure as their parent. figure, imshow('moon.tif'); himage = imhandles(gca) Display two images in a figure and uses imhandles to get handles to both of the image objects in the figure. subplot(1,2,1), imshow('autumn.tif'); subplot(1,2,2), imshow('glass.png'); himages = imhandles(gcf) See Also 3-408 imgca | imgcf imhist Purpose Display histogram of image data Syntax imhist(I) imhist(I, n) imhist(X, map) [counts,x] = imhist(...) Description imhist(I) displays a histogram for the image I above a grayscale colorbar. The number of bins in the histogram is specified by the image type. If I is a grayscale image, imhist uses a default value of 256 bins. If I is a binary image, imhist uses two bins. imhist(I, n) displays a histogram where n specifies the number of bins used in the histogram. n also specifies the length of the colorbar. If I is a binary image, n can only have the value 2. imhist(X, map) displays a histogram for the indexed image X. This histogram shows the distribution of pixel values above a colorbar of the colormap map. The colormap must be at least as long as the largest index in X. The histogram has one bin for each entry in the colormap. [counts,x] = imhist(...) returns the histogram counts in counts and the bin locations in x so that stem(x,counts) shows the histogram. For indexed images, imhist returns the histogram counts for each colormap entry; the length of counts is the same as the length of the colormap. Note The maximum value on the y-axis may be automatically reduced, so outlier spikes do not dominate. To show the full range of y-axis values, call imhist with the following syntax: [counts,x] = imhist(...) Then call stem: stem(x,counts) 3-409 imhist Tips For intensity images, the n bins of the histogram are each half-open intervals of width A/(n−1). In particular, for intensity images that are not int16, the pth bin is the half-open interval A( p − 1.5) A( p − 0.5) ≤x< , (n − 1) (n − 1) where x is the intensity value. For int16 intensity images, the pth bin is the half-open interval A( p − 1.5) A( p − 0.5) − 32768, − 32768 ≤ x < (n − 1) (n − 1) where x is the intensity value. The scale factor A depends on the image class. A is 1 if the intensity image is double or single, A is 255 if the intensity image is uint8, and A is 65535 if the intensity image is uint16 or int16. Class Support An input intensity image can be of class uint8, int8, uint16, int16, uint32, int32, single, double, or logical. An input indexed image can be of class uint8, uint16, single, double, or logical. Examples I = imread('pout.tif'); imhist(I) 3-410 imhist 1600 1400 1200 1000 800 600 400 200 0 0 See Also 50 100 150 200 250 histeq | hist 3-411 imhistmatch Purpose Adjust histogram of image to match N-bin histogram of reference image Syntax B = imhistmatch(A,Ref) B = imhistmatch(A,Ref,N) [B,hgram] = imhistmatch( ___ ) Description B = imhistmatch(A,Ref) image A is transformed so that the histogram of the returned image B approximately matches the histogram of reference image Ref built with 64 (default value) equally spaced histogram bins. The returned image B will have no more than 64 discrete levels. • Images A and Ref can be any of the permissible data types. • If both A and Ref are truecolor RGB images, then each color channel of A is matched independently to the corresponding color channel of Ref. • If A is a truecolor RGB image and Ref is a grayscale image, then each channel of A is matched against the single histogram derived from Ref. • If A is a grayscale image, then Ref must also be a grayscale image. • Images A and Ref need not be equal in size. B = imhistmatch(A,Ref,N) image A is transformed using a histogram derived from image Ref consisting of N equally spaced bins within the appropriate range for the given image data type. The returned image B will have no more than N discrete levels. The default value for N is 64. • If the data type of the image is either single or double, then the histogram range is [0, 1]. • If the data type of the image is uint8, then the histogram range is [0, 255] • If the data type of the image is uint16, then the histogram range is [0, 65535] 3-412 imhistmatch • If the data type of the image is int16, then the histogram range is [-32768, 32767] [B,hgram] = imhistmatch( ___ ) returns hgram, a vector of length N, containing the histogram counts derived from reference image Ref, using either of the previous two syntaxes. Input Arguments A - Input image truecolor image | grayscale image Input image to be transformed, specified as a truecolor or grayscale image. The returned image will take the data type class of the input image. Data Types single | double | int16 | uint8 | uint16 Ref - Reference image whose histogram is the reference histogram truecolor image | grayscale image Reference image whose histogram is the reference histogram, specified as truecolor or grayscale image. The reference image provides the equally spaced N bin reference histogram which output image B is trying to match. Data Types single | double | int16 | uint8 | uint16 N - Number of equally spaced bins in reference histogram 64 (default) | scalar Number of equally spaced bins in reference histogram, specified as a scalar value. In addition to specifying the number of equally spaced bins in the histogram for image Ref, N also represents the upper limit of the number of discrete data levels present in output image B. Data Types double 3-413 imhistmatch Output Arguments B - Output image truecolor RGB image | grayscale image Output image, returned as a truecolor or grayscale image. The output image is derived from image A whose histogram is an approximate match to the histogram of input image Ref built with N equally spaced bins. Image B is of the same size and data type as input image A. Input argument N represents the upper limit of the number of discrete levels contained in image B. Data Types single | double | int16 | uint8 | uint16 hgram - Histogram counts derived from reference image Ref vector | matrix Histogram counts derived from reference image Ref, specified as a vector or matrix. When Ref is a truecolor image, hgram is a 3xN matrix. When Ref is a grayscale image, hgram is a 1xN vector. Data Types double Examples Histogram matching of aerial images These aerial images, taken at different times, represent overlapping views of the same terrain in Concord, Massachusetts. This example demonstrates that input images A and Ref can be of different sizes and image types. Load both images. A = imread('concordaerial.png'); Ref = imread('concordorthophoto.png'); Querying for the size of the images reveals that both are different in size and type; image A is a truecolor RGB image, while image Ref is a grayscale image. Both images are of data type uint8. size(A) 3-414 imhistmatch ans = 2036 3060 3 size(Ref) ans = 2215 2956 Generate the histogram matched output image; each channel of A is matched against the single histogram of Ref built with 64 (default value) equally spaced bins. Output image B takes on the characteristics of image A; it is an RGB image whose size and data type is the same as image A. The number of distinct levels present in each RGB channel of image B is determined by the number of bins in the single aim histogram built from grayscale image Ref which in this case is 64. B = imhistmatch(A,Ref); 3-415 imhistmatch Multiple N values applied to RGB Images In this example, you will see the effect on output image B of varying N, the number of equally spaced bins in the aim histogram of image Ref, from its default value 64 to the maximum value of 256 for uint8 pixel data. The following images were taken with a digital camera and represent two different exposures of the same scene. A = imread('office_2.jpg'); Ref = imread('office_4.jpg'); % Dark Image % Reference image Image A, being the darker image, has a preponderance of its pixels in the lower bins. The reference image, Ref, is a properly exposed image and fully populates all of the available bins values in all three RGB channels: as shown in the table below, all three channels have 256 unique levels for 8–bit pixel values. 3-416 imhistmatch 3-417 imhistmatch Unique 8–bit level values in each RGB Channel Image A Image Ref Red Channel 205 256 Green Channel 193 256 Blue Channel 224 256 Output image B is generated using three different values of N: 64, 128 and 256. The objective of function imhistmatch is to transform image A such that the histogram of output image B is a match to the histogram of Ref built with N equally spaced bins. As a result, N represents the upper limit of the number of discrete data levels present in image B. [B64, hgram] = imhistmatch(A, Ref, 64); [B128, hgram] = imhistmatch(A, Ref, 128); [B256, hgram] = imhistmatch(A, Ref, 256); 3-418 imhistmatch 3-419 imhistmatch Unique 8–bit level values in each RGB Channel for N = [64 128 256] output Image B64 57 output image B128 101 output image B256 134 Green Channel 60 104 135 Blue Channel 58 104 136 Red Channel Note that as N increases, the number of levels in each RGB channel of output image B also increases. Histogram matching a 16–bit grayscale MRI image In this example, a 16 bit grayscale MRI image is loaded, darkened and histogram matched at two values of N. A 16–bit DICOM image of a knee imaged via MRI is loaded into the workspace. K = dicomread('knee1.dcm'); % read in original image K = dicomread('knee1.dcm'); % read in original 16-bit image LevelsK = unique(K(:)); % determine number of unique code values disp(['image K: # levels: ' num2str(length(LevelsK))]); disp(['max level = ' num2str( max(LevelsK) )]); disp(['min level = ' num2str( min(LevelsK) )]); image K: # levels = 448 max level = 473 min level = 0 Since it appears that all 448 discrete values are at low code values (darker), the image data will be scaled to span the entire 16-bit range of [0 65535] % Scale it to full 16-bit range 3-420 imhistmatch Kdouble = double(K); % cast uint16 to double kmult = 65535/(max(max(Kdouble(:)))); % full range multiplier Ref = uint16(kmult*Kdouble); % full range 16-bit reference image The reference image is darkened to yield the input A image argument to imhistmatch % build concave bow-shaped curve for darkening Reference image ramp = [0:65535]/65535; ppconcave = spline([0 .1 .50 .72 .87 1],[0 .025 .25 .5 .75 1]); Ybuf = ppval( ppconcave, ramp); Lut16bit = uint16( round( 65535*Ybuf ) ); % pass image Ref through LUT to darken image A = intlut(Ref,Lut16bit); The two images contain the same number of discrete code values, but differ in overall brightness. 3-421 imhistmatch Next, the histogram matched output image, B, is generated at two values of N. The first is the default value of 64, the second is the number of values present in image A of 448. B16bit64 = imhistmatch(A(:,:,1),Ref(:,:,1)); % default # bins: N = 64 N = length(LevelsA); % number of unique 16-bit code values in image B16bitUniq = imhistmatch(A(:,:,1),Ref(:,:,1),N); The following figure shows the 16 bit histograms of all four images; the y-axis scaling is the same for plots. 3-422 imhistmatch 3-423 imhistmatch Unique 16–bit code values in output B lmages Levels N B16bit64 63 64 B16bitUniq 222 448 N also represents the upper limit of discrete levels in the output image which is shown above; the number of levels increases from 63 to 222 when the number of histogram bins increases from 64 to 448. But note, in the above histogram plots, there are rapid fluctuations in adjacent histogram bins for the B image containing 222 levels, especially in the upper portion of the histogram range. By comparison, the 63 level B histogram has a relatively smooth and continuous progression of peaks in this region. Algorithms The objective of imhistmatch is to transform image A such the the histogram of image B matches the histogram derived from image Ref. It consists of N equally spaced bins which span the full range of the image data type. A consequence of matching histograms in this way is that N also represents the upper limit of the number of discrete data levels present in image B. An important behavioral aspect of this algorithm to note is that as N increases in value, the degree of rapid fluctuations between adjacent populated peaks in the histogram of image B tends to increase. This can be seen in the following histogram plots taken from the 16–bit grayscale MRI example. 3-424 imhistmatch An optimal value for N represents a trade-off between more output levels (larger values of N) while minimizing peak fluctuations in the histogram (smaller values of N). See Also histeq | imadjust | imhist 3-425 imhmax Purpose H-maxima transform Syntax I2 = imhmax(I,h) I2 = imhmax(I,h,conn) Description I2 = imhmax(I,h) suppresses all maxima in the intensity image I whose height is less than h, where h is a scalar. Regional maxima are connected components of pixels with a constant intensity value, and whose external boundary pixels all have a lower value. By default, imhmax uses 8-connected neighborhoods for 2-D images, and 26-connected neighborhoods for 3-D images. For higher dimensions, imhmax uses conndef(ndims(I),'maximal'). I2 = imhmax(I,h,conn) computes the H-maxima transform, where conn specifies the connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by- ...-by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. 3-426 imhmax Class Support I can be of any nonsparse numeric class and any dimension. I2 has the same size and class as I. Examples a = zeros(10,10); a(2:4,2:4) = 3; % maxima 3 higher than surround a(6:8,6:8) = 8; % maxima 8 higher than surround b = imhmax(a,4); % only the maxima higher than 4 survive. References [1] Soille, P., Morphological Image Analysis: Principles and Applications, Springer-Verlag, 1999, pp. 170-171. See Also conndef | imextendedmax | imhmin | imreconstruct | imregionalmax 3-427 imhmin Purpose H-minima transform Syntax I2 = imhmin(I,h) I2 = imhmin(I,h,conn) Description I2 = imhmin(I,h) suppresses all minima in I whose depth is less than h. I is a grayscale image and h is a scalar. Regional minima are connected components of pixels with a constant intensity value, and whose external boundary pixels all have a higher value. By default, imhmin uses 8-connected neighborhoods for 2-D images, and 26-connected neighborhoods for 3-D images. For higher dimensions, imhmin uses conndef(ndims(I),'maximal'). I2 = imhmin(I,h,conn) computes the H-minima transform, where conn specifies the connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by- ...-by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. 3-428 imhmin Class Support I can be of any nonsparse numeric class and any dimension. I2 has the same size and class as I. Examples Create a sample image with two regional minima. a = 10*ones(10,10); a(2:4,2:4) = 7; a(6:8,6:8) = 2 a = 10 10 10 10 10 10 10 10 10 10 10 7 7 7 10 10 10 10 10 10 10 7 7 7 10 10 10 10 10 10 10 7 7 7 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 2 2 2 10 10 10 10 10 10 10 2 2 2 10 10 10 10 10 10 10 2 2 2 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 Suppress all minima below a specified value. Note how the region with pixel valued 7 disappears in the transformed image. b = imhmin(a,4) b = 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 6 6 6 10 10 10 10 10 6 6 6 10 10 10 10 10 6 6 6 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 3-429 imhmin 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 References [1] Soille, P., Morphological Image Analysis: Principles and Applications, Springer-Verlag, 1999, pp. 170-171. See Also conndef | imextendedmin | imhmax | imreconstruct | imregionalmin 3-430 imimposemin Purpose Impose minima Syntax I2 = imimposemin(I,BW) I2 = imimposemin(I,BW,conn) Description I2 = imimposemin(I,BW) modifies the intensity image I using morphological reconstruction so it only has regional minima wherever BW is nonzero. BW is a binary image the same size as I. By default, imimposemin uses 8-connected neighborhoods for 2-D images and 26-connected neighborhoods for 3-D images. For higher dimensions, imimposemin uses conndef(ndims(I),'minimum'). I2 = imimposemin(I,BW,conn) specifies the connectivity, where conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can also be defined in a more general way for any dimension by using for conn a 3-by-3-by-...-by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. Class Support I can be of any nonsparse numeric class and any dimension. BW must be a nonsparse numeric array with the same size as I. I2 has the same size and class as I. 3-431 imimposemin Examples Modify an image so that it only has regional minima at one location. 1 Read an image and display it. This image is called the mask image. mask = imread('glass.png'); imshow(mask) 2 Create the marker image that will be used to process the mask image. The example creates a binary image that is the same size as the mask image and sets a small area of the binary image to 1. These pixels define the location in the mask image where a regional minimum will be imposed. marker = false(size(mask)); marker(65:70,65:70) = true; To show where these pixels of interest fall on the original image, this code superimposes the marker over the mask. The small white square marks the spot. This code is not essential to the impose minima operation. J = mask; J(marker) = 255; figure, imshow(J); title('Marker Image Superimposed on Mask'); 3-432 imimposemin 3 Impose the regional minimum on the input image using the imimposemin function. The imimposemin function uses morphological reconstruction of the mask image with the marker image to impose the minima at the specified location. Note how all the dark areas of the original image, except the marked area, are lighter. K = imimposemin(mask,marker); figure, imshow(K); 4 To illustrate how this operation removes all minima in the original image except the imposed minimum, compare the regional minima in the original image with the regional minimum in the processed image. These calls to imregionalmin return binary images that specify the locations of all the regional minima in both images. BW = imregionalmin(mask); figure, imshow(BW); 3-433 imimposemin title('Regional Minima in Original Image'); BW2 = imregionalmin(K); figure, imshow(BW2); title('Regional Minima After Processing'); Algorithms imimposemin uses a technique based on morphological reconstruction. See Also conndef | imreconstruct | imregionalmin 3-434 imlincomb Purpose Linear combination of images Syntax Z = imlincomb(K1,A1,K2,A2,...,Kn,An) Z = imlincomb(K1,A1,K2,A2,...,Kn,An,K) Z = imlincomb(...,output_class) Description Z = imlincomb(K1,A1,K2,A2,...,Kn,An) computes K1*A1 + K2*A2 + ... + Kn*An where K1, K2, through Kn are real, double scalars and A1, A2, through An are real, nonsparse, numeric arrays with the same class and size. Z has the same class and size as A1. Z = imlincomb(K1,A1,K2,A2,...,Kn,An,K) computes K1*A1 + K2*A2 + ... + Kn*An + K where imlincomb adds K, a real, double scalar, to the sum of the products of K1 through Kn and A1 through An. Z = imlincomb(...,output_class) lets you specify the class of Z. output_class is a string containing the name of a numeric class. When performing a series of arithmetic operations on a pair of images, you can achieve more accurate results if you use imlincomb to combine the operations, rather than nesting calls to the individual arithmetic functions, such as imadd. When you nest calls to the arithmetic functions, and the input arrays are of an integer class, each function truncates and rounds the result before passing it to the next function, thus losing accuracy in the final result. imlincomb computes each element of the output Z individually, in double-precision floating point. If Z is an integer array, imlincomb truncates elements of Z that exceed the range of the integer type and rounds off fractional values. On Intel architecture processors, imlincomb can take advantage of the Intel Integrated Performance Primitives (Intel IPP) library, thus accelerating its execution time. The Intel IPP library is activated only in the following cases: 3-435 imlincomb Z = imlincomb( 1.0, Z = imlincomb( 1.0, Z = imlincomb(-1.0, Z = imlincomb( 1.0 A1, 1.0, A2) A1,-1.0, A2) A1, 1.0, A2) , A1, K) where A1, A2, and Z are of class uint8, int16, or single and are of the same class. Examples Example 1 Scale an image by a factor of 2. I = imread('cameraman.tif'); J = imlincomb(2,I); imshow(J) Example 2 Form a difference image with the zero value shifted to 128. I = imread('cameraman.tif'); J = uint8(filter2(fspecial('gaussian'), I)); K = imlincomb(1,I,-1,J,128); % K(r,c) = I(r,c) - J(r,c) + 128 figure, imshow(K) Example 3 Add two images with a specified output class. I = imread('rice.png'); J = imread('cameraman.tif'); K = imlincomb(1,I,1,J,'uint16'); figure, imshow(K,[]) Example 4 To illustrate how imlincomb performs all the arithmetic operations before truncating the result, compare the results of calculating the average of two arrays, X and Y, using nested arithmetic functions and then using imlincomb. 3-436 imlincomb In the version that uses nested arithmetic functions, imadd adds 255 and 50 and truncates the result to 255 before passing it to imdivide. The average returned in Z(1,1) is 128. X Y Z Z = uint8([ 255 10 75; 44 225 100]); = uint8([ 50 20 50; 50 50 50 ]); = imdivide(imadd(X,Y),2) = 128 15 63 47 128 75 imlincomb performs the addition and division in double precision and only truncates the final result. The average returned in Z2(1,1) is 153. Z2 = imlincomb(.5,X,.5,Y) Z2 = 153 15 63 47 138 75 See Also imadd | imcomplement | imdivide | immultiply | imsubtract 3-437 imline Purpose Create draggable, resizable line Syntax h h h h H Description h = imline begins interactive placement of a line on the current axes. The function returns h, a handle to an imline object. The line has a = = = = = imline imline(hparent) imline(hparent, position) imline(hparent, x, y) imline(..., param1, val1,...) context menu associated with it that controls aspects of its appearance and behavior—see “Interactive Behavior” on page 3-439. Right-click on the line to access this context menu. h = imline(hparent) begins interactive placement of a line on the object specified by hparent. hparent specifies the HG parent of the line graphics, which is typically an axes but can also be any other object that can be the parent of an hggroup h = imline(hparent, position) creates a draggable, resizable line on the object specified by hparent. position is a 2-by-2 array that specifies the initial endpoint positions of the line in the form [X1 Y1; X2 Y2]. h = imline(hparent, x, y) creates a line on the object specified by hparent. x and y are two-element vectors that specify the initial endpoint positions of the line in the form x = [X1 X2], y = [Y1 Y2]. H = imline(..., param1, val1,...) creates a draggable, resizable line, specifying parameters and corresponding values that control the behavior of the line. The following tables lists the parameter available. Parameter names can be abbreviated, and case does not matter. 3-438 imline Parameter Description 'PositionConstraintFcn' Function handle fcn that is called whenever the object is dragged using the mouse. You can use this function to control where the line can be dragged. See the help for the setPositionConstraintFcn method for information about valid function handles. Interactive Behavior When you call imline with an interactive syntax, the pointer changes when over the image. Click and drag the mouse to to a cross hairs specify the position and length of the line, such as . The line supports a context menu that you can use to control aspects of its appearance and behavior. For more information about these interactive features, see the following table. Interactive Behavior Description Moving the line. Move the pointer over the line. The pointer . Click and drag changes to a fleur shape the mouse to move the line. Moving the endpoints of the line. Move the pointer over either end of the line. The pointer changes to the pointing finger, . Click and drag the mouse to resize the line. 3-439 imline Interactive Behavior Description Changing the color used to display the line. Move the pointer over the line. Right-click and select Set Color from the context menu. Retrieving the coordinates of the endpoints of the line. Move the pointer over the line. Right-click and select Copy Position from the context menu. imline copies a 2-by-2 array to the clipboard specifying the coordinates of the endpoints of the line in the form [X1 Y1; X2 Y2]. Methods Each imline object supports a number of methods. Type methods imline to see a list of the methods. addNewPositionCallback — Add new-position callback to ROI object See imroi for information. delete — Delete ROI object See imroi for information. getColor — Get color used to draw ROI object. See imroi for information. getPosition — Return current position of line Returns the endpoint positions of the line. pos = api.getPosition() pos is a 2-by-2 array [X1 Y1; X2 Y2]. getPositionConstraintFcn — Return function handle to current position constraint function See imroi for information. removeNewPositionCallback — Remove new-position callback from ROI object. See imroi for information. 3-440 imline resume — Resume execution of MATLAB command line See imroi for information. setColor — Set color used to draw ROI object See imroi for information. setConstrainedPosition — Set ROI object to new position See imroi for information. setPosition — Set line to new position setPosition(h,pos) sets the line h to a new position. The new position, pos, has the form, [X1 Y1; X2 Y2]. setPosition(h,x,y) sets the line h to a new position. x and y specify the endpoint positions of the line in the form x = [x1 x2], y = [y1 y2]. setPositionConstraintFcn — Set position constraint function of ROI object. See imroi for information. wait — Block MATLAB command line until ROI creation is finished See imroi for information. Tips If you use imline with an axes that contains an image object, and do not specify a position constraint function, users can drag the line outside the extent of the image and lose the line. When used with an axes created by the plot function, the axis limits automatically expand to accommodate the movement of the line. Examples Example 1 Use a custom color for displaying the line. Use addNewPositionCallback method. Move the line, note that the 2-by-2 position vector of the line is displayed in the title above the image. Explore the context menu of the line by right clicking on the line. figure, imshow('pout.tif'); h = imline(gca,[10 100], [100 100]); setColor(h,[0 1 0]); id = addNewPositionCallback(h,@(pos) title(mat2str(pos,3))); 3-441 imline % After observing the callback behavior, remove the callback. % using the removeNewPositionCallback API function. removeNewPositionCallback(h,id); Example 2 Interactively place a line by clicking and dragging. Use wait to block the MATLAB command line. Double-click on the line to resume execution of the MATLAB command line figure, imshow('pout.tif'); h = imline; position = wait(h); See Also 3-442 imellipse | imfreehand | impoint | impoly | imrect | imroi | makeConstrainToRectFcn immagbox Purpose Magnification box for scroll panel Syntax hbox = immagbox(hparent,himage) Description hbox = immagbox(hparent,himage) creates a Magnification box for the image displayed in a scroll panel created by imscrollpanel. hparent is a handle to the figure or uipanel object that will contain the Magnification box. himage is a handle to the target image (the image in the scroll panel). immagbox returns hbox, which is a handle to the Magnification box uicontrol object A Magnification box is an editable text box uicontrol that contains the current magnification of the target image. When you enter a new value in the magnification box, the magnification of the target image changes. When the magnification of the target image changes for any reason, the magnification box updates the magnification value. API Functions A Magnification box contains a structure of function handles, called an API. You can use the functions in this API to manipulate magnification box. To retrieve this structure, use the iptgetapi function. api = iptgetapi(hbox) The API for the Magnification box includes the following function. Function Description setMagnification Sets the magnification in units of screen pixels per image pixel. setMagnification(new_mag) where new_mag is a scalar magnification factor. Multiply new_mag by 100 to get percent magnification. For example if you call setMagnification(2), the magnification box will show the string '200%'. Examples Add a magnification box to a scrollable image. Because the toolbox scrollable navigation is incompatible with standard MATLAB figure 3-443 immagbox window navigation tools, the example suppresses the toolbar and menu bar in the figure window. The example positions the scroll panel in the figure window to allow room for the magnification box. hFig = figure('Toolbar','none',... 'Menubar','none'); hIm = imshow('pears.png'); hSP = imscrollpanel(hFig,hIm); set(hSP,'Units','normalized',... 'Position',[0 .1 1 .9]) hMagBox = immagbox(hFig,hIm); pos = get(hMagBox,'Position'); set(hMagBox,'Position',[0 0 pos(3) pos(4)]) Change the magnification of the image in the scroll panel, using the scroll panel API function setMagnification. Notice how the magnification box updates. apiSP = iptgetapi(hSP); apiSP.setMagnification(2) See also 3-444 imscrollpanel, iptgetapi immovie Purpose Make movie from multiframe image Note immovie(D,size) is an obsolete syntax and is no longer supported. Use immovie(X,map) instead. Syntax mov = immovie(X,map) mov = immovie(RGB) Description mov = immovie(X,map) returns the movie structure array mov from the images in the multiframe indexed image X with the colormap map. For details about the movie structure array, see the reference page for getframe. To play the movie, call implay. X comprises multiple indexed images, all having the same size and all using the colormap map. X is an m-by-n-by-1-by-k array, where k is the number of images. mov = immovie(RGB) returns the movie structure array mov from the images in the multiframe, truecolor image RGB. RGB comprises multiple truecolor images, all having the same size. RGB is an m-by-n-by-3-by-k array, where k is the number of images. Tips You can also use the MATLAB function avifile to make movies from images. The avifile function creates AVI files. To convert an existing MATLAB movie into an AVI file, use the movie2avi function. Class Support An indexed image can be uint8, uint16, single, double, or logical. A truecolor image can be uint8, uint16, single, or double. mov is a MATLAB movie structure. Examples load mri mov = immovie(D,map); implay(mov) See Also avifile | getframe | montage | movie | movie2avi 3-445 immultiply Purpose Multiply two images or multiply image by constant Syntax Z = immultiply(X,Y) Description Z = immultiply(X,Y) multiplies each element in array X by the corresponding element in array Y and returns the product in the corresponding element of the output array Z. If X and Y are real numeric arrays with the same size and class, then Z has the same size and class as X. If X is a numeric array and Y is a scalar double, then Z has the same size and class as X. If X is logical and Y is numeric, then Z has the same size and class as Y. If X is numeric and Y is logical, then Z has the same size and class as X. immultiply computes each element of Z individually in double-precision floating point. If X is an integer array, then elements of Z exceeding the range of the integer type are truncated, and fractional values are rounded. Note On Intel architecture processors, immultiply can take advantage of the Intel Integrated Performance Primitives (Intel IPP) library, thus accelerating its execution time. The Intel IPP library is activated only if arrays X, Y, and Z are of class logical, uint8, or single, and are of the same class. Examples Multiply an image by itself. Note how the example converts the class of the image from uint8 to uint16 before performing the multiplication to avoid truncating the results. I = imread('moon.tif'); I16 = uint16(I); J = immultiply(I16,I16); imshow(I), figure, imshow(J) Scale an image by a constant factor: 3-446 immultiply I = imread('moon.tif'); J = immultiply(I,0.5); subplot(1,2,1), imshow(I) subplot(1,2,2), imshow(J) See Also imabsdiff | imadd | imcomplement | imdivide | imlincomb | imsubtract | ippl 3-447 imnoise Purpose Add noise to image Syntax J = imnoise(I,type) J = imnoise(I,type,parameters) J = imnoise(I,'gaussian',m,v) J = imnoise(I,'localvar',V) J J J J Description = = = = imnoise(I,'localvar',image_intensity,var) imnoise(I,'poisson') imnoise(I,'salt & pepper',d) imnoise(I,'speckle',v) J = imnoise(I,type) adds noise of a given type to the intensity image I. type is a string that can have one of these values. Value Description 'gaussian' Gaussian white noise with constant mean and variance 'localvar' Zero-mean Gaussian white noise with an intensity-dependent variance 'poisson' Poisson noise 'salt & pepper' On and off pixels 'speckle' Multiplicative noise J = imnoise(I,type,parameters) Depending on type, you can specify additional parameters to imnoise. All numerical parameters are normalized; they correspond to operations with images with intensities ranging from 0 to 1. J = imnoise(I,'gaussian',m,v) adds Gaussian white noise of mean m and variance v to the image I. The default is zero mean noise with 0.01 variance. J = imnoise(I,'localvar',V) adds zero-mean, Gaussian white noise of local variance V to the image I. V is an array of the same size as I. 3-448 imnoise J = imnoise(I,'localvar',image_intensity,var) adds zero-mean, Gaussian noise to an image I, where the local variance of the noise, var, is a function of the image intensity values in I. The image_intensity and var arguments are vectors of the same size, and plot(image_intensity,var) plots the functional relationship between noise variance and image intensity. The image_intensity vector must contain normalized intensity values ranging from 0 to 1. J = imnoise(I,'poisson') generates Poisson noise from the data instead of adding artificial noise to the data. If I is double precision, then input pixel values are interpreted as means of Poisson distributions scaled up by 1e12. For example, if an input pixel has the value 5.5e-12, then the corresponding output pixel will be generated from a Poisson distribution with mean of 5.5 and then scaled back down by 1e12. If I is single precision, the scale factor used is 1e6. If I is uint8 or uint16, then input pixel values are used directly without scaling. For example, if a pixel in a uint8 input has the value 10, then the corresponding output pixel will be generated from a Poisson distribution with mean 10. J = imnoise(I,'salt & pepper',d) adds salt and pepper noise to the image I, where d is the noise density. This affects approximately d*numel(I) pixels. The default for d is 0.05. J = imnoise(I,'speckle',v) adds multiplicative noise to the image I, using the equation J = I+n*I, where n is uniformly distributed random noise with mean 0 and variance v. The default for v is 0.04. Note The mean and variance parameters for 'gaussian', 'localvar', and 'speckle' noise types are always specified as if the image were of class double in the range [0, 1]. If the input image is of class uint8 or uint16, the imnoise function converts the image to double, adds noise according to the specified type and parameters, and then converts the noisy image back to the same class as the input. 3-449 imnoise Class Support For most noise types, I can be of class uint8, uint16, int16, single, or double. For Poisson noise, int16 is not allowed. The output image J is of the same class as I. If I has more than two dimensions it is treated as a multidimensional intensity image and not as an RGB image. Examples I = imread('eight.tif'); J = imnoise(I,'salt & pepper',0.02); figure, imshow(I) figure, imshow(J) See Also rand | randn 3-450 imopen Purpose Morphologically open image Syntax IM2 = imopen(IM,SE) IM2 = imopen(IM,NHOOD) Description IM2 = imopen(IM,SE) performs morphological opening on the grayscale or binary image IM with the structuring element SE. The argument SE must be a single structuring element object, as opposed to an array of objects. The morphological open operation is an erosion followed by a dilation, using the same structuring element for both operations. IM2 = imopen(IM,NHOOD) performs opening with the structuring element strel(NHOOD), where NHOOD is an array of 0’s and 1’s that specifies the structuring element neighborhood. Class Support IM can be any numeric or logical class and any dimension, and must be nonsparse. If IM is logical, then SE must be flat. IM2 has the same class as IM. Examples Remove the smaller objects in an image. 1 Read the image into the MATLAB workspace and display it. I = imread('snowflakes.png'); imshow(I) 2 Create a disk-shaped structuring element with a radius of 5 pixels. se = strel('disk',5); 3-451 imopen 3 Remove snowflakes having a radius less than 5 pixels by opening it with the disk-shaped structuring element created in step 2. I_opened = imopen(I,se); figure, imshow(I_opened,[]) See Also 3-452 imclose | imdilate | imerode | strel imoverview Purpose Overview tool for image displayed in scroll panel Syntax imoverview(himage) hfig = imoverview(...) Description imoverview(himage) creates an Overview tool associated with the image specified by the handle himage, called the target image. The target image must be contained in a scroll panel created by imscrollpanel. The Overview tool is a navigation aid for images displayed in a scroll panel. imoverview creates the tool in a separate figure window that displays the target image in its entirety, scaled to fit. Over this scaled version of the image, the tool draws a rectangle, called the detail rectangle, that shows the portion of the target image that is currently visible in the scroll panel. To view portions of the image that are not currently visible in the scroll panel, move the detail rectangle in the Overview tool. The following figure shows the Image Tool with the Overview tool. 3-453 imoverview hfig = imoverview(...) returns a handle to the Overview tool figure. Note To create an Overview tool that can be embedded in an existing figure or uipanel object, use imoverviewpanel. Examples Create a figure, disabling the toolbar and menubar, because the toolbox navigation tools are not compatible with the standard MATLAB zoom and pan tools. Then create a scroll panel in the figure and use scroll panel API functions to set the magnification. hFig = figure('Toolbar','none',... 'Menubar','none'); hIm = imshow('tape.png'); hSP = imscrollpanel(hFig,hIm); api = iptgetapi(hSP); 3-454 imoverview api.setMagnification(2) % 2X = 200% imoverview(hIm) See Also imoverviewpanel | imscrollpanel 3-455 imoverviewpanel Purpose Overview tool panel for image displayed in scroll panel Syntax hpanel = imoverviewpanel(hparent,himage) Description hpanel = imoverviewpanel(hparent,himage) creates an Overview tool panel associated with the image specified by the handle himage, called the target image. himage must be contained in a scroll panel created by imsrollpanel. hparent is a handle to the figure or uipanel object that will contain the Overview tool panel. imoverviewpanel returns hpanel, a handle to the Overview tool uipanel object. The Overview tool is a navigation aid for images displayed in a scroll panel. imoverviewpanel creates the tool in a uipanel object that can be embedded in a figure or uipanel object. The tool displays the target image in its entirety, scaled to fit. Over this scaled version of image, the tool draws a rectangle, called the detail rectangle, that shows the portion of the target image that is currently visible in the scroll panel. To view portions of the image that are not currently visible in the scroll panel, move the detail rectangle in the Overview tool. Note To create an Overview tool in a separate figure, use imoverview. When created using imoverview, the Overview tool includes zoom-in and zoom-out buttons. Examples Create an Overview tool that is embedded in the same figure that contains the target image. hFig = figure('Toolbar','none','Menubar','none'); hIm = imshow('tissue.png'); hSP = imscrollpanel(hFig,hIm); set(hSP,'Units','normalized','Position',[0 .5 1 .5]) hOvPanel = imoverviewpanel(hFig,hIm); set(hOvPanel,'Units','Normalized',... 'Position',[0 0 1 .5]) See Also 3-456 imoverview | imscrollpanel impixel Purpose Pixel color values Syntax P = impixel(I) P = impixel(X,map) P = impixel(RGB) P = impixel(I,c,r) P = impixel(X,map,c,r) P = impixel(RGB,c,r) [c,r,P] = impixel(...) P = impixel(x,y,I,xi,yi) P = impixel(x,y,X,map,xi,yi) P = impixel(x,y,RGB,xi,yi) [xi,yi,P] = impixel(x,y,...) Description impixel returns the red, green, and blue color values of specified image pixels. In the syntax below, impixel displays the input image and waits for you to specify the pixels with the mouse. P = impixel(I) P = impixel(X,map) P = impixel(RGB) If you omit the input arguments, impixel operates on the image in the current axes. Use normal button clicks to select pixels. Press Backspace or Delete to remove the previously selected pixel. A shift-click, right-click, or double-click adds a final pixel and ends the selection; pressing Return finishes the selection without adding a pixel. When you finish selecting pixels, impixel returns an m-by-3 matrix of RGB values in the supplied output argument. If you do not supply an output argument, impixel returns the matrix in ans. You can also specify the pixels noninteractively, using these syntax. P = impixel(I,c,r) 3-457 impixel P = impixel(X,map,c,r) P = impixel(RGB,c,r) r and c are equal-length vectors specifying the coordinates of the pixels whose RGB values are returned in P. The kth row of P contains the RGB values for the pixel (r(k),c(k)). If you supply three output arguments, impixel returns the coordinates of the selected pixels. For example, [c,r,P] = impixel(...) To specify a nondefault spatial coordinate system for the input image, use these syntax. P = impixel(x,y,I,xi,yi) P = impixel(x,y,X,map,xi,yi) P = impixel(x,y,RGB,xi,yi) x and y are two-element vectors specifying the image XData and YData. xi and yi are equal-length vectors specifying the spatial coordinates of the pixels whose RGB values are returned in P. If you supply three output arguments, impixel returns the coordinates of the selected pixels. [xi,yi,P] = impixel(x,y,...) Class Support The input image can be of class uint8, uint16, int16, single, double, or logical. All other inputs are of class double. If the input is double, the output P is double. For all other input classes the output is single. The rest of the outputs are double. Tips 3-458 impixel works with indexed, intensity, and RGB images. impixel always returns pixel values as RGB triplets, regardless of the image type: impixel • For an RGB image, impixel returns the actual data for the pixel. The values are either uint8 integers or double floating-point numbers, depending on the class of the image array. • For an indexed image, impixel returns the RGB triplet stored in the row of the colormap that the pixel value points to. The values are double floating-point numbers. • For an intensity image, impixel returns the intensity value as an RGB triplet, where R=G=B. The values are either uint8 integers or double floating-point numbers, depending on the class of the image array. Examples RGB = imread('peppers.png'); c = [12 146 410]; r = [104 156 129]; pixels = impixel(RGB,c,r) pixels = 62 166 59 See Also 34 54 28 63 60 47 improfile 3-459 impixelinfo Purpose Pixel Information tool Syntax impixelinfo impixelinfo(h) impixelinfo(hparent,himage) hpanel = impixelinfo(...) Description impixelinfo creates a Pixel Information tool in the current figure. The Pixel Information tool displays information about the pixel in an image that the pointer is positioned over. The tool can display pixel information for all the images in a figure. The Pixel Information tool is a uipanel object, positioned in the lower-left corner of the figure. The tool contains the text string Pixel info: followed by the pixel information. Before you move the pointer over the image, the tool contains the default pixel information text string (X,Y) Pixel Value. Once you move the pointer over the image, the information displayed varies by image type, as shown in the following table. If you move the pointer off the image, the pixel information tool displays the default pixel information string for that image type. 3-460 Image Type Pixel Information Example Intensity (X,Y) Intensity (13,30) 82 Indexed (X,Y) <index> [R G B] (2,6) <4> [0.29 0.05 0.32] Binary (X,Y) BW (12,1) 0 Truecolor (X,Y) [R G B] (19,10) [15 255 10] Floating point image with CDataMapping property set to direct (X,Y) value <index> [R G B] (19,10) 82 <4> [15 255 10] impixelinfo For example, for grayscale (intensity) images, the pixel information tool displays the x and y coordinates of the pixel and its value, as shown in the following figure. If you want to display the pixel information without the “Pixel Info” label, use the impixelinfoval function. impixelinfo(h) creates a Pixel Information tool in the figure specified by h, where h is a handle to an image, axes, uipanel, or figure object. Axes, uipanel, or figure objects must contain at least one image object. impixelinfo(hparent,himage) creates a Pixel Information tool in hparent that provides information about the pixels in himage. himage is a handle to an image or an array of image handles. hparent is a handle to the figure or uipanel object that contains the pixel information tool. hpanel = impixelinfo(...) returns a handle to the Pixel Information tool uipanel. Note To copy the pixel information string to the clipboard, right-click while the pointer is positioned over a pixel. In the context menu displayed, choose Copy pixel info. Examples Display an image and add a Pixel Information tool to the figure. The example shows how you can change the position of the tool in the figure using properties of the tool uipanel object. h = imshow('hestain.png'); hp = impixelinfo; set(hp,'Position',[5 1 300 20]); Use the Pixel Information tool in a figure containing multiple images of different types. 3-461 impixelinfo figure subplot(1,2,1), imshow('liftingbody.png'); subplot(1,2,2), imshow('autumn.tif'); impixelinfo; See Also 3-462 impixelinfoval | imtool impixelinfoval Purpose Pixel Information tool without text label Syntax hcontrol = impixelinfoval(hparent,himage) Description hcontrol = impixelinfoval(hparent,himage) creates a Pixel Information tool in hparent that provides information about the pixels in the image specified by himage. hparent is a handle to a figure or uipanel object. himage can be a handle to an image or an array of image handles. The Pixel Information tool displays information about the pixel in an image that the pointer is positioned over. The tool displays pixel information for all the images in a figure. When created with impixelinfo, the tool is a uipanel object, positioned in the lower-left corner of the figure, that contains the text label Pixel Info: followed by the x- and y-coordinates of the pixel and its value. When created with impixelinfoval, the tool is a uicontrol object positioned in the lower-left corner of the figure, that displays the pixel information without the text label, as shown in the following figure. The information displayed depends on the image type. See impixelinfo for details. To copy the pixel value string to the Clipboard, right-click while the pointer is positioned over a pixel. In the context menu displayed, choose Copy pixel info. Examples Add a Pixel Information tool to a figure. Note how you can change the style and size of the font used to display the value in the tool using standard Handle Graphics commands. ankle = dicomread('CT-MONO2-16-ankle.dcm'); h = imshow(ankle,[]); 3-463 impixelinfoval hText = impixelinfoval(gcf,h); set(hText,'FontWeight','bold') set(hText,'FontSize',10) See also 3-464 impixelinfo impixelregion Purpose Pixel Region tool Syntax impixelregion impixelregion(h) hfig = impixelregion(...) Description impixelregion creates a Pixel Region tool associated with the image displayed in the current figure, called the target image. The Pixel Region tool opens a separate figure window containing an extreme close-up view of a small region of pixels in the target image, as shown in the following figure. 3-465 impixelregion Pixel Region tool button Pixel Region tool Pixel Region rectangle The Pixel Region rectangle defines the area of the target image that is displayed in the Pixel Region tool. You can move this rectangle over the target image using the mouse to view different regions. To get a closer view of the pixels displayed in the tool, use the zoom buttons on the Pixel Region tool toolbar or change the size of the Pixel Region rectangle using the mouse. You can also resize the Pixel Region tool itself to view more or fewer pixels. If the size of the pixels allows, the tool superimposes the numeric value of the pixel over each pixel. To get the current position of the Pixel Region rectangle, right-click on the rectangle and select Copy Position from the context menu. The Pixel Region tool copies a four-element position vector to the clipboard. 3-466 impixelregion To change the color of the Pixel Region rectangle, right-click and select Set Color. impixelregion(h) creates a Pixel Region tool associated with the object specified by the handle h. h can be a handle to a figure, axes, uipanel, or image object. If h is a handle to an axes or figure, impixelregion associates the tool with the first image found in the axes or figure. hfig = impixelregion(...) returns hfig, a handle of the Pixel Region tool figure. Note To create a Pixel Region tool that can be embedded in an existing figure window or uipanel, use impixelregionpanel. Examples Display an image and then create a Pixel Region tool associated with the image. imshow peppers.png impixelregion See Also impixelinfo | impixelregionpanel | imtool 3-467 impixelregionpanel Purpose Pixel Region tool panel Syntax hpanel = impixelregionpanel(hparent,himage) Description hpanel = impixelregionpanel(hparent,himage) creates a Pixel Region tool panel associated with the image specified by the handle himage, called the target image. This is the image whose pixels are to be displayed. hparent is the handle to the figure or uipanel object that will contain the Pixel Region tool panel. hpanel is the handle to the Pixel Region tool scroll panel. The Pixel Region tool is a uipanel object that contains an extreme close-up view of a small region of pixels in the target image. If the size of the pixels allows, the tool superimposes the numeric value of the pixel over each pixel. To define the region being examined, the tool overlays a rectangle on the target image, called the pixel region rectangle. To view pixels in a different region, click and drag the rectangle over the target image. See impixelregion for more information. Note To create a Pixel Region tool in a separate figure window, use impixelregion. Examples himage = imshow('peppers.png'); hfigure = figure; hpanel = impixelregionpanel(hfigure, himage); Set the panel’s position to the lower-left quadrant of the figure. set(hpanel, 'Position', [0 0 .5 .5]) See Also 3-468 impixelregion | imrect | imscrollpanel implay Purpose Play movies, videos, or image sequences Syntax implay implay(filename) implay(I) implay(..., FPS) Description implay opens a Movie Player for showing MATLAB movies, videos, or image sequences (also called image stacks). Use the implay File menu to select the movie or image sequence that you want to play. Use implay toolbar buttons or menu options to play the movie, jump to a specific frame in the sequence, change the frame rate of the display, or perform other exploration activities. You can open multiple implay movie players to view different movies simultaneously. The following figure shows the Movie Player containing an image sequence. Toolbar Playback toolbar Movie frames Player status Frame type (I or RGB) Frame size Current frame/ Frame rate and percentage total frames Note: + and of frame rate indicate playback achieved direction. 3-469 implay implay(filename) opens the implay movie player, displaying the content of the file specified by filename. The file can be an Audio Video Interleaved (AVI) file. implay reads one frame at a time, conserving memory during playback. implay does not play audio tracks. implay(I) opens the implay movie player, displaying the first frame in the multiframe image array specified by I. I can be a MATLAB movie structure, or a sequence of binary, grayscale, or truecolor images. A binary or grayscale image sequence can be an M-by-N-by-1-by-K array or an M-by-N-by-K array. A truecolor image sequence must be an M-by-N-by-3-by-K array. implay(..., FPS) specifies the rate at which you want to view the movie or image sequence. The frame rate is specified as frames-per-second. If omitted, implay uses the frame rate specified in the file or the default value 20. Class Support I can be numeric but uint8 is preferred. The actual data type used to Tips • You can access implay through the Plot Selector workspace tool, display pixels may differ from the source data type. which is represented by this icon: In your workspace, select the data you want to display. The Plot . Selector icon updates like this: . To open implay with your chosen data, either click on the Plot Selector icon or select implay from the Plot Selector drop-down menu. Examples Animate a sequence of images. load cellsequence implay(cellsequence,10); Visually explore a stack of MRI images. load mristack implay(mristack); 3-470 implay Play an AVI file. implay('rhinos.avi'); 3-471 impoint Purpose Create draggable point Syntax h h p p p Description h = impoint begins interactive placement of a draggable point on the current axes. The function returns h, a handle to an impoint object. The point has a context menu associated with it that controls aspects of its appearance and behavior—see “Interactive Behavior” on page 3-473. Right-click on the point to access this context menu. = = = = = impoint impoint(hparent) impoint(hparent, position) impoint(hparent, x, y) impoint(..., param, val) h = impoint(hparent) begins interactive placement of a point on the object specified by hparent. hparent specifies the HG parent of the point graphics, which is typically an axes but can also be any other object that can be the parent of an hggroup. p = impoint(hparent, position) creates a draggable point on the object specified by hparent. position is a 1-by-2 array of the form [x y] that specifies the initial position of the point. p = impoint(hparent, x, y) creates a draggable point on the object specified by hparent. x and y are both scalars that together specify the initial position of the point. p = impoint(..., param, val) creates a draggable point , specifying parameters and corresponding values that control the behavior of the point. The following table lists the parameter available. Parameter names can be abbreviated, and case does not matter. 3-472 impoint Parameter Description 'PositionConstraintFcn' Function handle fcn that is called whenever the point is dragged using the mouse. You can use this function to control where the point can be dragged. See the help for the setPositionConstraintFcn method for information about valid function handles. Interactive Behavior When you call impoint with an interactive syntax, the pointer changes to a cross hairs when over the image. Click and drag the mouse . The following table to specify the position of the point, such as describes the interactive behavior of the point, including the right-click context menu options. Interactive Behavior Description Moving the point. Move the mouse pointer over the point. The . mouse pointer changes to a fleur shape Click and drag the mouse to move the point. Changing the color used to display the point. Move the mouse pointer over the point. Right-click and select Set Color from the context menu and specify the color you want to use. Retrieving the coordinates of the point. Move the mouse pointer over the point. Right-click and select Copy Position from the context menu to copy a 1-by-2 array to the clipboard specifying the coordinates of the point [X Y]. 3-473 impoint Methods The following lists the methods supported by the impoint object. Type methods impoint to see a complete list of all the methods. addNewPositionCallback — Add new-position callback to ROI object See imroi for information. delete — Delete ROI object See imroi for information. getColor — Get color used to draw ROI object See imroi for information. getPosition — Return current position of point pos = getPosition(h) returns the current position of the point h. The returned position, pos, is a two-element vector [x y]. getPositionConstraintFcn — Return function handle to current position constraint function See imroi for information. removeNewPositionCallback — Remove new-position callback from ROI object. See imroi for information. resume — Resume execution of MATLAB command line See imroi for information. setColor — Set color used to draw ROI object See imroi for information. setConstrainedPosition — Set ROI object to new position See imroi for information. setPosition — Set point to new position setPosition(h,pos) sets the pointh to a new position. The new position, pos, has the form, [x y]. setPosition(h,new_x,new_y) sets the point h to a new position. new_x and new_y are both scalars that together specify the position of the point. 3-474 impoint setPositionConstraintFcn — Set position constraint function of ROI object. See imroi for information. setString — Set text label for point setString(h,s) sets a text label for the point h. The string, s, is placed to the lower right of the point. wait — Block MATLAB command line until ROI creation is finished See imroi for information. Tips If you use impoint with an axes that contains an image object, and do not specify a drag constraint function, users can drag the point outside the extent of the image and lose the point. When used with an axes created by the plot function, the axes limits automatically expand to accommodate the movement of the point. Examples Example 1 Use impoint methods to set custom color, set a label, enforce a boundary constraint, and update position in title as point moves. figure, imshow rice.png h = impoint(gca,100,200); % Update position in title using newPositionCallback addNewPositionCallback(h,@(h) title(sprintf('(%1.0f,%1.0f)',h(1),h(2)))); % Construct boundary constraint function fcn = makeConstrainToRectFcn('impoint',get(gca,'XLim'),get(gca,'YLim')); % Enforce boundary constraint function using setPositionConstraintFcn setPositionConstraintFcn(h,fcn); setColor(h,'r'); setString(h,'Point label'); Example 2 Interactively place a point. Use wait to block the MATLAB command line. Double-click on the point to resume execution of the MATLAB command line. figure, imshow('pout.tif'); 3-475 impoint p = impoint(gca,[]); p = wait(p); See Also 3-476 imellipse | imfreehand | imline | impoly | imrect | imroi | makeConstrainToRectFcn impoly Purpose Create draggable, resizable polygon Syntax h h h h Description h = impoly begins interactive placement of a polygon on the current axes. The function returns h, a handle to an impoly object. The polygon has a context menu associated with it that controls aspects of its appearance and behavior—see “Interactive Behavior” on page 3-478. Right-click on the polygon to access this context menu. = = = = impoly impoly(hparent) impoly(hparent, position) impoly(..., param1, val1, ...) h = impoly(hparent) begins interactive placement of a polygon on the object specified by hparent. hparent specifies the HG parent of the polygon graphics, which is typically an axes but can also be any other object that can be the parent of an hggroup. h = impoly(hparent, position) creates a draggable, resizable polygon on the object specified by hparent. position is an n-by-2 array that specifies the initial position of the vertices of the polygon. position has the form [X1,Y1;...;XN,YN]. h = impoly(..., param1, val1, ...) creates a draggable, resizable polygon, specifying parameters and corresponding values that control the behavior of the polygon. The following table lists available parameters. Parameter names can be abbreviated, and case does not matter. 3-477 impoly Parameter Description 'Closed' Scalar logical that controls whether the polygon is closed. When set to true (the default), impoly creates a closed polygon, that is, it draws a straight line between the last vertex specified and the first vertex specified to create a closed region. When Closed is false, impoly does not connect the last vertex with the first vertex, creating an open polygon (or polyline). 'PositionConstraintFcn' Function handle fcn that is called whenever the object is dragged using the mouse. You can use this function to control where the line can be dragged. See the help for the setPositionConstraintFcn method for information about valid function handles. Interactive Behavior When you call impoly with an interactive syntax, the pointer changes when over the image. Click and drag the mouse to a cross hairs to define the vertices of the polygon and adjust the size, shape, and position of the polygon. The polygon also supports a context menu that you can use to control aspects of its appearance and behavior. The choices in the context menu vary whether you position the pointer on an edge of the polygon (or anywhere inside the region) or on one of the vertices. The following figure shows a polygon being created. 3-478 impoly impoly pointer Polygon vertices The following table lists the interactive behaviors supported by impoly. Interactive Behavior Description Closing the polygon. Use any of the following mechanisms: • Move the pointer over the initial vertex of the polygon that you selected. The pointer changes to a circle . Click either mouse button. • Double-click the left mouse button. This action creates a vertex at the point under the mouse and draws a straight line connecting this vertex with the initial vertex. • Click the right mouse button. This action draws a line connecting the last vertex 3-479 impoly Interactive Behavior Description selected with the initial vertex; it does not create a new vertex. Adding a new vertex. Move the pointer over an edge of the polygon and press the A key. The shape of the pointer changes . Click the left mouse button to create a new vertex at that position on the line. Moving a vertex. (Reshaping the polygon.) Move the pointer over a vertex. The pointer changes to a circle . Click and drag the vertex to its new position. Deleting a vertex. Move the pointer over a vertex. The shape changes to a circle . Right-click and select Delete Vertex from the vertex context menu. This action deletes the vertex and adjusts the shape of the polygon, drawing a new straight line between the two vertices that were neighbors of the deleted vertex. Moving the polygon. Move the pointer inside the polygon. The . Click pointer changes to a fleur shape and drag the mouse to move the polygon. 3-480 Changing the color of the polygon Move the pointer inside the polygon. Right-click and select Set Color from the context menu. Retrieving the coordinates of the vertices Move the pointer inside the polygon. Right-click and select Copy Position from the context menu. impoly copies an n-by-2 array containing the x- and y-coordinates of each vertex to the clipboard. n is the number of vertices you specified. impoly Methods Each impoly object supports a number of methods, listed below. Methods inherited from the base class are links to that class. addNewPositionCallback — Add new-position callback to ROI object See imroi for information. createMask — Create mask within image See imroi for information. delete — Delete ROI object See imroi for information. getColor — Get color used to draw ROI object See imroi for information. getPosition — Return current position of polygon pos = getPosition(h) returns the current position of the polygon h. The returned position, pos, is an N-by-2 array [X1 Y1;...;XN YN]. getPositionConstraintFcn — Return function handle to current position constraint function See imroi for information. removeNewPositionCallback — Remove new-position callback from ROI object. See imroi for information. resume — Resume execution of MATLAB command line See imroi for information. setClosed — Set geometry of polygon setClosed(TF) sets the geometry of the polygon. TF is a logical scalar. true means that the polygon is closed. false means that the polygon is an open polyline. setColor — Set color used to draw ROI object See imroi for information. setConstrainedPosition — Set ROI object to new position See imroi for information. 3-481 impoly setPosition — Set polygon to new position setPosition(h,pos) sets the polygon h to a new position. The new position, pos, is an n-by-2 array, [x1 y1; ..; xn yn] where each row specifies the position of a vertex of the polygon. setPositionConstraintFcn — Set position constraint function of ROI object. See imroi for information. setVerticesDraggable — Control whether vertices may be dragged setVerticesDraggable(h,TF) sets the interactive behavior of the vertices of the polygon h. TF is a logical scalar. True means that the vertices of the polygon are draggable. False means that the vertices of the polygon are not draggable. wait — Block MATLAB command line until ROI creation is finished See imroi for information. Tips If you use impoly with an axes that contains an image object, and do not specify a position constraint function, users can drag the polygon outside the extent of the image and lose the polygon. When used with an axes created by the plot function, the axes limits automatically expand when the polygon is dragged outside the extent of the axes. Examples Example 1 Display updated position in the title. Specify a position constraint function using makeConstrainToRectFcn to keep the polygon inside the original xlim and ylim ranges. figure, imshow('gantrycrane.png'); h = impoly(gca, [188,30; 189,142; 93,141; 13,41; 14,29]); setColor(h,'yellow'); addNewPositionCallback(h,@(p) title(mat2str(p,3))); fcn = makeConstrainToRectFcn('impoly',get(gca,'XLim'),... get(gca,'YLim')); setPositionConstraintFcn(h,fcn); 3-482 impoly Example 2 Interactively place a polygon by clicking to specify vertex locations. Double-click or right-click to finish positioning the polygon. Use wait to block the MATLAB command line. Double-click on the polygon to resume execution of the MATLAB command line. figure, imshow('pout.tif'); h = impoly; position = wait(h); See also imellipse, imfreehand, imline, impoint, imrect, imroi, makeConstrainToRectFcn 3-483 impositionrect Purpose Create draggable position rectangle Syntax H = impositionrect(hparent,position) Note This function is obsolete and may be removed in future versions. Use imrect instead. Description H = impositionrect(hparent,position) creates a position rectangle on the object specified by hparent. The function returns H, a handle to the position rectangle, which is an hggroup object. hparent specifies the hggroup’s parent, which is typically an axes object, but can also be any other object that can be the parent of an hggroup. position is a four-element position vector that specifies the initial location of the rectangle. position has the form [XMIN YMIN WIDTH HEIGHT]. All measurements are in units specified by the Units property axes object.When you do not specify the position argument, impositionrect uses [0 0 1 1] as the default value. Tips A position rectangle can be dragged interactively using the mouse. When the position rectangle occupies a small number of screen pixels, its appearance changes to aid visibility. The position rectangle has a context menu associated with it that you can use to copy the current position to the clipboard and change the color used to display the rectangle. API Function Syntaxes A position rectangle contains a structure of function handles, called an API, that can be used to manipulate it. To retrieve this structure from the position rectangle, use the iptgetapi function. API = iptgetapi(H) The following lists the functions in the position rectangle API in the order they appear in the API structure. 3-484 impositionrect Function Description setPosition Sets the position rectangle to a new position. api.setPosition(new_position) where new_position is a four-element position vector. getPosition Returns the current position of the position rectangle. position = api.getPosition() position is a four-element position vector. delete Deletes the position rectangle associated with the API. api.delete() setColor Sets the color used to draw the position rectangle. api.setColor(new_color) where new_color can be a three-element vector specifying an RGB triplet, or a text string specifying the long or short names of a predefined color, such as 'white' or 'w'. For a complete list of these predefined colors and their short names, see ColorSpec. addNewPositionCallback Adds the function handle fun to the list of new-position callback functions. id = api.addNewPositionCallback(fun) Whenever the position rectangle changes its position, each function in the list is called with the syntax: fun(position) 3-485 impositionrect Function Description The return value, id, is used only with removeNewPositionCallback. removeNewPositionCallback Removes the corresponding function from the new-position callback list. api.removeNewPositionCallback(id) where id is the identifier returned by api.addNewPositionCallback setDragConstraintCallback Sets the drag constraint function to be the specified function handle, fcn. api.setDragConstraintCallback(fcn) Whenever the position rectangle is moved because of a mouse drag, the constraint function is called using the syntax: constrained_position = fcn(new_position) where new_position is a four-element position vector. This allows a client, for example, to control where the position rectangle may be dragged. Examples Display in the command window the updated position of the position rectangle as it moves in the axes. close all, plot(1:10) h = impositionrect(gca, [4 4 2 2]); api = iptgetapi(h); api.addNewPositionCallback(@(p) disp(p)); Constrain the position rectangle to move only up and down. 3-486 impositionrect close all, plot(1:10) h = impositionrect(gca, [4 4 2 2]); api = getappdata(h, 'API'); api.setDragConstraintCallback(@(p) [4 p(2:4)]); Specify the color of the position rectangle. close all, plot(1:10) h = impositionrect(gca, [4 4 2 2]); api = iptgetapi(h, 'API'); api.setColor([1 0 0]); When the position rectangle occupies only a few pixels on the screen, the rectangle is drawn in a different style to increase its visibility. close all, imshow cameraman.tif h = impositionrect(gca, [100 100 10 10]); See Also iptgetapi 3-487 improfile Purpose Pixel-value cross-sections along line segments Syntax c = improfile c = improfile(n) c = improfile(I,xi,yi) c = improfile(I,xi,yi,n) [cx,cy,c] = improfile(...) [cx,cy,c,xi,yi] = improfile(...) [...] = improfile(x,y,I,xi,yi) [...] = improfile(x,y,I,xi,yi,n) [...] = improfile(...,method) Description improfile computes the intensity values along a line or a multiline path in an image. improfile selects equally spaced points along the path you specify, and then uses interpolation to find the intensity value for each point. improfile works with grayscale images and RGB images. If you call improfile with one of these syntax, it operates interactively on the image in the current axes. c = improfile c = improfile(n) n specifies the number of points to compute the intensity value for. If you do not provide this argument, improfile chooses a value for n, roughly equal to the number of pixels the path traverses. You specify the line or path using the mouse, by clicking points in the image. Press Backspace or Delete to remove the previously selected point. A shift-click, right-click, or double-click adds a final point and ends the selection; pressing Return finishes the selection without adding a point. When you finish selecting points, improfile returns the interpolated data values in c. c is an n-by-1 vector if the input is 3-488 improfile a grayscale intensity image, or an n-by-1-by-3 array if the input is an RGB image. If you omit the output argument, improfile displays a plot of the computed intensity values. If the specified path consists of a single line segment, improfile creates a two-dimensional plot of intensity values versus the distance along the line segment; if the path consists of two or more line segments, improfile creates a three-dimensional plot of the intensity values versus their x- and y-coordinates. You can also specify the path non-interactively, using these syntax. c = improfile(I,xi,yi) c = improfile(I,xi,yi,n) xi and yi are equal-length vectors specifying the spatial coordinates of the endpoints of the line segments. You can use these syntax to return additional information. [cx,cy,c] = improfile(...) [cx,cy,c,xi,yi] = improfile(...) cx and cy are vectors of length n, containing the spatial coordinates of the points at which the intensity values are computed. To specify a non-default spatial coordinate system for the input image, use these syntax. [...] = improfile(x,y,I,xi,yi) [...] = improfile(x,y,I,xi,yi,n) x and y are two-element vectors specifying the image XData and YData. = improfile(...,method) uses the specified interpolation method. method is a string that can have one of these values. The default value is enclosed in braces ({}). [...] 3-489 improfile Value Description {'nearest'} Nearest-neighbor interpolation 'bilinear' Bilinear interpolation 'bicubic' Bicubic interpolation Class Support The input image can be uint8, uint16, int16, single, double, or logical. All other inputs and outputs must be double. Examples I = imread('liftingbody.png'); x = [19 427 416 77]; y = [96 462 37 33]; improfile(I,x,y),grid on; See Also impixel | interp2 3-490 imputfile Purpose Display Save Image dialog box Syntax [filename, ext, user_canceled] = imputfile Description [filename, ext, user_canceled] = imputfile displays the Save Image dialog box (shown below) which you can use to specify the full path and format of a file. Using the dialog box, you can navigate to folders in a file system and select a particular file or specify the name of a new file. imputfile limits the types of files displayed in the dialog box to the image file format selected in the Files of Type menu. Select image file format. When you click Save, imputfile returns the full path to the file in filenameand the file type selected from the Files of Type menu in ext. imputfile does not automatically add a file name extension (such as .jpg) to the file name. 3-491 imputfile If the user clicks Cancel or closes the Save Image dialog box, imputfile returns, setting user_canceled to True (1), and settingfilename and ext to empty strings; otherwise, user_canceled is False (0). Note The Save Image dialog box is modal; it blocks the MATLAB command line until you click Save or cancel the operation. See Also 3-492 imformats | imtool | imgetfile | imsave impyramid Purpose Image pyramid reduction and expansion Syntax B = impyramid(A, direction) Description B = impyramid(A, direction) computes a Gaussian pyramid reduction or expansion of A by one level. direction can be 'reduce' or 'expand'. If A is m-by-n and direction is 'reduce', then the size of B is ceil(M/2)-by-ceil(N/2). If direction is 'expand', then the size of B is (2*M-1)-by-(2*N-1). Reduction and expansion take place only in the first two dimensions. For example, if A is 100-by-100-by-3 and direction is 'reduce', then B is 50-by-50-by-3. Note that impyramid uses the kernel specified on page 533 of the Burt and Adelson paper cited below: 1 1 a⎤ ⎡1 a 1 w = ⎢ − , , a, , − ⎥ , where a = 0.375 . 4 4 2⎦ ⎣4 2 4 The parameter a is chosen to be 0.375 so that the equivalent weighting function is close to a Gaussian shape and the weights can be readily applied using fixed-point arithmetic. Class support A can be any numeric class except uint64 or int64, or it can be logical. The class of B is the same as the class of A. Examples Compute a four-level multiresolution pyramid of the cameraman image. I0 I1 I2 I3 = = = = imread('cameraman.tif'); impyramid(I0, 'reduce'); impyramid(I1, 'reduce'); impyramid(I2, 'reduce'); imshow(I0) 3-493 impyramid figure, imshow(I1) figure, imshow(I2) figure, imshow(I3) References [1] Burt and Adelson, "The Laplacian Pyramid as a Compact Image Code," IEEE Transactions on Communications, vol. COM-31, no. 4, April 1983, pp. 532-540. [2] Burt, "Fast Filter Transforms for Image Processing," Computer Graphics and Image Processing, vol. 16, 1981, pp. 20-51 See Also 3-494 imresize imquantize Purpose Quantize image using specified quantization levels and output values Syntax quant_A = imquantize(A,levels) quant_A = imquantize( ___ ,values) [quant_A,index] = imquantize( ___ ) Description quant_A = imquantize(A,levels) quantizes image A using specified quantization values contained in the N element vector levels. Output image quant_A is the same size as A and contains N + 1 discrete integer values in the range 1 to N + 1 which are determined by the following criteria: • If A(k) ≤ levels(1), then quant_A(k) = 1. • If levels(m-1) < A(k) ≤ levels(m) , then quant_A(k) = m. • If A(k) > levels(N), then quant_A(k) = N + 1. Note that imquantize assigns values to the two implicitly defined end intervals: • A(k) ≤ levels(1) • A(k) > levels(N) quant_A = imquantize( ___ ,values) adds the N + 1 element vector values where N = length(levels). Each of the N + 1 elements of values specify the quantization value for one of the N + 1 discrete pixel values in quant_A. • If A(k) ≤ levels(1), then quant_A(k) = values(1). • If levels(m-1) < A(k) ≤ levels(m) , then quant_A(k) = values(m). • If A(k) > levels(N), then quant_A(k) = values(N + 1). [quant_A,index] = imquantize( ___ ) returns matrix index such that: quant_A = values(index) 3-495 imquantize Input Arguments A - Input image image Input image, specified as a numeric array of any dimension. Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 levels - Quantization levels vector Quantization levels, specified as an N element vector. Values of the discrete quantization levels must be in monotonically increasing order. Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 values - Quantization values vector Quantization values, specified as an N + 1 element vector. Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 Output Arguments quant_A - Quantized output image image Quantized output image, returned as a numeric array the same size as A. If input argument values is specified, then quant_A is the same data type as values. If values is not specified, then quant_A is of class double. index - Mapping matrix matrix Mapping matrix, returned as a matrix the same size as input image A. It contains integer indices which access values to construct the 3-496 imquantize output image: quant_A = values(index). If input argument values is not defined, then index = quant_A. Data Types double Examples Image Threshold Compute multiple thresholds for an image using multithresh and apply those thresholds to the image using imquantize to get segment labels. I = imread('circlesBrightDark.png'); Computing two thresholds will quantize the image into three discrete levels thresh = multithresh(I,2); seg_I = imquantize(I,thresh); RGB = label2rgb(seg_I); % apply the thresholds to obtain segmen % convert to color image figure; imshowpair(I,RGB,'montage'); axis off; title('Original Image % display images side-by-side RGB Segmented Imag 3-497 imquantize Two Schemes for RGB Image Quantization Quantize truecolor RGB image to 8 levels using multi-level thresholding function multithresh. Compare results between thresholding the entire RGB image versus plane-by-plane thresholding. Read in truecolor RGB image. 3-498 imquantize I = imread('peppers.png'); imshow(I); axis off; title('RGB Image'); 3-499 imquantize Generate thresholds for seven levels from the entire RGB image. then repeat process for each plane in the RGB image. threshRGB = multithresh(I,7) % 7 thresholds from entire RGB image threshPlanes = zeros(3,7); % initialize % Compute thresholds for each R, G and B plane for i = 1:3 threshPlane(i,:) = multithresh(I(:,:,i),7); end threshPlane threshRGB = 24 51 79 109 141 177 221 92 74 60 125 100 86 159 128 127 195 164 165 231 209 222 threshPlane = 40 27 18 69 49 38 Process entire image with set of threshold values computed from entire image. Similarly, process each RGB plane separately using threshold vector computed from the given plane. Add black (0) and white (255) to value vector which assigns values to output image. value = [0 threshRGB(2:end) 255]; % Quantize entire image using one threshold vector quantRGB = imquantize(I, threshRGB, value); quantPlane = zeros( size(I) ); % Quantize each RGB plane using threshold vector generated for that plane for i = 1:3 value = [0 threshPlane(i,2:end) 255] % output value to assign quantPlane(:,:,i) = imquantize(I(:,:,i),threshPlane(i,:),value); end 3-500 imquantize quantPlane = uint8(quantPlane); % convert from double to uint8 Display both posterized images and note the visual differences in the two thresholding schemes. The following code snippet computes the number of unique RGB pixel vectors in each output image. Note that the plane-by-plane thresholding scheme yields about 23% more colors than the full RGB image scheme. 3-501 imquantize % convert images to mx3 matrices dim = size( quantRGB ); quantRGBmx3 = reshape(quantRGB, prod(dim(1:2)), 3); quantPlanemx3 = reshape(quantPlane, prod(dim(1:2)), 3); % extract only unique 3 element RGB pixel vectors from each matrix colorsRGB = unique( quantRGBmx3, 'rows' ); colorsPlane = unique( quantPlanemx3, 'rows' ); disp(['Number of unique colors in RGB image : ' int2str(length disp(['Number of unique colors in Plane-by-Plane image : ' int2str(length Number of unique colors in RGB image : 188 Number of unique colors in Plane-by-Plane image : 231 Threshold a Grayscale Image from 256 to 8 levels This example reduces the number of discrete levels in an image from 256 to 8. It then demonstrates two different schemes for assigning values to each of the eight output levels. I = imread('coins.png'); imshow(I); axis off; title('Grayscale Image'); 3-502 imquantize Obtain seven thresholds from multithresh to split the image into eight levels. thresh = multithresh(I,7); % 7 thresholds result in 8 image levels Construct the valuesMax vector such that the maximum value in each quantization interval is assigned to the eight levels of the output image. valuesMax = [thresh max(I(:))] [quant8_I_max,index] = imquantize(I,thresh,valuesMax); valuesMax = 65 88 119 149 169 189 215 255 3-503 imquantize Similarly, construct valuesMin such that the minimum value in each quantization interval is assigned to the eight levels of the output image valuesMin = [min(I(:)) thresh] valuesMin = 23 65 88 119 149 169 189 215 Instead of calling imquantize again with the vector valuesMin, use the output argument index to assign those values to the output image. quant8_I_min = valuesMin(index); Display both eight-level output images side by side. 3-504 imquantize See Also multithresh | label2rgb | rgb2ind 3-505 imreconstruct Purpose Morphological reconstruction Syntax IM = imreconstruct(marker,mask) IM = imreconstruct(marker,mask,conn) Description IM = imreconstruct(marker,mask) performs morphological reconstruction of the image marker under the image mask. marker and mask can be two intensity images or two binary images with the same size. The returned image IM is an intensity or binary image, respectively. marker must be the same size as mask, and its elements must be less than or equal to the corresponding elements of mask. By default, imreconstruct uses 8-connected neighborhoods for 2-D images and 26-connected neighborhoods for 3-D images. For higher dimensions, imreconstruct uses conndef(ndims(I),'maximal'). IM = imreconstruct(marker,mask,conn) performs morphological reconstruction with the specified connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by- ... -by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. 3-506 imreconstruct Morphological reconstruction is the algorithmic basis for several other Image Processing Toolbox functions, including imclearborder, imextendedmax, imextendedmin, imfill, imhmax, imhmin, and imimposemin. Class Support marker and mask must be nonsparse numeric (including uint64 or int64) or logical arrays with the same class and any dimension. IM is of the same class as marker and mask. Performance Note This function may take advantage of hardware optimization for data types logical, uint8, and single to run faster. Hardware optimization requires marker and mask to be 2-D images and conn to be either 4 or 8. Algorithms imreconstruct uses the fast hybrid grayscale reconstruction algorithm described in [1]. References [1] Vincent, L., "Morphological Grayscale Reconstruction in Image Analysis: Applications and Efficient Algorithms," IEEE Transactions on Image Processing, Vol. 2, No. 2, April, 1993, pp. 176-201. See Also imclearborder | imextendedmax | imextendedmin | imfill | imhmax | imhmin | imimposemin 3-507 imrect Purpose Create draggable rectangle Syntax H h h H Description H = imrect begins interactive placement of a rectangle on the current axes. The function returns h, a handle to an imrect object. The rectangle has a context menu associated with it that controls aspects of its appearance and behavior—see “Interactive Behavior” on page 3-509. Right-click on the rectangle to access this context menu. = = = = imrect imrect(hparent) imrect(hparent, position) imrect(..., param1, val1,...) h = imrect(hparent) begins interactive placement of a rectangle on the object specified by hparent. hparent specifies the HG parent of the rectangle graphics, which is typically an axes but can also be any other object that can be the parent of an hggroup. h = imrect(hparent, position) creates a draggable rectangle on the object specified by hparent. position is a four-element vector that specifies the initial size and location of the rectangle. position has the form [xmin ymin width height]. H = imrect(..., param1, val1,...) creates a draggable rectangle, specifying parameters and corresponding values that control the behavior of the rectangle. The following table lists the parameter available. Parameter names can be abbreviated, and case does not matter. Parameter Description 'PositionConstraintFcn' Function handle fcn that is called whenever the mouse is dragged. You can use this function to control where the rectangle can be dragged. See the help for the setPositionConstraintFcn method for information about valid function handles. 3-508 imrect Interactive Behavior When you call imrect with an interactive syntax, the pointer changes when over the image. You can create the rectangle to a cross hairs and adjust its size and position using the mouse. The rectangle also supports a context menu that you can use to control aspects of its appearance and behavior. The following figure shows the rectangle. Draggable, resizable, rectangle The following table lists the interactive behaviors supported by imrect. Interactive Behavior Description Moving the rectangle. Move the pointer inside the rectangle. The . Click pointer changes to a fleur shape and drag the mouse to move the rectangle. Resizing the rectangle. Move the pointer over any of the edges or corners of the rectangle, the shape changes to a double-ended arrow, . Click and drag the edge or corner using the mouse. Changing the color of the rectangle. Move the pointer inside the rectangle. Right-click and select Set Color from the context menu. 3-509 imrect Interactive Behavior Description Retrieving the coordinates of the current position Move the pointer inside the polygon. Right-click and select Copy Position from the context menu. imrect copies a four-element position vector to the clipboard. Preserve the current aspect ratio of the rectangle during interactive resizing. Move the pointer inside the rectangle. Right-click and select Fix Aspect Ratio from the context menu. Methods Each imrect object supports a number of methods, listed below. Type methods imrect to see a list of the methods. addNewPositionCallback — Add new-position callback to ROI object See imroi for information. createMask — Create mask within image See imroi for information. delete — Delete ROI object See imroi for information. getColor — Get color used to draw ROI object See imroi for information. getPosition — Return current position of rectangle pos = getPosition(h) returns the current position of the rectangle h. The returned position, pos, is a 1-by-4 array [xmin ymin width height]. getPositionConstraintFcn — Return function handle to current position constraint function See imroi for information. removeNewPositionCallback — Remove new-position callback from ROI object. See imroi for information. 3-510 imrect resume — Resume execution of MATLAB command line See imroi for information. setColor — Set color used to draw ROI object See imroi for information. setConstrainedPosition — Set ROI object to new position See imroi for information. setFixedAspectRatioMode — Control whether aspect ratio preserved during resize setFixedAspectRatioMode(h,TF) sets the interactive resize behavior of the rectangle h. TF is a logical scalar. True means that the current aspect ratio is preserved during interactive resizing. False means that interactive resizing is not constrained. setPosition — Set rectangle to new position setPosition(h,pos) sets the rectangle h to a new position. The new position, pos, has the form [xmin ymin width height]. setPositionConstraintFcn — Set position constraint function of ROI object See imroi for information. setResizable — Set resize behavior of rectangle setResizable(h,TF) sets whether the rectangle h may be resized interactively. TF is a logical scalar. wait — Block MATLAB command line until ROI creation is finished See imroi for information. Tips If you use imrect with an axes that contains an image object, and do not specify a position constraint function, users can drag the rectangle outside the extent of the image. When used with an axes created by the plot function, the axes limits automatically expand to accommodate the movement of the rectangle. When the API function setResizable is used to make the rectangle non-resizable, the Fix Aspect Ratio context menu item is not provided. 3-511 imrect Examples Example 1 Display updated position in the title. Specify a position constraint function using makeConstrainToRectFcn to keep the rectangle inside the original Xlim and Ylim ranges. figure, imshow('cameraman.tif'); h = imrect(gca, [10 10 100 100]); addNewPositionCallback(h,@(p) title(mat2str(p,3))); fcn = makeConstrainToRectFcn('imrect',get(gca,'XLim'),get(gca,'YLim')); setPositionConstraintFcn(h,fcn); Now drag the rectangle using the mouse. Example 2 Interactively place a rectangle by clicking and dragging. Use wait to block the MATLAB command line. Double-click on the rectangle to resume execution of the MATLAB command line. figure, imshow('pout.tif'); h = imrect; position = wait(h); See Also 3-512 imellipse | imfreehand | imline | impoint | impoly | imroi | makeConstrainToRectFcn imregionalmax Purpose Regional maxima Syntax BW = imregionalmax(I) BW = imregionalmax(I,conn) Description BW = imregionalmax(I) finds the regional maxima of I. imregionalmax returns the binary image BW that identifies the locations of the regional maxima in I. BW is the same size as I. In BW, pixels that are set to 1 identify regional maxima; all other pixels are set to 0. Regional maxima are connected components of pixels with a constant intensity value, and whose external boundary pixels all have a lower value. By default, imregionalmax uses 8-connected neighborhoods for 2-D images and 26-connected neighborhoods for 3-D images. For higher dimensions, imregionalmax uses conndef(ndims(I),'maximal'). BW = imregionalmax(I,conn) computes the regional maxima of I using the specified connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by- ...-by-3 matrix of 0’s and 1’s. The 1-valued 3-513 imregionalmax elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. Class Support I can be any nonsparse, numeric class and any dimension. BW is logical. Examples Create a sample image with several regional maxima. A = 10*ones(10,10); A(2:4,2:4) = 22; A(6:8,6:8) = 33; A(2,7) = 44; A(3,8) = 45; A(4,9) = 44; A = 10 10 10 10 22 22 10 22 22 10 22 22 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 22 22 22 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 33 33 33 10 10 10 44 10 10 10 33 33 33 10 10 10 10 45 10 10 33 33 33 10 10 10 10 10 44 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 Find the regional maxima. regmax = imregionalmax(A) regmax = 0 0 0 0 0 1 1 1 0 1 1 1 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 3-514 0 0 0 0 0 0 0 0 0 0 0 0 1 1 0 0 0 0 0 1 1 0 0 1 0 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 imregionalmax 0 0 0 See Also 0 0 0 0 0 0 0 0 0 0 0 0 1 0 0 1 0 0 1 0 0 0 0 0 0 0 0 conndef | imextendedmax | imhmax | imreconstruct | imregionalmin 3-515 imregionalmin Purpose Regional minima Syntax BW = imregionalmin(I) BW = imregionalmin(I,conn) Description BW = imregionalmin(I) computes the regional minima of I. The output binary image BW has value 1 corresponding to the pixels of I that belong to regional minima and 0 otherwise. BW is the same size as I. Regional minima are connected components of pixels with a constant intensity value, and whose external boundary pixels all have a higher value. By default, imregionalmin uses 8-connected neighborhoods for 2-D images and 26-connected neighborhoods for 3-D images. For higher dimensions, imregionalmin uses conndef(ndims(I),'maximal'). BW = imregionalmin(I,conn) specifies the desired connectivity. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by- ...-by-3 matrix of 0’s and 1’s. The 1-valued elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. 3-516 imregionalmin Class Support I can be any nonsparse, numeric class and any dimension. BW is logical. Examples Create a 10-by-10 pixel sample image that contains two regional minima. A = 10*ones(10,10); A(2:4,2:4) = 2; A(6:8,6:8) = 7; A = 10 10 10 10 2 2 10 2 2 10 2 2 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 2 2 2 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 7 7 7 10 10 10 10 10 10 10 7 7 7 10 10 10 10 10 10 10 7 7 7 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 Pass the sample image A to imregionalmin. The function returns a binary image, the same size as A, in which pixels with the value 1 represent the regional minima in A. imregionalmin sets all other pixels in to zero (0). B = imregionalmin(A) B = 0 0 0 0 1 1 0 1 1 0 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 3-517 imregionalmin 0 See Also 3-518 0 0 0 0 0 0 0 0 0 conndef | imextendedmin | imhmin | imimposemin | imreconstruct | imregionalmax imregconfig Purpose Configurations for intensity-based registration Syntax [optimizer,metric] = imregconfig(modality) Description [optimizer,metric] = imregconfig(modality) creates optimizer and metric configurations that you pass to imregister to perform intensity-based image registration. imregconfig returns optimizer and metric with default settings to provide a basic registration configuration. Input Arguments modality - Image capture modality 'monomodal' | 'multimodal' Image capture modality describes how your images have been captured, specified as either 'monomodal' (captured on the same device) or 'multimodal' (captured on different devices). Output Arguments optimizer - Optimization configuration optimizer object Optimization configuration describes the method for optimizing the similarity metric, returned as one of the optimizer objects, registration.optimizer.RegularStepGradientDescent or registration.optimizer.OnePlusOneEvolutionary metric - Metric configuration metric object Metric configuration describes the image similarity metric to be optimized during registration, returned as one of the metric objects, registration.metric.MeanSquares or registration.metric.MattesMutualInformation. Tips • Your registration results can improve if you adjust the optimizer or metric settings. For example, if you increase the number of iterations in the optimizer, reduce the optimizer step size, or change 3-519 imregconfig the number of samples in a stochastic metric, the registration improves to a point, at the expense of performance. Definitions Monomodal Images captured on the same device. Monomodal images have similar brightness ranges. Multimodal Images captured on different devices. Multimodal images usually have different brightness ranges. Examples Create Optimizer and Metric Configurations to Register Images Captured on the Same Device Load the images into the workspace and display them. fixed = imread('pout.tif'); moving = imrotate(fixed, 5, 'bilinear', 'crop'); imshowpair(fixed, moving,'Scaling','joint'); 3-520 imregconfig Create the optimizer and metric. The two images in this example were captured on the same device, so we’ll set the modality to'monomodal'. [optimizer, metric] = imregconfig('monomodal') optimizer = registration.optimizer.RegularStepGradientDescent Properties: GradientMagnitudeTolerance: 1.000000e-04 MinimumStepLength: 1.000000e-05 MaximumStepLength: 6.250000e-02 MaximumIterations: 100 RelaxationFactor: 5.000000e-01 metric = 3-521 imregconfig registration.metric.MeanSquares This class has no properties. Pass optimizer and metric to imregister to perform the registration. movingRegistered = imregister(moving,fixed,'rigid',optimizer, metric); View the registered images figure imshowpair(fixed, movingRegistered,'Scaling','joint'); See Also 3-522 imshowpair | imregisterregistration.metric.MattesMutualInformation | registration.metric.MeanSquares | registration.optimizer.RegularStepGradientDescent | registration.optimizer.OnePlusOneEvolutionary | imregconfig Concepts • “Intensity-Based Automatic Image Registration” 3-523 imregister Purpose Intensity-based image registration Syntax movingRegistered = imregister(moving,fixed,transformType, optimizer,metric) movingRegistered = imregister(moving,fixed,transformType, optimizer,metric,Name,Value) Description movingRegistered = imregister(moving,fixed,transformType,optimizer,metric) transforms a 2-D or 3-D moving image so that it is registered with the fixed image. • Both moving and fixed images must be of the same dimensionality, either 2-D or 3-D movingRegistered = imregister(moving,fixed,transformType,optimizer,metric,Name,Value) specifies additional options with one or more Name,Value pair arguments. Input Arguments moving - Moving image grayscale image Moving image is the image to be transformed into alignment with a reference image, specified as a 2-D or 3-D grayscale image. Data Types single | double | int8 | int16 | int32 | uint8 | uint16 | uint32 fixed - Fixed image grayscale image Fixed image is the reference image in the target orientation, specified as a 2-D or 3-D grayscale image. Data Types single | double | int8 | int16 | int32 | uint8 | uint16 | uint32 3-524 imregister transformType - Transform type 'translation' | 'rigid' | 'similarity' | 'affine' Transform type is the geometric transformation to be applied to the moving image, specified as one of the text strings listed in this table. Transform Type Description 'translation' (x,y) translation. 'rigid' Rigid transformation consisting of translation and rotation. 'similarity' Nonreflective similarity transformation consisting of translation, rotation, and scale. 'affine' Affine transformation consisting of translation, rotation, scale, and shear. optimizer - Optimization configuration optimizer object Optimizer configuration describes the method for optimizing the similarity metric, specified as an optimizer object returned by the imregconfig function: registration.optimizer.RegularStepGradientDescent or registration.optimizer.OnePlusOneEvolutionary. metric - Metric configuration metric object Metric configuration describes the image similarity metric to be optimized during registration, specified as a metric object returned by the imregconfig function: registration.metric.MeanSquares or registration.metric.MattesMutualInformation. Name-Value Pair Arguments Specify optional comma-separated pairs of Name,Value arguments, where Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can 3-525 imregister specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN. Example: 'DisplayOptimization',1 enables the verbose optimization mode. DisplayOptimization - Verbose optimization flag false (default) | true Verbose optimization flag controls whether optimization information is displayed in the command window during the registration process, specified as the comma-separated pair consisting of 'DisplayOptimization' and either true or false. Data Types logical PyramidLevels - Number of pyramid levels 3 (default) | positive integer Number of pyramid levels that imregister uses during the registration process, specified as the comma-separated pair consisting of 'PyramidLevels' and a positive integer. Example: 'PyramidLevels',4 sets the number of pyramid levels to 4. Data Types double Output Arguments movingRegistered - Transformed moving image matrix Transformed moving image, returned as a matrix. Any fill pixels introduced that do not correspond to locations in the original image are 0. Tips • Create optimizer and metric with the imregconfig function before calling imregister. • Your registration results can improve if you adjust the optimizer or metric settings. For example, if you increase the number of 3-526 imregister iterations in the optimizer, reduce the optimizer step size, or change the number of samples in a stochastic metric, the registration improves to a point, at the expense of performance. • If the spatial scaling of your images differs by more than 10%, you should resize them with imresize before registering them. • Use imshowpair or imfuse to visualize the results of registration. • Use imregister to register several images in an automated workflow. Definitions Monomodal Images captured on the same device. Monomodal images have similar brightness ranges. Multimodal Images captured on different devices. Multimodal images usually have different brightness ranges. Examples Register 2–D Images from Same Capture Device Read the reference image and create an unregistered copy. fixed = imread('pout.tif'); moving = imrotate(fixed, 5, 'bilinear', 'crop'); View the misaligned images. imshowpair(fixed, moving,'Scaling','joint'); 3-527 imregister Create a configuration suitable for registering images from the same sensor. [optimizer, metric] = imregconfig('monomodal') optimizer = registration.optimizer.RegularStepGradientDescent Properties: GradientMagnitudeTolerance: MinimumStepLength: MaximumStepLength: MaximumIterations: RelaxationFactor: metric = 3-528 1.000000e-04 1.000000e-05 6.250000e-02 100 5.000000e-01 imregister registration.metric.MeanSquares This class has no properties. Now modify the optimizer configuration to get more precision. optimizer.MaximumIterations = 300; optimizer.MinimumStepLength = 5e-4; Perform the registration. movingRegistered = imregister(moving,fixed,'rigid',optimizer,metric); View registered images. figure imshowpair(fixed, movingRegistered,'Scaling','joint'); 3-529 imregister See Also imregconfig | imshowpair | imfuse | imtransformregistration.metric.MattesMutualInformation | registration.metric.MeanSquares | registration.optimizer.RegularStepGradientDescent | registration.optimizer.OnePlusOneEvolutionary | Related Examples • “Registering Multimodal MRI Images” Concepts • “Intensity-Based Automatic Image Registration” 3-530 imresize Purpose Resize image Syntax B = imresize(A, scale) B = imresize(A, [numrows numcols]) [Y newmap] = imresize(X, map, scale) [...] = imresize(..., method) [...] = imresize(..., parameter, value, ...) Description B = imresize(A, scale) returns image B that is scale times the size of A. The input image A can be a grayscale, RGB, or binary image. If scale is between 0 and 1.0, B is smaller than A. If scale is greater than 1.0, B is larger than A. B = imresize(A, [numrows numcols]) returns image B that has the number of rows and columns specified by [numrows numcols]. Either numrows or numcols may be NaN, in which case imresize computes the number of rows or columns automatically to preserve the image aspect ratio. [Y newmap] = imresize(X, map, scale) resizes the indexed image X. scale can either be a numeric scale factor or a vector that specifies the size of the output image ([numrows numcols]). By default, imresize returns a new, optimized colormap (newmap) with the resized image. To return a colormap that is the same as the original colormap, use the 'Colormap' parameter (see below). = imresize(..., method) resizes the indexed image. method can be (1) a text string that specifies a general interpolation method, (2) a text string that specifies an interpolation kernel, or (3) a two-element cell array that specifies an interpolation kernel. [...] 3-531 imresize (1) Text String Specifying Interpolation Method Method Name Description 'nearest' Nearest-neighbor interpolation; the output pixel is assigned the value of the pixel that the point falls within. No other pixels are considered. 'bilinear' Bilinear interpolation; the output pixel value is a weighted average of pixels in the nearest 2-by-2 neighborhood 'bicubic' Bicubic interpolation (the default); the output pixel value is a weighted average of pixels in the nearest 4-by-4 neighborhood (2) Text String Specifying Interpolation Kernel Kernel Name Description 'box' Box-shaped kernel 'triangle' Triangular kernel (equivalent to 'bilinear') 'cubic' Cubic kernel (equivalent to 'bicubic') 3-532 'lanczos2' Lanczos-2 kernel 'lanczos3' Lanczos-3 kernel imresize (3) Two-element Cell Array Specifying Interpolation Kernel Form Description {f,w} f is a function handle for a custom interpolation kernel and w is the custom kernel’s width.f(x) must be zero outside the interval -w/2 <= x < w/2. Your function handle f may be called with a scalar or a vector input. = imresize(..., parameter, value, ...) you can control various aspects of the resizing operation by specifying parameter/value pairs with any of the previous syntaxes. The following table lists these parameters. [...] Parameter Value 'Antialiasing' A Boolean value that specifies whether to perform antialiasing when shrinking an image. The default value depends on the interpolation method. If the method is nearest-neighbor ('nearest'), the default is false; for all other interpolation methods, the default is true. ’Colormap' A text string that specifies whether imresize returns an optimized colormap or the original colormap (Indexed images only). If set to 'original', the output colormap (newmap) is the same as the input colormap (map). If set to 'optimized', imresize returns a new optimized colormap. The default value is 'optimized'. 'Dither' A Boolean value that specifies whether to perform color dithering (Indexed images only). The default value is true. 3-533 imresize Tips Parameter Value 'Method' As described above 'OutputSize' A two-element vector, [numrows numcols], that specifies the size of the output image. If you specify NaN for one of the values, imresize computes the value of the dimension to preserve the aspect ratio of the original image. 'Scale' A scalar or two-element vector that specifies the resize scale factors. If you specify a scalar, imresize uses the value as the scale factor for each dimension. If you specify a vector, imresize uses the individual values as the scale factors for the row and column dimensions, respectively. The function imresize changed in version 5.4 (R2007a). Previous versions of the Image Processing Toolbox used a somewhat different algorithm by default. If you need the same results produced by the previous implementation, use the function imresize_old. For bicubic interpolation, the output image may have some values slightly outside the range of pixel values in the input image. This may also occur for user-specified interpolation kernels. Class Support The input image can be numeric or logical and it must be nonsparse. The output image is of the same class as the input image. An input image that is an indexed image can be uint8, uint16, or double. Examples Shrink by factor of two using the defaults of bicubic interpolation and antialiasing. I = imread('rice.png'); J = imresize(I, 0.5); figure, imshow(I), figure, imshow(J) 3-534 imresize Shrink by factor of two using nearest-neighbor interpolation. (This is the fastest method, but it has the lowest quality.) J2 = imresize(I, 0.5, 'nearest'); Resize an indexed image [X, map] = imread('trees.tif'); [Y, newmap] = imresize(X, map, 0.5); imshow(Y, newmap) Resize an RGB image to have 64 rows. The number of columns is computed automatically. RGB = imread('peppers.png'); RGB2 = imresize(RGB, [64 NaN]); See Also imrotate | imtransform | tformarray | interp2 3-535 imroi Purpose Region-of-interest (ROI) base class Description Because the imroi class is abstract, creating an instance of the imroi class is not allowed. Methods imroi supports the following methods. Type methods imroi to see a complete list. addNewPositionCallback — Add new-position callback to ROI object id = addNewPositionCallback(h,fcn) adds the function handle fcn to the list of new-position callback functions of the ROI object h. Whenever the ROI object changes its position each function in the list is called with the syntax: fcn(pos) where pos is of the form returned by the object’s getPosition method. The return value, id, is used only with removeNewPositionCallback. createMask — Create mask within image BW = createMask(h) returns a mask, or binary image, that is the same size as the input image with 1s inside the ROI object h and 0s everywhere else. The input image must be contained within the same axes as the ROI. BW = createMask(h,h_im) returns a mask the same size as the image h_im with 1s inside the ROI object h and 0s outside. This syntax is required when the axes that contain the ROI hold more than one image. delete — Delete ROI object delete(h) deletes the ROI object h getColor — Get color used to draw ROI object. color = getColor(h) gets the color used to draw the ROI object h. The three-element vector color specifies an RGB triplet. getPosition — Return current position of ROI object pos = getPosition(h) returns current position of the ROI object h. 3-536 imroi getPositionConstraintFcn — Return function handle to current position constraint function fcn = getPositionConstraintFcn(h) returns a function handle fcn to the current position constraint function of the ROI object h. removeNewPositionCallback — Remove new-position callback from ROI object removeNewPositionCallback(h,id) removes the corresponding function from the new-position callback list of the ROI object h. id is the identifier returned by the addNewPositionCallback method. resume — Resume execution of MATLAB command line resume(h) resumes execution of the MATLAB command line. When called after a call to wait, resume causes wait to return an accepted position. The resume method is useful when you need to exit wait from a callback function. setColor — Set color used to draw ROI object. setColor(h,new_color) sets the color used to draw the ROI object h. new_color can be a three-element vector specifying an RGB triplet, or a text string specifying the long or short name of a predefined color, such as 'white' or 'w'. See ColorSpec for a list of predefined colors. setConstrainedPosition — Set ROI object to new position setConstrainedPosition(h,candidate_position) sets the ROI object h to a new position. The candidate position is subject to the position constraint function. candidate_position is of the form expected by the setPosition method. setPositionConstraintFcn — Set position constraint function of ROI object setPositionConstraintFcn(h,fcn) sets the position constraint function of the ROI object h to be the specified function handle, fcn. Whenever the object is moved because of a mouse drag, the constraint function is called using the syntax: constrained_position = fcn(new_position) where new_position is of the form returned by the getPosition method. You can use the makeConstrainToRectFcn to create this function. 3-537 imroi wait — Block MATLAB command line until ROI creation is finished accepted_pos = wait(h) blocks execution of the MATLAB command line until you finish positioning the ROI object h. You indicate completion by double-clicking on the ROI object. The returned position, accepted_pos, is of the form returned by the object’s getPosition method. See Also 3-538 makeConstrainToRectFcn imrotate Purpose Rotate image Syntax B = imrotate(A,angle) B = imrotate(A,angle,method) B = imrotate(A,angle,method,bbox) Description B = imrotate(A,angle) rotates image A by angle degrees in a counterclockwise direction around its center point. To rotate the image clockwise, specify a negative value for angle. imrotate makes the output image B large enough to contain the entire rotated image. imrotate uses nearest neighbor interpolation, setting the values of pixels in B that are outside the rotated image to 0 (zero). B = imrotate(A,angle,method) rotates image A, using the interpolation method specified by method. method is a text string that can have one of these values. The default value is enclosed in braces ({}). Value Description {'nearest'} Nearest-neighbor interpolation 'bilinear' Bilinear interpolation 'bicubic' Bicubic interpolation Note Bicubic interpolation can produce pixel values outside the original range. B = imrotate(A,angle,method,bbox) rotates image A, where bbox specifies the size of the returned image. bbox is a text string that can have one of the following values. The default value is enclosed in braces ({}). 3-539 imrotate Value Description 'crop' Make output image B the same size as the input image A, cropping the rotated image to fit {'loose'} Make output image B large enough to contain the entire rotated image. B is generally larger than A. Class Support The input image can be numeric or logical. The output image is of the same class as the input image. Performance Note This function may take advantage of hardware optimization for data types uint8, uint16, and single to run faster. Examples Read a solar spectra image, stored in FITS format, and rotate the image to bring it into horizontal alignment. A rotation of -1 degree is all that is required. I = fitsread('solarspectra.fts'); I = mat2gray(I); J = imrotate(I,-1,'bilinear','crop'); figure, imshow(I) figure, imshow(J) See Also 3-540 imcrop | imresize | imtransform | tformarray imsave Purpose Save Image Tool Syntax imsave imsave(h) [filename, user_canceled] = imsave( ) Description imsave creates a Save Image tool in a separate figure that is associated with the image in the current figure, called the target image. The Save Image tool displays an interactive file chooser dialog box (shown below) in which you can specify a path and filename. When you click Save, the Save Image tool writes the target image to a file using the image file format you select in the Files of Type menu. imsave uses imwrite to save the image, using default options. Select image file format. 3-541 imsave If you specify a filename that already exists, imsave displays a warning message. Select Yes to use the filename or No to return to the dialog to select another filename. If you select Yes, the Save Image tool attempts to overwrite the target file. Note The Save Image tool is modal; it blocks the MATLAB command line until you respond. imsave(h) creates a Save Image tool associated with the image specified by the handle h. h can be an image, axes, uipanel, or figure handle. If h is an axes or figure handle, imsave uses the first image returned by findobj(h,'Type','image'). [filename, user_canceled] = imsave( ) returns the full path to the file selected in filename. If you press the Cancel button, imsave setsuser_canceled to true (1); otherwise, false (0). Remarks In contrast to the Save as option in the figure File menu, the Save Image tool saves only the image displayed in the figure. The Save as option in the figure window File menu saves the entire figure window, not just the image. Examples imshow peppers.png imsave See Also imformats | imgetfile | imputfile | imwrite 3-542 imscrollpanel Purpose Scroll panel for interactive image navigation Syntax hpanel = imscrollpanel(hparent, himage) Description hpanel = imscrollpanel(hparent, himage) creates a scroll panel containing the target image (the image to be navigated). himage is a handle to the target image. hparent is a handle to the figure or uipanel that will contain the new scroll panel. The function returns hpanel, a handle to the scroll panel, which is a uipanel object. A scroll panel makes an image scrollable. If the size or magnification makes an image too large to display in a figure on the screen, the scroll panel displays a portion of the image at 100% magnification (one screen pixel represents one image pixel). The scroll panel adds horizontal and vertical scroll bars to enable navigation around the image. imscrollpanel changes the object hierarchy of the target image. Instead of the familiar figure->axes->image object hierarchy, imscrollpanel inserts several uipanel and uicontrol objects between the figure and the axes object. API Functions A scroll panel contains a structure of function handles, called an API. You can use the functions in this API to manipulate the scroll panel. To retrieve this structure, use the iptgetapi function, as in the following example. api = iptgetapi(hpanel) This table lists the scroll panel API functions, in the order they appear in the structure. 3-543 imscrollpanel Function Description setMagnification Sets the magnification of the target image in units of screen pixels per image pixel. mag = api.setMagnification(new_mag) where new_mag is a scalar magnification factor. getMagnification Returns the current magnification factor of the target image in units of screen pixels per image pixel. mag = api.getMagnification() Multiply mag by 100 to convert to percentage. For example if mag=2, the magnification is 200%. setMagnificationAndCenter Changes the magnification and makes the point cx,cy in the target image appear in the center of the scroll panel. This operation is equivalent to a simultaneous zoom and recenter. api.setMagnificationAndCenter(mag,cx,cy) findFitMag Returns the magnification factor that would make the target image just fit in the scroll panel. mag = api.findFitMag() setVisibleLocation Moves the target image so that the specified location is visible. Scrollbars update. api.setVisibleLocation(xmin, ymin) api.setVisibleLocation([xmin ymin]) 3-544 imscrollpanel Function Description getVisibleLocation Returns the location of the currently visible portion of the target image. loc = api.getVisibleLocation() where loc is a vector [xmin ymin]. getVisibleImageRect Returns the current visible portion of the image. r = api.getVisibleImageRect() where r is a rectangle [xmin ymin width height]. addNewMagnificationCallback Adds the function handle fcn to the list of new-magnification callback functions. id = api.addNewMagnificationCallback(fcn) Whenever the scroll panel magnification changes, each function in the list is called with the syntax: fcn(mag) where mag is a scalar magnification factor. The return value, id, is used only with removeNewMagnificationCallback. removeNewMagnificationCallback Removes the corresponding function from the new-magnification callback list. api.removeNewMagnificationCallback(id) where id is the identifier returned by addNewMagnificationCallback. 3-545 imscrollpanel Function Description addNewLocationCallback Adds the function handle fcn to the list of new-location callback functions. id = api.addNewLocationCallback(fcn) Whenever the scroll panel location changes, each function in the list is called with the syntax: fcn(loc) where loc is [xmin ymin]. The return value, id, is used only with removeNewLocationCallback. removeNewLocationCallback Removes the corresponding function from the new-location callback list. api.removeNewLocationCallback(id) where id is the identifier returned by addNewLocationCallback. replaceImage api.replaceImage(...,PARAM1,VAL1,PARAM2, VAL2,...) replaces the image displayed in the scroll panel. api.replaceImage(I) api.replaceImage(BW) api.replaceImage(RGB) api.replaceImage(I,MAP) api.replaceImage(filename) By default, the new image data is displayed centered, at 100% magnification. The image handle is unchanged. 3-546 imscrollpanel Function Description The parameters you can specify include many of the parameters supported by imshow, including 'Colormap', 'DisplayRange', and 'InitialMagnification'. In addition, you can use the 'PreserveView' parameter to preserve the current magnification and centering of the image during replacement. Specify the logical scalar True to preserve current centering and magnification. Parameter names can be abbreviated, and case does not matter. Note Scrollbar navigation as provided by imscrollpanel is incompatible with the default MATLAB figure navigation buttons (pan, zoom in, zoom out). The corresponding menu items and toolbar buttons should be removed in a custom GUI that includes a scrollable uipanel created by imscrollpanel. When you run imscrollpanel, it appears to take over the entire figure because, by default, an hpanel object has 'Units' set to 'normalized' and 'Position' set to [0 0 1 1]. If you want to see other children of hparent while using your new scroll panel, you must manually set the 'Position' property of hpanel. Examples Create a scroll panel with a Magnification Box and an Overview tool. 1 Create a scroll panel. hFig = figure('Toolbar','none',... 'Menubar','none'); hIm = imshow('saturn.png'); hSP = imscrollpanel(hFig,hIm); set(hSP,'Units','normalized',... 'Position',[0 .1 1 .9]) 2 Add a Magnification Box and an Overview tool. 3-547 imscrollpanel hMagBox = immagbox(hFig,hIm); pos = get(hMagBox,'Position'); set(hMagBox,'Position',[0 0 pos(3) pos(4)]) imoverview(hIm) 3 Get the scroll panel API to programmatically control the view. api = iptgetapi(hSP); 4 Get the current magnification and position. mag = api.getMagnification(); r = api.getVisibleImageRect(); 5 View the top left corner of the image. api.setVisibleLocation(0.5,0.5) 6 Change the magnification to the value that just fits. api.setMagnification(api.findFitMag()) 7 Zoom in to 1600% on the dark spot. api.setMagnificationAndCenter(16,306,800) See Also immagbox | imoverview | imoverviewpanel | imtool | iptgetapi How To • “Adding Navigation Aids to a GUI” 3-548 imshow Purpose Display image Note • The syntax imshow(x,y,...) has been removed. Use the imshow(...,'XData',x,'YData',y) syntax instead. • The syntax imshow(I,N) has been removed. Your grayscale image will be displayed using 256 shades of gray. • The syntax imshow(...,'truesize') has been removed. Use the imshow(...,'InitialMagnification',100) syntax instead. • The syntax imshow(...,'notruesize') has been removed. Use the imshow(...,'InitialMagnification','fit') syntax instead. Syntax imshow(I) imshow(I,[low high]) imshow(RGB) imshow(BW) imshow(X,map) imshow(filename) himage = imshow(...) imshow(..., param1, val1, param2, val2,...) Description imshow(I) displays the grayscale image I. imshow(I,[low high]) displays the grayscale image I, specifying the display range for I in [low high]. The value low (and any value less than low) displays as black; the value high (and any value greater than high) displays as white. Values in between are displayed as intermediate shades of gray, using the default number of gray levels. If you use an empty matrix ([]) for [low high], imshow uses [min(I(:)) max(I(:))]; that is, the minimum value in I is displayed as black, and the maximum value is displayed as white. imshow(RGB) displays the truecolor image RGB. 3-549 imshow imshow(BW) displays the binary image BW. imshow displays pixels with the value 0 (zero) as black and pixels with the value 1 as white. imshow(X,map) displays the indexed image X with the colormap map. A color map matrix may have any number of rows, but it must have exactly 3 columns. Each row is interpreted as a color, with the first element specifying the intensity of red light, the second green, and the third blue. Color intensity can be specified on the interval 0.0 to 1.0. imshow(filename) displays the image stored in the graphics file filename. The file must contain an image that can be read by imread or dicomread. imshow calls imread or dicomread to read the image from the file, but does not store the image data in the MATLAB workspace. If the file contains multiple images, imshow displays the first image in the file. The file must be in the current directory or on the MATLAB path. himage = imshow(...) returns the handle to the image object created by imshow. imshow(..., param1, val1, param2, val2,...) displays the image, specifying parameters and corresponding values that control various aspects of the image display. The following table lists all imshow parameters in alphabetical order. Parameter names can be abbreviated, and case does not matter. Parameter Value 'Border' Text string that controls whether imshow includes a border around the image displayed in the figure window. Valid strings are 'tight' and 'loose'. Note: There can still be a border if the image is very small, or if there are other objects besides the image and its axes in the figure. By default, the border is set to the value returned by iptgetpref('ImshowBorder'). 'Colormap' 3-550 2–D, real, m-by-3 matrix specifying a colormap. imshow uses this to set the figure’s colormap property. Use this parameter to view grayscale images in false color. If imshow Parameter Value you specify an empty colormap ([]), imshow ignores this parameter. 'DisplayRange' Two-element vector [LOW HIGH] that controls the display range of a grayscale image. See the imshow(I,[low high]) syntax for more details about how to set this parameter. Note Including the parameter name is optional, except when the image is specified by a filename. The syntax imshow(I,[LOW HIGH]) is equivalent to imshow(I,'DisplayRange',[LOW HIGH]). However, the 'DisplayRange' parameter must be specified when calling imshow with a filename, for example imshow(filename,'DisplayRange'[LOW HIGH]). 'InitialMagnification' A numeric scalar value, or the text string 'fit', that specifies the initial magnification used to display the image. When set to 100, imshow displays the image at 100% magnification (one screen pixel for each image pixel). When set to 'fit', imshow scales the entire image to fit in the window. On initial display, imshow always displays the entire image. If the magnification value is large enough that the image would be too big to display on the screen, imshow warns and displays the image at the largest magnification that fits on the screen. By default, the initial magnification parameter is set to the value returned by iptgetpref('ImshowInitialMagnification'). If the image is displayed in a figure with its 'WindowStyle' property set to 'docked', imshow warns and displays the image at the largest magnification that fits in the figure. 3-551 imshow Parameter Value Note: If you specify the axes position (using subplot or axes), imshow ignores any initial magnification you might have specified and defaults to the 'fit' behavior. When used with the 'Reduce' parameter, only 'fit' is allowed as an initial magnification. 'Parent' Handle of an axes that specifies the parent of the image object that will be created by imshow. 'Reduce' Logical value that specifies whether imshow subsamples the image in filename. The 'Reduce' parameter is only valid for TIFF images and you must specify a file name. Use this parameter to display overviews of very large images. 'XData' Two-element vector that establishes a nondefault spatial coordinate system by specifying the image XData. The value can have more than two elements, but only the first and last elements are actually used. 'YData' Two-element vector that establishes a nondefault spatial coordinate system by specifying the image YData. The value can have more than two elements, but only the first and last elements are actually used. Note If you are building a GUI where you want to control the figure and axes properties, be sure to use the imshow(..., 'Parent', ax) syntax. Class Support 3-552 A truecolor image can be uint8, uint16, single, or double. An indexed image can be logical, uint8, single, or double. A grayscale image can be logical, uint8, int16, uint16, single, or double. A binary image must be of class logical. imshow For grayscale images of class single or double, the default display range is [0 1]. If your image’s data range is much larger or smaller than the default display range, you might need to experiment with setting the display range to see features in the image that would not be visible using the default display range. For all grayscale images having integer types, the default display range is [intmin(class(I)) intmax(class(I))]. If your image is int8, int16, uint32, int32 or single, the CData in the resulting image object will be double. For all other classes, the CData matches the input image class. Related Toolbox Preferences You can use the iptsetpref function to set several toolbox preferences that modify the behavior of imshow. • 'ImshowBorder' controls whether imshow displays the image with a border around it. • 'ImshowAxesVisible' controls whether imshow displays the image with the axes box and tick labels. • 'ImshowInitialMagnification' controls the initial magnification for image display, unless you override it in a particular call by specifying imshow(...,'InitialMagnification',initial_mag). For more information about these preferences, see iptprefs. Tips imshow is the toolbox’s fundamental image display function, optimizing figure, axes, and image object property settings for image display. imtool provides all the image display capabilities of imshow but also provides access to several other tools for navigating and exploring images, such as the Pixel Region tool, Image Information tool, and the Adjust Contrast tool. imtool presents an integrated environment for displaying images and performing some common image processing tasks. The imshow function is not supported when MATLAB is started with the -nojvm option. 3-553 imshow You can access imshow through the Plot Selector workspace tool, which . In your is represented by this icon: workspace, select the data you want to display. The Plot Selector icon changes to look like this: . Scroll down to Image Processing Toolbox Plots. Select imshow(I). Examples Display an image from a file. imshow('board.tif') Display an indexed image. [X,map] = imread('trees.tif'); imshow(X,map) Display a grayscale image. I = imread('cameraman.tif'); imshow(I) Display the same grayscale image, adjusting the display range. h = imshow(I,[0 80]); See Also 3-554 imread | imtool | iptprefs | subimage | truesize | warp | image | imagesc imshowpair Purpose Compare differences between images Syntax imshowpair(A,B) imshowpair(A,B,method) imshowpair( ___ ,Name,Value) Description imshowpair(A,B) displays the differences between images A and B. If A and B are different sizes, the smaller dimensions are padded with zeros on the bottom and right edges so that the two image are the same size in the display. imshowpair(A,B,method) uses the visualization method specified by method. imshowpair( ___ ,Name,Value) specifies additional options with one or more Name,Value pair arguments, using any of the previous syntaxes. Input Arguments A,B - Input images grayscale images | truecolor images | binary images Input images to be combined into a composite image, specified as any combination of grayscale, truecolor, or binary images. Data Types single | double | int8 | int16 | int32 | int64 | uint16 | uint32 | uint64 | logical method - Visualization method 'falsecolor' (default) | 'blend' | 'diff' | 'montage' Visualization method for creating the composite image, specified as one of the text strings in the following table. 3-555 imshowpair Method Description 'falsecolor' Creates a composite RGB image showing A and B overlaid in different color bands. Gray regions in the composite image show where the two images have the same intensities. Magenta and green regions show where the intensities are different. This is the default method. 'blend' Overlays A and B using alpha blending. 'diff' Creates a difference image from A and B. 'montage' Places A and B next to each other in the same image. Example: imshowpair(A,B,'montage') displays A and B next to each other. Name-Value Pair Arguments Specify optional comma-separated pairs of Name,Value arguments, where Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN. Example: 'Scaling','joint' scales the intensity values of A and B together as a single data set. Scaling - Image data scaling option 'independent' (default) | 'joint' | 'none' Image data scaling option that controls the intensity scaling of the pixels representing the input images in the output image, specified as the comma-separated pair consisting of 'Scaling' and one of the text strings in the following table. 3-556 imshowpair 'independent' Scales the intensity values of A and B independently from each other. 'joint' Scales the intensity values in the images jointly as if they were together in the same image. This option is useful when you want to visualize registrations of monomodal images, where one image contains fill values that are outside the dynamic range of the other image. 'none' No additional scaling. ColorChannels - Output color channel for each input image [R G B] | `red-cyan' | `green-magenta' (default) Output color channel for each input image, specified as the comma-separated pair consisting of `ColorChannels' and one of the text strings from the following table. `ColorChannels' can only be used with the 'falsecolor' visualization method. Tips [R G B] A three element vector that specifies which image to assign to the red, green, and blue channels. The R, G, and B values must be 1 (for the first input image), 2 (for the second input image), and 0 (for neither image). 'red-cyan' A shortcut for the vector [1 2 2], which is suitable for red/cyan stereo anaglyphs. 'green-magenta' A shortcut for the vector [1 2 2], which is a high contrast option, ideal for people with many kinds of color blindness. • Use imfuse to create composite visualizations that you can save to a file. Use imshowpair to display composite visualizations to the screen. 3-557 imshowpair Examples Display Two Images That Differ by Rotation and Offset Display a pair of grayscale images with two different visualization methods, 'diff' and 'blend'. Load an image into the workspace. Create a copy with a rotation and offset applied. A = imread('cameraman.tif'); B = imrotate(A,5,'bicubic','crop'); Display the difference of A and B. imshowpair(A,B,'diff'); Display a blended overlay A and B. figure; imshowpair(A,B,'blend','Scaling','joint'); 3-558 imshowpair Display Two Images with Different Brightness Ranges Load an image into the workspace. Create a copy and apply rotation, offset, and a brightness adjustment. A = dicomread('CT-MONO2-16-ankle.dcm'); B = double(imrotate(A,10,'bicubic','crop')); B = B * 0.2; Display the images with the default, 'falsecolor', method and apply brightness scaling independently to each image. figure; imshowpair(A,B,'Scaling','independent'); 3-559 imshowpair See Also 3-560 imfuse | imregister | imshow | imtransform imsubtract Purpose Subtract one image from another or subtract constant from image Syntax Z = imsubtract(X,Y) Description Z = imsubtract(X,Y) subtracts each element in array Y from the corresponding element in array X and returns the difference in the corresponding element of the output array Z. X and Y are real, nonsparse numeric arrays of the same size and class, or Y is a double scalar. The array returned, Z, has the same size and class as X unless X is logical, in which case Z is double. If X is an integer array, elements of the output that exceed the range of the integer type are truncated, and fractional values are rounded. Note On Intel architecture processors, imsubtract can take advantage of the Intel Integrated Performance Primitives (Intel IPP) library, thus accelerating its execution time. The (Intel IPP) library is activated only if array X is of class uint8, int16, or single. Examples Subtract two uint8 arrays. Note that negative results are rounded to 0. X Y Z Z = uint8([ 255 10 75; 44 225 100]); = uint8([ 50 50 50; 50 50 50 ]); = imsubtract(X,Y) = 205 0 0 175 25 50 Estimate and subtract the background of an image: I = imread('rice.png'); background = imopen(I,strel('disk',15)); Ip = imsubtract(I,background); imshow(Ip,[]) 3-561 imsubtract Subtract a constant value from an image: I = imread('rice.png'); Iq = imsubtract(I,50); figure, imshow(I), figure, imshow(Iq) See Also 3-562 imabsdiff | imadd | imcomplement | imdivide | imlincomb | immultiply | ippl imtool Purpose Image Tool Syntax imtool imtool(I) imtool(I,[low high]) imtool(RGB) imtool(BW) imtool(X,map) imtool(filename) hfigure = imtool(...) imtool close all imtool(...,param1,val1,param2,val2,...) Description imtool opens a new Image Tool in an empty state. Use the File menu options Open or Import from Workspace to choose an image for display. imtool(I) displays the grayscale image I. imtool(I,[low high]) displays the grayscale image I, specifying the display range for I in the vector [low high]. The value low (and any value less than low) is displayed as black, the value high (and any value greater than high) is displayed as white. Values in between are displayed as intermediate shades of gray. imtool uses the default number of gray levels. If you use an empty matrix ([]) for [low high], imtool uses [min(I(:)) max(I(:))]; the minimum value in I is displayed as black, and the maximum value is displayed as white. imtool(RGB) displays the truecolor image RGB. imtool(BW) displays the binary image BW. Pixel values of 0 display as black; pixel values of 1 display as white. imtool(X,map) displays the indexed image X with colormap map. imtool(filename) displays the image contained in the graphics file filename. The file must contain an image that can be read by imread or dicomread or a reduced resolution dataset (R-Set) created by rsetwrite. If the file contains multiple images, the first one is 3-563 imtool displayed. The file must be in the current directory or on the MATLAB path. hfigure = imtool(...) returns hfigure, a handle to the figure created by imtool. close(Hfigure) closes the Image Tool. imtool close all closes all image tools. imtool(...,param1,val1,param2,val2,...) displays the image, specifying parameters and corresponding values that control various aspects of the image display. The following table lists all imshow parameters. Parameter names can be abbreviated, and case does not matter. Parameter Value 'Colormap' 2-D, real, m-by-3 matrix specifying the colormap to use for the figure’s colormap property. Use this parameter to view grayscale images in false color. If you specify an empty colormap ([]), imtool ignores this parameter. 'DisplayRange' Two-element vector [LOW HIGH] that controls the display range of a grayscale image. See the imtool(I,[low high]) syntax for more details about how to set this parameter. Note Including the parameter name is optional, except when the image is specified by a filename. The syntax imtool(I,[LOW HIGH]) is equivalent to imtool(I,'DisplayRange',[LOW HIGH]). However, the 'DisplayRange' parameter must be specified when calling imtool with a filename, as in the syntax imtool(filename,'DisplayRange',[LOW HIGH]). 'InitialMagnification' 3-564 One of two text strings: 'adaptive' or 'fit' or a numeric scalar value that specifies the initial magnification used to display the image. imtool Parameter Value When set to 'adaptive', the entire image is visible on initial display. If the image is too large to display on the screen, imtool displays the image at the largest magnification that fits on the screen. When set to 'fit', imtool scales the entire image to fit in the window. When set to a numeric value, the value specifies the magnification as a percentage. For example, if you specify 100, the image is displayed at 100% magnification (one screen pixel for each image pixel). Note When the image aspect ratio is such that less than one pixel would be displayed in either dimension at the requested magnification, imtool issues a warning and displays the image at 100%. By default, the initial magnification parameter is set to the value returned by iptgetpref('ImtoolInitialMagnification'). Class Support A truecolor image can be uint8, uint16, single, or double. An indexed image can be logical, uint8, single, or double. A grayscale image can be uint8, uint16, int16, single, or double. A binary image must be logical. A binary image is of class logical. For all grayscale images having integer types, the default display range is [intmin(class(I)) intmax(class(I))]. For grayscale images of class single or double, the default display range is [0 1]. If the data range of a single or double image is much larger or smaller than the default display range, you might need to 3-565 imtool experiment with setting the display range to see features in the image that would not be visible using the default display range. Large Data Support To view very large TIFF or NITF images that will not fit into memory, you can use rsetwrite to create a reduced resolution dataset (R-Set) viewable in imtool. R-Sets can also improve performance of imtool for large images that fit in memory. The following tools can be used with an R-Set: Overview, Zoom, Pan, Image Information, and Distance. Other tools, however, will not work with an R-Set. You cannot use the Pixel Region, Adjust Contrast, Crop Image, and Window/Level tools. Please note that the Pixel Information tool displays only the x and y coordinates of a pixel and not the associated intensity, index, or [R G B] values. Related Toolbox Preferences You can use the Image Processing Preferences dialog box to set toolbox preferences that modify the behavior of imtool. To access the dialog, select File > Preferences in the MATLAB desktop or Image Tool menu. Also, you can set preferences programmatically with iptsetpref. The imtool preferences include: • 'ImtoolInitialMagnification' controls the initial magnification for image display. To override this toolbox preference, specify the 'InitialMagnification' parameter when you call imtool, as follows: imtool(...,'InitialMagnification',initial_mag). • 'ImtoolStartWithOverview' controls whether the Overview tool opens automatically when you open an image using the Image Tool. Possible values: true— Overview tool opens when you open an image. {false}— Overview tool does not open when you open an image. This is the default behavior. For more information about these preferences, see iptprefs. 3-566 imtool Tips imshow is the toolbox’s fundamental image display function, optimizing figure, axes, and image object property settings for image display. imtool provides all the image display capabilities of imshow but also provides access to several other tools for navigating and exploring images, such as the Pixel Region tool, Image Information tool, and the Adjust Contrast tool. imtool presents an integrated environment for displaying images and performing some common image processing tasks. You can access imtool through the Plot Selector workspace tool, which . In your is represented by this icon: workspace, select the data you want to display. The Plot Selector icon changes to look like this: . Scroll down to Image Processing Toolbox Plots. Select imtool(I). Examples Display an image from a file. imtool('board.tif') Display an indexed image. [X,map] = imread('trees.tif'); imtool(X,map) Display a grayscale image. I = imread('cameraman.tif'); imtool(I) Display a grayscale image, adjusting the display range. h = imtool(I,[0 80]); close(h) See Also imageinfo | imcontrast | imoverview | impixelregion | imread | imshow | iptprefs | rsetwrite 3-567 imtophat Purpose Top-hat filtering Syntax IM2 = imtophat(IM,SE) IM2 = imtophat(IM,NHOOD) Description IM2 = imtophat(IM,SE) performs morphological top-hat filtering on the grayscale or binary input image IM. Top-hat filtering computes the morphological opening of the image (using imopen) and then subtracts the result from the original image. imtophat uses the structuring element SE, where SE is returned by strel. SE must be a single structuring element object, not an array containing multiple structuring element objects. IM2 = imtophat(IM,NHOOD) where NHOOD is an array of 0s and 1s that specifies the size and shape of the structuring element, is the same as imptophat(IM,strel(NHOOD)). Class Support IM can be numeric or logical and must be nonsparse. The output image IM2 has the same class as the input image. If the input is binary (logical), the structuring element must be flat. Examples You can use top-hat filtering to correct uneven illumination when the background is dark. This example uses top-hat filtering with a disk-shaped structuring element to remove the uneven background illumination from an image. 1 Read an image into the MATLAB workspace. I = imread('rice.png'); imshow(I) 3-568 imtophat 2 Create the structuring element and perform top-hat filtering of the image. se = strel('disk',12); J = imtophat(I,se); figure, imshow(J) 3 Use imadjust to improve the visibility of the result. K = imadjust(J); figure, imshow(K) 3-569 imtophat See Also 3-570 imbothat | strel imtransform Purpose Apply 2-D spatial transformation to image Syntax B = imtransform(A,tform) B = imtransform(A,tform,interp) [B,xdata,ydata] = imtransform(...) [B,xdata,ydata] = imtransform(...,Name,Value) Description B = imtransform(A,tform) transforms the image A according to the 2-D spatial transformation defined by tform. If ndims(A) > 2, such as for an RGB image, then imtransform applies the same 2-D transformation to all 2-D planes along the higher dimensions. B = imtransform(A,tform,interp) specifies the form of interpolation to use. [B,xdata,ydata] = imtransform(...) returns the location of the output image B in the output X-Y space. By default, imtransform calculates xdata and ydata automatically so that B contains the entire transformed image A. However, you can override this automatic calculation by specifying values for the 'XData' and 'YData' arguments. [B,xdata,ydata] = imtransform(...,Name,Value) transforms the image with additional options for controlling various aspects of the spatial transformation specified by one or more Name,Value pair arguments. Tips • Image Registration. The imtransform function automatically shifts the origin of your output image to make as much of the transformed image visible as possible. If you use imtransform to do image registration, the syntax B = imtransform(A,tform) can produce unexpected results. To control the spatial location of the output image, set 'XData' and 'YData' explicitly. • Pure Translation. Calling the imtransform function with a purely translational transformation, results in an output image that is exactly like the input image unless you specify 'XData' and 'YData' values in your call to imtransform. For example, if you want the 3-571 imtransform output to be the same size as the input revealing the translation relative to the input image, call imtransform as shown in the following syntax: B = imtransform(A,T,'XData',[1 size(A,2)],... 'YData',[1 size(A,1)]) For more information about this topic, see “Translate Image Using maketform and imtransform” in the User’s Guide, especially the section “Understanding the Coordinates of the Transformed Image”. • Transformation Speed. When you do not specify the output-space location for B using 'XData' and 'YData', imtransform estimates the location automatically using the function findbounds. You can use findbounds as a quick forward-mapping option for some commonly used transformations, such as affine or projective. For transformations that do not have a forward mapping, such as the polynomial ones computed by cp2tform, findbounds can take much longer. If you can specify 'XData' and 'YData' directly for such transformations, imtransform may run noticeably faster. • Clipping. The automatic estimate of 'XData' and 'YData' using findbounds sometimes clips the output image. To avoid clipping, set 'XData' and 'YData' directly. • Arbitrary Dimensional Transformations. Use a 2-D transformation for tform when using imtransform. For arbitrary-dimensional array transformations, see tformarray. Input Arguments A An image of any nonsparse numeric class (real or complex) or of class logical. tform A spatial transformation structure returned by maketform or cp2tform. imtransform assumes spatial-coordinate conventions for the transformation tform. Specifically, the first dimension of 3-572 imtransform the transformation is the horizontal or x-coordinate, and the second dimension is the vertical or y-coordinate. This convention is the reverse of the array subscripting convention in MATLAB. interp A string that specifies the form of interpolation to use. interp can be one of the following strings: 'bicubic', 'bilinear', or 'nearest' (nearest-neighbor). Alternatively, interp can be a resampler structure returned by makeresampler. This option allows more control over how imtransform performs resampling. Default: 'bilinear' Name-Value Pair Arguments Optional comma-separated pairs of Name,Value arguments, where Name is the argument name and Value is the corresponding value. Name must appear within single quotes (' ') and is not case sensitive. You can specify several name and value pair arguments in any order as Name1, Value1, ..., NameN, ValueN. UData A two-element, real vector that, when combined with 'VData', specifies the spatial location of image A in the 2-D input space U-V. The two elements of 'UData' give the u-coordinates (horizontal) of the first and last columns of A, respectively. Default: [1 size(A,2)] VData A two-element, real vector that, when combined with 'UData', specifies the spatial location of image A in the 2-D input space U-V. The two elements of 'VData' give the v-coordinates (vertical) of the first and last rows of A, respectively. Default: [1 size(A,1)] 3-573 imtransform XData A two-element, real vector that, when combined with 'YData', specifies the spatial location of the output image B in the 2-D output space X-Y. The two elements of 'XData' give the x-coordinates (horizontal) of the first and last columns of B, respectively. Default: If you do not specify 'XData' and 'YData', imtransform estimates values that contain the entire transformed output image. To determine these values, imtransform uses the findbounds function. YData A two-element real vector that, when combined with 'XData', specifies the spatial location of the output image B in the 2-D output space X-Y. The two elements of 'YData' give the y-coordinates (vertical) of the first and last rows of B, respectively. Default: If you do not specify 'XData' and 'YData', imtransform estimates values that contain the entire transformed output image. To determine these values, imtransform uses the findbounds function. XYScale A one- or two-element real vector. The first element of 'XYScale' specifies the width of each output pixel in X-Y space. The second element (if present) specifies the height of each output pixel. If 'XYScale' has only one element, then the same value specifies both width and height. Default: If you do not specify 'XYScale' but you do specify 'Size', then imtransform calculates 'XYScale' from 'Size', 'XData', and 'YData'. If you do not provide 'XYScale' or 'Size', then imtransform uses the scale of the input pixels for 'XYScale', except in cases where an excessively large output image would result. 3-574 imtransform Note In cases where preserving the scale of the input image would result in an excessively large output image, the imtransform function automatically increases the 'XYScale'. To ensure that the output pixel scale matches the input pixel scale, specify the 'XYScale' parameter. For example, call imtransform as shown in the following syntax: B = imtransform(A,T,'XYScale',1) Size A two-element vector of nonnegative integers that specifies the number of rows and columns of the output image B. For higher dimensions, imtransform takes the size of B directly from the size of A. Thus, size(B,k) equals size(A,k) for k > 2. Default: If you do not specify 'Size', imtransform derives this value from 'XData', 'YData', and 'XYScale'. FillValues An array containing one or several fill values. The imtransform function uses fill values for output pixels when the corresponding transformed location in the input image is completely outside the input image boundaries. If A is 2-D, 'FillValues' requires a scalar. However, if A’s dimension is greater than two, then you can specify 'FillValues' as an array whose size satisfies the following constraint: size(fill_values,k) must equal either size(A,k+2) or 1. For example, if A is a uint8 RGB image that is 200-by-200-by-3, then possibilities for 'FillValues' include the following values. Value Fill 0 Fill with black [0;0;0] Fill with black 3-575 imtransform Value Fill 255 Fill with white [255;255;255] Fill with white [0;0;255] Fill with blue [255;255;0] Fill with yellow If A is 4-D with size 200-by-200-by-3-by-10, then you can specify 'FillValues' as a scalar, 1-by-10, 3-by-1, or 3-by-10. Output Arguments B Output image of any nonsparse numeric class (real or complex) or of class logical. xdata Two-element vector that specifies the x-coordinates of the first and last columns of B. Note Sometimes the output values xdata and ydata do not exactly equal the input 'XData' and 'YData' arguments. The values differ either because of the need for an integer number of rows and columns, or because you specify values for 'XData', 'YData', 'XYScale', and 'Size' that are not entirely consistent. In either case, the first element of xdata and ydata always equals the first element of 'XData' and 'YData', respectively. Only the second elements of xdata and ydata can be different. ydata Two-element vector that specifies the y-coordinates of the first and last rows of B. 3-576 imtransform Examples Simple Transformation. Apply a horizontal shear to an intensity image: I = imread('cameraman.tif'); tform = maketform('affine',[1 0 0; .5 1 0; 0 0 1]); J = imtransform(I,tform); imshow(I), figure, imshow(J) Horizontal Shear Projective Transformation. Map a square to a quadrilateral with a projective transformation: % Set up an input coordinate system so that the input image % fills the unit square with vertices (0 0),(1 0),(1 1),(0 1). I = imread('cameraman.tif'); udata = [0 1]; vdata = [0 1]; % Transform to a quadrilateral with vertices (-4 2),(-8 3), % (-3 -5),(6 3). tform = maketform('projective',[ 0 0; 1 0; 1 1; 0 1],... [-4 2; -8 -3; -3 -5; 6 3]); % Fill with gray and use bicubic interpolation. % Make the output size the same as the input size. 3-577 imtransform [B,xdata,ydata] = imtransform(I, tform, 'bicubic', ... 'udata', udata,... 'vdata', vdata,... 'size', size(I),... 'fill', 128); subplot(1,2,1), imshow(I,'XData',udata,'YData',vdata), ... axis on subplot(1,2,2), imshow(B,'XData',xdata,'YData',ydata), ... axis on Projective Transformation Image Registration. Register an aerial photo to an orthophoto: % Read in the aerial photo. unregistered = imread('westconcordaerial.png'); figure, imshow(unregistered) 3-578 imtransform Aerial Photo % Read in the orthophoto. figure, imshow('westconcordorthophoto.png') Orthophoto % Load control points that were previously picked. load westconcordpoints 3-579 imtransform % Create a transformation structure for a projective % transformation. t_concord = cp2tform(input_points,base_points,'projective'); % Get the width and height of the orthophoto and perform % the transformation. info = imfinfo('westconcordorthophoto.png'); registered = imtransform(unregistered,t_concord,... 'XData',[1 info.Width], 'YData',[1 info.Height]); figure, imshow(registered) Transformed Image See Also checkerboard | cp2tform | imresize | imrotate | maketform | makeresampler | tformarray Tutorials • “Translate Image Using maketform and imtransform” • Exploring Slices from a 3-Dimensional MRI Data Set • Padding and Shearing an Image Simultaneously 3-580 imview Purpose Display image in image tool Note imview has been removed. Use imtool instead. 3-581 ind2gray Purpose Convert indexed image to grayscale image Syntax I = ind2gray(X,map) Description I = ind2gray(X,map) converts the image X with colormap map to a grayscale image I. ind2gray removes the hue and saturation information from the input image while retaining the luminance. Note A grayscale image is also called a gray-scale, gray scale, or gray-level image. Class Support X can be of class uint8, uint16, single, or double. map is double. I is of the same class as X. Examples load trees I = ind2gray(X,map); imshow(X,map) figure,imshow(I) Algorithms ind2gray converts the colormap to NTSC coordinates using rgb2ntsc, 3-582 and sets the hue and saturation components (I and Q) to zero, creating a ind2gray gray colormap. ind2gray then replaces the indices in the image X with the corresponding grayscale intensity values in the gray colormap. See Also gray2ind | imshow | imtool | mat2gray | rgb2gray | rgb2ntsc 3-583 ind2rgb Purpose Convert indexed image to RGB image Syntax RGB = ind2rgb(X,map) Description RGB = ind2rgb(X,map) converts the matrix X and corresponding colormap map to RGB (truecolor) format. Class Support X can be of class uint8, uint16, or double. RGB is an m-by-n-by-3 array of class double. See Also ind2gray | rgb2ind 3-584 interfileinfo Purpose Read metadata from Interfile file Syntax info = interfileinfo(filename) Description info = interfileinfo(filename) returns a structure whose fields contain information about an image in a Interfile file. filename is a string that specifies the name of the file. The file must be in the current directory or in a directory on the MATLAB path. The Interfile file format was developed for the exchange of nuclear medicine data. In Interfile 3.3, metadata is stored in a header file, separate from the image data. The two files have the same name with different file extensions. The header file has the file extension .hdr and the image file has the file extension .img. Examples Read metadata from an Interfile file. info = interfileinfo('MyFile.hdr'); For more information about this file format, visit the Interfile Archive, maintained by the Department of Medical Physics and Bioengineering, University College, London, UK. See Also interfileread 3-585 interfileread Purpose Read images in Interfile format Syntax A = interfileread(filename) A = interfileread(filename, window) Description A = interfileread(filename) reads the images in the first energy window of filename into A, where A is an M-by-N array for a single image and an M-by-N-by-P array for multiple images. The file must be in the current directory or in a directory on the MATLAB path. A = interfileread(filename, window) reads the images in the energy window specified by window of filename into A. The images in the energy window must be of the same size. Examples Read image data from an Interfile file. img = interfileread('MyFile.hdr'); For more information about this file format, visit the Interfile Archive, maintained by the Department of Medical Physics and Bioengineering, University College, London, UK. See also 3-586 interfileinfo intlut Purpose Convert integer values using lookup table Syntax B = intlut(A, LUT) Description B = intlut(A, LUT) converts values in array A based on lookup table LUT and returns these new values in array B. For example, if A is a vector whose kth element is equal to alpha, then B(k) is equal to the LUT value corresponding to alpha, i.e., LUT(alpha+1). Class Support A can be uint8, uint16, or int16. If A is uint8, LUT must be a uint8 vector with 256 elements. If A is uint16 or int16, LUT must be a vector with 65536 elements that has the same class as A. B has the same size and class as A. Examples A = uint8([1 2 3 4; 5 6 7 8; 9 10 11 12]) LUT = repmat(uint8([0 150 200 255]),1,64); B = intlut(A, LUT) See Also ind2gray | rgb2ind 3-587 ippl Purpose Check for presence of Intel Integrated Performance Primitives (Intel IPP) library Syntax TF = ippl [TF B] = ippl Description The Intel Integrated Performance Primitives (Intel IPP) library provides a collection of basic functions used in signal and image processing. The Intel IPP library takes advantage of the parallelism of the Single-Instruction, Multiple-Data (SIMD) instructions that make up the core of the MMX technology and Streaming SIMD Extensions. These instructions are available only on the Intel architecture processors. The Intel IPP library is used by some of the Image Processing Toolbox functions to accelerate their execution time. TF = ippl returns true (1) if the Intel IPP library is available and false (0) otherwise. [TF B] = ippl returns an additional column cell array B. The array B contains a string describing the Intel IPP library module. When the Intel IPP library is available, some of the Image Processing Toolbox arithmetic functions (imabsdiff, imdivide, and immultiply) and the imfilter function take advantage of it. Toolbox functions that use these functions also benefit. Notes The Intel IPP library is used only for some data types and only under specific conditions. See the help sections of the functions listed above for detailed information on when the Intel IPP library is activated. You can enable or disable the Intel IPP library by using the Image Processing Preferences dialog box, part of the MATLAB Preferences dialog box. You can open this dialog box by selecting Preferences from the MATLAB Desktop File menu and then choosing Image Processing. You can also enable or disable the Intel IPP library at the command line. To disable the Intel IPP library, use this command: 3-588 ippl iptsetpref('UseIPPL', false) To enable IPPL, use this command: iptsetpref('UseIPPL', true) Note that enabling or disabling the Intel IPP library has the effect of clearing all loaded MEX-files. See Also imabsdiff | imdivide | imfilter | immultiply | iptprefs 3-589 iptaddcallback Purpose Add function handle to callback list Syntax ID = iptaddcallback(h,callback,func_handle) Description ID = iptaddcallback(h,callback,func_handle) adds the function handle func_handle to the list of functions to be called when the callback specified by callback executes. callback is a string specifying the name of a callback property of the Handle Graphics object specified by the handle h. iptaddcallback returns a unique callback identifier, ID, that can be used with iptremovecallback to remove the function from the callback list. iptaddcallback can be useful when you need to notify more than one tool about the same callback event for a single object. Note Callback functions that have already been added to an object using the set command continue to work after you call iptaddcallback. The first time you call iptaddcallback for a given object and callback, the function checks to see if a different callback function is already installed. If a callback is already installed, iptaddcallback replaces that callback function with the iptaddcallback callback processor, and then adds the preexisting callback function to the iptaddcallback list. Examples Create a figure and register two callback functions. Whenever MATLAB detects mouse motion over the figure, function handles f1 and f2 are called in the order in which they were added to the list. h = figure; f1 = @(varargin) disp('Callback 1'); f2 = @(varargin) disp('Callback 2'); iptaddcallback(h, 'WindowButtonMotionFcn', f1); iptaddcallback(h, 'WindowButtonMotionFcn', f2); See Also 3-590 iptremovecallback iptcheckconn Purpose Check validity of connectivity argument Syntax iptcheckconn(conn, func_name, var_name, arg_pos) Description iptcheckconn(conn, func_name, var_name, arg_pos) checks whether conn is a valid connectivity argument. If it is invalid, the function issues a formatted error message. A connectivity argument can be one of the following scalar values: 1, 4, 6, 8, 18, or 26. A connectivity argument can also be a 3-by-3-by- ... -by-3 array of 0’s and 1s. The central element of a connectivity array must be nonzero and the array must be symmetric about its center. func_name is a string that specifies the name used in the formatted error message to identify the function checking the connectivity argument. var_name is a string that specifies the name used in the formatted error message to identify the argument being checked. arg_pos is a positive integer that indicates the position of the argument being checked in the function argument list. iptcheckconn includes this information in the formatted error message. Class Support conn must be of class double or logical and must be real and nonsparse. Examples Create a 4-by-4 array and pass it as the connectivity argument. iptcheckconn(eye(4), 'func_name','var_name',2) 3-591 iptcheckhandle Purpose Check validity of handle Syntax iptcheckhandle(H, valid_types, func_name, var_name, arg_pos) Description iptcheckhandle(H, valid_types, func_name, var_name, arg_pos) checks the validity of the handle H and issues a formatted error message if the handle is invalid. H must be a handle to a single figure, uipanel, hggroup, axes, or image object. valid_types is a cell array of strings specifying the set of Handle Graphics object types to which H is expected to belong. For example, if you specify valid_types as {'uipanel','figure'}, H can be a handle to either a uipanel object or a figure object. func_name is a string that specifies the name used in the formatted error message to identify the function checking the handle. var_name is a string that specifies the name used in the formatted error message to identify the argument being checked. arg_pos is a positive integer that indicates the position of the argument being checked in the function argument list. iptcheckhandle converts this value to an ordinal number and includes this information in the formatted error message. Examples To trigger the error message, create a figure that does not contain an axes object and then check for a valid axes handle. fig = figure; % create figure without an axes iptcheckhandle(fig,{'axes'},'my_function','my_variable',2) The following shows the format of the error message and indicates which parts you can customize using iptcheckhandle arguments. 3-592 iptcheckhandle See Also iptcheckinput | iptcheckmap | iptchecknargin | iptcheckstrs | iptnum2ordinal 3-593 iptcheckinput Purpose Check validity of array Syntax iptcheckinput(A, classes, attributes, func_name, var_name, arg_pos) Description iptcheckinput(A, classes, attributes, func_name, var_name, arg_pos) checks the validity of the array A and issues a formatted error message if it is invalid. classes is a cell array of strings specifying the set of classes to which A is expected to belong. For example, if you specify classes as {'logical' 'cell'}, A is required to be either a logical array or a cell array. The string 'numeric' is interpreted as an abbreviation for the classes uint8, uint16, uint32, int8, int16, int32, single, and double. attributes is a cell array of strings specifying the set of attributes that A must satisfy. For example, if attributes is {'real' 'nonempty' 'finite'}, A must be real and nonempty, and it must contain only finite values. The following table lists the supported attributes in alphabetical order. 2d nonempty odd twod column nonnan positive vector even nonnegative real finite nonsparse row integer nonzero scalar func_name is a string that specifies the name used in the formatted error message to identify the function checking the input. var_name is a string that specifies the name used in the formatted error message to identify the argument being checked. arg_pos is a positive integer that indicates the position of the argument being checked in the function argument list. iptcheckinput converts this value to an ordinal number and includes this information in the formatted error message. 3-594 iptcheckinput Examples To trigger this error message, create a three-dimensional array and then check for the attribute '2d'. A = [ 1 2 3; 4 5 6 ]; B = [ 7 8 9; 10 11 12]; C = cat(3,A,B); iptcheckinput(C,{'numeric'},{'2d'},'func_name','var_name',2) The following shows the format of the error message and indicates which parts you can customize using iptcheckinput arguments. See Also iptcheckhandle | iptcheckmap | iptchecknargin | iptcheckstrs | iptnum2ordinal 3-595 iptcheckmap Purpose Check validity of colormap Syntax iptcheckmap(map, func_name, var_name, arg_pos) Description iptcheckmap(map, func_name, var_name, arg_pos) checks the validity of the MATLAB colormap and issues a formatted error message if it is invalid. func_name is a string that specifies the name used in the formatted error message to identify the function checking the colormap. var_name is a string that specifies the name used in the formatted error message to identify the argument being checked. arg_pos is a positive integer that indicates the position of the argument being checked in the function argument list. iptcheckmap includes this information in the formatted error message. Examples bad_map = ones(10); iptcheckmap(bad_map,'func_name','var_name',2) The following shows the format of the error message and indicates which parts you can customize using iptcheckmap arguments. See Also 3-596 iptcheckhandle | iptcheckinput | iptchecknargin | iptcheckstrs iptchecknargin Purpose Check number of input arguments Syntax iptchecknargin(low, high, num_inputs, func_name) Description iptchecknargin(low, high, num_inputs, func_name) checks whether num_inputs is in the range indicated by low and high. If not, iptchecknargin issues a formatted error message. low should be a scalar nonnegative integer. high should be a scalar nonnegative integer or Inf. func_name is a string that specifies the name used in the formatted error message to identify the function checking the handle. Examples Create a function and use iptchecknargin to check that the number of arguments passed to the function is within the expected range. function test_function(varargin) iptchecknargin(1,3,nargin,mfilename); Trigger the error message by executing the function at the MATLAB command line, specifying more than the expected number of arguments. test_function(1,2,3,4) See Also iptcheckhandle | iptcheckinput | iptcheckmap | iptcheckstrs | iptnum2ordinal 3-597 iptcheckstrs Purpose Check validity of option string Syntax out = iptcheckstrs(in, valid_strs, func_name, var_name, arg_pos) Description out = iptcheckstrs(in, valid_strs, func_name, var_name, arg_pos) checks the validity of the option string in. It returns the matching string in valid_strs in out. iptcheckstrs looks for a case-insensitive, nonambiguous match between in and the strings in valid_strs. valid_strs is a cell array containing strings. func_name is a string that specifies the name used in the formatted error message to identify the function checking the strings. var_name is a string that specifies the name used in the formatted error message to identify the argument being checked. arg_pos is a positive integer that indicates the position of the argument being checked in the function argument list. iptcheckstrs converts this value to an ordinal number and includes this information in the formatted error message. Examples To trigger this error message, define a cell array of some text strings and pass in another string that isn’t in the cell array. iptcheckstrs('option3',{'option1','option2'},... 'func_name','var_name',2) The following shows the format of the error message and indicates which parts you can customize using iptcheckhandle arguments. 3-598 iptcheckstrs See Also iptcheckhandle | iptcheckinput | iptcheckmap | iptchecknargin | iptnum2ordinal 3-599 iptdemos Purpose Index of Image Processing Toolbox examples Syntax iptdemos Description iptdemos displays the HTML page that lists all the Image Processing examples. iptdemos displays the page in the MATLAB Help browser. 3-600 iptgetapi Purpose Get Application Programmer Interface (API) for handle Syntax API = iptgetapi(h) Description API = iptgetapi(h) returns the API structure associated with handle h if there is one. Otherwise, iptgetapi returns an empty array. For more information about handle APIs, see the help for immagbox, impositionrect, or imscrollpanel. Examples hFig = figure('Toolbar','none',... 'Menubar','none'); hIm = imshow('tape.png'); hSP = imscrollpanel(hFig,hIm); api = iptgetapi(hSP); api.setMagnification(2) % 2X = 200% See Also immagbox | imrect | imscrollpanel 3-601 iptGetPointerBehavior Purpose Retrieve pointer behavior from HG object Syntax pointerBehavior = iptGetPointerBehavior(h) Description pointerBehavior = iptGetPointerBehavior(h) returns the pointer behavior structure associated with the Handle Graphics object h. A pointer behavior structure contains function handles that interact with a figure’s pointer manager (see iptPointerManager) to control what happens when the figure’s mouse pointer moves over and then exits the object. See iptSetPointerBehavior for details. If h does not contain a pointer behavior structure, iptGetPointerBehavior returns []. See Also 3-602 iptPointerManager | iptSetPointerBehavior iptgetpref Purpose Get values of Image Processing Toolbox preferences Syntax prefs = iptgetpref value = iptgetpref(prefname) Description prefs = iptgetpref returns a structure containing all the Image Processing Toolbox preferences with their current values. Each field in the structure has the name of an Image Processing Toolbox preference. value = iptgetpref(prefname) returns the value of the Image Processing Toolbox preference specified by the string prefname. See iptprefs for a complete list of valid preference names or access the Image Processing preferences dialog box from the File menu in the MATLAB desktop. Preference names are not case sensitive and can be abbreviated. Examples value = iptgetpref('ImshowAxesVisible') value = off See Also imshow | iptprefs | iptsetpref 3-603 ipticondir Purpose Directories containing IPT and MATLAB icons Syntax [D1, D2] = ipticondir Description [D1, D2] = ipticondir returns the names of the directories containing the Image Processing Toolbox icons (D1) and the MATLAB icons (D2). Examples [iptdir, MATLABdir] = ipticondir dir(iptdir) See Also imtool 3-604 iptnum2ordinal Purpose Convert positive integer to ordinal string Syntax string = iptnum2ordinal(number) Description string = iptnum2ordinal(number) converts the positive integer number to the ordinal text string string. Examples The following example returns the string 'fourth'. str = iptnum2ordinal(4) The following example returns the string '23rd'. str = iptnum2ordinal(23) 3-605 iptPointerManager Purpose Create pointer manager in figure Syntax iptPointerManager(hFigure) iptPointerManager(hFigure, 'disable') iptPointerManager(hFigure, 'enable') Description iptPointerManager(hFigure) creates a pointer manager in the specified figure. The pointer manager controls pointer behavior for any Handle Graphics objects in the figure that contain pointer behavior structures. Use iptSetPointerBehavior to associate a pointer behavior structure with a particular object to define specific actions that occur when the mouse pointer moves over and then leaves the object. See iptSetPointerBehavior for more information. iptPointerManager(hFigure, 'disable') disables the figure’s pointer manager. iptPointerManager(hFigure, 'enable') enables and updates the figure’s pointer manager. Note If the figure already contains a pointer manager, iptPointerManager(hFigure) does not create a new one. It has the same effect as iptPointerManager(hFigure, 'enable'). Tips iptPointerManager considers not just the object the pointer is over, but all objects in the figure. iptPointerManager searches the HG hierarchy to find the first object that contains a pointer behavior structure. The iptPointerManager then executes that object’s pointer behavior function. For example, you could set the pointer to be a fleur and associate that pointer with the axes. Then, when you slide the pointer into the figure window, it will initially be the default pointer, then change to a fleur when you cross into the axes, and remain a fleur when you slide over the objects parented to the axes. 3-606 iptPointerManager Examples Plot a line. Create a pointer manager in the figure. Then, associate a pointer behavior structure with the line object in the figure that changes the mouse pointer into a fleur whenever the pointer is over it. h = plot(1:10); iptPointerManager(gcf); enterFcn = @(hFigure, currentPoint)... set(hFigure, 'Pointer', 'fleur'); iptSetPointerBehavior(h, enterFcn); See Also iptGetPointerBehavior | iptSetPointerBehavior 3-607 iptprefs Purpose Display Image Processing Preferences dialog box Syntax iptprefs Description iptprefs opens the Image Processing Preferences dialog box, part of the MATLAB Preferences dialog box. You can also open this dialog box by selecting Preferences from the MATLAB Desktop File menu, and then choosing Image Processing. The Image Processing Preferences dialog box contains display preferences for imtool and imshow and an option for enabling the Intel Integrated Performance Primitives (Intel IPP) library. Also, you can set all preferences at the command line with the iptsetpref function. To see how the options in the dialog box correspond to the commands, view the following picture. 3-608 iptprefs Image Processing Preferences Dialog Box The following table details the available preferences and their syntaxes. Note that preference names are case insensitive and you can abbreviate them. The default value appears enclosed in braces ({}). 3-609 iptprefs Available Image Processing Preferences Preference Name Description 'ImtoolStartWithOverview' Controls whether the Overview tool opens automatically when you open an image using the Image Tool (imtool). Possible values: true— Overview tool opens when you open an image. {false}— Overview tool does not open when you open an image. This is the default behavior. 'ImtoolInitialMagnification' Controls the initial magnification of the image displayed by imtool. Possible values: {'adaptive'} — Display the entire image. If the image is too large to display on the screen at 100% magnification, display the image at the largest magnification that fits on the screen. This is the default. Any numeric value — Specify the magnification as a percentage. A magnification of 100% means that there should be one screen pixel for every image pixel. 'fit' — Scale the image so that it fits into the window in its entirety. You can override this preference by specifying the 'InitialMagnification' parameter when you call imtool. 3-610 iptprefs Available Image Processing Preferences (Continued) Preference Name Description 'ImshowAxesVisible' Controls whether imshow displays images with the axes box and tick labels. Possible values: 'on' — Include axes box and tick labels. {'off'} — Do not include axes box and tick labels. 'ImshowBorder' Controls whether imshow includes a border around the image in the figure window. Possible values: {'loose'} — Include a border between the image and the edges of the figure window, thus leaving room for axes labels, titles, etc. 'tight' — Adjust the figure size so that the image entirely fills the figure. Note There still can be a border if the image is very small, or if there are other objects besides the image and its axes in the figure. You can override this preference by specifying the 'Border' parameter when you call imshow. 3-611 iptprefs Available Image Processing Preferences (Continued) Preference Name Description 'ImshowInitialMagnification' Controls the initial magnification of the image displayed by imshow. Possible values: Any numeric value — imshow interprets numeric values as a percentage. The default value is 100. A magnification of 100% means that there should be one screen pixel for every image pixel. 'fit' — Scale the image so that it fits into the window in its entirety. You can override this preference by specifying the 'InitialMagnification' parameter when you call imshow, or by calling the truesize function manually after displaying the image. 'UseIPPL' Controls whether some toolbox functions use the Intel IPP library or not. Possible values: {true} — Enable use of the Intel IPP library. false — Disable use of the Intel IPP library. Note: Setting this preference value clears all loaded MEX-files. See Also 3-612 imshow | imtool | iptgetpref | iptsetpref iptremovecallback Purpose Delete function handle from callback list Syntax iptremovecallback(h,callback,ID) Description iptremovecallback(h,callback,ID) deletes a callback from the list of callbacks created by imaddcallback for the object with handle h and the associated callback string callback. ID is the identifier of the callback to be deleted. This ID is returned by iptaddcallback when you add the function handle to the callback list. Examples Register three callbacks and try them interactively. h = figure; f1 = @(varargin) disp('Callback 1'); f2 = @(varargin) disp('Callback 2'); f3 = @(varargin) disp('Callback 3'); id1 = iptaddcallback(h, 'WindowButtonMotionFcn', f1); id2 = iptaddcallback(h, 'WindowButtonMotionFcn', f2); id3 = iptaddcallback(h, 'WindowButtonMotionFcn', f3); Remove one of the callbacks and then move the mouse over the figure again. Whenever MATLAB detects mouse motion over the figure, function handles f1 and f3 are called in that order. iptremovecallback(h, 'WindowButtonMotionFcn', id2); See Also iptaddcallback 3-613 iptSetPointerBehavior Purpose Store pointer behavior structure in Handle Graphics object Syntax iptSetPointerBehavior(h, pointerBehavior) iptSetPointerBehavior(h, []) iptSetPointerBehavior(h, enterFcn) Description iptSetPointerBehavior(h, pointerBehavior) stores the specified pointer behavior structure in the specified Handle Graphics object, h. If h is an array of objects, iptSetPointerBehavior stores the same structure in each object. When used with a figure’s pointer manager (see iptPointerManager), a pointer behavior structure controls what happens when the figure’s mouse pointer moves over and then exits an object in the figure. For details about this structure, see “Pointer Behavior Structure” on page 3-614. iptSetPointerBehavior(h, []) clears the pointer behavior from the Handle Graphics object or objects. iptSetPointerBehavior(h, enterFcn) creates a pointer behavior structure, setting the enterFcn field to the function handle specified, and setting the traverseFcn and exitFcn fields to []. See “Pointer Behavior Structure” on page 3-614 for details about these fields. This syntax is provided as a convenience because, for most common uses, only the enterFcn is necessary. Pointer Behavior Structure A pointer behavior structure contains three fields: enterFcn, traverseFcn, and exitFcn. You set the value of these fields to function handles and use the iptSetPointerBehavior function to associate this structure with an HG object in a figure. If the figure has a pointer manager installed, the pointer manager calls these functions when the following events occur. If you set a field to[], no action is taken. 3-614 iptSetPointerBehavior Function Handle When Called enterFcn Called when the mouse pointer moves over the object. traverseFcn Called once when the mouse pointer moves over the object, and called again each time the mouse moves within the object. exitFcn Called when the mouse pointer leaves the object. When the pointer manager calls the functions you create, it passes two arguments: a handle to the figure and the current position of the pointer. Examples Example 1 Change the mouse pointer to a fleur whenever it is over a specific object and restore the original pointer when the mouse pointer moves off the object. The example creates a patch object and associates a pointer behavior structure with the object. Because this scenario requires only an enterFcn, the example uses the iptSetPointerBehavior(n, enterFcn) syntax. The example then creates a pointer manager in the figure. Note that the pointer manager takes care of restoring the original figure pointer. hPatch = patch([.25 .75 .75 .25 .25],... [.25 .25 .75 .75 .25], 'r'); xlim([0 1]); ylim([0 1]); enterFcn = @(figHandle, currentPoint)... set(figHandle, 'Pointer', 'fleur'); iptSetPointerBehavior(hPatch, enterFcn); iptPointerManager(gcf); 3-615 iptSetPointerBehavior Example 2 Change the appearance of the mouse pointer, depending on where it is within the object. This example sets up the pointer behavior structure, setting the enterFcn and exitFcn fields to [], and setting traverseFcn to a function named overMe that handles the position-specific behavior. overMe is an example function (in \toolbox\images\imdemos) that varies the mouse pointer depending on the location of the mouse within the object. For more information, edit overMe. hPatch = patch([.25 .75 .75 .25 .25],... [.25 .25 .75 .75 .25], 'r'); xlim([0 1]) ylim([0 1]) pointerBehavior.enterFcn = []; pointerBehavior.exitFcn = []; pointerBehavior.traverseFcn = @overMe; iptSetPointerBehavior(hPatch, pointerBehavior); iptPointerManager(gcf); Example 3 Change the figure’s title when the mouse pointer is over the object. In this scenario, enterFcn and exitFcn are used to achieve the desired side effect, and traverseFcn is []. hPatch = patch([.25 .75 .75 .25 .25],... [.25 .25 .75 .75 .25], 'r'); xlim([0 1]) ylim([0 1]) pointerBehavior.enterFcn = ... @(figHandle, currentPoint)... set(figHandle, 'Name', 'Over patch'); pointerBehavior.exitFcn = ... @(figHandle, currentPoint) set(figHandle, 'Name', ''); pointerBehavior.traverseFcn = []; 3-616 iptSetPointerBehavior iptSetPointerBehavior(hPatch, pointerBehavior); iptPointerManager(gcf) See Also iptGetPointerBehavior | iptPointerManager 3-617 iptsetpref Purpose Set Image Processing Toolbox preferences or display valid values Syntax iptsetpref(prefname) iptsetpref(prefname,value) Description iptsetpref(prefname) displays the valid values for the Image Processing Toolbox preference specified by prefname. iptsetpref(prefname,value) sets the Image Processing Toolbox preference specified by the string prefname to the value specified by value. The setting persists until you change it. You can also use the Image Processing Preferences dialog box to set the preferences. To access the dialog, select Preferences from the File menu in the MATLAB desktop. For more information about available preferences, see iptprefs. Examples iptsetpref('ImshowBorder','tight') See Also imshow | imtool | iptgetpref | iptprefs 3-618 iptwindowalign Purpose Align figure windows Syntax iptwindowalign(fixed_fig, fixed_fig_edge, moving_fig, moving_fig_edge) Description iptwindowalign(fixed_fig, fixed_fig_edge, moving_fig, moving_fig_edge) moves the figure moving_fig to align it with the figure fixed_fig. moving_fig and fixed_fig are handles to figure objects. fixed_fig_edge and moving_fig_edge describe the alignment of the figures in relation to their edges and can take any of the following values: 'left', 'right', 'hcenter', 'top', 'bottom', or 'vcenter'. 'hcenter' means center horizontally and 'vcenter' means center vertically. The following figure shows these alignments. 3-619 iptwindowalign Notes The two specified locations must be consistent in terms of their direction. For example, you cannot specify 'left' for fixed_fig_edge and 'bottom' for moving_fig_edge. iptwindowalign constrains the position adjustment of moving_fig to keep it entirely visible on the screen. iptwindowalign has no effect if either figure window is docked. Examples To illustrate some possible figure window alignments, first create two figures: fig1 and fig2. Initially, fig2 overlays fig1 on the screen. fig1 = figure; fig2 = figure; Use iptwindowalign to move fig2 so its left edge is aligned with the right edge of fig1. iptwindowalign(fig1,'right',fig2,'left'); Now move fig2 so its top edge is aligned with the bottom edge of fig1. iptwindowalign(fig1, 'bottom', fig2, 'top'); 3-620 iptwindowalign Now move fig2 so the two figures are centered horizontally. iptwindowalign(fig1, 'hcenter', fig2, 'hcenter'); 3-621 iptwindowalign See Also 3-622 imtool iradon Purpose Inverse Radon transform Syntax I = iradon(R, theta) I = iradon(P, theta, interp, filter, frequency_scaling, output_size) [I,H] = iradon(...) Description I = iradon(R, theta) reconstructs the image I from projection data in the two-dimensional array R. The columns of R are parallel beam projection data. iradon assumes that the center of rotation is the center point of the projections, which is defined as ceil(size(R,1)/2). theta describes the angles (in degrees) at which the projections were taken. It can be either a vector containing the angles or a scalar specifying D_theta, the incremental angle between projections. If theta is a vector, it must contain angles with equal spacing between them. If theta is a scalar specifying D_theta, the projections were taken at angles theta = m*D_theta, where m = 0,1,2,...,size(R,2)-1. If the input is the empty matrix ([]), D_theta defaults to 180/size(R,2). iradon uses the filtered back-projection algorithm to perform the inverse Radon transform. The filter is designed directly in the frequency domain and then multiplied by the FFT of the projections. The projections are zero-padded to a power of 2 before filtering to prevent spatial domain aliasing and to speed up the FFT. I = iradon(P, theta, interp, filter, frequency_scaling, output_size) specifies parameters to use in the inverse Radon transform. You can specify any combination of the last four arguments. iradon uses default values for any of these arguments that you omit. interp specifies the type of interpolation to use in the back projection. The available options are listed in order of increasing accuracy and computational complexity. Value Description 'nearest' Nearest-neighbor interpolation 'linear' Linear interpolation (the default) 3-623 iradon Value Description 'spline' Spline interpolation 'pchip' Shape-preserving piecewise cubic interpolation 'cubic' Same as ’pchip’ 'v5cubic' Cubic interpolation from MATLAB 5. This method does not extrapolate, and it issues a warning and uses'spline' if X is not equally spaced. filter specifies the filter to use for frequency domain filtering. filter can be any of the strings that specify standard filters. Value Description 'Ram-Lak' Cropped Ram-Lak or ramp filter. This is the default. The frequency response of this filter is | f |. Because this filter is sensitive to noise in the projections, one of the filters listed below might be preferable. These filters multiply the Ram-Lak filter by a window that deemphasizes high frequencies. 'Shepp-Logan' Multiplies the Ram-Lak filter by a sinc function 'Cosine' Multiplies the Ram-Lak filter by a cosine function 'Hamming' Multiplies the Ram-Lak filter by a Hamming window 'Hann' Multiplies the Ram-Lak filter by a Hann window 'None' No filtering. When you specify this value, iradon returns unfiltered backprojection data. frequency_scaling is a scalar in the range (0,1] that modifies the filter by rescaling its frequency axis. The default is 1. If frequency_scaling is less than 1, the filter is compressed to fit into the frequency range [0,frequency_scaling], in normalized frequencies; all frequencies above frequency_scaling are set to 0. 3-624 iradon output_size is a scalar that specifies the number of rows and columns in the reconstructed image. If output_size is not specified, the size is determined from the length of the projections. output_size = 2*floor(size(R,1)/(2*sqrt(2))) If you specify output_size, iradon reconstructs a smaller or larger portion of the image but does not change the scaling of the data. If the projections were calculated with the radon function, the reconstructed image might not be the same size as the original image. [I,H] = iradon(...) returns the frequency response of the filter in the vector H. Class Support R can be double or single. All other numeric input arguments must be of class double. I has the same class as R. H is double. Examples Compare filtered and unfiltered backprojection. P = phantom(128); R = radon(P,0:179); I1 = iradon(R,0:179); I2 = iradon(R,0:179,'linear','none'); subplot(1,3,1), imshow(P), title('Original') subplot(1,3,2), imshow(I1), title('Filtered backprojection') subplot(1,3,3), imshow(I2,[]), title('Unfiltered backprojection') 3-625 iradon Compute the backprojection of a single projection vector. The iradon syntax does not allow you to do this directly, because if theta is a scalar it is treated as an increment. You can accomplish the task by passing in two copies of the projection vector and then dividing the result by 2. P = phantom(128); R = radon(P,0:179); r45 = R(:,46); I = iradon([r45 r45], [45 45])/2; imshow(I, []) title('Backprojection from the 45-degree projection') Algorithms iradon uses the filtered back projection algorithm to perform the References [1] Kak, A. C., and M. Slaney, Principles of Computerized Tomographic Imaging, New York, NY, IEEE Press, 1988. See Also fan2para | fanbeam | ifanbeam | para2fan | phantom | radon 3-626 inverse Radon transform. The filter is designed directly in the frequency domain and then multiplied by the FFT of the projections. The projections are zero-padded to a power of 2 before filtering to prevent spatial domain aliasing and to speed up the FFT. isbw Purpose True for binary image Syntax flag = isbw(A) isbw has been removed. Description flag = isbw(A) returns 1 if A is a binary image and 0 otherwise. The input image A is considered to be a binary image if it is a nonsparse logical array. Class Support The input image A can be any MATLAB array. See Also isind | isgray | isrgb 3-627 isflat Purpose True for flat structuring element Syntax TF = isflat(SE) Description TF = isflat(SE) returns true (1) if the structuring element SE is flat; otherwise it returns false (0). If SE is an array of STREL objects, then TF is the same size as SE. Class Support SE is a STREL object. TF is a double-precision value. See Also strel 3-628 isgray Purpose True for grayscale image Syntax flag = isgray(A) isgray has been removed. Description flag = isgray(A) returns 1 if A is a grayscale intensity image and 0 otherwise. isgray uses these criteria to decide whether A is an intensity image: • If A is of class double, all values must be in the range [0,1], and the number of dimensions of A must be 2. • If A is of class uint16 or uint8, the number of dimensions of A must be 2. Note A four-dimensional array that contains multiple grayscale images returns 0, not 1. Class Support The input image A can be of class logical, uint8, uint16, or double. See Also isbw | isind | isrgb 3-629 isicc Purpose True for valid ICC color profile Syntax TF = isicc(P) Description TF = isicc(P) returns True if structure P is a valid ICC color profile; otherwise False. isicc checks if P has a complete set of the tags required for an ICC profile. P must contain a Header field, which in turn must contain a Version field and a DeviceClass field. These fields, and others, are used to determine the set of required tags according to the ICC Profile Specification, either Version 2 (ICC.1:2001-04) or Version 4 (ICC.1:2001-12), which are available at www.color.org. The set of required tags is given in Section 6.3 in either version. Examples Read in an ICC profile and isicc returns True. P = iccread('sRGB.icm'); TF = isicc(P) TF = 1 This example creates a MATLAB structure and uses isicc to test if it’s a valid ICC profile. isicc returns False. S.name = 'Any Student'; S.score = 83; S.grade = 'B+' TF = isicc(S) TF = 0 3-630 isicc See Also applycform | iccread | iccwrite | makecform 3-631 isind Purpose True for indexed image Syntax flag = isind(A) isind has been removed. Description flag = isind(A) returns 1 if A is an indexed image and 0 otherwise. isind uses these criteria to determine if A is an indexed image: • If A is of class double, all values in A must be integers greater than or equal to 1, and the number of dimensions of A must be 2. • If A is of class uint8 or uint16, the number of dimensions of A must be 2. Note A four-dimensional array that contains multiple indexed images returns 0, not 1. Class Support A can be of class logical, uint8, uint16, or double. See Also isbw | isgray | isrgb 3-632 isnitf Purpose Check if file is National Imagery Transmission Format (NITF) file Syntax [tf, NITF_version] = isnitf(filename) Description [tf, NITF_version] = isnitf(filename) returns True (1) if the file specified by filename is a National Imagery Transmission Format (NITF) file, otherwise False (0). If the file is a NITF file, isnitf returns a text string identifying the NITF version in NITF_version, such as '2.1'. If the file is not a NITF file, NITF_version contains the text string 'UNK'. See Also nitfinfo | nitfread 3-633 isrgb Purpose True for RGB image Syntax flag = isrgb(A) isrgb has been removed. Description flag = isrgb(A) returns 1 if A is an RGB truecolor image and 0 otherwise. isrgb uses these criteria to determine whether A is an RGB image: • If A is of class double, all values must be in the range [0,1], and A must be m-by-n-by-3. • If A is of class uint16 or uint8, A must be m-by-n-by-3. Note A four-dimensional array that contains multiple RGB images returns 0, not 1. Class Support A can be of class logical, uint8, uint16, or double. See Also isbw | isgray | isind 3-634 isrset Purpose Check if file is R-Set Syntax [tf, supported] = isrset(filename) Description [tf, supported] = isrset(filename) sets tf to true if the file filename is a reduced resolution dataset (R-Set) created by rsetwrite and false if it is not. The value of supported is true if the R-Set file is compatible with the R-Set tools (such as imtool) in the version of the Image Processing Toolbox you are using. If supported is false, the R-Set file was probably created by a newer version of rsetwrite than the one in the version of the Image Processing Toolbox you are using. See Also rsetwrite 3-635 lab2double Purpose Convert L*a*b* data to double Syntax labd = lab2double(lab) Description labd = lab2double(lab) converts an M-by-3 or M-by-N-by-3 array of L*a*b* color values to class double. The output array labd has the same size as lab. The Image Processing Toolbox software follows the convention that double-precision L*a*b* arrays contain 1976 CIE L*a*b* values. L*a*b* arrays that are uint8 or uint16 follow the convention in the ICC profile specification (ICC.1:2001-4, www.color.org) for representing L*a*b* values as unsigned 8-bit or 16-bit integers. The ICC encoding convention is illustrated by these tables. Value (L*) uint8 Value uint16 Value 0.0 0 0 100.0 255 65280 100.0 + (25500/65280) None 65535 Value (a* or b*) uint8 Value uint16 Value -128.0 0 0 0.0 128 32768 127.0 255 65280 127.0 + (255/256) None 65535 Class Support lab is a uint8, uint16, or double array that must be real and nonsparse. labd is double. Examples Convert full intensity neutral color (white) from uint8 to double. lab2double(uint8([255 128 128])) 3-636 lab2double ans = 100 See Also 0 0 applycform | lab2uint8 | lab2uint16 | makecform | whitepoint | xyz2double | xyz2uint16 3-637 lab2uint16 Purpose Convert L*a*b* data to uint16 Syntax lab16 = lab2uint16(lab) Description lab16 = lab2uint16(lab) converts an M-by-3 or M-by-N-by-3 array of L*a*b* color values to uint16. lab16 has the same size as lab. The Image Processing Toolbox software follows the convention that double-precision L*a*b* arrays contain 1976 CIE L*a*b* values. L*a*b* arrays that are uint8 or uint16 follow the convention in the ICC profile specification (ICC.1:2001-4, www.color.org) for representing L*a*b* values as unsigned 8-bit or 16-bit integers. The ICC encoding convention is illustrated by these tables. Value (L*) uint8 Value uint16 Value 0.0 0 0 100.0 255 65280 100.0 + (25500/65280) None 65535 Value (a* or b*) uint8 Value uint16 Value -128.0 0 0 0.0 128 32768 127.0 255 65280 127.0 + (255/256) None 65535 Class Support lab can be a uint8, uint16, or double array that must be real and nonsparse. lab16 is of class uint16. Examples Convert full intensity neutral color (white) from double to uint16. lab2uint16(100 0 0) ans = 3-638 lab2uint16 65280 32768 32768 See Also applycform | lab2double | lab2uint8 | makecform | whitepoint | xyz2double | xyz2uint16 3-639 lab2uint8 Purpose Convert L*a*b* data to uint8 Syntax lab8 = lab2uint8(lab) Description lab8 = lab2uint8(lab) converts an M-by-3 or M-by-N-by-3 array of color values to uint8. lab8 has the same size as lab. The Image Processing Toolbox software follows the convention that double-precision arrays contain 1976 CIE values. arrays that are uint8 or uint16 follow the convention in the ICC profile specification (ICC.1:2001-4, www.color.org) for representing values as unsigned 8-bit or 16-bit integers. The ICC encoding convention is illustrated by these tables. Value (L*) uint8 Value uint16 Value 0.0 0 0 100.0 255 65280 100.0 + (25500/65280) None 65535 Value (a* or b*) uint8 Value uint16 Value -128.0 0 0 0.0 128 32768 127.0 255 65280 127.0 + (255/256) None 65535 Class Support lab is a uint8, uint16, or double array that must be real and nonsparse. lab8 is uint8. Examples Convert full intensity neutral color (white) from double to uint8. lab2uint8([100 0 0]) ans = 3-640 lab2uint8 255 See Also 128 128 applycform | lab2double | lab2uint16 | makecform | whitepoint | xyz2double | xyz2uint16 3-641 label2rgb Purpose Convert label matrix into RGB image Syntax RGB RGB RGB RGB Description RGB = label2rgb(L) converts a label matrix, L, such as those returned by labelmatrix, bwlabel, bwlabeln, or watershed, into an RGB color image for the purpose of visualizing the labeled regions. The label2rgb function determines the color to assign to each object based on the number of objects in the label matrix and range of colors in the colormap. The label2rgb function picks colors from the entire range. = = = = label2rgb(L) label2rgb(L, map) label2rgb(L, map, zerocolor) label2rgb(L, map, zerocolor, order) RGB = label2rgb(L, map) defines the colormap map to be used in the RGB image. map can have any of the following values: • n-by-3 colormap matrix • String containing the name of a MATLAB colormap function, such as 'jet' or 'gray' (See colormap for a list of supported colormaps.) • Function handle of a colormap function, such as @jet or @gray If you do not specify map, the default value is 'jet'. RGB = label2rgb(L, map, zerocolor) defines the RGB color of the elements labeled 0 (zero) in the input label matrix L. As the value of zerocolor, specify an RGB triple or one of the strings listed in this table. 3-642 Value Color 'b' Blue 'c' Cyan 'g' Green 'k' Black 'm' Magenta label2rgb Value Color 'r' Red 'w' White 'y' Yellow If you do not specify zerocolor, the default value for zero-labeled elements is [1 1 1] (white). RGB = label2rgb(L, map, zerocolor, order) controls how label2rgb assigns colormap colors to regions in the label matrix. If order is 'noshuffle' (the default), label2rgb assigns colormap colors to label matrix regions in numerical order. If order is 'shuffle', label2rgb assigns colormap colors pseudorandomly. label2rgb supports the generation of efficient, production-quality C/C++ code from MATLAB. For best results, when using the standard syntax: RGB = label2rgb(L, map, zerocolor, order) • Submit at least two input arguments: the label matrix, L, and the colormap matrix, map. • map must be an n-by-3, double, colormap matrix. You cannot use a string containing the name of a MATLAB colormap function or a function handle of a colormap function. • If you set the boundary color zerocolor to the same color as one of the regions, label2rgb will not issue a warning. • If you supply a value for order, it must be 'noshuffle'. To see a complete list of toolbox functions that support code generation, see “Supported Functions”. Class Support The input label matrix L can have any numeric class. It must contain finite, nonnegative integers. The output of label2rgb is of class uint8. 3-643 label2rgb Examples Use label2rgb to customize display of labelmatrix. I = imread('rice.png'); figure, imshow(I) Original BW = im2bw(I, graythresh(I)); CC = bwconncomp(BW); L = labelmatrix(CC); RGB = label2rgb(L); figure, imshow(RGB) RGB RGB2 = label2rgb(L, 'spring', 'c', 'shuffle'); figure, imshow(RGB2) 3-644 label2rgb RGB2 See Also bwconncomp | bwlabel | colormap | ismember | labelmatrix | watershed 3-645 labelmatrix Purpose Create label matrix from bwconncomp structure Syntax L = labelmatrix(CC) Description L = labelmatrix(CC) creates a label matrix from the connected components structure CC returned by bwconncomp. The size of L is CC.ImageSize. The elements of L are integer values greater than or equal to 0. The pixels labeled 0 are the background. The pixels labeled 1 make up one object; the pixels labeled 2 make up a second object; and so on. The class of L depends on CC.NumObjects, as shown in the following table. Class Range 'uint8' CC.NumObjects ≤ 255 'uint16' 256 ≤ CC.NumObjects ≤ 65535 'uint32' 65536 ≤ CC.NumObjects ≤ 232 − 1 'double' CC.NumObjects ≥ 232 labelmatrix is more memory efficient than bwlabel and bwlabeln because it returns its label matrix in the smallest numeric class necessary for the number of objects. Class Support CC is a structure returned by bwconncomp. The label matrix L is uint8, uint16, uint32, or double. Examples Calculate the connected components and display results: BW = imread('text.png'); CC = bwconncomp(BW); L = labelmatrix(CC); L2 = bwlabel(BW); whos L L2 3-646 labelmatrix The output for whos appears as follows: Name L L2 Size 256x256 256x256 Bytes 65536 524288 Class Attributes uint8 double figure, imshow(label2rgb(L)); The output for imshow appears as follows: See Also bwconncomp | bwlabel | bwlabeln | label2rgb | regionprops 3-647 makecform Purpose Create color transformation structure Syntax C C C C C C C C C C C C C C C Description = = = = = = makecform(type) makecform(type, 'WhitePoint', WP) makecform(type, 'AdaptedWhitePoint', WP) makecform('srgb2cmyk', 'RenderingIntent', intent) makecform('cmyk2srgb', 'RenderingIntent', intent) makecform('adapt', 'WhiteStart', WPS, 'WhiteEnd', WPE, 'AdaptModel', modelname) = makecform('icc', src_profile, dest_profile) = makecform('icc', src_profile, dest_profile, 'SourceRenderingIntent', src_intent, 'DestRenderingIntent', dest_intent) = makecform('clut', profile, LUTtype) = makecform('mattrc', MatTrc, 'Direction', direction) = makecform('mattrc', profile, 'Direction', direction) = makecform('mattrc', profile, 'Direction', direction, 'RenderingIntent', intent) = makecform('graytrc', profile, 'Direction', direction) = makecform('graytrc', profile, 'Direction', direction, 'RenderingIntent', intent) = makecform('named', profile, space) C = makecform(type) creates the color transformation structure C that defines the color space conversion specified by type. To perform the transformation, pass the color transformation structure as an argument to the applycform function. The type argument specifies one of the conversions listed in the following table. makecform supports conversions between members of the family of device-independent color spaces defined by the CIE, Commission Internationale de l’Éclairage (International Commission on Illumination). In addition, makecform also supports conversions to and from the sRGB and CMYK color spaces. For a list of the abbreviations used by the Image Processing Toolbox software for each color space, see the Remarks section of this reference page. 3-648 makecform Type Description 'cmyk2srgb' Convert from the CMYK color space to the sRGB color space. 'lab2lch' Convert from the L*a*b* to the L*ch color space. 'lab2srgb' Convert from the L*a*b* to the sRGB color space. 'lab2xyz' Convert from the L*a*b* to the XYZ color space. 'lch2lab' Convert from the L*ch to the L*a*b* color space. 'srgb2cmyk' Convert from the sRGB to the CMYK color space. 'srgb2lab' Convert from the sRGB to the L*a*b* color space. 'srgb2xyz' Convert from the sRGB to the XYZ color space. 'upvpl2xyz' Convert from the u′v′L to the XYZ color space. 'uvl2xyz' Convert from the uvL to the XYZ color space. 'xyl2xyz' Convert from the xyY to the XYZ color space. 'xyz2lab' Convert from the XYZ to the L*a*b* color space. 'xyz2srgb' Convert from the XYZ to the sRGB color space. 'xyz2upvpl' Convert from the XYZ to the u′v′L color space. 'xyz2uvl' Convert from the XYZ to the uvL color space. 'xyz2xyl' Convert from the XYZ to the xyY color space. 3-649 makecform C = makecform(type, 'WhitePoint', WP) specifies the value of the reference white point. type can be either 'xyz2lab' or 'lab2xyz'. WP is a 1-by-3 vector of XYZ values scaled so that Y = 1. The default is whitepoint('ICC'). Use the whitepoint function to create the WP vector. C = makecform(type, 'AdaptedWhitePoint', WP) specifies the adapted white point. type can be either 'srgb2lab', 'lab2srgb', 'srgb2xyz', or 'xyz2srgb'. As above, WP is a row vector of XYZ values scaled so that Y = 1. If not specified, the default adapted white point is whitepoint('ICC'). To get answers consistent with some published sRGB equations, specify whitepoint('D65') for the adapted white point. C = makecform('srgb2cmyk', 'RenderingIntent', intent) and C = makecform('cmyk2srgb', 'RenderingIntent', intent) specify the rendering intent for transforms of type srgb2cmyk and cmyk2srgb. These transforms convert data between sRGB IEC61966-2.1 and "Specifications for Web Offset Publications" (SWOP) CMYK. intent must be one of these strings: 'AbsoluteColorimetric', 'Perceptual', 'RelativeColorimetric', or 'Saturation'. For more information, see the table Rendering Intent on page 3-651. C = makecform('adapt', 'WhiteStart', WPS, 'WhiteEnd', WPE, 'AdaptModel', modelname) creates a linear chromatic-adaptation transform. WPS and WPE are row vectors of XYZ values, scaled so that Y = 1, specifying the starting and ending white points. modelname is either 'vonKries' or 'Bradford' and specifies the type of chromatic-adaptation model to be employed. If 'AdaptModel' is not specified, it defaults to 'Bradford'. C = makecform('icc', src_profile, dest_profile) creates a color transform based on two ICC profiles. src_profile and dest_profile are ICC profile structures returned by iccread. C = makecform('icc', src_profile, dest_profile, 'SourceRenderingIntent', src_intent, 'DestRenderingIntent', dest_intent) creates a color transform based on two ICC color profiles, 3-650 makecform src_profile and dest_profile, specifying rendering intent arguments for the source, src_intent, and the destination, dest_intent, profiles. Rendering intents specify the style of reproduction that should be used when these profiles are combined. For most devices, the range of reproducible colors is much smaller than the range of colors represented by the PCS. Rendering intents define gamut mapping techniques. Possible values for these rendering intents are listed below. Each rendering intent has distinct aesthetic and color-accuracy trade-offs. Rendering Intent Value Description 'AbsoluteColorimetric' Maps all out-of-gamut colors to the nearest gamut surface while maintaining the relationship of all in-gamut colors. This absolute rendering contains color data that is relative to a perfectly reflecting diffuser. 'Perceptual' (default) Employs vendor-specific gamut mapping techniques for optimizing the range of producible colors of a given device. The objective is to provide the most aesthetically pleasing result even though the relationship of the in-gamut colors might not be maintained. This media-relative rendering contains color data that is relative to the device’s white point. 3-651 makecform Rendering Intent (Continued) Value Description 'RelativeColorimetric' Maps all out-of-gamut colors to the nearest gamut surface while maintaining the relationship of all in-gamut colors. This media-relative rendering contains color data that is relative to the device’s white point. 'Saturation' Employs vendor-specific gamut mapping techniques for maximizing the saturation of device colors. This rendering is generally used for simple business graphics such as bar graphs and pie charts. This media-relative rendering contains color data that is relative to the device’s white point. C = makecform('clut', profile, LUTtype) creates the color transformation structure C based on a color lookup table (CLUT) contained in an ICC color profile. profile is an ICC profile structure returned by iccread. LUTtype specifies which clut in the profile structure is to be used. Each LUTtype listed in the table below contains the components of an 8-bit or 16-bit LUTtag that performs a transformation between device colors and PCS colors using a particular rendering. For more information about 'clut' transformations, see Section 6.5.7 of the International Color Consortium specification ICC.1:2001-04 (Version 2) or Section 6.5.9 of ICC.1:2001-12 (Version 4), available at www.color.org. LUT Type Description 'AToB0' Device to PCS: perceptual rendering intent (default) 3-652 'AToB1' Device to PCS: media-relative colorimetric rendering intent 'AToB2' Device to PCS: saturation rendering intent 'AToB3' Device to PCS: ICC-absolute rendering intent makecform LUT Type Description 'BToA0' PCS to device: perceptual rendering intent 'BToA1' PCS to device: media-relative colorimetric rendering intent 'BToA2' PCS to device: saturation rendering intent 'BToA3' PCS to device: ICC-absolute rendering intent 'Gamut' Determines which PCS colors are out of gamut for a given device 'Preview0' PCS colors to the PCS colors available for soft proofing using the perceptual rendering 'Preview1' PCS colors available for soft proofing using the media-relative colorimetric rendering. 'Preview2' PCS colors to the PCS colors available for soft proofing using the saturation rendering. C = makecform('mattrc', MatTrc, 'Direction', direction) creates the color transformation structure C based on a Matrix/Tone Reproduction Curve (MatTRC) model, containing an RGB-to-XYZ matrix and RGB Tone Reproduction Curves. MatTRC is typically the 'MatTRC' field of an ICC profile structure returned by iccread, based on tags contained in an ICC color profile. direction can be either 'forward' or 'inverse' and specifies whether the MatTRC is to be applied in the forward (RGB to XYZ) or inverse (XYZ to RGB) direction. For more information, see section 6.3.1.2 of the International Color Consortium specification ICC.1:2001-04 or ICC.1:2001-12, available at www.color.org. C = makecform('mattrc', profile, 'Direction', direction) creates a color transform based on the MatTRC field of the given ICC profile structure profile. direction is either 'forward' or 'inverse' and specifies whether the MatTRC is applied in the forward (RGB to XYZ) or inverse (XYZ to RGB) direction. 3-653 makecform C = makecform('mattrc', profile, 'Direction', direction, 'RenderingIntent', intent) is similar, but adds the option of specifying the rendering intent. intent must be either 'RelativeColorimetric' (the default) or 'AbsoluteColorimetric'. When 'AbsoluteColorimetric' is specified, the colorimetry is referenced to a perfect diffuser, rather than to the Media White Point of the profile. C = makecform('graytrc', profile, 'Direction', direction) creates the color transformation structure C that specifies a monochrome transform based on a single-channel Tone Reproduction Curve (GrayTRC) contained in an ICC color profile. direction can be either 'forward' or 'inverse' and specifies whether the grayTRC transform is to be applied in the forward (device to PCS) or inverse (PCS to device) direction. ("Device" here refers to the grayscale signal communicating with the monochrome device. "PCS" is the Profile Connection Space of the ICC profile and can be either XYZ or L*a*b*, depending on the 'ConnectionSpace' field in profile.Header.) C = makecform('graytrc', profile, 'Direction', direction, 'RenderingIntent', intent) is similar but adds the option of specifying the rendering intent. intent must be either 'RelativeColorimetric' (the default) or 'AbsoluteColorimetric'. When 'AbsoluteColorimetric' is specified, the colorimetry is referenced to a perfect diffuser, rather than to the Media White Point of the profile. C = makecform('named', profile, space) creates the color transformation structure C that specifies the transformation from color names to color-space coordinates. profile must be a profile structure for a Named Color profile (with a NamedColor2 field). space is either 'PCS' or 'Device'. The 'PCS' option is always available and will return L*a*b* or XYZ coordinates, depending on the 'ConnectionSpace' field in profile.Header, in 'double' format. The 'Device' option, when active, returns device coordinates, the dimension depending on the 'ColorSpace' field in profile.Header, also in 'double' format. 3-654 makecform Tips The Image Processing Toolbox software uses the following abbreviations to represent color spaces. Abbreviation Description xyz 1931 CIE XYZ tristimulus values (2° observer) xyl 1931 CIE xyY chromaticity values (2° observer), where x and y refer to the xy-coordinates of the associated CIE chromaticity diagram, and l refers to Y (luminance). uvl 1960 CIE uvY values, where u and v refer to the uv-coordinates, and l refers to Y (luminance). upvpl 1976 CIE u′v′Y values, where up and vp refer to the u′v′-coordinates and l refers to Y (luminance). lab 1976 CIE L*a*b* values Note l or L refers to L* (CIE 1976 psychometric lightness) rather than luminance (Y). lch Polar transformation of CIE L*a*b* values, where c = chroma and h = hue cmyk Standard values used by printers srgb Standard computer monitor RGB values, (IEC 61966-2-1) Examples Convert RGB image to L*a*b*, assuming input image is sRGB. rgb = imread('peppers.png'); cform = makecform('srgb2lab'); lab = applycform(rgb,cform); 3-655 makecform Convert from a non-standard RGB color profile to the device-independent XYZ profile connection space. Note that the ICC input profile must includes a MatTRC value. InputProfile = iccread('myRGB.icc'); C = makecform('mattrc',InputProfile.MatTRC, ... 'direction', 'forward'); See Also applycform | iccread | iccwrite | isicc | lab2double | lab2uint8 | lab2uint16 | whitepoint | xyz2double | xyz2uint16 How To • “Converting Color Data Between Color Spaces” 3-656 makeConstrainToRectFcn Purpose Create rectangularly bounded drag constraint function Syntax fcn = makeConstrainToRectFcn(type, xlim, ylim) Description fcn = makeConstrainToRectFcn(type, xlim, ylim) creates a position constraint function for draggable tools of a given type, where type is one of the following strings: 'imellipse', 'imfreehand', 'imline', 'impoint', 'impoly', or 'imrect'. The rectangular boundaries of the position constraint function are described by the vectors xlim and ylim where xlim = [xmin xmax] and ylim = [ymin ymax]. Examples Constrain drag of impoint within axes limits. figure, plot(1:10); h = impoint(gca,2,6); api = iptgetapi(h); fcn = makeConstrainToRectFcn('impoint',get(gca,'XLim'),... get(gca,'YLim')); api.setPositionConstraintFcn(fcn); See Also imdistline | imellipse | imfreehand | imline | impoint | impoly | imrect 3-657 makehdr Purpose Create high dynamic range image Syntax HDR = makehdr(files) HDR = makehdr(files, param1, val1,...) Description HDR = makehdr(files) creates the single-precision, high dynamic range image from the set of spatially registered low dynamic range images listed in the files cell array. makehdr uses the middle exposure between the brightest and darkest images as the base exposure for the high dynamic range calculations. (This value does not need to appear in any particular file.) Note When you call makehdr with this syntax, the low dynamic range image files must contain exif exposure metadata. HDR = makehdr(files, param1, val1,...) creates a high dynamic range image from the low dynamic range images in files, specifying parameters and corresponding values that control various aspects of the image creation. Parameter names can be abbreviated and case does not matter. Note Only one of the BaseFile, ExposureValues, and RelativeExposure parameters may be used at a time. 3-658 makehdr Parameter Description 'BaseFile' Character array containing the name of the file to use as the base exposure. 'ExposureValues' Vector of exposure values, with one element for each low dynamic range image in the cell array files. An increase in one exposure value (EV) corresponds to a doubling of exposure, while a decrease in one EV corresponds to a halving of exposure. Any positive value is allowed. This parameter overrides EXIF exposure metadata. 'RelativeExposure'Vector of relative exposure values, with one element for each low dynamic range image in the cell array files. An image with a relative exposure (RE) of 0.5 has half as much exposure as an image with an RE of 1. An RE value of 3 has three times the exposure of an image with an RE of 1. This parameter overrides EXIF exposure metadata. Examples 'MinimumLimit' Numeric scalar value in the range [0 255] that specifies the minimum correctly exposed value. For each low dynamic range image, pixels with smaller values are considered underexposed and will not contribute to the final high dynamic range image. 'MaximumLimit' Numeric scalar value in the range [0 255] that specifies the maximum correctly exposed value. For each low dynamic range image, pixels with larger values are considered overexposed and will not contribute to the final high dynamic range image. Make a high dynamic range image from a series of six low dynamic range images that share the same f/stop number and have different exposure times. Use tonemap to visualize the HDR image. 3-659 makehdr files = {'office_1.jpg', 'office_2.jpg', 'office_3.jpg', ... 'office_4.jpg', 'office_5.jpg', 'office_6.jpg'}; expTimes = [0.0333, 0.1000, 0.3333, 0.6250, 1.3000, 4.0000]; hdr = makehdr(files, 'RelativeExposure', expTimes ./ expTimes(1)); rgb = tonemap(hdr); figure; imshow(rgb) References [1] Reinhard, et al. "High Dynamic Range Imaging." 2006. Ch. 4. See Also hdrread | tonemap 3-660 makelut Purpose Create lookup table for use with bwlookup Syntax lut = makelut(fun,n) Description lut = makelut(fun,n) returns a lookup table for use with bwlookup. fun is a function that accepts an n-by-n matrix of 1’s and 0’s as input and return a scalar. n can be either 2 or 3. makelut creates lut by passing all possible 2-by-2 or 3-by-3 neighborhoods to fun, one at a time, and constructing either a 16-element vector (for 2-by-2 neighborhoods) or a 512-element vector (for 3-by-3 neighborhoods). The vector consists of the output from fun for each possible neighborhood. fun must be a function handle. Parameterizing Functions, in the MATLAB Mathematics documentation, explains how to provide additional parameters to the function fun. Class Support lut is returned as a vector of class double. Examples Construct a lookup table for 2-by-2 neighborhoods. In this example, the function passed to makelut returns TRUE if the number of 1’s in the neighborhood is 2 or greater, and returns FALSE otherwise. f = @(x) (sum(x(:)) >= 2); lut = makelut(f,2) lut = 0 0 0 1 0 1 1 1 0 1 3-661 makelut 1 1 1 1 1 1 See Also bwlookup How To • “Anonymous Functions” • “Parameterizing Functions” 3-662 makeresampler Purpose Create resampling structure Syntax R = makeresampler(interpolant, padmethod) Description R = makeresampler(interpolant, padmethod) creates a separable resampler structure for use with tformarray and imtransform. The interpolant argument specifies the interpolating kernel that the separable resampler uses. In its simplest form, interpolant can have any of the following strings as a value. Interpolant Description 'cubic' Cubic interpolation 'linear' Linear interpolation 'nearest' Nearest-neighbor interpolation If you are using a custom interpolating kernel, you can specify interpolant as a cell array in either of these forms: {half_width, positive_half} half_width is a positive scalar designating {half_width, interp_fcn} interp_fcn is a function handle that returns interpolating kernel values, given an array of input values in the interval [0 positive_half]. the half width of a symmetric interpolating kernel. positive_half is a vector of values regularly sampling the kernel on the closed interval [0 positive_half]. To specify the interpolation method independently along each dimension, you can combine both types of interpolant specifications. The number of elements in the cell array must equal the number of transform dimensions. For example, if you specify this value for interpolant {'nearest', 'linear', {2 KERNEL_TABLE}} 3-663 makeresampler the resampler uses nearest-neighbor interpolation along the first transform dimension, linear interpolation along the second dimension, and a custom table-based interpolation along the third. The padmethod argument controls how the resampler interpolates or assigns values to output elements that map close to or outside the edge of the input array. The following table lists all the possible values of padmethod. Pad Method Description 'bound' Assigns values from the fill value array to points that map outside the array and repeats border elements of the array for points that map inside the array (same as 'replicate'). When interpolant is 'nearest', this pad method produces the same results as 'fill'. 'bound' is like 'fill', but avoids mixing fill values and input image values. 'circular' Pads array with circular repetition of elements within the dimension. Same as padarray. 'fill' Generates an output array with smooth-looking edges (except when using nearest-neighbor interpolation). For output points that map near the edge of the input array (either inside or outside), it combines input image and fill values. When interpolant is 'nearest', this pad method produces the same results as 'bound'. 'replicate' Pads array by repeating border elements of array. Same as padarray. 'symmetric' Pads array with mirror reflections of itself. Same as padarray. In the case of 'fill', 'replicate', 'circular', or 'symmetric', the resampling performed by tformarray or imtransform occurs in two logical steps: 3-664 makeresampler 1 Pad the array A infinitely to fill the entire input transform space. 2 Evaluate the convolution of the padded A with the resampling kernel at the output points specified by the geometric map. Each nontransform dimension is handled separately. The padding is virtual, (accomplished by remapping array subscripts) for performance and memory efficiency. If you implement a custom resampler, you can implement these behaviors. Custom Resamplers The syntaxes described above construct a resampler structure that uses the separable resampler function that ships with the Image Processing Toolbox software. It is also possible to create a resampler structure that uses a user-written resampler by using this syntax: R = makeresampler(PropertyName,PropertyValue,...) The makeresampler function supports the following properties. Property Description 'Type' Can have the value 'separable' or 'custom' and must always be supplied. If 'Type' is 'separable', the only other properties that can be specified are 'Interpolant' and 'PadMethod', and the result is equivalent to using the makeresampler(interpolant,padmethod) syntax. If 'Type' is 'custom', you must specify the 'NDims' and 'ResampleFcn' properties and, optionally, the 'CustomData' property. 'PadMethod' See the padmethod argument for more information. 'Interpolant' See the interpolant argument for more information. 'NDims' Positive integer indicating the dimensionality the custom resampler can handle. Use a value of Inf to indicate that the custom resampler can handle any dimension. If 'Type' is 'custom', NDims is required. 3-665 makeresampler Property Description 'ResampleFcn' Handle to a function that performs the resampling. The function is called with the following interface. B = resample_fcn(A,M,TDIMS_A,TDIMS_B,FSIZE_A,FSIZE_B,F,R) See the help for tformarray for information about the inputs A, TDIMS_A, TDIMS_B, and F. The argument M is an array that maps the transform subscript space of B to the transform subscript space of A. If A has N transform dimensions (N = length(TDIMS_A)) and B has P transform dimensions (P = length(TDIMS_B)), then ndims(M) = P + 1, if N > 1 and P if N == 1, and size(M,P + 1) = N. The first P dimensions of M correspond to the output transform space, permuted according to the order in which the output transform dimensions are listed in TDIMS_B. (In general TDIMS_A and TDIMS_B need not be sorted in ascending order, although such a limitation might be imposed by specific resamplers.) Thus, the first P elements of size(M) determine the sizes of the transform dimensions of B. The input transform coordinates to which each point is mapped are arrayed across the final dimension of M, following the order given in TDIMS_A. M must be double. FSIZE_A and FSIZE_B are the full sizes of A and B, padded with 1’s as necessary to be consistent with TDIMS_A, TDIMS_B, and size(A). 'CustomData' Examples User-defined. Stretch an image in the y-direction using a separable resampler that applies cubic interpolation in the y-direction and nearest-neighbor interpolation in the x-direction. (This is equivalent to, but faster than, applying bicubic interpolation.) A = imread('moon.tif'); resamp = makeresampler({'nearest','cubic'},'fill'); stretch = maketform('affine',[1 0; 0 1.3; 0 0]); B = imtransform(A,stretch,resamp); 3-666 makeresampler See Also imtransform | tformarray 3-667 maketform Purpose Create spatial transformation structure (TFORM) Syntax T T T T T T T T T T Description = = = = = = maketform(transformtype,...) maketform('affine',A) maketform('affine',U,X) maketform('projective',A) maketform('projective',U,X) maketform('custom', NDIMS_IN, NDIMS_OUT, FORWARD_FCN, INVERSE_FCN, TDATA) = maketform('box',tsize,LOW,HIGH) = maketform('box',INBOUNDS, OUTBOUNDS) = maketform('composite',T1,T2,...,TL) = maketform('composite', [T1 T2 ... TL]) T = maketform(transformtype,...) creates a multidimensional spatial transformation structure (called a TFORM struct) that can be used with the tformfwd, tforminv, fliptform, imtransform, or tformarray functions. transformtype can be any of the following spatial transformation types. maketform supports a special syntax for each transformation type. See the following sections for information about these syntax. Transform Type Description 'affine' Affine transformation in 2-D or N-D 'projective' Projective transformation in 2-D or N-D 3-668 'custom' User-defined transformation that can be N-D to M-D 'box' Independent affine transformation (scale and shift) in each dimension 'composite' Composition of an arbitrary number of more basic transformations maketform Transform Types Affine T = maketform('affine',A) builds a TFORM struct T for an N-dimensional affine transformation. A is a nonsingular real (N+1)-by-(N+1) or (N+1)-by-N matrix. If A is (N+1)-by-(N+1), the last column of A must be [zeros(N,1);1]. Otherwise, A is augmented automatically, such that its last column is [zeros(N,1);1]. The matrix A defines a forward transformation such that tformfwd(U,T), where U is a 1-by-N vector, returns a 1-by-N vector X, such that X = U * A(1:N,1:N) + A(N+1,1:N). T has both forward and inverse transformations. T = maketform('affine',U,X) builds a TFORM struct T for a two-dimensional affine transformation that maps each row of U to the corresponding row of X. The U and X arguments are each 3-by-2 and define the corners of input and output triangles. The corners cannot be collinear. Projective T = maketform('projective',A) builds a TFORM struct for an N-dimensional projective transformation. A is a nonsingular real (N+1)-by-(N+1) matrix. A(N+1,N+1) cannot be 0. The matrix A defines a forward transformation such that tformfwd(U,T), where U is a 1-by-N vector, returns a 1-by-N vector X, such that X = W(1:N)/W(N+1), where W = [U 1] * A. The transformation structure T has both forward and inverse transformations. T = maketform('projective',U,X) builds a TFORM struct T for a two-dimensional projective transformation that maps each row of U to the corresponding row of X. The U and X arguments are each 4-by-2 and define the corners of input and output quadrilaterals. No three corners can be collinear. 3-669 maketform Note An affine or projective transformation can also be expressed like this, for a 3-by-2 A: [X Y]' = A' * [U V 1] ' Or, like this, for a 3-by-3 A: [X Y 1]' = A' * [U V 1]' Custom T = maketform('custom', NDIMS_IN, NDIMS_OUT, FORWARD_FCN, INVERSE_FCN, TDATA) builds a custom TFORM struct T based on user-provided function handles and parameters. NDIMS_IN and NDIMS_OUT are the numbers of input and output dimensions. FORWARD_FCN and INVERSE_FCN are function handles to forward and inverse functions. Those functions must support the following syntax: Forward function: X = FORWARD_FCN(U,T) Inverse function: U = INVERSE_FCN(X,T) where U is a P-by-NDIMS_IN matrix whose rows are points in the transformation’s input space, and X is a P-by-NDIMS_OUT matrix whose rows are points in the transformation’s output space. The TDATA argument can be any MATLAB array and is typically used to store parameters of the custom transformation. It is accessible to FORWARD_FCN and INVERSE_FCN via the tdata field of T. Either FORWARD_FCN or INVERSE_FCN can be empty, although at least INVERSE_FCN must be defined to use T with tformarray or imtransform. Box T = maketform('box',tsize,LOW,HIGH) or T = maketform('box',INBOUNDS, OUTBOUNDS) builds an N-dimensional affine TFORM struct T. The tsize argument is an 3-670 maketform N-element vector of positive integers. LOW and HIGH are also N-element vectors. The transformation maps an input box defined by the opposite corners ones(1,N) and tsize or, alternatively, by corners INBOUNDS(1,:) and INBOUND(2,:) to an output box defined by the opposite corners LOW and HIGH or OUTBOUNDS(1,:) and OUTBOUNDS(2,:). LOW(K) and HIGH(K) must be different unless tsize(K) is 1, in which case the affine scale factor along the Kth dimension is assumed to be 1.0. Similarly, INBOUNDS(1,K) and INBOUNDS(2,K) must be different unless OUTBOUNDS(1,K) and OUTBOUNDS(2,K) are the same, and vice versa. The 'box' TFORM is typically used to register the row and column subscripts of an image or array to some world coordinate system. Composite T = maketform('composite',T1,T2,...,TL) or T = maketform('composite', [T1 T2 ... TL]) builds a TFORM struct T whose forward and inverse functions are the functional compositions of the forward and inverse functions of T1, T2, ..., TL. Note that the inputs T1, T2, ..., TL are ordered just as they would be when using the standard notation for function composition: T = T1 T2 ... TL and note also that composition is associative, but not commutative. This means that in order to apply T to the input U, one must apply TL first and T1 last. Thus if L = 3, for example, then tformfwd(U,T) is the same as tformfwd(tformfwd(tformfwd(U,T3),T2),T1). The components T1 through TL must be compatible in terms of the numbers of input and output dimensions. T has a defined forward transform function only if all the component transforms have defined forward transform functions. T has a defined inverse transform function only if all the component functions have defined inverse transform functions. Examples Make and apply an affine transformation. T = maketform('affine',[.5 0 0; .5 2 0; 0 0 1]); tformfwd([10 20],T) I = imread('cameraman.tif'); I2 = imtransform(I,T); 3-671 maketform imshow(I), figure, imshow(I2) See Also 3-672 tformfwd | tforminv | fliptform | imtransform | tformarray mat2gray Purpose Convert matrix to grayscale image Syntax I = mat2gray(A, [amin amax]) I = mat2gray(A) Description I = mat2gray(A, [amin amax]) converts the matrix A to the intensity image I. The returned matrix I contains values in the range 0.0 (black) to 1.0 (full intensity or white). amin and amax are the values in A that correspond to 0.0 and 1.0 in I. I = mat2gray(A) sets the values of amin and amax to the minimum and maximum values in A. Class Support The input array A can be logical or numeric. The output image I is double. Examples I = imread('rice.png'); J = filter2(fspecial('sobel'),I); K = mat2gray(J); imshow(I), figure, imshow(K) See Also gray2ind | ind2gray | rgb2gray 3-673 mean2 Purpose Average or mean of matrix elements Syntax B = mean2(A) Description B = mean2(A) computes the mean of the values in A. Class Support The input image A can be numeric or logical. The output image B is a scalar of class double. Algorithms mean2 computes the mean of an array A using mean(A(:)). See Also std2 | mean | std 3-674 medfilt2 Purpose 2-D median filtering Note The syntax medfilt2(A,[M N],(Mb Nb],...) has been removed. Syntax B B B B Description Median filtering is a nonlinear operation often used in image processing to reduce "salt and pepper" noise. A median filter is more effective than convolution when the goal is to simultaneously reduce noise and preserve edges. = = = = medfilt2(A, [m n]) medfilt2(A) medfilt2(A, 'indexed', ...) medfilt2(..., padopt) B = medfilt2(A, [m n]) performs median filtering of the matrix A in two dimensions. Each output pixel contains the median value in the m-by-n neighborhood around the corresponding pixel in the input image. medfilt2 pads the image with 0s on the edges, so the median values for the points within [m n]/2 of the edges might appear distorted. B = medfilt2(A) performs median filtering of the matrix A using the default 3-by-3 neighborhood. B = medfilt2(A, 'indexed', ...) processes A as an indexed image, padding with 0s if the class of A is uint8, or 1s if the class of A is double. B = medfilt2(..., padopt) controls how the matrix boundaries are padded. padopt may be 'zeros' (the default), 'symmetric', or 'indexed'. If padopt is 'symmetric', A is symmetrically extended at the boundaries. If padopt is 'indexed', A is padded with ones if it is double; otherwise it is padded with zeros. Class Support The input image A can be of class logical or numeric (unless the 'indexed' syntax is used, in which case A cannot be of class uint16). The output image B is of the same class as A. 3-675 medfilt2 Note For information about performance considerations, see ordfilt2. Tips If the input image A is of an integer class, all the output values are returned as integers. If the number of pixels in the neighborhood (i.e., m*n) is even, some of the median values might not be integers. In these cases, the fractional parts are discarded. Logical input is treated similarly. For example, suppose you call medfilt2 using 2-by-2 neighborhoods, and the input image is a uint8 array that includes this neighborhood. 1 5 4 8 medfilt2 returns an output value of 4 for this neighborhood, although the true median is 4.5. Examples Add salt and pepper noise to an image and then restore the image using medfilt2. I = imread('eight.tif'); J = imnoise(I,'salt & pepper',0.02); K = medfilt2(J); imshow(J), figure, imshow(K) 3-676 medfilt2 Algorithms medfilt2 uses ordfilt2 to perform the filtering. References [1] Lim, Jae S., Two-Dimensional Signal and Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1990, pp. 469-476. See Also filter2 | ordfilt2 | wiener2 3-677 montage Purpose Display multiple image frames as rectangular montage Syntax montage(filenames) montage(I) montage(X, map) montage(..., param1, value1, param2, value2, ...) h = montage(...) Description montage(filenames) displays a montage of the images specified in filenames. filenames is an N-by-1 or 1-by-N cell array of filenames. If the files are not in the current directory or in a directory on the MATLAB path, you must specify the full pathname. See the imread command for more information. If one or more of the image files contains an indexed image, montage uses the colormap from the first indexed image file. montage arranges the frames so that they roughly form a square. montage(I) displays all the frames of a multiframe image array I in a single image object. I can be a sequence of binary, grayscale, or truecolor images. A binary or grayscale image sequence must be an M-by-N-by-1-by-K array. A truecolor image sequence must be an M-by-N-by-3-by-K array. montage(X, map) displays all the frames of the indexed image array X, using the colormap map for all frames. X is an M-by-N-by-1-by-K array. montage(..., param1, value1, param2, value2, ...) returns a customized display of an image montage, depending on the values of the optional parameter/value pairs. See “Parameters” on page 3-678 for a list of available parameters. h = montage(...) returns the handle to the image object. Parameters The following table lists the parameters available, alphabetically by name. Parameter names can be abbreviated, and case does not matter. 3-678 montage Parameter Value 'DisplayRange' A 1-by-2 vector, [LOW HIGH] that controls the display range of each image in a grayscale sequence. The value LOW (and any value less than LOW) displays as black; the value HIGH (and any value greater than HIGH) displays as white. If you specify an empty matrix ([]), montage uses the minimum and maximum values of the images to be displayed in the montage as specified by 'Indices'. For example, if 'Indices' is 1:K and the 'DisplayRange' is set to [], the minimum value in I (min(I(:)) is displayed as black, and the maximum value (max(I(:)) is displayed as white. Default: Range of the data type of I. 'Indices' A numeric array specifying which frames to display in the montage. For example, to create a montage of the first four frames in I, enter montage(I,'Indices',1:4);. You can use this parameter to specify individual frames or skip frames. For example, the value 1:2:20 displays every other frame. Default: 1:K, where K is the total number of frames to display. 'Size' A 2-element vector, [NROWS NCOLS], specifying the number of rows and number of columns in the montage. You can use NaNs in the size vector to indicate that montage should calculate size in a particular dimension in a way that includes all the images in the montage. For example, if 'Size’ is [2 NaN], the montage will have 2 rows, and the number of columns will be computed automatically to include all of the images in the montage. The images are displayed horizontally across columns. Default: Calculated so the images in the montage roughly form a square.montage considers the aspect ratio when calculating the number of images to display horizontally and vertically. Class Support A grayscale image array can be logical, uint8, uint16, int16, single, or double. An indexed image can be logical, uint8, uint16, single, or double. The colormap must be double. A truecolor image can be 3-679 montage uint8, uint16, single, or double. The output is a handle to the image object produced by montage. Examples Create a montage from a series of files. By default, montage arranges the images into a square. fileFolder = fullfile(matlabroot,'toolbox','images','imdemos'); dirOutput = dir(fullfile(fileFolder,'AT3_1m4_*.tif')); fileNames = {dirOutput.name}' montage(fileNames); Display the same set of images in two rows and five columns. montage(fileNames, 'Size', [2 5]); This example shows you how to customize the number of images in the montage and the contrast in the montage. load mri montage(D,map) 3-680 montage Create a new montage of the first 9 images. figure montage(D, map, 'Indices', 1:9); Maximize the contrast of D without using the colormap. figure montage(D, 'DisplayRange', []); See Also immovie | imshow 3-681 multithresh Purpose Multilevel image thresholds using Otsu ´s method Syntax thresh = multithresh(A) thresh = multithresh(A,N) [thresh,metric] = multithresh( ___ ) Description thresh = multithresh(A) returns the single threshold value thresh computed for image A using Otsu’s method. • thresh is an input argument to imquantize that converts A into a binary image. thresh = multithresh(A,N) returns thresh containing N threshold values using Otsu’s method. • thresh is a 1xN vector which can be used to convert image A into an image with N + 1 discrete levels using imquantize. [thresh,metric] = multithresh( ___ ) returns metric, a measure of the effectiveness of the computed thresholds. metric is in the range [0 1] and a higher value indicates greater effectiveness of the thresholds in separating the input image into N + 1 classes based on Otsu’s objective criterion. Input Arguments A - Input image image Input image, specified as a non-sparse numeric matrix of any dimension. multithresh finds the thresholds based on the aggregate histogram of the entire matrix. An RGB image is considered a 3-D numeric array and the thresholds are computed for the combined data from all three color planes. multithresh uses the range of the input A [min(A(:)) max(A(:))] as the limits for computing the histogram which is used in subsequent computations. Any NaNs are ignored in computation. Any Infs and -Infs are counted in the first and last bin of the histogram, respectively. 3-682 multithresh For degenerate inputs where the number of unique values in A is less than or equal to N, there is no viable solution using Otsu’s method. For such inputs, thresh contains all the unique values from A and possibly some extra values that are chosen arbitrarily. Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 N - Number of threshold values 1 (default) | scalar Number of threshold values, specified as a scalar value. For N > 2, multithresh uses search-based optimization of Otsu’s criterion to find the thresholds. The search-based optimization guarantees only locally optimal results. Since the chance of converging to local optimum increases with N, it is preferable to use smaller values of N, typically N < 10. The maximum allowed value for N is 20. Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 Output Arguments thresh - Set of values used to quantize an image 1xN vector Set of values used to quantize an image, returned as a 1xN vector, whose data type is the same as image A. metric - Measure of the effectiveness of the thresholds scalar Measure of the effectiveness of the thresholds, returned as a scalar value. Higher values indicates greater effectiveness of the thresholds in separating the input image into N+1 classes based on Otsu’s objective criterion. For degenerate inputs where the number of unique values in A is less than or equal to N, metric equals 0. Data Types double 3-683 multithresh Examples Image Threshold Compute multiple thresholds for an image using multithresh and apply those thresholds to the image using imquantize to get segment labels. I = imread('circlesBrightDark.png'); Computing two thresholds quantizes the image into three discrete levels. thresh = multithresh(I,2); seg_I = imquantize(I,thresh); % Apply the thresholds to obtain segmented RGB = label2rgb(seg_I); % convert to color image figure; imshowpair(I,RGB,'montage'); axis off; title('Original Image 3-684 % display images side-by-side RGB Segmented Image') multithresh Two Schemes for RGB Image Quantization Quantize the truecolor RGB image to eight levels using multilevel thresholding function multithresh. Compare results between thresholding the entire RGB image versus plane-by-plane thresholding. Read in a truecolor RGB image. 3-685 multithresh I = imread('peppers.png'); imshow(I); axis off; title('RGB Image'); 3-686 multithresh Generate thresholds for seven levels from the entire RGB image; then repeat process for each plane in the RGB image threshRGB = multithresh(I,7) % 7 thresholds from entire RGB image threshPlanes = zeros(3,7); % initialize % Compute thresholds for each R, G, and B plane for i = 1:3 threshPlane(i,:) = multithresh(I(:,:,i),7); end threshPlane threshRGB = 24 51 79 109 141 177 221 92 74 60 125 100 86 159 128 127 195 164 165 231 209 222 threshPlane = 40 27 18 69 49 38 Process the entire image with the set of threshold values computed from the entire image. Similarly, process each RGB plane separately using the threshold vector computed from the given plane. Add black (0) and white (255) to value vector which assigns values to the output image. value = [0 threshRGB(2:end) 255]; % Quantize entire image using one threshold vector quantRGB = imquantize(I, threshRGB, value); quantPlane = zeros( size(I) ); % Quantize each RGB plane using threshold vector generated for that pl for i = 1:3 value = [0 threshPlane(i,2:end) 255] % output value to assign quantPlane(:,:,i) = imquantize(I(:,:,i), threshPlane(i,:), value); end 3-687 multithresh quantPlane = uint8( quantPlane ); % convert from double to uint8 Display both posterized images and note the visual differences in the two thresholding schemes. The following code snippet computes the number of unique RGB pixel vectors in each output image. Note that the plane-by-plane thresholding scheme yields about 23% more colors than the full RGB image scheme. 3-688 multithresh % Convert images to mx3 matrices dim = size( quantRGB ); quantRGBmx3 = reshape(quantRGB, prod(dim(1:2)), 3); quantPlanemx3 = reshape(quantPlane, prod(dim(1:2)), 3); % Extract only unique 3 element RGB pixel vectors from each matrix colorsRGB = unique( quantRGBmx3, 'rows'); colorsPlane = unique( quantPlanemx3, 'rows'); disp(['Number of unique colors in RGB image : ' int2str(len disp(['Number of unique colors in Plane-by-Plane image : ' int2str(len Number of unique colors in RGB image : 188 Number of unique colors in Plane-by-Plane image : 231 Behavior of Output Argument metric Compute various thresholds for different values of N and on different images as a way of showing the variation of metric. I = imread('circlesBrightDark.png'); % find all unique grayscale values in image uniqLevels = unique(I(:)); disp(['Number of unique levels = ' int2str( length(uniqLevels) )]); Number of unique levels = 148 Compute a series of thresholds at monotonically increasing values of N % Compute the thresholds Nvals = [1 2 4 8]; for i = 1:length(Nvals) [thresh, metric] = multithresh(I, Nvals(i) ); disp(['N = ' int2str(Nvals(i)) ' | metric = ' num2str(metric)]); end N = 1 | metric = 0.54767 3-689 multithresh N = 2 N = 4 N = 8 | | | metric = 0.98715 metric = 0.99648 metric = 0.99902 Apply the N=8 set of thresholds to obtain a 9 level segmented image via imquantize. seg_Neq8 = imquantize(I,thresh); uniqLevels = unique( seg_Neq8(:) ) % Verify that image has only 9 level uniqLevels = 1 2 3 4 5 6 7 8 9 seg_Neq8 is input to multithresh and N is set to equal to 8 which is 1 less than the number of levels in this segmented image. [thresh, metric] = multithresh(seg_Neq8,8) thresh = Columns 1 through 7 1.8784 Column 8 8.1216 3-690 2.7882 3.6667 4.5451 5.4549 6.3333 7.2118 multithresh metric = 1 Note what happens when N is increased by 1 and now equals the number of levels in the image. [thresh, metric] = multithresh(seg_Neq8,9) Warning: No solution exists because the number of unique levels in ima too few to find 9 thresholds. Returning an arbitrarily chosen solution > In multithresh at 171 thresh = 1 2 3 4 5 6 7 8 9 metric = 0 Here the input was degenerate because the number of levels in the image was too few for the number of requested thresholds. Hence metric is 0. References [1] Otsu, N., "A Threshold Selection Method from Gray-Level Histograms," IEEE Transactions on Systems, Man, and Cybernetics, Vol. 9, No. 1, 1979, pp. 62-66. See Also graythresh | imquantize | im2bw | rgb2ind 3-691 nitfinfo Purpose Read metadata from National Imagery Transmission Format (NITF) file Syntax metadata = nitfinfo(filename) Description metadata = nitfinfo(filename) returns a structure whose fields contain file-level metadata about the images, annotations, and graphics in a National Imagery Transmission Format (NITF) file. NITF is an mage format used by the U.S. government and military for transmitting documents. A NITF file can contain multiple images and include text and graphic layers. filename is a character array that specifies the name of the NITF file, which must be in the current directory, in a directory on the MATLAB path, or contain the full path to the file. nitfinfo supports version 2.0 and 2.1 NITF files, at all Joint Interoperability Test Command (JITC) compliance levels, as well as the NATO Secondary Image Format (NSIF) 1.0. nitfinfo does not support NITF 1.1 files. See Also 3-692 isnitf | nitfread nitfread Purpose Read image from NITF file Syntax X = nitfread(filename) X = nitfread(filename,idx) X = nitfread(...,'PixelRegion',{rows,cols}) Description X = nitfread(filename) reads the first image from the National Imagery Transmission Format (NITF) file specified by the character array filename. The filename array must be in the current directory or in a directory on the MATLAB path, or it must contain the full path to the file. X = nitfread(filename,idx) reads the image with index number idx from a NITF file that contains multiple images. X = nitfread(...,'PixelRegion',{rows,cols}) reads a region of pixels from a NITF image. rows and cols are two or three element vectors, where the first value is the starting location, and the last value is the ending location. In the three value syntax, the second value is the increment. This function supports version 2.0 and 2.1 NITF files, as well as NSIF 1.0. Compressed images, image submasks, and NITF 1.1 files are not supported. See Also isnitf | nitfinfo 3-693 nlfilter Purpose General sliding-neighborhood operations Syntax B = nlfilter(A, [m n], fun) B = nlfilter(A, 'indexed',...) Description B = nlfilter(A, [m n], fun) applies the function fun to each m-by-n sliding block of the grayscale image A. fun is a function that accepts an m-by-n matrix as input and returns a scalar result. c = fun(x) fun must be a function handle. Parameterizing Functions, in the MATLAB Mathematics documentation, explains how to provide additional parameters to the function fun. c is the output value for the center pixel in the m-by-n block x. nlfilter calls fun for each pixel in A. nlfilter zero-pads the m-by-n block at the edges, if necessary. B = nlfilter(A, 'indexed',...) processes A as an indexed image, padding with 1’s if A is of class single or double and 0’s if A is of class logical, uint8, or uint16. Class Support The input image A can be of any class supported by fun. The class of B depends on the class of the output from fun. When A is grayscale, it can be any numeric type or logical. When A is indexed, it can be logical, uint8, uint16, single, or double. Tips nlfilter can take a long time to process large images. In some cases, the colfilt function can perform the same operation much faster. Examples This example produces the same result as calling medfilt2 with a 3-by-3 neighborhood. A = imread('cameraman.tif'); A = im2double(A); 3-694 nlfilter fun = @(x) median(x(:)); B = nlfilter(A,[3 3],fun); imshow(A), figure, imshow(B) See Also blockproc | colfilt | function_handle How To • “Anonymous Functions” • “Parameterizing Functions” 3-695 normxcorr2 Purpose Normalized 2-D cross-correlation Syntax C = normxcorr2(template, A) Description C = normxcorr2(template, A) computes the normalized cross-correlation of the matrices template and A. The matrix A must be larger than the matrix template for the normalization to be meaningful. The values of template cannot all be the same. The resulting matrix C contains the correlation coefficients, which can range in value from -1.0 to 1.0. Class Support The input matrices can be numeric. The output matrix C is double. Tips Normalized cross-correlation is an undefined operation in regions where A has zero variance over the full extent of the template. In these regions, we assign correlation coefficients of zero to the output C. Algorithms normxcorr2 uses the following general procedure [1], [2]: 1 Calculate cross-correlation in the spatial or the frequency domain, depending on size of images. 2 Calculate local sums by precomputing running sums. [1] 3 Use local sums to normalize the cross-correlation to get correlation coefficients. The implementation closely follows following formula from [1]: γ(u, v) = where 3-696 {∑ ∑ x, y ⎡⎣ f ( x, y ) − fu,v ⎤⎦ ⎡⎣t ( x − u, y − v) − t ⎤⎦ ⎡ f ( x, y ) − fu,v ⎤ ⎦ x, y ⎣ 2 ∑ x, y ⎡⎣t( x − u, y − v) − t ⎤⎦ 2 } 0 .5 normxcorr2 • f is the image. • t is the mean of the template • fu,v is the mean of f ( x, y) in the region under the template. Examples template = .2*ones(11); % Make light gray plus on dark gray background template(6,3:9) = .6; template(3:9,6) = .6; BW = template > 0.5; % Make white plus on black background figure, imshow(BW), figure, imshow(template) % Make new image that offsets the template offsetTemplate = .2*ones(21); offset = [3 5]; % Shift by 3 rows, 5 columns offsetTemplate( (1:size(template,1))+offset(1),... (1:size(template,2))+offset(2) ) = template; figure, imshow(offsetTemplate) % Cross-correlate BW and offsetTemplate to recover offset cc = normxcorr2(BW,offsetTemplate); [max_cc, imax] = max(abs(cc(:))); [ypeak, xpeak] = ind2sub(size(cc),imax(1)); corr_offset = [ (ypeak-size(template,1)) (xpeak-size(template,2)) ]; isequal(corr_offset,offset) % 1 means offset was recovered References [1] Lewis, J. P., "Fast Normalized Cross-Correlation," Industrial Light & Magic [2] Haralick, Robert M., and Linda G. Shapiro, Computer and Robot Vision, Volume II, Addison-Wesley, 1992, pp. 316-317. See Also corrcoef 3-697 ntsc2rgb Purpose Convert NTSC values to RGB color space Syntax rgbmap = ntsc2rgb(yiqmap) RGB = ntsc2rgb(YIQ) Description rgbmap = ntsc2rgb(yiqmap) converts the m-by-3 NTSC (television) color values in yiqmap to RGB color space. If yiqmap is m-by-3 and contains the NTSC luminance (Y) and chrominance (I and Q) color components as columns, then rgbmap is an m-by-3 matrix that contains the red, green, and blue values equivalent to those colors. Both rgbmap and yiqmap contain intensities in the range 0 to 1.0. The intensity 0 corresponds to the absence of the component, while the intensity 1.0 corresponds to full saturation of the component. RGB = ntsc2rgb(YIQ) converts the NTSC image YIQ to the equivalent truecolor image RGB. ntsc2rgb computes the RGB values from the NTSC components using 0.956 0.621⎤ ⎡Y ⎤ ⎡ R ⎤ ⎡1.000 ⎢ G ⎥ = ⎢1.000 −0.272 −0.647 ⎥ ⎢ I ⎥ . ⎢ ⎥ ⎢ ⎥⎢ ⎥ ⎢⎣ B ⎥⎦ ⎢⎣1.000 −1.106 1.703 ⎥⎦ ⎢⎣ Q ⎥⎦ Class Support The input image or colormap must be of class double. The output is of class double. Examples Convert RGB image to NTSC and back. RGB = imread('board.tif'); NTSC = rgb2ntsc(RGB); RGB2 = ntsc2rgb(NTSC); See Also 3-698 rgb2ntsc | rgb2ind | ind2rgb | ind2gray openrset Purpose Open R-Set file Syntax openrset(filename) Description openrset(filename) opens the reduced resolution dataset (R-Set) specified by filename for viewing. See Also imtool | rsetwrite 3-699 ordfilt2 Purpose 2-D order-statistic filtering Syntax B = ordfilt2(A, order, domain) B = ordfilt2(A, order, domain, S) B = ordfilt2(..., padopt) Description B = ordfilt2(A, order, domain) replaces each element in A by the orderth element in the sorted set of neighbors specified by the nonzero elements in domain. B = ordfilt2(A, order, domain, S) where S is the same size as domain, uses the values of S corresponding to the nonzero values of domain as additive offsets. B = ordfilt2(..., padopt) controls how the matrix boundaries are padded. Set padopt to 'zeros' (the default) or 'symmetric'. If padopt is 'zeros', A is padded with 0’s at the boundaries. If padopt is 'symmetric', A is symmetrically extended at the boundaries. Class Support The class of A can be logical, uint8, uint16, or double. The class of B is the same as the class of A, unless the additive offset form of ordfilt2 is used, in which case the class of B is double. Tips domain is equivalent to the structuring element used for binary image operations. It is a matrix containing only 1’s and 0’s; the 1’s define the neighborhood for the filtering operation. For example, B = ordfilt2(A,5,ones(3,3)) implements a 3-by-3 median filter; B = ordfilt2(A,1,ones(3,3)) implements a 3-by-3 minimum filter; and B = ordfilt2(A,9,ones(3,3)) implements a 3-by-3 maximum filter. B = ordfilt2(A,1,[0 1 0; 1 0 1; 0 1 0]) replaces each element in A by the minimum of its north, east, south, and west neighbors. The syntax that includes S (the matrix of additive offsets) can be used to implement grayscale morphological operations, including grayscale dilation and erosion. 3-700 ordfilt2 Performance Considerations When working with large domain matrices that do not contain any zero-valued elements, ordfilt2 can achieve higher performance if A is in an integer data format (uint8, int8, uint16, int16). The gain in speed is larger for uint8 and int8 than for the 16-bit data types. For 8-bit data formats, the domain matrix must contain seven or more rows. For 16-bit data formats, the domain matrix must contain three or more rows and 520 or more elements. Examples This examples uses a maximum filter with a [5 5] neighborhood. This is equivalent to imdilate(image,strel('square',5)). A = imread('snowflakes.png'); B = ordfilt2(A,25,true(5)); figure, imshow(A), figure, imshow(B) References [1] Haralick, Robert M., and Linda G. Shapiro, Computer and Robot Vision, Volume I, Addison-Wesley, 1992. [2] Huang, T.S., G.J.Yang, and G.Y.Tang. "A fast two-dimensional median filtering algorithm.", IEEE transactions on Acoustics, Speech and Signal Processing, Vol ASSP 27, No. 1, February 1979 See Also medfilt2 3-701 otf2psf Purpose Convert optical transfer function to point-spread function Syntax PSF = otf2psf(OTF) PSF = otf2psf(OTF, OUTSIZE) Description PSF = otf2psf(OTF) computes the inverse Fast Fourier Transform (IFFT) of the optical transfer function (OTF) array and creates a point-spread function (PSF), centered at the origin. By default, the PSF is the same size as the OTF. PSF = otf2psf(OTF, OUTSIZE) converts the OTF array into a PSF array, where OUTSIZE specifies the size of the output point-spread function. The size of the output array must not exceed the size of the OTF array in any dimension. To center the PSF at the origin, otf2psf circularly shifts the values of the output array down (or to the right) until the (1,1) element reaches the central position, then it crops the result to match dimensions specified by OUTSIZE. Note that this function is used in image convolution/deconvolution when the operations involve the FFT. Class Support OTF can be any nonsparse, numeric array. PSF is of class double. Examples PSF = fspecial('gaussian',13,1); OTF = psf2otf(PSF,[31 31]); % PSF --> OTF PSF2 = otf2psf(OTF,size(PSF)); % OTF --> PSF2 subplot(1,2,1); surf(abs(OTF)); title('|OTF|'); axis square; axis tight subplot(1,2,2); surf(PSF2); title('Corresponding PSF'); axis square; axis tight See Also psf2otf | circshift | padarray 3-702 padarray Purpose Pad array Syntax B = padarray(A, padsize) B = padarray(A, padsize, padval) B = padarray(A, padsize, padval, direction) Description B = padarray(A, padsize) pads array A with 0’s (zeros). padsize is a vector of nonnegative integers that specifies both the amount of padding to add and the dimension along which to add it. The value of an element in the vector specifies the amount of padding to add. The order of the element in the vector specifies the dimension along which to add the padding. For example, a padsize value of [2 3] means add 2 elements of padding along the first dimension and 3 elements of padding along the second dimension. By default, paddarray adds padding before the first element and after the last element along the specified dimension. B = padarray(A, padsize, padval) pads array A where padval specifies the value to use as the pad value. padarray uses the value 0 (zero) as the default. padval can be a scalar that specifies the pad value directly or one of the following text strings that specifies the method padarray uses to determine the values of the elements added as padding. Value Meaning 'circular' Pad with circular repetition of elements within the dimension. 'replicate' Pad by repeating border elements of array. 'symmetric' Pad array with mirror reflections of itself. B = padarray(A, padsize, padval, direction) pads A in the direction specified by the string direction. direction can be one of the following strings. The default value is enclosed in braces ({}). 3-703 padarray Value Meaning {'both'} Pads before the first element and after the last array element along each dimension. This is the default. 'post' Pad after the last array element along each dimension. 'pre' Pad before the first array element along each dimension. Class Support When padding with a constant value, A can be numeric or logical. When padding using the 'circular', 'replicate', or 'symmetric' methods, A can be of any class. B is of the same class as A. Examples Example 1 Add three elements of padding to the beginning of a vector. The padding elements, indicated by the gray shading, contain mirror copies of the array elements. a = [ 1 2 3 4 ]; b = padarray(a,[0 3],'symmetric','pre') b == Example 2 Add three elements of padding to the end of the first dimension of the array and two elements of padding to the end of the second dimension. The example uses the value of the last array element as the padding value. A = [1 2; 3 4]; B = padarray(A,[3 2],'replicate','post') B = 3-704 padarray Example 3 Add three elements of padding to the vertical and horizontal dimensions of a three-dimensional array. Use default values for the pad value and direction. A = [ 1 2; 3 4]; B = [ 5 6; 7 8]; C = cat(3,A,B) C(:,:,1) = 1 3 2 4 C(:,:,2) = 5 7 6 8 D = padarray(C,[3 3]) D(:,:,1) == 3-705 padarray D(:,:,2) === See Also 3-706 circshift | imfilter para2fan Purpose Convert parallel-beam projections to fan-beam Syntax F = para2fan(P, D) I = para2fan(..., param1, val1, param2, val2,...) [F, fan_positions, fan_rotation_angles] = fan2para(...) Description F = para2fan(P, D) computes the fan-beam data (sinogram) F from the parallel-beam data (sinogram) P. Each column of P contains the parallel-beam sensor samples at one rotation angle. D is the distance in pixels from the center of rotation to the center of the sensors. The sensors are assumed to have a one-pixel spacing. The parallel-beam rotation angles are assumed to be spaced equally to cover [0,180] degrees. The calculated fan-beam rotation angles cover [0,360) with the same spacing as the parallel-beam rotation angles. The calculated fan-beam angles are equally spaced with the spacing set to the smallest angle implied by the sensor spacing. I = para2fan(..., param1, val1, param2, val2,...) specifies parameters that control various aspects of the para2fan conversion. Parameter names can be abbreviated, and case does not matter. Default values are enclosed in braces like this: {default}. Parameters include Parameter Description 'FanCoverage' String specifying the range through which the beams are rotated. Possible values: {'cycle'} or 'minimal' See ifanbeam for details. 'FanRotationIncrement' Positive real scalar specifying the rotation angle increment of the fan-beam projections in degrees. If 'FanCoverage' is 'cycle', 'FanRotationIncrement' must be a factor of 360. If 'FanRotationIncrement' is not specified, then it is set to the same spacing as the parallel-beam rotation angles. 3-707 para2fan Parameter Description 'FanSensorGeometry' Text string specifying how sensors are positioned. Possible values: {'arc'} or 'line' See fanbeam for details. 'FanSensorSpacing' Positive real scalar specifying the spacing of the fan beams. Interpretation of the value depends on the setting of 'FanSensorGeometry': If 'FanSensorGeometry' is 'arc', the value defines the angular spacing in degrees. Default value is 1. If 'FanSensorGeometry' is 'line', the value defines the linear spacing in pixels. If 'FanSensorSpacing' is not specified, the default is the smallest value implied by 'ParallelSensorSpacing' such that If 'FanSensorGeometry' is 'arc', 'FanSensorSpacing' is 180/PI*ASIN(PSPACE/D) where PSPACE is the value of 'ParallelSensorSpacing'. If 'FanSensorGeometry' is 'line', 'FanSensorSpacing' is D*ASIN(PSPACE/D) 3-708 para2fan Parameter Description 'Interpolation' Text string specifying the type of interpolation used between the parallel-beam and fan-beam data. 'nearest' — Nearest-neighbor {'linear'} — Linear 'spline' — Piecewise cubic spline 'pchip' — Piecewise cubic Hermite (PCHIP) 'cubic' — Same as 'pchip' 'ParallelCoverage' Text string specifying the range of rotation. 'cycle' -- Parallel data covers 360 degrees {'halfcycle'} — Parallel data covers 180 degrees 'ParallelRotationIncrement' Positive real scalar specifying the parallel-beam rotation angle increment, measured in degrees. Parallel beam angles are calculated to cover [0,180) degrees with increment PAR_ROT_INC, where PAR_ROT_INC is the value of 'ParallelRotationIncrement'. 180/PAR_ROT_INC must be an integer. If 'ParallelRotationIncrement' is not specified, the increment is assumed to be the same as the increment of the fan-beam rotation angles. 'ParallelSensorSpacing' Positive real scalar specifying the spacing of the parallel-beam sensors in pixels. The range of sensor locations is implied by the range of fan angles and is given by [D*sin(min(FAN_ANGLES)),D*sin(max(FAN_ANGLES))] If 'ParallelSensorSpacing' is not specified, the spacing is assumed to be uniform and is set to the minimum spacing implied by the fan angles and sampled over the range implied by the fan angles. 3-709 para2fan [F, fan_positions, fan_rotation_angles] = fan2para(...) returns the fan-beam sensor measurement angles in fan_positions, if 'FanSensorGeometry' is 'arc'. If 'FanSensorGeometry’ is 'line', fan_positions contains the fan-beam sensor positions along the line of sensors. fan_rotation_angles contains rotation angles. Class Support P and D can be double or single, and must be nonsparse. The other numeric input arguments must be double. The output arguments are double. Examples Generate parallel-beam projections ph = phantom(128); theta = 0:180; [P,xp] = radon(ph,theta); imshow(theta,xp,P,[],'n'), axis normal title('Parallel-Beam Projections') xlabel('\theta (degrees)') ylabel('x''') colormap(hot), colorbar Convert to fan-beam projections [F,Fpos,Fangles] = para2fan(P,100); figure, imshow(Fangles,Fpos,F,[],'n'), axis normal title('Fan-Beam Projections') xlabel('\theta (degrees)') ylabel('Sensor Locations (degrees)') colormap(hot), colorbar See Also 3-710 fan2para | fanbeam | iradon | ifanbeam | phantom | radon phantom Purpose Create head phantom image Syntax P = phantom(def, n) P = phantom(E, n) [P, E] = phantom(...) Description P = phantom(def, n) generates an image of a head phantom that can be used to test the numerical accuracy of radon and iradon or other two-dimensional reconstruction algorithms. P is a grayscale intensity image that consists of one large ellipse (representing the brain) containing several smaller ellipses (representing features in the brain). def is a string that specifies the type of head phantom to generate. Valid values are • 'Shepp-Logan' — Test image used widely by researchers in tomography • 'Modified Shepp-Logan' (default) — Variant of the Shepp-Logan phantom in which the contrast is improved for better visual perception n is a scalar that specifies the number of rows and columns in P. If you omit the argument, n defaults to 256. P = phantom(E, n) generates a user-defined phantom, where each row of the matrix E specifies an ellipse in the image. E has six columns, with each column containing a different parameter for the ellipses. This table describes the columns of the matrix. Column Parameter Meaning Column 1 A Additive intensity value of the ellipse Column 2 a Length of the horizontal semiaxis of the ellipse Column 3 b Length of the vertical semiaxis of the ellipse Column 4 x0 x-coordinate of the center of the ellipse 3-711 phantom Column Parameter Meaning Column 5 y0 y-coordinate of the center of the ellipse Column 6 phi Angle (in degrees) between the horizontal semiaxis of the ellipse and the x-axis of the image For purposes of generating the phantom, the domains for the x- and y-axes span [-1,1]. Columns 2 through 5 must be specified in terms of this range. [P, E] = phantom(...) returns the matrix E used to generate the phantom. Class Support All inputs and all outputs must be of class double. Tips For any given pixel in the output image, the pixel’s value is equal to the sum of the additive intensity values of all ellipses that the pixel is a part of. If a pixel is not part of any ellipse, its value is 0. The additive intensity value A for an ellipse can be positive or negative; if it is negative, the ellipse will be darker than the surrounding pixels. Note that, depending on the values of A, some pixels can have values outside the range [0,1]. Examples 3-712 P = phantom('Modified Shepp-Logan',200); imshow(P) phantom References [1] Jain, Anil K., Fundamentals of Digital Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1989, p. 439. See Also radon | iradon 3-713 poly2mask Purpose Convert region of interest (ROI) polygon to region mask Syntax BW = poly2mask(x, y, m, n) Description BW = poly2mask(x, y, m, n) computes a binary region of interest (ROI) mask, BW, from an ROI polygon, represented by the vectors x and y. The size of BW is m-by-n. poly2mask sets pixels in BW that are inside the polygon (X,Y) to 1 and sets pixels outside the polygon to 0. poly2mask closes the polygon automatically if it isn’t already closed. Note on Rectangular Polygons When the input polygon goes through the middle of a pixel, sometimes the pixel is determined to be inside the polygon and sometimes it is determined to be outside (see Algorithm for details). To specify a polygon that includes a given rectangular set of pixels, make the edges of the polygon lie along the outside edges of the bounding pixels, instead of the center of the pixels. For example, to include pixels in columns 4 through 10 and rows 4 through 10, you might specify the polygon vertices like this: x = [4 10 10 4 4]; y = [4 4 10 10 4]; mask = poly2mask(x,y,12,12) mask = 3-714 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 0 0 poly2mask 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 In this example, the polygon goes through the center of the bounding pixels, with the result that only some of the desired bounding pixels are determined to be inside the polygon (the pixels in row 4 and column 4 and not in the polygon). To include these elements in the polygon, use fractional values to specify the outside edge of the 4th row (3.5) and the 10th row (10.5), and the outside edge of the 4th column (3.5) and the outside edge of the 10th column (10.5) as vertices, as in the following example: x = [3.5 10.5 10.5 3.5 3.5]; y = [3.5 3.5 10.5 10.5 3.5]; mask = poly2mask(x,y,12,12) mask = 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 Class Support The class of BW is logical Examples x = [63 186 54 190 63]; y = [60 60 209 204 60]; bw = poly2mask(x,y,256,256); 3-715 poly2mask imshow(bw) hold on plot(x,y,'b','LineWidth',2) hold off Create a mask using random points. x = 256*rand(1,4); y = 256*rand(1,4); x(end+1) = x(1); y(end+1) = y(1); bw = poly2mask(x,y,256,256); imshow(bw) hold on plot(x,y,'b','LineWidth',2) hold off Algorithms 3-716 When creating a region of interest (ROI) mask, poly2mask must determine which pixels are included in the region. This determination can be difficult when pixels on the edge of a region are only partially covered by the border line. The following figure illustrates a triangular region of interest, examining in close-up one of the vertices of the ROI. The figure shows how pixels can be partially covered by the border of a region-of-interest. poly2mask Pixels on the Edge of an ROI Are Only Partially Covered by Border To determine which pixels are in the region, poly2mask uses the following algorithm: 1 Divide each pixel (unit square) into a 5-by-5 grid. See “Dividing Pixels into a 5-by-5 Subpixel Grid” on page 3-718 for an illustration. 2 Adjust the position of the vertices to be on the intersections of the subpixel grid. See “Adjusting the Vertices to the Subpixel Grid” on page 3-718 for an illustration. 3 Draw a path from each adjusted vertex to the next, following the edges of the subpixel grid. See “Drawing a Path Between the Adjusted Vertices” on page 3-719 for an illustration. 4 Determine which border pixels are inside the polygon using this rule: if a pixel’s central subpixel is inside the boundaries defined by the 3-717 poly2mask path between adjusted vertices, the pixel is considered inside the polygon. See “Determing Which Pixels Are in the Region” on page 3-720 for an illustration. Dividing Pixels into a 5-by-5 Subpixel Grid The following figure shows the pixel that contains the vertex of the ROI shown previously with this 5-by-5 subpixel grid. Adjusting the Vertices to the Subpixel Grid poly2mask adjusts each vertex of the polygon so that the vertex lies on the subpixel grid. Note how poly2mask rounds up x and y coordinates to find the nearest grid corner. This creates a second, modified polygon, slightly smaller, in this case, than the original ROI. A portion is shown in the following figure. 3-718 poly2mask Drawing a Path Between the Adjusted Vertices poly2mask forms a path from each adjusted vertex to the next, following the edges of the subpixel grid. In the following figure, a portion of this modified polygon is shown by the thick dark lines. 3-719 poly2mask Determing Which Pixels Are in the Region poly2mask uses the following rule to determine which border pixels are inside the polygon: if the pixel’s central subpixel is inside the modified polygon, the pixel is inside the region. In the following figure, the central subpixels of pixels on the ROI border are shaded a dark gray color. Pixels inside the polygon are shaded a lighter gray. Note that the pixel containing the vertex is not part of the ROI because its center pixel is not inside the modified polygon. 3-720 poly2mask See Also roipoly 3-721 psf2otf Purpose Convert point-spread function to optical transfer function Syntax OTF = psf2otf(PSF) OTF = psf2otf(PSF,OUTSIZE) Description OTF = psf2otf(PSF) computes the fast Fourier transform (FFT) of the point-spread function (PSF) array and creates the optical transfer function array, OTF, that is not influenced by the PSF off-centering. By default, the OTF array is the same size as the PSF array. OTF = psf2otf(PSF,OUTSIZE) converts the PSF array into an OTF array, where OUTSIZE specifies the size of the OTF array. OUTSIZE cannot be smaller than the PSF array size in any dimension. To ensure that the OTF is not altered because of PSF off-centering, psf2otf postpads the PSF array (down or to the right) with 0’s to match dimensions specified in OUTSIZE, then circularly shifts the values of the PSF array up (or to the left) until the central pixel reaches (1,1) position. Note that this function is used in image convolution/deconvolution when the operations involve the FFT. Class Support PSF can be any nonsparse, numeric array. OTF is of class double. Examples PSF = fspecial('gaussian',13,1); OTF = psf2otf(PSF,[31 31]); % PSF --> OTF subplot(1,2,1); surf(PSF); title('PSF'); axis square; axis tight subplot(1,2,2); surf(abs(OTF)); title('Corresponding |OTF|'); axis square; axis tight See Also otf2psf | circshift | padarray 3-722 qtdecomp Purpose Quadtree decomposition Syntax S S S S S Description = = = = = qtdecomp(I) qtdecomp(I, qtdecomp(I, qtdecomp(I, qtdecomp(I, threshold) threshold, mindim) threshold, [mindim maxdim]) fun) qtdecomp divides a square image into four equal-sized square blocks, and then tests each block to see if it meets some criterion of homogeneity. If a block meets the criterion, it is not divided any further. If it does not meet the criterion, it is subdivided again into four blocks, and the test criterion is applied to those blocks. This process is repeated iteratively until each block meets the criterion. The result can have blocks of several different sizes. S = qtdecomp(I) performs a quadtree decomposition on the intensity image I and returns the quadtree structure in the sparse matrix S. If S(k,m) is nonzero, then (k,m) is the upper left corner of a block in the decomposition, and the size of the block is given by S(k,m). By default, qtdecomp splits a block unless all elements in the block are equal. S = qtdecomp(I, threshold) splits a block if the maximum value of the block elements minus the minimum value of the block elements is greater than threshold. threshold is specified as a value between 0 and 1, even if I is of class uint8 or uint16. If I is uint8, the threshold value you supply is multiplied by 255 to determine the actual threshold to use; if I is uint16, the threshold value you supply is multiplied by 65535. S = qtdecomp(I, threshold, mindim) will not produce blocks smaller than mindim, even if the resulting blocks do not meet the threshold condition. S = qtdecomp(I, threshold, [mindim maxdim]) will not produce blocks smaller than mindim or larger than maxdim. Blocks larger than maxdim are split even if they meet the threshold condition. maxdim/mindim must be a power of 2. 3-723 qtdecomp S = qtdecomp(I, fun) uses the function fun to determine whether to split a block. qtdecomp calls fun with all the current blocks of size m-by-m stacked into an m-by-m-by-k array, where k is the number of m-by-m blocks. fun returns a logical k-element vector, whose values are 1 if the corresponding block should be split, and 0 otherwise. (For example, if k(3) is 0, the third m-by-m block should not be split.) fun must be a function_handle. Parameterizing Functions, in the MATLAB Mathematics documentation, explains how to provide additional parameters to the function fun. Class Support For the syntaxes that do not include a function, the input image can be of class logical, uint8, uint16, int16, single, or double. For the syntaxes that include a function, the input image can be of any class supported by the function. The output matrix is always of class sparse. Tips qtdecomp is appropriate primarily for square images whose dimensions are a power of 2, such as 128-by-128 or 512-by-512. These images can be divided until the blocks are as small as 1-by-1. If you use qtdecomp with an image whose dimensions are not a power of 2, at some point the blocks cannot be divided further. For example, if an image is 96-by-96, it can be divided into blocks of size 48-by-48, then 24-by-24, 12-by-12, 6-by-6, and finally 3-by-3. No further division beyond 3-by-3 is possible. To process this image, you must set mindim to 3 (or to 3 times a power of 2); if you are using the syntax that includes a function, the function must return 0 at the point when the block cannot be divided further. Examples I = uint8([1 1 1 1 1 1 2 1 1 1 1 1 1 20 22 20 22 20 22 20 22 2 3 6 1 4 5 1 7 7 1 6 6 20 22 22 20 20 20 20 20 S = qtdecomp(I,.05); 3-724 6;... 6 8;... 7 7;... 5 5;... 1 2 3 4;... 5 4 7 8;... 9 12 40 12;... 13 14 15 16]); qtdecomp disp(full(S)); View the block representation of quadtree decomposition. I = imread('liftingbody.png'); S = qtdecomp(I,.27); blocks = repmat(uint8(0),size(S)); for dim = [512 256 128 64 32 16 8 4 2 1]; numblocks = length(find(S==dim)); if (numblocks > 0) values = repmat(uint8(1),[dim dim numblocks]); values(2:dim,2:dim,:) = 0; blocks = qtsetblk(blocks,S,dim,values); end end blocks(end,1:end) = 1; blocks(1:end,end) = 1; imshow(I), figure, imshow(blocks,[]) The following figure shows the original image and a representation of the quadtree decomposition of the image. 3-725 qtdecomp Image courtesy of NASA See Also function_handle | qtgetblk | qtsetblk How To • “Anonymous Functions” • “Parameterizing Functions” 3-726 qtgetblk Purpose Block values in quadtree decomposition Syntax [vals, r, c] = qtgetblk(I, S, dim) [vals, idx] = qtgetblk(I, S, dim) Description [vals, r, c] = qtgetblk(I, S, dim) returns in vals an array containing the dim-by-dim blocks in the quadtree decomposition of I. S is the sparse matrix returned by qtdecomp; it contains the quadtree structure. vals is a dim-by-dim-by-k array, where k is the number of dim-by-dim blocks in the quadtree decomposition; if there are no blocks of the specified size, all outputs are returned as empty matrices. r and c are vectors containing the row and column coordinates of the upper left corners of the blocks. [vals, idx] = qtgetblk(I, S, dim) returns in idx a vector containing the linear indices of the upper left corners of the blocks. Class Support I can be of class logical, uint8, uint16, int16, single, or double. S is of class sparse. Tips The ordering of the blocks in vals matches the columnwise order of the blocks in I. For example, if vals is 4-by-4-by-2, vals(:,:,1) contains the values from the first 4-by-4 block in I, and vals(:,:,2) contains the values from the second 4-by-4 block. Examples I = [1 1 1 1 20 20 20 22 1 1 1 1 22 22 22 22 1 2 1 1 20 22 20 20 1 1 1 1 22 20 20 20 2 4 10 20 1 5 9 13 3 5 15 25 2 6 10 14 6 6 7 7 3 7 11 15 6 8 7 7 4 8 12 16]; S = qtdecomp(I,5); 3-727 qtgetblk [vals,r,c] = qtgetblk(I,S,4) See Also 3-728 qtdecomp | qtsetblk qtsetblk Purpose Set block values in quadtree decomposition Syntax J = qtsetblk(I, S, dim, vals) Description J = qtsetblk(I, S, dim, vals) replaces each dim-by-dim block in the quadtree decomposition of I with the corresponding dim-by-dim block in vals. S is the sparse matrix returned by qtdecomp; it contains the quadtree structure. vals is a dim-by-dim-by-k array, where k is the number of dim-by-dim blocks in the quadtree decomposition. Class Support I can be of class logical, uint8, uint16, int16, single, or double. S is of class sparse. Tips The ordering of the blocks in vals must match the columnwise order of the blocks in I. For example, if vals is 4-by-4-by-2, vals(:,:,1) contains the values used to replace the first 4-by-4 block in I, and vals(:,:,2) contains the values for the second 4-by-4 block. Examples I = [1 1 1 1 20 20 20 22 1 1 1 1 22 22 22 22 1 2 1 1 20 22 20 20 1 1 1 1 22 20 20 20 2 4 10 20 1 5 9 13 3 5 15 25 2 6 10 14 6 6 7 7 3 7 11 15 6 8 7 7 4 8 12 16]; S = qtdecomp(I,5); newvals = cat(3,zeros(4),ones(4)); J = qtsetblk(I,S,4,newvals) See Also qtdecomp | qtgetblk 3-729 radon Purpose Radon transform Syntax R = radon(I, theta) [R,xp] = radon(...) Description R = radon(I, theta) returns the Radon transform R of the intensity image I for the angle theta degrees. The Radon transform is the projection of the image intensity along a radial line oriented at a specific angle. If theta is a scalar, R is a column vector containing the Radon transform for theta degrees. If theta is a vector, R is a matrix in which each column is the Radon transform for one of the angles in theta. If you omit theta, it defaults to 0:179. [R,xp] = radon(...) returns a vector xp containing the radial coordinates corresponding to each row of R. The radial coordinates returned in xp are the values along the x’-axis, which is oriented at theta degrees counterclockwise from the x-axis. The origin of both axes is the center pixel of the image, which is defined as floor((size(I)+1)/2) For example, in a 20-by-30 image, the center pixel is (10,15). Class Support I can be of class double, logical, or any integer class. All other inputs and outputs are of class double. Examples iptsetpref('ImshowAxesVisible','on') I = zeros(100,100); I(25:75, 25:75) = 1; theta = 0:180; [R,xp] = radon(I,theta); imshow(R,[],'Xdata',theta,'Ydata',xp,... 'InitialMagnification','fit') xlabel('\theta (degrees)') ylabel('x''') 3-730 radon colormap(hot), colorbar iptsetpref('ImshowAxesVisible','off') References Bracewell, Ronald N., Two-Dimensional Imaging, Englewood Cliffs, NJ, Prentice Hall, 1995, pp. 505-537. Lim, Jae S., Two-Dimensional Signal and Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1990, pp. 42-45. Algorithms The Radon transform of an image is the sum of the Radon transforms of each individual pixel. The algorithm first divides pixels in the image into four subpixels and projects each subpixel separately, as shown in the following figure. 3-731 radon Projections Bins Image Each subpixel’s contribution is proportionally split into the two nearest bins, according to the distance between the projected location and the bin centers. If the subpixel projection hits the center point of a bin, the bin on the axes gets the full value of the subpixel, or one-fourth the value of the pixel. If the subpixel projection hits the border between two bins, the subpixel value is split evenly between the bins. See Also 3-732 fan2para | fanbeam | ifanbeam | iradon | para2fan | phantom rangefilt Purpose Local range of image Syntax J = rangefilt(I) J = rangefilt(I, NHOOD) Description J = rangefilt(I) returns the array J, where each output pixel contains the range value (maximum value − minimum value) of the 3-by-3 neighborhood around the corresponding pixel in the input image I. The image I can have any dimension. The output image J is the same size as the input image I. J = rangefilt(I, NHOOD) performs range filtering of the input image I where you specify the neighborhood in NHOOD. NHOOD is a multidimensional array of zeros and ones where the nonzero elements specify the neighborhood for the range filtering operation. NHOOD's size must be odd in each dimension. By default, rangefilt uses the neighborhood true(3). rangefilt determines the center element of the neighborhood by floor((size(NHOOD) + 1)/2). For information about specifying neighborhoods, see Notes. Class Support I can be logical or numeric and must be real and nonsparse. NHOOD can be logical or numeric and must contain zeros or ones. The output image J is the same class as I, except for signed integer data types. The output class for signed data types is the corresponding unsigned integer data type. For example, if the class of I is int8, then the class of J is uint8. Notes rangefilt uses the morphological functions imdilate and imerode to determine the maximum and minimum values in the specified neighborhood. Consequently, rangefilt uses the padding behavior of these morphological functions. In addition, to specify neighborhoods of various shapes, such as a disk, use the strel function to create a structuring element object and 3-733 rangefilt then use the getnhood method to extract the neighborhood from the structuring element object. Examples (2-D) Identify the two flying objects by measuring the local range. I = imread('liftingbody.png'); J = rangefilt(I); imshow(I), figure, imshow(J); (3-D) Quantify land cover changes in an RGB image. The example first converts the image to L*a*b* colorspace to separate intensity information into a single plane of the image, and then calculates the local range in each layer. I = imread('autumn.tif'); cform = makecform('srgb2lab'); LAB = applycform(I, cform); rLAB = rangefilt(LAB); imshow(I); figure, imshow(rLAB(:,:,1),[]); figure, imshow(rLAB(:,:,2),[]); figure, imshow(rLAB(:,:,3),[]); See Also 3-734 entropyfilt | getnhood | imdilate | imerode | stdfilt | strel reflect Purpose Reflect structuring element Syntax SE2 = reflect(SE) Description SE2 = reflect(SE) reflects a structuring element through its center. The effect is the same as if you rotated the structuring element’s domain 180 degrees around its center (for a 2-D structuring element). If SE is an array of structuring element objects, then reflect(SE) reflects each element of SE, and SE2 has the same size as SE. Class Support SE and SE2 are STREL objects. Examples se = strel([0 0 1; 0 0 0; 0 0 0]) se2 = reflect(se) se = Flat STREL object containing 1 neighbor. Neighborhood: 0 0 0 0 0 0 1 0 0 se2 = Flat STREL object containing 1 neighbor. Neighborhood: 0 0 0 0 1 0 See Also 0 0 0 strel 3-735 regionprops Purpose Measure properties of image regions Syntax STATS STATS STATS STATS Description STATS = regionprops(BW, properties) measures a set of properties for each connected component (object) in the binary image, BW. The image BW is a logical array; it can have any dimension. = = = = regionprops(BW, properties) regionprops(CC, properties) regionprops(L, properties) regionprops(..., I, properties) STATS = regionprops(CC, properties) measures a set of properties for each connected component (object) in CC, which is a structure returned by bwconncomp. STATS = regionprops(L, properties) measures a set of properties for each labeled region in the label matrix L. Positive integer elements of L correspond to different regions. For example, the set of elements of L equal to 1 corresponds to region 1; the set of elements of L equal to 2 corresponds to region 2; and so on. STATS = regionprops(..., I, properties) measures a set of properties for each labeled region in the image I. The first input to regionprops—either BW, CC, or L—identifies the regions in I. The sizes must match: size(I) must equal size(BW), CC.ImageSize, or size(L). STATS is a structure array with length equal to the number of objects in BW, CC.NumObjects, or max(L(:)). The fields of the structure array denote different properties for each region, as specified by properties. Properties properties can be a comma-separated list of strings, a cell array containing strings, the single string 'all', or the string 'basic'. If properties is the string 'all', regionprops computes all the shape measurements, listed in Shape Measurements on page 3-737. If called with a grayscale image, regionprops also returns the pixel value measurements, listed in Pixel Value Measurements on page 3-737. If properties is not specified or if it is the string 'basic', regionprops computes only the 'Area', 'Centroid', and 'BoundingBox' 3-736 regionprops measurements. You can calculate the following properties on N-D inputs: 'Area', 'BoundingBox', 'Centroid', 'FilledArea', 'FilledImage', 'Image', 'PixelIdxList', 'PixelList', and 'SubarrayIdx'. Shape Measurements 'Area' 'EulerNumber' 'Orientation' 'BoundingBox' 'Extent' 'Perimeter' 'Centroid' 'Extrema' 'PixelIdxList' 'ConvexArea' 'FilledArea' 'PixelList' 'ConvexHull' 'FilledImage' 'Solidity' 'ConvexImage' 'Image' 'SubarrayIdx' 'Eccentricity' 'MajorAxisLength' 'EquivDiameter' 'MinorAxisLength' Pixel Value Measurements Definitions 'MaxIntensity' 'MinIntensity' 'MeanIntensity' 'PixelValues' 'WeightedCentroid' 'Area' — Scalar; the actual number of pixels in the region. (This value might differ slightly from the value returned by bwarea, which weights different patterns of pixels differently.) 'BoundingBox' — The smallest rectangle containing the region, a 1-by-Q *2 vector, where Q is the number of image dimensions: ndims(L), ndims(BW), or numel(CC.ImageSize). BoundingBox is [ul_corner width], where: 3-737 regionprops ul_corner is in the form [x y z ...] and specifies the upper-left corner of the bounding box width is in the form [x_width y_width ...] and specifies the width of the bounding box along each dimension 'Centroid' – 1-by-Q vector that specifies the center of mass of the region. Note that the first element of Centroid is the horizontal coordinate (or x-coordinate) of the center of mass, and the second element is the vertical coordinate (or y-coordinate). All other elements of Centroid are in order of dimension. This figure illustrates the centroid and bounding box for a discontiguous region. The region consists of the white pixels; the green box is the bounding box, and the red dot is the centroid. 'ConvexHull' — p-by-2 matrix that specifies the smallest convex polygon that can contain the region. Each row of the matrix contains the x- and y-coordinates of one vertex of the polygon. This property is supported only for 2-D input label matrices. 'ConvexImage' — Binary image (logical) that specifies the convex hull, with all pixels within the hull filled in (i.e., set to on). (For pixels that the boundary of the hull passes through, regionprops uses the same logic as roipoly to determine whether the pixel is inside or outside the hull.) The image is the size of the bounding box of the region. This property is supported only for 2-D input label matrices. 'ConvexArea' — Scalar that specifies the number of pixels in 'ConvexImage'. This property is supported only for 2-D input label matrices. 3-738 regionprops 'Eccentricity' — Scalar that specifies the eccentricity of the ellipse that has the same second-moments as the region. The eccentricity is the ratio of the distance between the foci of the ellipse and its major axis length. The value is between 0 and 1. (0 and 1 are degenerate cases; an ellipse whose eccentricity is 0 is actually a circle, while an ellipse whose eccentricity is 1 is a line segment.) This property is supported only for 2-D input label matrices. 'EquivDiameter' — Scalar that specifies the diameter of a circle with the same area as the region. Computed as sqrt(4*Area/pi). This property is supported only for 2-D input label matrices. 'EulerNumber' — Scalar that specifies the number of objects in the region minus the number of holes in those objects. This property is supported only for 2-D input label matrices. regionprops uses 8-connectivity to compute the EulerNumber measurement. To learn more about connectivity, see “Pixel Connectivity”. 'Extent' — Scalar that specifies the ratio of pixels in the region to pixels in the total bounding box. Computed as the Area divided by the area of the bounding box. This property is supported only for 2-D input label matrices. 'Extrema' — 8-by-2 matrix that specifies the extrema points in the region. Each row of the matrix contains the x- and y-coordinates of one of the points. The format of the vector is [top-left top-right right-top right-bottom bottom-right bottom-left left-bottom left-top]. This property is supported only for 2-D input label matrices. This figure illustrates the extrema of two different regions. In the region on the left, each extrema point is distinct. In the region on the right, certain extrema points (e.g., top-left and left-top) are identical. 3-739 regionprops 'FilledArea' — Scalar specifying the number of on pixels in FilledImage. 'FilledImage' — Binary image (logical) of the same size as the bounding box of the region. The on pixels correspond to the region, with all holes filled in. 'Image' — Binary image (logical) of the same size as the bounding box of the region; the on pixels correspond to the region, and all other pixels are off. 'MajorAxisLength' — Scalar specifying the length (in pixels) of the major axis of the ellipse that has the same normalized second central moments as the region. This property is supported only for 2-D input label matrices. 3-740 regionprops 'MaxIntensity' — Scalar specifying the value of the pixel with the greatest intensity in the region. 'MeanIntensity' — Scalar specifying the mean of all the intensity values in the region. 'MinIntensity' — Scalar specifying the value of the pixel with the lowest intensity in the region. 'MinorAxisLength' — Scalar; the length (in pixels) of the minor axis of the ellipse that has the same normalized second central moments as the region. This property is supported only for 2-D input label matrices. 'Orientation' — Scalar; the angle (in degrees ranging from -90 to 90 degrees) between the x-axis and the major axis of the ellipse that has the same second-moments as the region. This property is supported only for 2-D input label matrices. This figure illustrates the axes and orientation of the ellipse. The left side of the figure shows an image region and its corresponding ellipse. The right side shows the same ellipse, with features indicated graphically: • The solid blue lines are the axes. • The red dots are the foci. • The orientation is the angle between the horizontal dotted line and the major axis. 'Perimeter' — Scalar; the distance around the boundary of the region. regionprops computes the perimeter by calculating the distance between each adjoining pair of pixels around the border of the region. If the image contains discontiguous regions, regionprops returns 3-741 regionprops unexpected results. The following figure shows the pixels included in the perimeter calculation for this object. 'PixelIdxList' — p-element vector containing the linear indices of the pixels in the region. 'PixelList' — p-by-Q matrix specifying the locations of pixels in the region. Each row of the matrix has the form [x y z ...] and specifies the coordinates of one pixel in the region. 'PixelValues' — p-by-1 vector, where p is the number of pixels in the region. Each element in the vector contains the value of a pixel in the region. 'Solidity' — Scalar specifying the proportion of the pixels in the convex hull that are also in the region. Computed as Area/ConvexArea. This property is supported only for 2-D input label matrices. 'SubarrayIdx' — Cell-array containing indices such that L(idx{:}) extracts the elements of L inside the object bounding box. 'WeightedCentroid' — p-by-Q vector of coordinates specifying the center of the region based on location and intensity value. The first element of WeightedCentroid is the horizontal coordinate (or x-coordinate) of the weighted centroid. The second element 3-742 regionprops is the vertical coordinate (or y-coordinate). All other elements of WeightedCentroid are in order of dimension. Class Support If the first input is BW, BW must be a logical array and it can have any dimension. If the first input is CC, CC must be a structure returned by bwconncomp. If the first input is L, L must be real, nonsparse, and contain integers. L can have any numeric class and any dimension. Tips Note on Terminology You can use regionprops on contiguous regions and discontiguous regions. Contiguous regions are also called "objects," "connected components," and "blobs." A label matrix containing contiguous regions might look like this: 1 1 0 2 2 0 3 3 1 1 0 2 2 0 3 3 Elements of L equal to 1 belong to the first contiguous region or connected component; elements of L equal to 2 belong to the second connected component; etc. Discontiguous regions are regions that might contain multiple connected components. A label matrix containing discontiguous regions might look like this: 1 1 0 1 1 0 2 2 1 1 0 1 1 0 2 2 Elements of L equal to 1 belong to the first region, which is discontiguous and contains two connected components. Elements of L equal to 2 belong to the second region, which is a single connected component. Selecting Regions Based on Certain Criteria The function ismember is useful in conjunction with regionprops, bwconncomp, and labelmatrix for creating a binary image containing only objects or regions that meet certain criteria. For example, these 3-743 regionprops commands create a binary image containing only the regions whose area is greater than 80. cc = bwconncomp(BW); stats = regionprops(cc, 'Area'); idx = find([stats.Area] > 80); BW2 = ismember(labelmatrix(cc), idx); Using the Comma-Separated List Syntax The comma-separated list syntax for structure arrays is very useful when you work with the output of regionprops. For example, for a field that contains a scalar, you can use this syntax to create a vector containing the value of this field for each region in the image. For instance, if stats is a structure array with field Area, then the following two expressions are equivalent: stats(1).Area, stats(2).Area, ..., stats(end).Area and stats.Area Therefore, you can use these calls to create a vector containing the area of each region in the image. stats = regionprops(L, 'Area'); allArea = [stats.Area]; allArea is a vector of the same length as the structure array stats. Performance Considerations Most of the measurements take very little time to compute. However, there are a few measuements, listed below, that can take significantly longer, depending on the number of regions in L: • 'ConvexHull' 3-744 regionprops • 'ConvexImage' • 'ConvexArea' • 'FilledImage' Note that computing certain groups of measurements takes about the same amount of time as computing just one of them because regionprops takes advantage of intermediate computations used in both computations. Therefore, it is fastest to compute all the desired measurements in a single call to regionprops. Using bwlabel, bwlabeln, bwconncomp, and regionprops The functions bwlabel, bwlabeln, and bwconncomp all compute connected components for binary images. bwconncomp replaces the use of bwlabel and bwlabeln. It uses significantly less memory and is sometimes faster than the other functions. Function Input Dimension Output Form Memory Use Connectivity bwlabel 2-D Double-precision label matrix High 4 or 8 bwlabeln N-D Double-precision label matrix High Any bwconncomp N-D CC struct Low Any The output of bwlabel and bwlabeln is a double-precision label matrix. To compute a label matrix using a more memory-efficient data type, use the labelmatrix function on the output of bwconncomp: CC = bwconncomp(BW); L = labelmatrix(CC); To extract features from a binary image using regionprops with the default connectivity, it is no longer necessary to call bwlabel or bwlabeln first. You can simply pass the binary image directly to regionprops, which then uses the memory-efficient bwconncomp to 3-745 regionprops compute the connected components automatically for you. To extract features from a binary image using a nondefault connectivity, call bwconncomp first and then pass the result to regionprops: CC = bwconncomp(BW, CONN); S = regionprops(CC); Examples Label the connected pixel components in the text.png image, compute their centroids, and superimpose the centroid locations on the image: BW = imread('text.png'); s = regionprops(BW, 'centroid'); centroids = cat(1, s.Centroid); imshow(BW) hold on plot(centroids(:,1), centroids(:,2), 'b*') hold off See Also 3-746 bwconncomp | bwlabel | bwlabeln | ismember | labelmatrix | watershed registration.metric.MattesMutualInformation Purpose Mattes mutual information metric configuration object Description A MattesMutualInformation object describes a mutual information metric configuration that you pass to the function imregister to solve image registration problems. Construction metric = registration.metric.MattesMutualInformation() constructs a MattesMutualInformation object. Properties NumberOfSpatialSamples Number of spatial samples used to compute the metric. NumberOfSpatialSamples is a positive scalar integer value that defines the number of random pixels imregister uses to compute the metric. Your registration results are more reproducible (at the cost of performance) as you increase this value. imregister only uses NumberOfSpatialSamples when UseAllPixels = 0 (false). The default value for NumberOfSpatialSamples is 500. NumberOfHistogramBins Number of histogram bins used to compute the metric. NumberOfHistogramBins is a positive scalar integer value that defines the number of bins imregister uses to compute the joint distribution histogram. The default value is 50, and the minimum value is 5. UseAllPixels Logical scalar that specifies whether imregister should use all pixels in the overlap region of the images to compute the metric. You can achieve significantly better performance if you set this property to 0 (false). When UseAllPixels = 0, the NumberOfSpatialSamples property controls the number of random pixel locations that imregister uses to compute the metric. The results of your registration might not be reproducible when UseAllPixels = 0. This is because imregister selects a 3-747 registration.metric.MattesMutualInformation random subset of pixels from the images to compute the metric. The default value forUseAllPixels is 1 (true). Definitions Mutual Information Metric Metric used to maximize the number of coincident pixels with the same relative brightness value. This metric is best suited for images with different brightness ranges. Copy Semantics Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB Programming Fundamentals documentation. Tips • Larger values of mutual information correspond to better registration results. You can examine the computed values of Mattes mutual information if you enable 'DisplayOptimization' when you call imregister, for example: movingRegistered = imregister(moving,fixed,'rigid',optimizer,metric,'DisplayOptimization',t Examples Register MRI Images with MattesMutualInformation Metric Register two MRI images of a knee that were obtained using different protocols. Read the images into the workspace. fixed = dicomread('knee1.dcm'); moving = dicomread('knee2.dcm'); View the misaligned images. imshowpair(fixed, moving,'Scaling','joint'); 3-748 registration.metric.MattesMutualInformation Create the optimizer configuration object suitable for registering images from different sensors. optimizer = registration.optimizer.OnePlusOneEvolutionary; Create the MattesMutualInformation metric configuration object. metric = registration.metric.MattesMutualInformation metric = registration.metric.MattesMutualInformation Properties: 3-749 registration.metric.MattesMutualInformation NumberOfSpatialSamples: 500 NumberOfHistogramBins: 50 UseAllPixels: 1 Tune the properties of the optimizer so that the problem will converge on a global maxima. Increase the number of iterations the optimizer will use to solve the problem. optimizer.InitialRadius = 0.009; optimizer.Epsilon = 1.5e-4; optimizer.GrowthFactor = 1.01; optimizer.MaximumIterations = 300; Register the moving and fixed images. movingRegistered = imregister(moving, fixed, 'affine', optimizer, metric) View the registered images. figure; imshowpair(fixed, movingRegistered,'Scaling','joint'); 3-750 registration.metric.MattesMutualInformation Algorithms The imregister function uses an iterative process to register images. The metric you pass to imregister defines the image similarity metric for evaluating the accuracy of the registration. An image similarity metric takes two images and returns a scalar value that describes how similar the images are. The optimizer you pass to imregister defines the methodology for minimizing or maximizing the similarity metric. Mutual information metrics are information theoretic techniques for measuring how related two variables are. These algorithms use the joint probability distribution of a sampling of pixels from two images to measure the certainty that the values of one set of pixels map to similar values in the other image. This information is a quantitative measure of how similar the images are. High mutual information implies a large 3-751 registration.metric.MattesMutualInformation reduction in the uncertainty (entropy) between the two distributions, signaling that the images are likely better aligned. The Mattes mutual information algorithm uses a single set of pixel locations for the duration of the optimization, instead of drawing a new set at each iteration. The number of samples used to compute the probability density estimates and the number of bins used to compute the entropy are both user selectable. The marginal and joint probability density function is evaluated at the uniformly spaced bins using the samples. Entropy values are computed by summing over the bins. Zero-order and third-order B-spline kernels are used to compute the probability density functions of the fixed and moving images, respectively.[1] References [1] Rahunathan, Smriti, D. Stredney, P. Schmalbrock, and B.D. Clymer. Image Registration Using Rigid Registration and Maximization of Mutual Information. Poster presented at: MMVR13. The 13th Annual Medicine Meets Virtual Reality Conference; 2005 January 26–29; Long Beach, CA. [2] D. Mattes, D.R. Haynor, H. Vesselle, T. Lewellen, and W. Eubank. "Non-rigid multimodality image registration." (Proceedings paper).Medical Imaging 2001: Image Processing. SPIE Publications, 3 July 2001. pp. 1609–1620. Alternatives Use imregconfig to construct a metric configuration for typical image registration scenarios. See Also registration.metric.MeanSquares | imregister Concepts • Class Attributes • Property Attributes 3-752 registration.metric.MeanSquares Purpose Mean square error metric configuration object Description A MeanSquares object describes a mean square error metric configuration that you pass to the function imregister to solve image registration problems. Construction metric = registration.metric.MeanSquares() constructs a MeanSquares object. Copy Semantics Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB Programming Fundamentals documentation. Tips • This metric is an element-wise difference between two input images. The ideal value is zero. You can examine the computed values of mean square error if you enable 'DisplayOptimization' when you call imregister. For example, movingRegistered = imregister(moving,fixed,'rigid',optimizer,metric Examples Register Remote Sensing Images with MeanSquares Metric Create a MeanSquares object and use it to register two images captured with different sensors. In general, imregister doesn’t support perspective transformations. However it returns good results for this problem, which uses a similarity transformation. Read the images into the workspace. fixed = imread('westconcordorthophoto.png'); moving = rgb2gray(imread('westconcordaerial.png')); View the misaligned images. imshowpair(fixed, moving,'Scaling','joint'); 3-753 registration.metric.MeanSquares Create the optimizer configuration object suitable for registering images from different sensors. optimizer = registration.optimizer.OnePlusOneEvolutionary; Create the MeanSquares metric configuration object. Even though the images came from different sensors, they have an intensity relationship similar enough to use mean square error as the similarity metric. metric = registration.metric.MeanSquares metric = 3-754 registration.metric.MeanSquares registration.metric.MeanSquares This class has no properties. Increase MaximumIterations property of the optimizer to allow for more iterations. optimizer.MaximumIterations = 1000; Register the moving and fixed images. movingRegistered = imregister(moving, fixed, 'similarity', optimizer, View the registered images. figure; imshowpair(fixed, movingRegistered,'Scaling','joint'); 3-755 registration.metric.MeanSquares Algorithms The imregister function uses an iterative process to register images. The metric you pass to imregister defines the image similarity metric for evaluating the accuracy of the registration. An image similarity metric takes two images and returns a scalar value that describes how similar the images are. The optimizer you pass to imregister defines the methodology for minimizing or maximizing the similarity metric. The mean squares image similarity metric is computed by squaring the difference of corresponding pixels in each image and taking the mean of the those squared differences. Use imregconfig to construct a metric configuration for typical image registration scenarios. 3-756 registration.metric.MeanSquares See Also registration.metric.MattesMutualInformation | imregister 3-757 registration.optimizer.OnePlusOneEvolutionary Purpose One-plus-one evolutionary optimizer configuration object Description A OnePlusOneEvolutionary object describes a one-plus-one evolutionary optimization configuration that you pass to the function imregister to solve image registration problems. Construction optimizer = registration.optimizer.OnePlusOneEvolutionary() Constructs a OnePlusOneEvolutionary object. Properties GrowthFactor Growth factor of the search radius. GrowthFactor is a positive scalar value that the optimizer uses to control the rate at which the search radius grows in parameter space. If you set GrowthFactor to a large value, the optimization is fast, but it might result in finding only the metric’s local extrema. If you set GrowthFactor to a small value, the optimization is slower, but it is likely to converge on a better solution. The default value of GrowthFactor is 1.05. Epsilon Minimum size of the search radius. Epsilon is a positive scalar value that controls the accuracy of convergence by adjusting the minimum size of the search radius. If you set Epsilon to a small value, the optimization of the metric is more accurate, but the computation takes longer. If you set Epsilon to a large value, the computation time deceases at the expense of accuracy. The default value of Epsilon is 1.5e-6. InitialRadius Initial size of search radius. InitialRadius is a positive scalar value that controls the initial search radius of the optimizer. If you set InitialRadius to a large value, the computation time decreases. However, overly large 3-758 registration.optimizer.OnePlusOneEvolutionary values of InitialRadius might result in an optimization that fails to converge. The default value of InitialRadius is 6.25e-3. MaximumIterations Maximum number of optimizer iterations. MaximumIterations is a positive scalar integer value that determines the maximum number of iterations the optimizer performs at any given pyramid level. The registration could converge before the optimizer reaches the maximum number of iterations. The default value of MaximumIterations is 100. Copy Semantics Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB Programming Fundamentals documentation. Examples Register MRI Images with OnePlusOneEvolutionary Optimizer Register two MRI images of a knee that were obtained using different protocols. Read the images into the workspace. fixed = dicomread('knee1.dcm'); moving = dicomread('knee2.dcm'); View the misaligned images. imshowpair(fixed, moving,'Scaling','joint'); 3-759 registration.optimizer.OnePlusOneEvolutionary Create the optimizer configuration object suitable for registering images from different sensors. optimizer = registration.optimizer.OnePlusOneEvolutionary optimizer = registration.optimizer.OnePlusOneEvolutionary Properties: GrowthFactor: Epsilon: InitialRadius: MaximumIterations: 3-760 1.050000e+00 1.500000e-06 6.250000e-03 100 registration.optimizer.OnePlusOneEvolutionary Create the MattesMutualInformation metric configuration object. metric = registration.metric.MattesMutualInformation; Tune the properties of the optimizer so that the problem will converge on a global maxima. Increase the number of iterations the optimizer will use to solve the problem. optimizer.InitialRadius = 0.009; optimizer.Epsilon = 1.5e-4; optimizer.GrowthFactor = 1.01; optimizer.MaximumIterations = 300; Register the moving and fixed images. movingRegistered = imregister(moving, fixed, 'affine', optimizer, metr View the registered images. figure imshowpair(fixed, movingRegistered,'Scaling','joint'); 3-761 registration.optimizer.OnePlusOneEvolutionary Algorithms The imregister function uses an iterative process to register images. The metric you pass to imregister defines the image similarity metric for evaluating the accuracy of the registration. An image similarity metric takes two images and returns a scalar value that describes how similar the images are. The optimizer you pass to imregister defines the methodology for minimizing or maximizing the similarity metric. An evolutionary algorithm iterates to find a set of parameters that produce the best possible registration result. It does this by perturbing, or mutating, the parameters from the last iteration (the parent). If the new (child) parameters yield a better result, then the child becomes the new parent whose parameters are perturbed, perhaps more aggressively. If the parent yields a better result, it remains the parent and the next perturbation is less aggressive. 3-762 registration.optimizer.OnePlusOneEvolutionary References [1] Styner, M., C. Brechbuehler, G. Székely, and G. Gerig. "Parametric estimate of intensity inhomogeneities applied to MRI." IEEE Transactions on Medical Imaging. Vol. 19, Number 3, 2000, pp. 153-165. Alternatives Use imregconfig to construct an optimizer configuration for typical image registration scenarios. See Also registration.optimizer.RegularStepGradientDescent | imregister Concepts • Class Attributes • Property Attributes 3-763 registration.optimizer.RegularStepGradientDescent Purpose Regular step gradient descent optimizer configuration object Description A RegularStepGradientDescent object describes a regular step gradient descent optimization configuration that you pass to the function imregister to solve image registration problems. Construction optimizer = registration.optimizer.RegularStepGradientDescent() constructs a RegularStepGradientDescent object. Properties GradientMagnitudeTolerance Gradient magnitude tolerance. GradientMagnitudeTolerance is a positive scalar value that controls the optimization process. When the value of the gradient is smaller than GradientMagnitudeTolerance, it is an indication that the optimizer might have reached a plateau. The default value of GradientMagnitudeTolerance is 1e-4. MinimumStepLength Tolerance for convergence. MinimumStepLength is a positive scalar value that controls the accuracy of convergence. If you set MinimumStepLength to a small value, the optimization takes longer to compute, but it is likely to converge on a more accurate metric value. The default value of MinimumStepLength is 1e-5. MaximumStepLength Initial step length. MaximumStepLength is a positive scalar value that controls the initial step length used in optimization. If you set MaximumStepLength to a large value, the computation time decreases. However, the optimizer might fail to converge if you set MaximumStepLength to an overly large value. The default value of MaximumStepLength is 0.0625. 3-764 registration.optimizer.RegularStepGradientDescent MaximumIterations Maximum number of iterations. MaximumIterations is a positive scalar integer value that determines the maximum number of iterations the optimizer performs at any given pyramid level. The registration could converge before the optimizer reaches the maximum number of iterations. The default value of MaximumIterations is 100. RelaxationFactor Step length reduction factor. RelaxationFactor is a scalar value between 0 and 1 that defines the rate at which the optimizer reduces step size during convergence. Whenever the optimizer determines that the direction of the gradient changed, it reduces the size of the step length. If your metric is noisy, you can set RelaxationFactor to a larger value. This leads to a more stable convergence at the expense of computation time. The default value of RelaxationFactor is 0.5. Copy Semantics Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB Programming Fundamentals documentation. Examples Register Images with RegularStepGradientDescent Optimizer Create a RegularStepGradientDescent object and use it to register two images captured with the same device. Read the reference image and create an unregistered copy. fixed = imread('pout.tif'); moving = imrotate(fixed, 5, 'bilinear', 'crop'); View the misaligned images. imshowpair(fixed, moving,'Scaling','joint'); 3-765 registration.optimizer.RegularStepGradientDescent Create the optimizer configuration object suitable for registering images from the same device. optimizer = registration.optimizer.RegularStepGradientDescent Create the metric configuration object. metric = registration.metric.MeanSquares; Now modify the optimizer configuration to get more precision. optimizer.MaximumIterations = 300; optimizer.MinimumStepLength = 5e-4; Perform the registration. movingRegistered = imregister(moving,fixed,'rigid',optimizer,metric); View registered images. 3-766 registration.optimizer.RegularStepGradientDescent figure imshowpair(fixed, movingRegistered,'Scaling','joint'); Algorithms The imregister function uses an iterative process to register images. The metric you pass to imregister defines the image similarity metric for evaluating the accuracy of the registration. An image similarity metric takes two images and returns a scalar value that describes how similar the images are. The optimizer you pass to imregister defines the methodology for minimizing or maximizing the similarity metric. The regular step gradient descent optimization adjusts the transformation parameters so that the optimization follows the gradient of the image similarity metric in the direction of the extrema. It uses constant length steps along the gradient between computations until the gradient changes direction, at which point the step length is halved. Use imregconfig to construct an optimizer configuration for typical image registration scenarios. 3-767 registration.optimizer.RegularStepGradientDescent See Also registration.optimizer.OnePlusOneEvolutionary | imregister Concepts • Class Attributes • Property Attributes 3-768 rgb2gray Purpose Convert RGB image or colormap to grayscale Syntax I = rgb2gray(RGB) newmap = rgb2gray(map) Description I = rgb2gray(RGB) converts the truecolor image RGB to the grayscale intensity image I. rgb2gray converts RGB images to grayscale by eliminating the hue and saturation information while retaining the luminance. newmap = rgb2gray(map) returns a grayscale colormap equivalent to map. Note A grayscale image is also called a gray-scale, gray scale, or gray-level image. Class Support If the input is an RGB image, it can be of class uint8, uint16, single, or double. The output image I is of the same class as the input image. If the input is a colormap, the input and output colormaps are both of class double. Examples Convert an RGB image to a grayscale image. I = imread('board.tif'); J = rgb2gray(I); figure, imshow(I), figure, imshow(J); Convert the colormap to a grayscale colormap. [X,map] = imread('trees.tif'); gmap = rgb2gray(map); figure, imshow(X,map), figure, imshow(X,gmap); Algorithms rgb2gray converts RGB values to grayscale values by forming a weighted sum of the R, G, and B components: 3-769 rgb2gray 0.2989 * R + 0.5870 * G + 0.1140 * B Note that these are the same weights used by the rgb2ntsc function to compute the Y component. See Also 3-770 ind2gray | mat2gray | ntsc2rgb | rgb2ind | rgb2ntsc rgb2ntsc Purpose Convert RGB color values to NTSC color space Syntax yiqmap = rgb2ntsc(rgbmap) YIQ = rgb2ntsc(RGB) Description yiqmap = rgb2ntsc(rgbmap) converts the m-by-3 RGB values in rgbmap to NTSC color space. yiqmap is an m-by-3 matrix that contains the NTSC luminance (Y) and chrominance (I and Q) color components as columns that are equivalent to the colors in the RGB colormap. YIQ = rgb2ntsc(RGB) converts the truecolor image RGB to the equivalent NTSC image YIQ. Tips In the NTSC color space, the luminance is the grayscale signal used to display pictures on monochrome (black and white) televisions. The other components carry the hue and saturation information. rgb2ntsc defines the NTSC components using 0.587 0.114 ⎤ ⎡ R ⎤ ⎡Y ⎤ ⎡0.299 ⎢ I ⎥ = ⎢0.596 −0.274 −0.322⎥ ⎢ G ⎥ ⎢ ⎥ ⎢ ⎥⎢ ⎥ ⎢⎣ Q ⎥⎦ ⎢⎣ 0.211 −0.523 0.312⎥⎦ ⎢⎣ B ⎥⎦ Class Support RGB can be of class uint8, uint16, int16, single, or double. RGBMAP can be double. The output is double. See Also ntsc2rgb | rgb2ind | ind2rgb | ind2gray 3-771 rgb2ycbcr Purpose Convert RGB color values to YCbCr color space Syntax ycbcrmap = rgb2ycbcr(map) YCBCR = rgb2ycbcr(RGB) Description ycbcrmap = rgb2ycbcr(map) converts the RGB values in map to the YCbCr color space. map must be an M-by-3 array. ycbcrmap is an M-by-3 matrix that contains the YCbCr luminance (Y) and chrominance (Cb and Cr) color values as columns. Each row in ycbcfmap represents the equivalent color to the corresponding row in the RGB colormap, map. YCBCR = rgb2ycbcr(RGB) converts the truecolor image RGB to the equivalent image in the YCbCr color space. RGB must be a M-by-N-by-3 array. If the input is uint8, YCBCR is uint8, where Y is in the range [16 235], and Cb and Cr are in the range [16 240]. If the input is a double, Y is in the range [16/255 235/255] and Cb and Cr are in the range [16/255 240/255]. If the input is uint16, Y is in the range [4112 60395] and Cb and Cr are in the range [4112 61680]. Class Support If the input is an RGB image, it can be of class uint8, uint16, or double. If the input is a colormap, it must be double. The output image is of the same class as the input image. Examples Convert RGB image to YCbCr. RGB = imread('board.tif'); YCBCR = rgb2ycbcr(RGB); Convert RGB color space to YCbCr. map = jet(256); newmap = rgb2ycbcr(map); References 3-772 [1] Poynton, C. A.A Technical Introduction to Digital Video, John Wiley & Sons, Inc., 1996, p. 175. rgb2ycbcr [2] Rec. ITU-R BT.601-5, Studio Encoding Parameters of Digital Television for Standard 4:3 and Wide-screen 16:9 Aspect Ratios, (1982-1986-1990-1992-1994-1995), Section 3.5. See Also ntsc2rgb | rgb2ntsc | ycbcr2rgb 3-773 roicolor Purpose Select region of interest (ROI) based on color Syntax BW = roicolor(A,low,high) BW = roicolor(A,v) Description roicolor selects a region of interest (ROI) within an indexed or intensity image and returns a binary image. (You can use the returned image as a mask for masked filtering using roifilt2.) BW = roicolor(A,low,high) returns an ROI selected as those pixels that lie within the colormap range [low high]. BW = (A >= low) & (A <= high) BW is a binary image with 0’s outside the region of interest and 1’s inside. BW = roicolor(A,v) returns an ROI selected as those pixels in A that match the values in vector v. BW is a binary image with 1’s where the values of A match the values of v. Class Support The input image A must be numeric. The output image BW is of class logical. Examples load clown BW = roicolor(X,10,20); imshow(X,map) figure,imshow(BW) 3-774 roicolor See Also roifilt2 | roipoly 3-775 roifill Purpose Fill in specified region of interest (ROI) polygon in grayscale image Syntax J = roifill J = roifill(I) J = roifill(I, c, r) J = roifill(I, BW) [J,BW] = roifill(...) J = roifill(x, y, I, xi, yi) [x, y, J, BW, xi, yi] = roifill(...) Description Use roifill to fill in a specified region of interest (ROI) polygon in a grayscale image. roifill smoothly interpolates inward from the pixel values on the boundary of the polygon by solving Laplace’s equation. The boundary pixels are not modified. roifill can be used, for example, to erase objects in an image. J = roifill creates an interactive polygon tool, associated with the image displayed in the current figure, called the target image. You use the mouse to define the ROI – see “Interactive Behavior” on page 3-777. When you are finished defining the ROI, fill in the area specified by the ROI by double-clicking inside the region or by right-clicking anywhere inside the region and selecting Fill Area from the context menu. roifill returns the image, J, which is the same size as I with the region filled in (see “Examples” on page 3-780). Note If you do not specify an output argument, roifill displays the filled image in a new figure. J = roifill(I) displays the image I and creates an interactive polygon tool associated with the image. J = roifill(I, c, r) fills in the polygon specified by c and r, which are equal-length vectors containing the row-column coordinates of the pixels on vertices of the polygon. The kth vertex is the pixel (r(k),c(k)). 3-776 roifill J = roifill(I, BW) uses BW (a binary image the same size as I) as a mask. roifill fills in the regions in I corresponding to the nonzero pixels in BW. If there are multiple regions, roifill performs the interpolation on each region independently. [J,BW] = roifill(...) returns the binary mask used to determine which pixels in I get filled. BW is a binary image the same size as I with 1’s for pixels corresponding to the interpolated region of I and 0’s elsewhere. J = roifill(x, y, I, xi, yi) uses the vectors x and y to establish a nondefault spatial coordinate system. xi and yi are equal-length vectors that specify polygon vertices as locations in this coordinate system. [x, y, J, BW, xi, yi] = roifill(...) returns the XData and YData in x and y, the output image in J, the mask image in BW, and the polygon coordinates in xi and yi. xi and yi are empty if the roifill(I,BW) form is used. Interactive Behavior When you call roifill with an interactive syntax, the pointer changes when you move it over the target image. to a cross hairs shape Using the mouse, you specify a region-of-interest by selecting vertices of a polygon. You can change the size or shape of the polygon using the mouse. The following figure illustrates a polygon defined by multiple vertices. For more information about all the interactive capabilities of roifill, see the table that follows. 3-777 roifill ROI tool pointer Polygon vertices Interactive Behavior Description Closing the polygon. (Completing the region-of-interest.) Use any of the following mechanisms: • Move the pointer over the initial vertex of the polygon that you selected. The shape changes to a circle . Click either mouse button. • Double-click the left mouse button. This action creates a vertex at the point under the mouse and draws a straight line connecting this vertex with the initial vertex. • Click the right mouse button. This action draws a line connecting the last vertex 3-778 roifill Interactive Behavior Description selected with the initial vertex; it does not create a new vertex. Deleting the polygon Press Backspace, Escape or Delete, or right-click inside the region and select Cancel from the context menu. Note: If you delete the ROI, the function returns empty values. Moving the polygon Move the pointer inside the region. The . Click and drag pointer changes to a fleur the mouse to move the polygon. Changing the color of the polygon Move the pointer inside the region. Right-click and select Set color from the context menu. Adding a new vertex. Move the pointer over an edge of the polygon and press the A key. The shape of the pointer changes . Click the left mouse button to create a new vertex at that position on the line. Moving a vertex. (Reshaping the region-of-interest.) Move the pointer over a vertex. The pointer changes to a circle . Click and drag the vertex to its new position. 3-779 roifill Interactive Behavior Description Deleting a vertex. Move the pointer over a vertex. The pointer changes to a circle . Right-click and select Delete Vertex from the context menu. This action deletes the vertex and adjusts the shape of the polygon, drawing a new straight line between the two vertices that were neighbors of the deleted vertex. Retrieving the coordinates of the vertices Move the pointer inside the region. Right-click and select Copy position from the context menu to copy the current position to the Clipboard. Position is an n-by-2 array containing the x- and y-coordinates of each vertex, where n is the number of vertices you selected. Class Support The input image I can of class uint8, uint16, int16, single, or double. The input binary mask BW can be any numeric class or logical. The output binary mask BW is always logical. The output image J is of the same class as I. All other inputs and outputs are of class double. Examples This example uses roifill to fill a region in the input image, I. For more examples, especially of the interactive syntaxes, see “Filling an ROI”. I = imread('eight.tif'); c = [222 272 300 270 221 194]; r = [21 21 75 121 121 75]; J = roifill(I,c,r); imshow(I) figure, imshow(J) 3-780 roifill See Also impoly | roifilt2 | roipoly 3-781 roifilt2 Purpose Filter region of interest (ROI) in image Syntax J = roifilt2(h, I, BW) J = roifilt2(I, BW, fun) Description J = roifilt2(h, I, BW) filters the data in I with the two-dimensional linear filter h. BW is a binary image the same size as I that defines an ROI used as a mask for filtering. roifilt2 returns an image that consists of filtered values for pixels in locations where BW contains 1’s, and unfiltered values for pixels in locations where BW contains 0’s. For this syntax, roifilt2 calls filter2 to implement the filter. J = roifilt2(I, BW, fun) processes the data in I using the function fun. The result J contains computed values for pixels in locations where BW contains 1’s, and the actual values in I for pixels in locations where BW contains 0’s. fun must be a function handle. Parameterizing Functions, in the MATLAB Mathematics documentation, explains how to provide additional parameters to the function fun. Class Support For the syntax that includes a filter h, the input image can be logical or numeric, and the output array J has the same class as the input image. For the syntax that includes a function, I can be of any class supported by fun, and the class of J depends on the class of the output from fun. Examples This example continues the roipoly example, filtering the region of the image I specified by the mask BW. The roifilt2 function returns the filtered image J, shown in the following figure. I = imread('eight.tif'); c = [222 272 300 270 221 194]; r = [21 21 75 121 121 75]; BW = roipoly(I,c,r); H = fspecial('unsharp'); J = roifilt2(H,I,BW); figure, imshow(I), figure, imshow(J) 3-782 roifilt2 See Also filter2 | function_handle | imfilter | roipoly How To • “Anonymous Functions” • “Parameterizing Functions” 3-783 roipoly Purpose Specify polygonal region of interest (ROI) Syntax BW = roipoly BW = roipoly(I) BW = roipoly(I, c, r) BW = roipoly(x, y, I, xi, yi) [BW, xi, yi] = roipoly(...) [x, y, BW, xi, yi] = roipoly(...) Description Use roipoly to specify a polygonal region of interest (ROI) within an image. roipoly returns a binary image that you can use as a mask for masked filtering. BW = roipoly creates an interactive polygon tool, associated with the image displayed in the current figure, called the target image. With the polygon tool active, the pointer changes to cross hairs when you move the pointer over the image in the figure. Using the mouse, you specify the region by selecting vertices of the polygon. You can move or resize the polygon using the mouse. The following figure illustrates a polygon defined by multiple vertices. The following table describes all the interactive behavior of the polygon tool. ROI tool pointer 3-784 Polygon vertices roipoly When you are finished positioning and sizing the polygon, create the mask by double-clicking, or by right-clicking inside the region and selecting Create mask from the context menu. roipoly returns the mask as a binary image, BW, the same size as I. In the mask image, roipoly sets pixels inside the region to 1 and pixels outside the region to 0. Interactive Behavior Description Closing the polygon. (Completing the region-of-interest.) Use any of the following mechanisms: • Move the pointer over the initial vertex of the polygon that you selected. The pointer changes to a circle . Click either mouse button. • Double-click the left mouse button. This action creates a vertex at the point under the mouse pointer and draws a straight line connecting this vertex with the initial vertex. • Right-click the mouse. This draws a line connecting the last vertex selected with the initial vertex; it does not create a new vertex at the point under the mouse. Moving the entire polygon Deleting the polygon Move the pointer inside the region. The . Click pointer changes to a fleur shape and drag the polygon over the image. Press Backspace, Escape or Delete, or right-click inside the region and select Cancel from the context menu. Note: If you delete the ROI, the function returns empty values. 3-785 roipoly Interactive Behavior Description Moving a vertex. (Reshaping the region-of-interest.) Move the pointer over a vertex. The pointer changes to a circle . Click and drag the vertex to its new position. Adding a new vertex. Move the pointer over an edge of the polygon and press the A key. The pointer changes shape to . Click the left mouse button to create a new vertex at that point on the edge. Deleting a vertex. (Reshaping the region-of-interest.) Move the pointer over the vertex. The pointer changes to a circle . Right-click and select Delete vertex from the context menu. roipoly draws a new straight line between the two vertices that were neighbors of the deleted vertex. Changing the color of the polygon Move the pointer anywhere inside the boundary of the region and click the right mouse button. Select Set color from the context menu. Retrieving the coordinates of the vertices Move the pointer inside the region. Right-click and select Copy position from the context menu to copy the current position to the Clipboard. The position is an n-by-2 array containing the x- and y-coordinates of each vertex, where n is the number of vertices. Note If you call roipoly without specifying any output arguments, roipoly displays the resulting mask image in a new figure window. BW = roipoly(I) displays the image I and creates an interactive polygon tool associated with that image. 3-786 roipoly BW = roipoly(I, c, r) returns the ROI specified by the polygon described by vectors c and r, which specify the column and row indices of each vertex, respectively. c and r must be the same size. BW = roipoly(x, y, I, xi, yi) uses the vectors x and y to establish a nondefault spatial coordinate system. xi and yi are equal-length vectors that specify polygon vertices as locations in this coordinate system. [BW, xi, yi] = roipoly(...) returns the x- and y-coordinates of the polygon vertices in xi and yi. Note roipoly always produces a closed polygon. If the points specified describe a closed polygon (i.e., if the last pair of coordinates is identical to the first pair), the length of xi and yi is equal to the number of points specified. If the points specified do not describe a closed polygon, roipoly adds a final point having the same coordinates as the first point. (In this case the length of xi and yi is one greater than the number of points specified.) [x, y, BW, xi, yi] = roipoly(...) returns the XData and YData in x and y, the mask image in BW, and the polygon coordinates in xi and yi. Class Support The input image I can be of class uint8, uint16, int16, single, or double. The output image BW is of class logical. All other inputs and outputs are of class double. Tips For any of the roipoly syntaxes, you can replace the input image I with two arguments, m and n, that specify the row and column dimensions of an arbitrary image. For example, these commands create a 100-by-200 binary mask. c = [112 112 79 79]; r = [37 66 66 37]; BW = roipoly(100,200,c,r); 3-787 roipoly If you specify m and n with an interactive form of roipoly, an m-by-n black image is displayed, and you use the mouse to specify a polygon within this image. Examples Use roipoly to create a mask image, BW, the same size as the input image, I. The example in roifilt2 continues this example, filtering the specified region in the image. For more examples, especially of the interactive syntaxes, see “Specifying a Region of Interest (ROI)”. I = imread('eight.tif'); c = [222 272 300 270 221 194]; r = [21 21 75 121 121 75]; BW = roipoly(I,c,r); figure, imshow(I) figure, imshow(BW) See Also 3-788 impoly | poly2mask | roifilt2 | roicolor | roifill rsetwrite Purpose Create reduced resolution data set from image file Syntax rsetfile = rsetwrite(File_Name) rsetfile = rsetwrite(File_Name, output_filename) rsetfile = rsetwrite(adapter, output_filename) Description rsetfile = rsetwrite(File_Name), where File_Name is a TIFF or NITF image file, creates a reduced resolution data set (R-Set) from the specified file. The R-Set file is written to the current working directory with a name based on the input file name. For example, if File_Name is 'VeryLargeImage.tiff', rsetfile will be 'VeryLargeImage.rset'. If an image file contains multiple images, only the first one is used. rsetfile = rsetwrite(File_Name, output_filename) creates an R-Set from the specified image file, using output_filename as the name of the new file. In this case, rsetfile and output_filename contain the same string. rsetfile = rsetwrite(adapter, output_filename) creates an R-Set from the specified Image Adapter object, adapter. Image Adapters are user-defined classes that provide rsetwrite a common API for reading a particular image file format. See the documentation for ImageAdapter for more details. Tips rsetwrite creates an R-Set file by dividing an image into spatial tiles and resampling the image at different resolution levels. When you open the R-Set file in the Image Tool and zoom in, you view tiles at a higher resolution. When you zoom out, you view tiles at a lower resolution. In this way, clarity of the image and memory usage are balanced for optimal performance. The R-Set file contains a compressed copy of the full-resolution data. Because R-Set creation can be time consuming, a progress bar shows the status of the operation. If you cancel the operation, processing stops, no file is written, and the rsetfile variable will be empty. rsetwrite supports NITF image files that are uncompressed and Version 2.0 or higher. It does not support NITF files with more than 3-789 rsetwrite three bands or with floating point data. Images with more than one data band are OK if they contain unsigned integer data. While it is possible to create an R-Set from an image where the dimensions are smaller than the size of a single R-Set tile, the resulting R-set file will likely be larger and take longer to load than the original file. The current size of an R-Set tile is 512 x 512 pixels. Examples Example 1: Create an R-Set File Visualize a very large image by using an R-Set. Replace 'MyReallyBigImage.tif' in the example below with the name of your file: big_file = 'MyReallyBigImage.tif'; rset_file = rsetwrite(big_file); imtool(rset_file) Example 2: Convert TIFF Files to R-Set Files Create R-Set files for every TIFF in a directory containing very large images. Put the R-Set files into a temporary directory: d = dir('*.tif*'); image_dir = pwd; cd(tempdir) for p = 1:numel(d) big_file = fullfile(image_dir, d(p).name); rsetwrite(big_file); end See Also 3-790 imread | imtool std2 Purpose Standard deviation of matrix elements Syntax b = std2(A) Description b = std2(A) computes the standard deviation of the values in A. Class Support A can be numeric or logical. B is a scalar of class double. Algorithms std2 computes the standard deviation of the array A using std(A(:)). See Also corr2 | mean2 | std | mean 3-791 stdfilt Purpose Local standard deviation of image Syntax J = stdfilt(I) J = stdfilt(I, NHOOD) Description J = stdfilt(I) returns the array J, where each output pixel contains the standard deviation of the 3-by-3 neighborhood around the corresponding pixel in the input image I. I can have any dimension. The output image J is the same size as the input image I. For pixels on the borders of I, stdfilt uses symmetric padding. In symmetric padding, the values of padding pixels are a mirror reflection of the border pixels in I. J = stdfilt(I, NHOOD) calculates the local standard deviation of the input image I, where you specify the neighborhood in NHOOD. NHOOD is a multidimensional array of zeros and ones where the nonzero elements specify the neighbors. NHOOD's size must be odd in each dimension. By default, stdfilt uses the neighborhood ones(3). stdfilt determines the center element of the neighborhood by floor((size(NHOOD) + 1)/2). Class Support I can be logical or numeric and must be real and nonsparse. NHOOD can be logical or numeric and must contain zeros and/or ones. J is of class double. Notes To specify neighborhoods of various shapes, such as a disk, use the strel function to create a structuring element object and then use the getnhood method to extract the neighborhood from the structuring element object. Examples I = imread('circuit.tif'); J = stdfilt(I); imshow(I); figure, imshow(J,[]); See Also entropyfilt | getnhood | rangefilt | std2 | strel 3-792 strel Purpose Create morphological structuring element (STREL) Syntax SE SE SE SE SE SE SE SE SE SE SE SE Description SE = strel(shape, parameters) creates a structuring element, SE, of the type specified by shape. This table lists all the supported shapes. Depending on shape, strel can take additional parameters. See the syntax descriptions that follow for details about creating each type of structuring element. = = = = = = = = = = = = strel(shape, parameters) strel('arbitrary', NHOOD) strel('arbitrary', NHOOD, HEIGHT) strel('ball', R, H, N) strel('diamond', R) strel('disk', R, N) strel('line', LEN, DEG) strel('octagon', R) strel('pair', OFFSET) strel('periodicline', P, V) strel('rectangle', MN) strel('square', W) Flat Structuring Elements 'arbitrary' 'pair' 'diamond' 'periodicline' 'disk' 'rectangle' 'line' 'square' 'octagon' Nonflat Structuring Elements 'arbitrary' 'ball' SE = strel('arbitrary', NHOOD) creates a flat structuring element where NHOOD specifies the neighborhood. NHOOD is a matrix containing 1’s and 0’s; the location of the 1’s defines the neighborhood for the 3-793 strel morphological operation. The center (or origin) of NHOOD is its center element, given by floor((size(NHOOD)+1)/2). You can omit the 'arbitrary' string and just use strel(NHOOD). SE = strel('arbitrary', NHOOD, HEIGHT) creates a nonflat structuring element, where NHOOD specifies the neighborhood. HEIGHT is a matrix the same size as NHOOD containing the height values associated with each nonzero element of NHOOD. The HEIGHT matrix must be real and finite valued. You can omit the 'arbitrary' string and just use strel(NHOOD,HEIGHT). SE = strel('ball', R, H, N) creates a nonflat, ball-shaped structuring element (actually an ellipsoid) whose radius in the X-Y plane is R and whose height is H. Note that R must be a nonnegative integer, H must be a real scalar, and N must be an even nonnegative integer. When N is greater than 0, the ball-shaped structuring element is approximated by a sequence of N nonflat, line-shaped structuring elements. When N equals 0, no approximation is used, and the structuring element members consist of all pixels whose centers are no greater than R away from the origin. The corresponding height values are determined from the formula of the ellipsoid specified by R and H. If N is not specified, the default value is 8. Note Morphological operations run much faster when the structuring element uses approximations (N > 0) than when it does not (N = 0). SE = strel('diamond', R) creates a flat, diamond-shaped structuring element, where R specifies the distance from the structuring element origin to the points of the diamond. R must be a nonnegative integer scalar. 3-794 strel SE = strel('disk', R, N) creates a flat, disk-shaped structuring element, where R specifies the radius. R must be a nonnegative integer. N must be 0, 4, 6, or 8. When N is greater than 0, the disk-shaped structuring element is approximated by a sequence of N periodic-line structuring elements. When N equals 0, no approximation is used, and the structuring element members consist of all pixels whose centers are no greater than R away from the origin. If N is not specified, the default value is 4. Note Morphological operations run much faster when the structuring element uses approximations (N > 0) than when it does not (N = 0). However, structuring elements that do not use approximations (N = 0) are not suitable for computing granulometries. Sometimes it is necessary for strel to use two extra line structuring elements in the approximation, in which case the number of decomposed structuring elements used is N + 2. 3-795 strel SE = strel('line', LEN, DEG) creates a flat linear structuring element that is symmetric with respect to the neighborhood center. DEG specifies the angle (in degrees) of the line as measured in a counterclockwise direction from the horizontal axis. LEN is approximately the distance between the centers of the structuring element members at opposite ends of the line. SE = strel('octagon', R) creates a flat, octagonal structuring element, where R specifies the distance from the structuring element origin to the sides of the octagon, as measured along the horizontal and vertical axes. R must be a nonnegative multiple of 3. SE = strel('pair', OFFSET) creates a flat structuring element containing two members. One member is located at the origin. The second member’s location is specified by the vector OFFSET. OFFSET must be a two-element vector of integers. 3-796 strel SE = strel('periodicline', P, V) creates a flat structuring element containing 2*P+1 members. V is a two-element vector containing integer-valued row and column offsets. One structuring element member is located at the origin. The other members are located at 1*V, -1*V, 2*V, -2*V, ..., P*V, -P*V. SE = strel('rectangle', MN) creates a flat, rectangle-shaped structuring element, where MN specifies the size. MN must be a two-element vector of nonnegative integers. The first element of MN is the number of rows in the structuring element neighborhood; the second element is the number of columns. 3-797 strel SE = strel('square', W) creates a square structuring element whose width is W pixels. W must be a nonnegative integer scalar. Notes For all shapes except 'arbitrary', structuring elements are constructed using a family of techniques known collectively as structuring element decomposition. The principle is that dilation by some large structuring elements can be computed faster by dilation with a sequence of smaller structuring elements. For example, dilation by an 11-by-11 square structuring element can be accomplished by dilating first with a 1-by-11 structuring element and then with an 11-by-1 structuring element. This results in a theoretical performance improvement of a factor of 5.5, although in practice the actual performance improvement is somewhat less. Structuring element decompositions used for the 'disk' and 'ball' shapes are approximations; all other decompositions are exact. Methods This table lists the methods supported by the STREL object. 3-798 Method Description getheight Get height of structuring element getneighbors Get structuring element neighbor locations and heights getnhood Get structuring element neighborhood getsequence Extract sequence of decomposed structuring elements isflat Return true for flat structuring element reflect Reflect structuring element translate Translate structuring element strel Examples se1 se2 se3 se4 Algorithms The method used to decompose diamond-shaped structuring elements is known as "logarithmic decomposition" [1]. = = = = strel('square',11) strel('line',10,45) strel('disk',15) strel('ball',15,5) % % % % 11-by-11 square length 10, angle 45 degrees disk, radius 15 ball, radius 15, height 5 The method used to decompose disk structuring elements is based on the technique called "radial decomposition using periodic lines" [2], [3]. For details, see the MakeDiskStrel subfunction in toolbox/images/images/@strel/strel.m. The method used to decompose ball structuring elements is the technique called "radial decomposition of spheres" [2]. References [1] van den Boomgard, R, and R. van Balen, "Methods for Fast Morphological Image Transforms Using Bitmapped Images," Computer Vision, Graphics, and Image Processing: Graphical Models and Image Processing, Vol. 54, Number 3, pp. 252–254, May 1992. [2] Adams, R., "Radial Decomposition of Discs and Spheres," Computer Vision, Graphics, and Image Processing: Graphical Models and Image Processing, Vol. 55, Number 5, pp. 325–332, September 1993. [3] Jones, R., and P. Soille, "Periodic lines: Definition, cascades, and application to granulometrie," Pattern Recognition Letters, Vol. 17, pp. 1057–1063, 1996. See Also imdilate | imerode 3-799 stretchlim Purpose Find limits to contrast stretch image Syntax LOW_HIGH = stretchlim(I) LOW_HIGH = stretchlim(I, TOL) LOW_HIGH = stretchlim(RGB, TOL) Description LOW_HIGH = stretchlim(I) returns LOW_HIGH, a two-element vector of pixel values that specify lower and upper limits that can be used for contrast stretching image I. By default, values in LOW_HIGH specify the bottom 1% and the top 1% of all pixel values. The gray values returned can be used by the imadjust function to increase the contrast of an image. LOW_HIGH = stretchlim(I, TOL) where TOL is a two-element vector [LOW_FRACT HIGH_FRACT] that specifies the fraction of the image to saturate at low and high pixel values. If TOL is a scalar, LOW_FRACT = TOL, and HIGH_FRACT = 1 LOW_FRACT, which saturates equal fractions at low and high pixel values. If you omit the argument, TOL defaults to [0.01 0.99], saturating 2%. If TOL = 0, LOW_HIGH = [min(I(:)); max(I(:))]. LOW_HIGH = stretchlim(RGB, TOL) returns a 2-by-3 matrix of intensity pairs to saturate each plane of the RGB image. TOL specifies the same fractions of saturation for each plane. Note If TOL is too big, such that no pixels would be left after saturating low and high pixel values, stretchlim returns [0 1]. Class Support The input image can be of class uint8, uint16, int16, double, or single. The output limits returned, LOW_HIGH, are of class double and have values between 0 and 1. Examples I = imread('pout.tif'); J = imadjust(I,stretchlim(I),[]); 3-800 stretchlim imshow(I), figure, imshow(J) See Also brighten | histeq | imadjust 3-801 subimage Purpose Display multiple images in single figure Syntax subimage(X, map) subimage(I) subimage(BW) subimage(RGB) subimage(x, y...) h = subimage(...) Description You can use subimage in conjunction with subplot to create figures with multiple images, even if the images have different colormaps. subimage works by converting images to truecolor for display purposes, thus avoiding colormap conflicts. subimage(X, map) displays the indexed image X with colormap map in the current axes. subimage(I) displays the intensity image I in the current axes. subimage(BW) displays the binary image BW in the current axes. subimage(RGB) displays the truecolor image RGB in the current axes. subimage(x, y...) displays an image using a nondefault spatial coordinate system. h = subimage(...) returns a handle to an image object. Class Support The input image can be of class logical, uint8, uint16, or double. Examples load trees [X2,map2] = imread('forest.tif'); subplot(1,2,1), subimage(X,map) subplot(1,2,2), subimage(X2,map2) See Also imshow | subplot 3-802 tformarray Purpose Apply spatial transformation to N-D array Syntax B = tformarray(A, T, R, TDIMS_A, TDIMS_B, TSIZE_B, TMAP_B, F) Description B = tformarray(A, T, R, TDIMS_A, TDIMS_B, TSIZE_B, TMAP_B, F) applies a spatial transformation to array A to produce array B. The tformarray function is like imtransform, but is intended for problems involving higher-dimensioned arrays or mixed input/output dimensionality, or requiring greater user control or customization. (Anything that can be accomplished with imtransform can be accomplished with a combination of maketform, makeresampler, findbounds, and tformarray; but for many tasks involving 2-D images, imtransform is simpler.) This table provides a brief description of all the input arguments. See the following section for more detail about each argument. (Click an argument in the table to move to the appropriate section.) Argument Description A Input array or image T Spatial transformation structure, called a TFORM, typically created with maketform R Resampler structure, typically created with makeresampler TDIMS_A Row vector listing the input transform dimensions TDIMS_B Row vector listing the output transform dimensions TSIZE_B Output array size in the transform dimensions TMAP_B Array of point locations in output space; can be used as an alternative way to specify a spatial transformation F Array of fill values A can be any nonsparse numeric array, and can be real or complex. 3-803 tformarray T is a TFORM structure that defines a particular spatial transformation. For each location in the output transform subscript space (as defined by TDIMS_B and TSIZE_B), tformarray uses T and the function tforminv to compute the corresponding location in the input transform subscript space (as defined by TDIMS_A and size(A)). If T is empty, tformarray operates as a direct resampling function, applying the resampler defined in R to compute values at each transform space location defined in TMAP_B (if TMAP_B is nonempty), or at each location in the output transform subscript grid. R is a structure that defines how to interpolate values of the input array at specified locations. R is usually created with makeresampler, which allows fine control over how to interpolate along each dimension, as well as what input array values to use when interpolating close to the edge of the array. TDIMS_A and TDIMS_B indicate which dimensions of the input and output arrays are involved in the spatial transformation. Each element must be unique, and must be a positive integer. The entries need not be listed in increasing order, but the order matters. It specifies the precise correspondence between dimensions of arrays A and B and the input and output spaces of the transformer T. length(TDIMS_A) must equal T.ndims_in, and length(TDIMS_B) must equal T.ndims_out. For example, if T is a 2-D transformation, TDIMS_A = [2 1], and TDIMS_B = [1 2], then the column dimension and row dimension of A correspond to the first and second transformation input-space dimensions, respectively. The row and column dimensions of B correspond to the first and second output-space dimensions, respectively. TSIZE_B specifies the size of the array B along the output-space transform dimensions. Note that the size of B along nontransform dimensions is taken directly from the size of A along those dimensions. If, for example, T is a 2-D transformation, size(A) = [480 640 3 10], TDIMS_B is [2 1], and TSIZE_B is [300 200], then size(B) is [200 300 3]. 3-804 tformarray TMAP_B is an optional array that provides an alternative way of specifying the correspondence between the position of elements of B and the location in output transform space. TMAP_B can be used, for example, to compute the result of an image warp at a set of arbitrary locations in output space. If TMAP_B is not empty, then the size of TMAP_B takes the form [D1 D2 D3 ... DN L] where N equals length(TDIMS_B). The vector [D1 D2 ... DN] is used in place of TSIZE_B. If TMAP_B is not empty, then TSIZE_B should be []. The value of L depends on whether or not T is empty. If T is not empty, then L is T.ndims_out, and each L-dimension point in TMAP_B is transformed to an input-space location using T. If T is empty, then L is length(TDIMS_A), and each L-dimensional point in TMAP_B is used directly as a location in input space. F is a double-precision array containing fill values. The fill values in F can be used in three situations: • When a separable resampler is created with makeresampler and its padmethod is set to either 'fill' or 'bound'. • When a custom resampler is used that supports the 'fill' or 'bound' pad methods (with behavior that is specific to the customization). • When the map from the transform dimensions of B to the transform dimensions of A is deliberately undefined for some points. Such points are encoded in the input transform space by NaNs in either TMAP_B or in the output of TFORMINV. In the first two cases, fill values are used to compute values for output locations that map outside or near the edges of the input array. Fill values are copied into B when output locations map well outside the input array. See makeresampler for more information about 'fill' and 'bound'. F can be a scalar (including NaN), in which case its value is replicated across all the nontransform dimensions. F can also be a nonscalar, 3-805 tformarray whose size depends on size(A) in the nontransform dimensions. Specifically, if K is the Jth nontransform dimension of A, then size(F,J) must be either size(A,K) or 1. As a convenience to the user, tformarray replicates F across any dimensions with unit size such that after the replication size(F,J) equals size(A,K). For example, suppose A represents 10 RGB images and has size 200-by-200-by-3-by-10, T is a 2-D transformation, and TDIMS_A and TDIMS_B are both [1 2]. In other words, tformarray will apply the same 2-D transform to each color plane of each of the 10 RGB images. In this situation you have several options for F: • F can be a scalar, in which case the same fill value is used for each color plane of all 10 images. • F can be a 3-by-1 vector, [R G B]'. Then R, G, and B are used as the fill values for the corresponding color planes of each of the 10 images. This can be interpreted as specifying an RGB fill color, with the same color used for all 10 images. • F can be a 1-by-10 vector. This can be interpreted as specifying a different fill value for each of 10 images, with that fill value being used for all three color planes. • F can be a 3-by-10 matrix, which can be interpreted as supplying a different RGB fill color for each of the 10 images. Class Support A can be any nonsparse numeric array, and can be real or complex. It can also be of class logical. Examples Create a 2-by-2 checkerboard image where each square is 20 pixels wide, then transform it with a projective transformation. Use a pad method of 'circular’ when creating a resampler, so that the output appears to be a perspective view of an infinite checkerboard. Swap the output dimensions. Specify a 100-by-100 output image. Leave TMAP_B empty, since TSIZE_B is specified. Leave the fill value empty, since it won’t be needed. I = checkerboard(20,1,1); 3-806 tformarray figure; imshow(I) T = maketform('projective',[1 1; 41 1; 41 41; 1 41],... [5 5; 40 5; 35 30; -10 30]); R = makeresampler('cubic','circular'); J = tformarray(I,T,R,[1 2],[2 1],[100 100],[],[]); figure; imshow(J) See Also findbounds | imtransform | makeresampler | maketform 3-807 tformfwd Purpose Apply forward spatial transformation Syntax [X, Y] = tformfwd(T, U, V) [X1, X2, X3,...] = tformfwd(T, U1, U2, U3,...) X = tformfwd(T, U) X = tformfwd(T, U) [X1, X2, X3,...] = tformfwd(T, U) X = tformfwd(T, U1, U2, U3,...) X = tformfwd(U,T) Description [X, Y] = tformfwd(T, U, V) applies the 2D-to-2D spatial transformation defined in T to coordinate arrays U and V, mapping the point [U(k) V(k)] to the point [X(k) Y(k)]. T is a TFORM struct created with maketform, fliptform, or cp2tform. Both T.ndims_in and T.ndims_out must equal 2. U and V are typically column vectors matching in length. In general, U and V can have any dimensionality, but must have the same size. In any case, X and Y will have the same size as U and V. [X1, X2, X3,...] = tformfwd(T, U1, U2, U3,...) applies the ndims_in-to-ndims_out spatial transformation defined in TFORM structure T to the coordinate arrays U1,U2,...,UNDIMS_IN (where NDIMS_IN = T.ndims_in and NDIMS_OUT = T.ndims_out). The number of output arguments must equal NDIMS_OUT. The transformation maps the point [U1(k) U2(k) ... UNDIMS_IN(k)] to the point [X1(k) X2(k) ... XNDIMS_OUT(k)]. U1,U2,U3,... can have any dimensionality, but must be the same size. X1,X2,X3,... must have this size also. X = tformfwd(T, U) applies the ndims_in-to-ndims_out spatial transformation defined in TFORM structure T to each row of U, where 3-808 tformfwd U is an M-by-NDIMS_IN matrix. It maps the point U(k,:) to the point X(k,:). X is an M-by-NDIMS_OUT matrix. X = tformfwd(T, U), where U is an (N+1)-dimensional array, maps the point U(k1,k2,...,kN,:) to the point X(k1,k2,...,kN,:). size(U,N+1) must equal NDIMS_IN. X is an (N+1)-dimensional array, with size(X,I) equal to size(U,I) for I = 1,...,N and size(X,N+1) equal to NDIMS_OUT. [X1, X2, X3,...] = tformfwd(T, U) maps an (N+1)-dimensional array to NDIMS_OUT equally sized N-dimensional arrays. X = tformfwd(T, U1, U2, U3,...) maps NDIMS_IN N-dimensional arrays to one (N+1)-dimensional array. Note X = tformfwd(U,T) is an older form of the two-argument syntax that remains supported for backward compatibility. Examples Create an affine transformation that maps the triangle with vertices (0,0), (6,3), (-2,5) to the triangle with vertices (-1,-1), (0,-10), (4,4). u = [ 0 6 -2]'; v = [ 0 3 5]'; x = [-1 0 4]'; y = [-1 -10 4]'; tform = maketform('affine',[u v],[x y]); Validate the mapping by applying tformfwd. Results should equal [x, y] [xm, ym] = tformfwd(tform, u, v) See Also cp2tform | fliptform | maketform | tforminv 3-809 tforminv Purpose Apply inverse spatial transformation Syntax [U,V] = tforminv(T,X,Y) [U1,U2,U3,...] = tforminv(T,X1,X2,X3,...) U = tforminv(T,X) [U1,U2,U3,...] = tforminv(T,X) U = tforminv(T,X1,X2,X3,...) Description [U,V] = tforminv(T,X,Y) applies the 2D-to-2D inverse transformation defined in TFORM structure T to coordinate arrays X and Y, mapping the point [X(k) Y(k)] to the point [U(k) V(k)]. Both T.ndims_in and T.ndims_out must equal 2. X and Y are typically column vectors matching in length. In general, X and Y can have any dimensionality, but must have the same size. In any case, U and V will have the same size as X and Y. [U1,U2,U3,...] = tforminv(T,X1,X2,X3,...) applies the NDIMS_OUT-to-NDIMS_IN inverse transformation defined in TFORM structure T to the coordinate arrays X1,X2,...,XNDIMS_OUT (where NDIMS_IN = T.ndims_in and NDIMS_OUT = T.ndims_out). The number of output arguments must equal NDIMS_IN. The transformation maps the point [X1(k) X2(k) ... XNDIMS_OUT(k)] to the point [U1(k) U2(k) ... UNDIMS_IN(k)]. X1,X2,X3,... can have any dimensionality, but must be the same size. U1,U2,U3,... have this size also. U = tforminv(T,X) applies the NDIMS_OUT-to-NDIMS_IN inverse transformation defined in TFORM structure T to each row of X, where X is an M-by-NDIMS_OUT matrix. It maps the point X(k,:) to the point U(k,:). U is an M-by-NDIMS_IN matrix. 3-810 tforminv U = tforminv(T,X), where X is an (N+1)-dimensional array, maps the point X(k1,k2,...,kN,:) to the point U(k1,k2,...,kN,:). size(X,N+1) must equal NDIMS_OUT. U is an (N+1)-dimensional array, with size(U,I) equal to size(X,I) for I = 1,...,N and size(U,N+1) equal to NDIMS_IN. [U1,U2,U3,...] = tforminv(T,X) maps an (N+1)-dimensional array to NDIMS_IN equally-sized N-dimensional arrays. U = tforminv(T,X1,X2,X3,...) maps NDIMS_OUT N-dimensional arrays to one (N+1)-dimensional array. Note U = tforminv(X,T) is an older form of the two-argument syntax that remains supported for backward compatibility. Examples Create an affine transformation that maps the triangle with vertices (0,0), (6,3), (-2,5) to the triangle with vertices (-1,-1), (0,-10), (4,4). u = [ 0 6 -2]'; v = [ 0 3 5]'; x = [-1 0 4]'; y = [-1 -10 4]'; tform = maketform('affine',[u v],[x y]); Validate the mapping by applying tforminv. Results should equal [u, v]. [um, vm] = tforminv(tform, x, y) See Also cp2tform | tformfwd | maketform | fliptform 3-811 tonemap Purpose Render high dynamic range image for viewing Syntax RGB = tonemap(HDR) RGB = tonemap(HDR, param1, val1, ...) Description RGB = tonemap(HDR) converts the high dynamic range image HDR to a lower dynamic range image, RGB, suitable for display, using a process called tone mapping. Tone mapping is a technique used to approximate the appearance of high dynamic range images on a display with a more limited dynamic range. RGB = tonemap(HDR, param1, val1, ...) performs tone mapping where parameters control various aspects of the operation. The following table lists these parameters. 3-812 Parameter Description 'AdjustLightness' A two-element vector in the form [low high] that specifies the overall lightness of the rendered image. low and high are luminance values of the low dynamic range image, in the range [0, 1]. These values are passed to imadjust. 'AdjustSaturation' A numeric value that specifies the saturation of colors in the rendered image. When the value is greater than 1, the colors are more saturated. When the value is in the range [0, 1) colors are less saturated. 'NumberOfTiles' A two-element vector of the form [rows cols] that specifies the number of tiles used during the adaptive histogram equalization part of the tone mapping operation. rows and cols specify the number of tile rows and columns. Both rows and cols must be at least 2. The total number of image tiles is equal to rows * cols. A larger number of tiles results in an tonemap Parameter Description image with greater local contrast. The default for rows and cols is 4. Class Support The high dynamic range image HDR must be a m-by-n-by-3 single or double array. The output image RGB is an m-by-n-by-3 uint8 image. Examples Load a high dynamic range image, convert it to a low dynamic range image while deepening shadows and increasing saturation, and display the results. hdr = hdrread('office.hdr'); imshow(hdr) rgb = tonemap(hdr, 'AdjustLightness', [0.1 1], ... 'AdjustSaturation', 1.5); figure; imshow(rgb) See Also adapthisteq | hdrread | stretchlim 3-813 translate Purpose Translate structuring element (STREL) Syntax SE2 = translate(SE,V) Description SE2 = translate(SE,V) translates the structuring element SE in N-D space. SE is an array of structuring elements, created using the strel function. V is an N-element vector that specifies the offsets of the desired translation in each dimension, relative to the structuring element’s origin. If you specify an array, translate reshapes the array into a vector. SE2 is an array of structuring elements the same size as SE. Each individual structuring element in SE2 is the translation of the corresponding structuring element in SE. Class Support SE and SE2 are STREL objects; V is a vector of doubles that must contain Examples Translate a 3-by-3 structuring element. only integers. se = strel(ones(3)) se2 = translate(se,[-2 -2]) The following figure shows the original structuring element and the translated structuring element. 3-814 translate Dilating with a translated version of strel(1) is a way to translate an input image in space by an integer number of pixels. This example translates the cameraman.tif image down and to the right by 25 pixels. I = imread('cameraman.tif'); se = translate(strel(1), [25 25]); J = imdilate(I,se); imshow(I), title('Original') figure, imshow(J), title('Translated'); See Also strel | reflect 3-815 truesize Purpose Adjust display size of image Syntax truesize(fig,[mrows ncols]) Description truesize(fig,[mrows ncols]) adjusts the display size of an image. fig is a figure containing a single image or a single image with a colorbar. [mrows ncols] is a 1-by-2 vector that specifies the requested screen area (in pixels) that the image should occupy. truesize(fig) uses the image height and width for [mrows ncols]. This results in the display having one screen pixel for each image pixel. If you do not specify a figure, truesize uses the current figure. Examples Fit image to figure window. imshow(checkerboard,'InitialMagnification','fit') Resize image and figure to show image at its 80-by-80 pixel size. truesize See Also 3-816 imshow | iptsetpref | iptgetpref uintlut Purpose Compute new values of A based on lookup table (LUT) Syntax B = uintlut(A,LUT) uintlut has been removed. Use intlut instead. Class Support A must be uint8 or uint16. If A is uint8, then LUT must be a uint8 vector with 256 elements. If A is uint16, then LUT must be a uint16 vector with 65536 elements. B has the same size and class as A. Examples A = uint8([1 2 3 4; 5 6 7 8;9 10 11 12]); LUT = repmat(uint8([0 150 200 255]),1,64); B = uintlut(A,LUT); imshow(A,[]), figure, imshow(B); See Also impixel | improfile 3-817 viscircles Purpose Create circle Syntax viscircles(centers,radii) viscircles(ax,centers,radii) h = viscircles(ax,centers,radii) h = viscircles( ___ ,Name,Value) Description viscircles(centers,radii) draws circles with specified centers and radii onto the current axes. viscircles(ax,centers,radii) draws circles onto the axes specified by ax. h = viscircles(ax,centers,radii) returns a vector of hggroup handles to each circle. These handles are children of the axes object, ax. h = viscircles( ___ ,Name,Value) specifies additional options with one or more Name,Value pair arguments, using any of the previous syntaxes. Input Arguments centers - Coordinates of circle centers two-column matrix Coordinates of circle centers, specified as a P-by-2 matrix, such as that obtained from imfindcircles. The x-coordinates of the circle centers are in the first column and the y-coordinates are in the second column. The coordinates can be integers (of any numeric type) or floating-point values (of type double or single). Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 radii - Circle radii column vector 3-818 viscircles Circle radii, specified as a column vector such as that returned by imfindcircles. The radius value at radii(j) corresponds to the circle with center coordinates centers(j,:). The values of radii can be nonnegative integers (of any numeric type) or floating-point values (of type double or single). Data Types single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 ax - Axes in which to draw circles handle Axes in which to draw circles, specified as a handle object returned by gca or axes. Data Types double Name-Value Pair Arguments Specify optional comma-separated pairs of Name,Value arguments, where Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN. Example: 'EdgeColor','b' specifies blue circle edges, using the short name for blue. EdgeColor - Color of circle edge [R G B] | short name | long name | `red' (default) | `none' Color of circle edges, specified as the comma-separated pair consisting of 'EdgeColor', followed by any ColorSpec value or 'none'. Example: 'EdgeColor','b' specifies blue circle edges. LineStyle - Line style of circle edge '-' (default) | '--' | ':' 3-819 viscircles Line style of circle edge, specified as the comma-separated pair consisting of 'LineStyle' and any line specifier in the table below. Specifier Line Style ’- ’ Solid line (default) ’--’ Dashed line ’: ’ Dotted line ’-.’ Dash-dot line 'none' No line Example: 'LineStyle','--' specifies a dashed line at each circle edge. LineWidth - Width of circle edge double | 2 (default) Width of circle edge expressed in points, where each point equals 1/72 of an inch, specified as the comma-separated pair consisting of 'LineWidth' followed by a positive floating-point double value. Example: 'LineWidth',4 specifies a 4-point line width. Output Arguments h - Handles of the circles vector Handles of the circles, returned as a vector of hggroup object handles. These handles are children of the axes object ax. Examples Draw Edge Lines Around Both Bright and Dark Circles in an Image Read the image into the workspace and display it. A = imread('circlesBrightDark.png'); imshow(A) 3-820 viscircles Define the radius range. Rmin = 30; Rmax = 65; Find all the bright circles in the image within the radius range. [centersBright, radiiBright] = imfindcircles(A,[Rmin Rmax],'ObjectPola Find all the dark circles in the image within the radius range. [centersDark, radiiDark] = imfindcircles(A,[Rmin Rmax],'ObjectPolarity Draw blue lines at bright circle edges. 3-821 viscircles viscircles(centersBright, radiiBright,'EdgeColor','b'); Draw red dashed lines at dark circle edges. viscircles(centersDark, radiiDark,'LineStyle','--'); 3-822 viscircles See Also imfindcircles | imdistline | imtool 3-823 warp Purpose Display image as texture-mapped surface Syntax warp(X,map) warp(I,n) warp(BW) warp(RGB) warp(z,...) warp(x,y,z...) h = warp(...) Description warp(X,map) displays the indexed image X with colormap map as a texture map on a simple rectangular surface. warp(I,n) displays the intensity image I with grayscale colormap of length n as a texture map on a simple rectangular surface. warp(BW) displays the binary image BW as a texture map on a simple rectangular surface. warp(RGB) displays the RGB image in the array RGB as a texture map on a simple rectangular surface. warp(z,...) displays the image on the surface z. warp(x,y,z...) displays the image on the surface (x,y,z). h = warp(...) returns a handle to a texture-mapped surface. Class Support The input image can be of class logical, uint8, uint16, or double. Tips Texture-mapped surfaces are generally rendered more slowly than images. See Also imshow | image | imagesc | surf 3-824 watershed Purpose Watershed transform Syntax L = watershed(A) L = watershed(A, conn) Description L = watershed(A) computes a label matrix identifying the watershed regions of the input matrix A, which can have any dimension. The elements of L are integer values greater than or equal to 0. The elements labeled 0 do not belong to a unique watershed region. These are called watershed pixels. The elements labeled 1 belong to the first watershed region, the elements labeled 2 belong to the second watershed region, and so on. By default, watershed uses 8-connected neighborhoods for 2-D inputs and 26-connected neighborhoods for 3-D inputs. For higher dimensions, watershed uses the connectivity given by conndef(ndims(A),'maximal'). L = watershed(A, conn) specifies the connectivity to be used in the watershed computation. conn can have any of the following scalar values. Value Meaning Two-dimensional connectivities 4 4-connected neighborhood 8 8-connected neighborhood Three-dimensional connectivities 6 6-connected neighborhood 18 18-connected neighborhood 26 26-connected neighborhood Connectivity can be defined in a more general way for any dimension by using for conn a 3-by-3-by- ...-by-3 matrix of 0’s and 1’s. The 1-valued 3-825 watershed elements define neighborhood locations relative to the center element of conn. Note that conn must be symmetric about its center element. Remarks The watershed transform algorithm used by this function changed in version 5.4 (R2007a) of the Image Processing Toolbox software. The previous algorithm occasionally produced labeled watershed basins that were not contiguous. If you need to obtain the same results as the previous algorithm, use the function watershed_old. Class Support A can be a numeric or logical array of any dimension, and it must be nonsparse. The output array L is of class double. Examples 2-D Example 1 Make a binary image containing two overlapping circular objects. center1 = -10; center2 = -center1; dist = sqrt(2*(2*center1)^2); radius = dist/2 * 1.4; lims = [floor(center1-1.2*radius) ceil(center2+1.2*radius)]; [x,y] = meshgrid(lims(1):lims(2)); bw1 = sqrt((x-center1).^2 + (y-center1).^2) <= radius; bw2 = sqrt((x-center2).^2 + (y-center2).^2) <= radius; bw = bw1 | bw2; figure, imshow(bw,'InitialMagnification','fit'), title('bw') 2 Compute the distance transform of the complement of the binary image. D = bwdist(~bw); figure, imshow(D,[],'InitialMagnification','fit') title('Distance transform of ~bw') 3 Complement the distance transform, and force pixels that don’t belong to the objects to be at -Inf. 3-826 watershed D = -D; D(~bw) = -Inf; 4 Compute the watershed transform and display the resulting label matrix as an RGB images. L = watershed(D); rgb = label2rgb(L,'jet',[.5 .5 .5]); figure, imshow(rgb,'InitialMagnification','fit') title('Watershed transform of D') 3-D Example 1 Make a 3-D binary image containing two overlapping spheres. center1 = -10; center2 = -center1; dist = sqrt(3*(2*center1)^2); radius = dist/2 * 1.4; lims = [floor(center1-1.2*radius) ceil(center2+1.2*radius)]; [x,y,z] = meshgrid(lims(1):lims(2)); bw1 = sqrt((x-center1).^2 + (y-center1).^2 + ... (z-center1).^2) <= radius; bw2 = sqrt((x-center2).^2 + (y-center2).^2 + ... (z-center2).^2) <= radius; bw = bw1 | bw2; figure, isosurface(x,y,z,bw,0.5), axis equal, title('BW') xlabel x, ylabel y, zlabel z xlim(lims), ylim(lims), zlim(lims) view(3), camlight, lighting gouraud 2 Compute the distance transform. D = bwdist(~bw); figure, isosurface(x,y,z,D,radius/2), axis equal title('Isosurface of distance transform') xlabel x, ylabel y, zlabel z xlim(lims), ylim(lims), zlim(lims) 3-827 watershed view(3), camlight, lighting gouraud 3 Complement the distance transform, force nonobject pixels to be -Inf, and then compute the watershed transform. D = -D; D(~bw) = -Inf; L = watershed(D); figure isosurface(x,y,z,L==2,0.5) isosurface(x,y,z,L==3,0.5) axis equal title('Segmented objects') xlabel x, ylabel y, zlabel z xlim(lims), ylim(lims), zlim(lims) view(3), camlight, lighting gouraud Algorithms watershed uses the Fernand Meyer algorithm [1]. References [1] Meyer, Fernand, "Topographic distance and watershed lines,” Signal Processing , Vol. 38, July 1994, pp. 113-125. See Also bwlabel | bwlabeln | bwdist | regionprops 3-828 whitepoint Purpose XYZ color values of standard illuminants Syntax xyz = whitepoint(string) xyz = whitepoint Description xyz = whitepoint(string) returns xyz, a three-element row vector of XYZ values scaled so that Y = 1. string specifies the white reference illuminant. The following table lists all the possible values for string. The default value is enclosed in braces ({}). Value Description 'a' CIE standard illuminant A 'c' CIE standard illuminant C 'd50' CIE standard illuminant D50 'd55' CIE standard illuminant D55 'd65' CIE standard illuminant D65 {'icc'} ICC standard profile connection space illuminant; a 16-bit fractional approximation of D50 xyz = whitepoint is the same as xyz = whitepoint('icc'). Class Support string is a character array. xyz is of class double. Examples Return the XYZ color space representation of the default white reference illuminant 'icc'. wp_icc = whitepoint wp_icc = 0.9642 1.0000 0.8249 3-829 whitepoint See Also 3-830 applycform | lab2double | lab2uint8 | lab2uint16 | makecform | xyz2double | xyz2uint16 wiener2 Purpose 2-D adaptive noise-removal filtering Note The syntax wiener2(I,[m n],[mblock nblock],noise) has been removed. Use the wiener2(I,[m n],noise) syntax instead. Syntax J = wiener2(I,[m n],noise) [J,noise] = wiener2(I,[m n]) Description wiener2 lowpass-filters a grayscale image that has been degraded by constant power additive noise. wiener2 uses a pixelwise adaptive Wiener method based on statistics estimated from a local neighborhood of each pixel. J = wiener2(I,[m n],noise) filters the image I using pixelwise adaptive Wiener filtering, using neighborhoods of size m-by-n to estimate the local image mean and standard deviation. If you omit the [m n] argument, m and n default to 3. The additive noise (Gaussian white noise) power is assumed to be noise. [J,noise] = wiener2(I,[m n]) also estimates the additive noise power before doing the filtering. wiener2 returns this estimate in noise. Class Support The input image I is a two-dimensional image of class uint8, uint16, int16, single, or double. The output image J is of the same size and class as I. Examples For an example, see “Removing Noise By Adaptive Filtering”. Algorithms wiener2 estimates the local mean and variance around each pixel. = 1 ∑ a(n1 , n2 ) NM n ,n ∈ 1 2 and 3-831 wiener2 2 = 1 a2 (n1 , n2 ) − 2 , ∑ NM n ,n ∈ 1 2 where is the N-by-M local neighborhood of each pixel in the image A. wiener2 then creates a pixelwise Wiener filter using these estimates, b(n1 , n2 ) = + 2 − 2 2 (a(n1 , n2 ) − ), where ν2 is the noise variance. If the noise variance is not given, wiener2 uses the average of all the local estimated variances. References Lim, Jae S., Two-Dimensional Signal and Image Processing, Englewood Cliffs, NJ, Prentice Hall, 1990, p. 548, equations 9.44 -- 9.46. See Also filter2 | medfilt2 3-832 xyz2double Purpose Convert XYZ color values to double Syntax xyxd = xyz2double(XYZ) Description xyxd = xyz2double(XYZ) converts an M-by-3 or M-by-N-by-3 array of XYZ color values to double. xyzd has the same size as XYZ. The Image Processing Toolbox software follows the convention that double-precision XYZ arrays contain 1931 CIE XYZ values. XYZ arrays that are uint16 follow the convention in the ICC profile specification (ICC.1:2001-4, www.color.org) for representing XYZ values as unsigned 16-bit integers. There is no standard representation of XYZ values as unsigned 8-bit integers. The ICC encoding convention is illustrated by this table. Value (X, Y, or Z) uint16 Value 0.0 0 1.0 32768 1.0 + (32767/32768) 65535 Class Support xyz is a uint16 or double array that must be real and nonsparse. xyzd is of class double. Examples Convert uint16-encoded XYZ values to double. xyz2double(uint16([100 32768 65535])) ans = 0.0031 See Also 1.0000 2.0000 applycform | lab2double | lab2uint16 | lab2uint8 | makecform | whitepoint | xyz2uint16 3-833 xyz2uint16 Purpose Convert XYZ color values to uint16 Syntax xyz16 = xyz2uint16(xyz) Description xyz16 = xyz2uint16(xyz) converts an M-by-3 or M-by-N-by-3 array of XYZ color values to uint16. xyz16 has the same size as xyz. The Image Processing Toolbox software follows the convention that double-precision XYZ arrays contain 1931 CIE XYZ values. XYZ arrays that are uint16 follow the convention in the ICC profile specification (ICC.1:2001-4, www.color.org) for representing XYZ values as unsigned 16-bit integers. There is no standard representation of XYZ values as unsigned 8-bit integers. The ICC encoding convention is illustrated by this table. Value (X, Y, or Z) uint16 Value 0.0 0 1.0 32768 1.0 + (32767/32768) 65535 Class Support xyz is a uint16 or double array that must be real and nonsparse. xyz16 is uint8. Examples Convert XYZ values to uint16 encoding. xyz2uint16([0.1 0.5 1.0]) ans = 3277 16384 32768 See Also 3-834 applycform | lab2double | lab2uint16 | lab2uint8 | makecform | whitepoint | xyz2double ycbcr2rgb Purpose Convert YCbCr color values to RGB color space Syntax rgbmap = ycbcr2rgb(ycbcrmap) RGB = ycbcr2rgb(YCBCR) Description rgbmap = ycbcr2rgb(ycbcrmap) converts the YCbCr values in the colormap ycbcrmap to the RGB color space. If ycbcrmap is M-by-3 and contains the YCbCr luminance (Y) and chrominance (Cb and Cr) color values as columns, rgbmap is returned as an M-by-3 matrix that contains the red, green, and blue values equivalent to those colors. RGB = ycbcr2rgb(YCBCR) converts the YCbCr image YCBCR to the equivalent truecolor image RGB. Class Support If the input is a YCbCr image, it can be of class uint8, uint16, or double. The output image is of the same class as the input image. If the input is a colormap, the input and output colormaps are both of class double. Examples Convert image from RGB space to YCbCr space and back. rgb = imread('board.tif'); ycbcr = rgb2ycbcr(rgb); rgb2 = ycbcr2rgb(ycbcr); References [1] Poynton, C. A.A Technical Introduction to Digital Video, John Wiley & Sons, Inc., 1996, p. 175. [2] Rec. ITU-R BT.601-5, Studio Encoding Parameters of Digital Television for Standard 4:3 and Wide-screen 16:9 Aspect Ratios, (1982-1986-1990-1992-1994-1995), Section 3.5. See Also ntsc2rgb | rgb2ntsc | rgb2ycbcr 3-835 ycbcr2rgb 3-836 Index A Index adapthisteq 3-2 affine transformations definition 3-111 analyze75info 3-6 analyze75read 3-7 analyzing images edge detection 3-165 intensity profiles 3-488 pixel values 3-457 quadtree decomposition 3-723 applycform 3-9 applylut 3-11 averaging filter creating 3-194 axes2pix 3-14 B basicimageinfo 3-304 bestblk 3-15 binary images applying a lookup table 3-11 constructing lookup tables 3-661 labeling connected components 3-54 object selection 3-83 using neighborhood operations 3-11 block processing block size 3-15 using nlfilter 3-694 bwarea 3-14 3-24 bwareaopen 3-26 bwboundaries 3-29 bwdist 3-41 bweuler 3-50 bwhitmiss 3-52 bwlabel 3-54 bwlabeln 3-57 bwmorph 3-70 bwpack 3-78 bwperim 3-81 bwselect 3-83 bwtraceboundary 3-85 bwulterode 3-88 bwunpack 3-90 C Canny edge detector 3-165 checkerboard 3-91 chessboard distance transform using bwdist 3-41 cityblock distance transform using bwdist 3-41 closing 3-71 col2im 3-93 colfilt 3-94 color spaces converting between 3-698 3-771 NTSC 3-698 3-771 column processing 3-94 reshaping columns into blocks 3-93 conndef 3-97 connected components using bwlabel 3-54 convmtx2 3-99 convolution convolution matrix 3-99 corr2 3-107 correlation coefficient 3-107 cp2tform 3-108 cpcorr 3-120 cpselect 3-122 cpstruct2pairs 3-126 D dct2 3-127 dctmtx 3-130 decomposition of structuring elements Index-1 Index getting sequence 3-222 deconvblind 3-131 deconvlucy 3-134 deconvreg 3-137 deconvwnr 3-139 decorrstretch 3-144 demosaic 3-145 dicomanon 3-149 dicomdict 3-151 dicominfo 3-152 dicomlookup 3-154 dicomread 3-155 dicomuid 3-157 dicomwrite 3-158 dilation grayscale 3-700 discrete cosine transform transform matrix 3-130 disk filter 3-194 display techniques displaying images at true size 3-816 multiple images 3-802 E edge 3-164 edge detection methods 3-165 edgetaper 3-171 entropy 3-172 entropyfilt 3-173 erosion grayscale 3-700 Euclidean distance transform using bwdist 3-42 F fan2para 3-175 fanbeam 3-180 Index-2 filter design frequency sampling method 3-191 frequency transformation method 3-200 windowing method 3-207 filters averaging 3-194 disk 3-194 Gaussian 3-194 Laplacian 3-194 Log 3-194 median 3-675 motion 3-194 order-statistic 3-700 Prewitt 3-194 Sobel 3-194 unsharp 3-194 findbounds 3-185 fliptform 3-188 frequency response computing 3-189 frequency sampling method (filter design) using fsamp2 3-191 frequency transformation method (filter design) using ftrans2 3-200 freqz2 3-189 fsamp2 3-191 fspecial 3-194 ftrans2 3-200 fwind1 3-203 fwind2 3-207 G Gaussian filter 3-194 Gaussian noise adding 3-448 getheight 3-211 getimage 3-212 getimagemodel 3-215 getline 3-216 Index getneighbors 3-217 getnhood 3-218 getpts 3-219 getrangefromclass 3-220 getrect 3-221 getsequence 3-222 gray2ind 3-224 grayscale morphological operations 3-700 grayslice 3-237 graythresh 3-239 H hdrread 3-240 hdrwrite 3-241 histeq 3-242 histogram equalization 3-242 hough 3-247 houghlines 3-252 houghpeaks 3-255 I iccfind 3-257 iccread 3-259 iccroot 3-263 iccwrite 3-264 idct2 3-266 ifanbeam 3-268 im2bw 3-273 im2col 3-275 im2double 3-277 im2int16 3-278 3-280 im2java2d 3-279 im2single 3-280 im2uint16 3-281 im2uint8 3-282 imabsdiff 3-283 imadd 3-285 imadjust 3-287 image transformations affine 3-111 local weighted mean 3-112 nonreflective similarity 3-111 piecewise linear 3-112 polynomial 3-111 projective 3-111 similarity 3-111 imageinfo 3-295 imagemodel 3-298 images creating movies 3-445 displaying multiple images 3-802 getting data from axes 3-212 imbothat 3-307 imclearborder 3-310 imclose 3-313 imcolormaptool 3-315 imcomplement 3-317 imcontour 3-319 imcontrast 3-321 imcrop 3-324 imdilate 3-329 imdisplayrange 3-334 imdistline 3-336 imdivide 3-344 imellipse 3-346 imerode 3-351 imextendedmax 3-355 imextendedmin 3-357 imfill 3-359 imfilter 3-363 imfreehand 3-385 imgca 3-394 imgcf 3-396 imgetfile 3-397 imhandles 3-408 imhist 3-409 imhmax 3-426 imhmin 3-428 Index-3 Index imimposemin 3-431 imlincomb 3-435 imline 3-438 immagbox 3-443 immovie 3-445 immultiply 3-446 imnoise 3-448 imopen 3-451 imoverview 3-453 imoverviewpanel 3-456 impixel 3-457 impixelinfo 3-460 impixelinfoval 3-463 impixelregion 3-465 impixelregionpanel 3-468 implay 3-469 impoint 3-472 impoly 3-477 impositionrect 3-484 improfile 3-488 imputfile 3-491 impyramid 3-493 imreconstruct 3-506 imrect 3-508 imregionalmax 3-513 imregionalmin 3-516 imresize 3-531 imroi 3-536 imrotate 3-539 imsave 3-541 imscrollpanel 3-543 imshow 3-549 imsubtract 3-561 imtool 3-563 imtophat 3-568 imtransform 3-571 imview 3-581 ind2gray 3-582 ind2rgb 3-584 Index-4 indexed images converting from intensity 3-224 Intel® Integrated Performance Primitives Library 3-588 intensity images converting from matrices 3-673 converting from RGB 3-769 converting to indexed 3-224 intensity profiles 3-488 interfileinfo 3-585 interfileread 3-586 intlut 3-587 ippl 3-588 iptaddcallback 3-590 iptcheckconn 3-591 iptcheckhandle 3-592 iptcheckinput 3-594 iptcheckmap 3-596 iptchecknargin 3-597 iptcheckstrs 3-598 iptcondir 3-604 iptdemos 3-600 iptgetapi 3-601 iptGetPointerBehavior 3-602 iptgetpref 3-603 iptnum2ordinal 3-605 iptPointerManager 3-606 iptremovecallback 3-613 iptSetPointerBehavior 3-614 iptsetpref 3-618 iptwindowalign 3-619 iradon 3-623 isbw 3-627 isflat 3-628 isgray 3-629 isicc 3-630 isind 3-632 isnitf 3-633 isrgb 3-634 Index L N lab2double 3-636 lab2uint16 3-638 lab2uint8 3-640 label2rgb 3-642 neighborhoods binary image operations 3-11 nitfinfo 3-692 nitfread 3-693 nlfilter 3-694 noise adding to an image 3-448 nonreflective similarity transformations 3-111 normxcorr2 3-696 NTSC color space 3-698 3-771 ntsc2rgb 3-698 Laplacian filter 3-194 Laplacian of Gaussian edge detector 3-165 local weighted mean transformations 3-112 Log filters 3-194 lookup tables constructing 3-661 M makecform 3-648 makeConstrainToRectFcn 3-657 makehdr 3-658 makelut 3-661 makeresampler 3-663 maketform 3-668 mat2gray 3-673 matrices converting to intensity images 3-673 McClellan transform 3-200 mean2 3-674 medfilt2 3-675 median filtering 3-675 montage 3-678 morphological operations closing 3-71 diagonal fill 3-71 grayscale 3-700 shrinking objects 3-73 motion filters 3-194 movies creating from images 3-445 multiframe images displaying 3-678 multilevel thresholding 3-237 O object selection 3-83 order-statistic filtering 3-700 ordfilt2 3-700 otf2psf 3-702 P padarray 3-703 para2fan 3-707 phantom 3-711 piecewise linear transformations 3-112 pixel values using impixel 3-457 Poisson noise adding 3-448 poly2mask 3-714 polynomial transformations 3-111 Prewitt edge detector 3-165 Prewitt filters 3-194 projective transformations 3-111 psf2otf 3-722 Q qtdecomp 3-723 Index-5 Index qtgetblk 3-727 qtsetblk 3-729 quadtree decomposition 3-723 getting block values 3-727 setting block values 3-729 quasi-euclidean distance transform using bwdist 3-42 R radon 3-730 rangefilt 3-733 reflect 3-735 regionprops 3-736 RGB images converting to intensity 3-769 rgb2gray 3-769 rgb2ntsc 3-771 rgb2ycbcr 3-772 Roberts edge detector 3-165 roicolor 3-774 roifill 3-776 roifilt2 3-782 roipoly 3-784 S salt and pepper noise adding 3-448 similarity transformations 3-111 Sobel edge detector 3-165 Sobel filters 3-194 speckle noise adding 3-448 statistical properties mean 3-674 standard deviation 3-791 std2 3-791 stdfilt 3-792 strel 3-793 Index-6 stretchlim 3-800 structuring elements decomposition sequence 3-222 determining composition 3-332 subimage 3-802 T tformarray 3-803 tformfwd 3-808 tforminv 3-810 thresholding to create indexed image from intensity image 3-237 tonemap 3-812 transforms discrete cosine 3-127 translate 3-814 truesize 3-816 U uintlut 3-817 unsharp filters 3-194 W warp 3-824 watershed 3-825 whitepoint 3-829 wiener2 3-831 windowing method (filter design) 3-207 X xyz2double 3-833 xyz2uint16 3-834 Y ycbcr2rgb 3-835 Index Z zero-cross edge detector 3-165 Index-7
* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project
advertisement
© 2021