While I was working on a prototype yesterday, I found myself writing a small bit of code that turned out to be so useful, I wondered why I had never done it before. I'd like to show it to you. It'll be an opportunity to explore some recent advances in MATLAB that make useful function syntaxes easy to write.<\/span><\/div>
I wrote a simple function called <\/span>imageSizeInXY<\/span>. This function takes a MATLAB Graphics <\/span>Image<\/span> object and returns its total width and height in the spatial x-y units of the axes.<\/span><\/div>function <\/span>out = imageSizeInXY(im)<\/span><\/span><\/div> <\/div>    <\/span>...<\/span><\/span><\/div> <\/div>end<\/span><\/span><\/div><\/div>(I'll show the full implementation below.) I was using the function like this.<\/span><\/div>A = imread(<\/span>\"peppers.png\"<\/span>);<\/span><\/span><\/div><\/div>im = imshow(A, XData = [-1 1], YData = [-1 1]);<\/span><\/span><\/div><\/div>axis <\/span>on<\/span><\/span><\/div><\/div><\/div><\/div><\/div><\/div><\/div><\/div><\/div>imageSizeInXY_v1(im)<\/span><\/span><\/div>ans = <\/span>1\u00d72<\/span><\/div><\/div>    2.0039    2.0052\r\n<\/div><\/div><\/div><\/div><\/div><\/div><\/div><\/div><\/div><\/div><\/div><\/div>But this function only works if I have captured the image object in a variable. Usually, I call <\/span>imshow<\/span> with no output argument, and so I don't have the image object:<\/span><\/div>imshow(A, XData = [-1 1], YData = [-1 1])<\/span><\/span><\/div><\/div>I thought to myself, it would sure be nice if I could just call <\/span>imageSizeInXY<\/span> with no input arguments, and it would just automatically tell me about the image that's displayed in the current figure. After thinking about this briefly, I wrote the following:<\/span><\/div>function <\/span>out = imageSizeInXY(im)<\/span><\/span><\/div>    <\/span>arguments<\/span><\/span><\/div>        im <\/span>(1,1) matlab.graphics.primitive.Image <\/span>= findimage<\/span><\/span><\/div>    <\/span>end<\/span><\/span><\/div> <\/div>    <\/span>...<\/span><\/span><\/div> <\/div>end<\/span><\/span><\/div> <\/div>function <\/span>im = findimage<\/span><\/span><\/div>    image_objects = imhandles(imgca);<\/span><\/span><\/div>    <\/span>if <\/span>isempty(image_objects)<\/span><\/span><\/div>        error(<\/span>\"No image object found.\"<\/span>);<\/span><\/span><\/div>    <\/span>end<\/span><\/span><\/div>    im = image_objects(1);<\/span><\/span><\/div>end<\/span><\/span><\/div><\/div>The first interesting piece here is the use of the <\/span>arguments<\/span> block, a MATLAB language syntax that was introduced in R2019b. The <\/span>arguments<\/span> block<\/span><\/a>, and more generally the <\/span>function argument validation<\/span><\/a> features, helps to implement function behavior with helpful error messages and useful defaults while writing very little code.<\/span><\/div>Let's look more closely at the beginning of the function.<\/span><\/div>function <\/span>out = imageSizeInXY(im)<\/span><\/span><\/div>    <\/span>arguments<\/span><\/span><\/div>        im <\/span>(1,1) matlab.graphics.primitive.Image <\/span>= findimage<\/span><\/span><\/div>    <\/span>end<\/span><\/span><\/div><\/div>The <\/span>arguments<\/span> block lets us specify constraints and default behavior for the function's input arguments. The \"<\/span>(1,1)<\/span>\" part says that the input argument, <\/span>im<\/span>, must have size <\/span>$1 \\times 1$<\/span>. In other words, it must be a scalar. The next part, \"<\/span>matlab.graphics.primitive.Image<\/span>,\" indicates that <\/span>im<\/span> is required to be that class (or convertible to it).<\/span><\/div>MATLAB will enforce these size and type constraints automatically, issuing specific error messages if they are not met.<\/span><\/div><\/img><\/div>Note that you can get the full class name of MATLAB graphics objects by calling <\/span>class<\/span>:<\/span><\/div>class(im)<\/span><\/span><\/div>ans = <\/span>'matlab.graphics.primitive.Image'<\/div><\/div><\/div><\/div><\/div><\/div>The \"<\/span>= findimage<\/span>\" portion is used to automatically provide a default value for the input <\/span>im<\/span>. This can be a constant value or an expression. In this case, <\/span>findimage<\/span> is an expression that calls the local function that I have written:<\/span><\/div>function <\/span>im = findimage<\/span><\/span><\/div>    image_objects = imhandles(imgca);<\/span><\/span><\/div>    <\/span>if <\/span>isempty(image_objects)<\/span><\/span><\/div>        error(<\/span>\"No image object found.\"<\/span>);<\/span><\/span><\/div>    <\/span>end<\/span><\/span><\/div>    im = image_objects(1);<\/span><\/span><\/div>end<\/span><\/span><\/div><\/div>The functions <\/span>imgca<\/span> and <\/span>imhandles<\/span> are Image Processing Toolbox utilities. The function <\/span>imgca<\/span> returns the most recently current <\/span>axes<\/span> object containing one or more images, and <\/span>imhandles<\/span> returns the <\/span>image<\/span> objects within it.<\/span><\/div>The last few lines are just me being careful to handle the cases where there are no <\/span>image<\/span> objects to be found, or where there are multiple <\/span>image<\/span> objects in the <\/span>axes<\/span>.<\/span><\/div>The full implementation, including the simple size calculation, is below.<\/span><\/div>function <\/span>out = imageSizeInXY(im)<\/span><\/span><\/div>    <\/span>arguments<\/span><\/span><\/div>        im <\/span>(1,1) matlab.graphics.primitive.Image <\/span>= findimage<\/span><\/span><\/div>    <\/span>end<\/span><\/span><\/div> <\/div>    pixel_width = extent(im.XData,size(im.CData,2));<\/span><\/span><\/div>    pixel_height = extent(im.YData,size(im.CData,1));<\/span><\/span><\/div> <\/div>    x1 = im.XData(1) - (pixel_width \/ 2);<\/span><\/span><\/div>    x2 = im.XData(end) + (pixel_width \/ 2);<\/span><\/span><\/div> <\/div>    y1 = im.YData(1) - (pixel_height \/ 2);<\/span><\/span><\/div>    y2 = im.YData(end) + (pixel_height \/ 2);<\/span><\/span><\/div> <\/div>    out = [(x2 - x1) (y2 - y1)];<\/span><\/span><\/div>end<\/span><\/span><\/div> <\/div>function <\/span>im = findimage<\/span><\/span><\/div>    image_objects = imhandles(imgca);<\/span><\/span><\/div>    <\/span>if <\/span>isempty(image_objects)<\/span><\/span><\/div>        error(<\/span>\"No image object found.\"<\/span>);<\/span><\/span><\/div>    <\/span>end<\/span><\/span><\/div>    im = image_objects(1);<\/span><\/span><\/div>end<\/span><\/span><\/div> <\/div>function <\/span>e = extent(data,num_pixels)<\/span><\/span><\/div>    <\/span>if <\/span>(num_pixels <= 1)<\/span><\/span><\/div>        e = 1;<\/span><\/span><\/div>    <\/span>else<\/span><\/span><\/div>        e = (data(2) - data(1)) \/ (num_pixels - 1);<\/span><\/span><\/div>    <\/span>end<\/span><\/span><\/div>end<\/span><\/span><\/div><\/div>Now I don't have to remember to call <\/span>imshow<\/span> with an output argument in order to use it.<\/span><\/div>If you haven't already explored using function argument validation and <\/span>arguments<\/span> blocks for writing your own MATLAB functions, I encourage you to give them a try. It's really worth it!<\/span><\/div>\r\n