imcrop

Crop image

Syntax

Icropped = imcrop

Icropped = imcrop(I)

Xcropped = imcrop(X,cmap)

___ = imcrop(h)

Icropped = imcrop(I,rect)

Xcropped = imcrop(X,cmap,rect)

___ = imcrop(xref,yref,___)

[___,rectout] = imcrop(___)

[xrefout,yrefout,___] = imcrop(___)

imcrop(___)

Description

Crop Image Interactively

Note

The interactive syntaxes do not support categorical images. For categorical images, you must specify the crop region, rect.

Icropped = imcrop creates an interactive Crop Image tool associated with the grayscale, truecolor, or binary image displayed in the current figure. imcrop returns the cropped image, Icropped.

With this syntax and the other interactive syntaxes, the Crop Image tool blocks the MATLAB^® command line until you complete the operation. For more information about using the Crop Image tool, see Interactive Behavior.

Icropped = imcrop(I) displays the grayscale, truecolor, or binary image I in a figure window and creates an interactive Crop Image tool associated with the image.

Xcropped = imcrop(X,cmap) displays the indexed image X in a figure using the colormap cmap, and creates an interactive Crop Image tool associated with that image. imcrop returns the cropped indexed image, Xcropped, which also has the colormap cmap.

___ = imcrop(h) creates an interactive Crop Image tool associated with the image specified by the handle h.

Crop Image by Specifying Crop Region

Icropped = imcrop(I,rect) crops the image I according to the position and dimensions specified in the crop rectangle rect. The cropped image includes all pixels in the input image that are completely or partially enclosed by the rectangle.

The actual size of the output image does not always correspond exactly with the width and height specified by rect. 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 with spatial (x,y) coordinates (20,20). The lower right corner of the rectangle is the center of the pixel with spatial (x,y) coordinates (60,50). The resulting output image has size 31-by-41 pixels, not 30-by-40 pixels.

Xcropped = imcrop(X,cmap,rect) crops the indexed image X with colormap cmap according to the position and dimensions specified in the crop rectangle rect. imcrop returns the cropped indexed image, Xcropped, which also has the colormap cmap.

___ = imcrop(xref,yref,___) crops the input image using the world coordinate system defined by xref and yref. After the xref and yref input arguments, you can specify the arguments of any syntax that includes an input image I or X.

Specify Additional Output Options

[___,rectout] = imcrop(___) also returns the position of the crop rectangle in rectout. You can use the input arguments of any other syntax.

[xrefout,yrefout,___] = imcrop(___) also returns the image limits of the input image in xrefout and yrefout.

imcrop(___) without output arguments displays the cropped image in a new figure window. This syntax does not support categorical images.

Examples

Crop Image Using Interactive Crop Image Tool

Read image into the workspace.

I = imread('llama.jpg');

Open the Crop Image tool associated with this image. Specify a variable in which to store the cropped image. The example includes the optional return value rect in which imcrop returns the four-element position vector of the rectangle you draw.

[J,rect] = imcrop(I);

When you move the cursor over the image, it changes to a cross-hairs. The Crop Image tool blocks the command line until you complete the operation.

Using the mouse, draw a rectangle over the portion of the image that you want to crop. Perform the crop operation by double-clicking in the crop rectangle or selecting Crop Image on the context menu.

The cropped image appears in the figure window.

The Crop Image tool returns the cropped area in the return variable, J. The variable rect is the four-element position vector describing the crop rectangle you specified. Get information about the returned variables.

whos

  Name        Size                  Bytes  Class     Attributes

  I         876x1314x3            3453192  uint8               
  J         413x483x3              598437  uint8               
  rect        1x4                      32  double              

Crop Image By Specifying Crop Rectangle

Read image into the workspace.

I = imread('circuit.tif');

Crop image, specifying crop rectangle.

I2 = imcrop(I,[75 68 130 112]);

Display original image and cropped image.

subplot(1,2,1)
imshow(I)
title('Original Image')
subplot(1,2,2)
imshow(I2)
title('Cropped Image')

Center Crop Image Using Spatial Referencing Rectangle

Read and display an image.

I = imread('parkavenue.jpg');
imshow(I)

Specify a target window size as a two-element vector of the form [width, height].

targetSize = [300 600];

Create a Rectangle object that specifies the spatial extent of the crop window.

r = centerCropWindow2d(size(I),targetSize);

Crop the image to the spatial extents. Display the cropped region.

J = imcrop(I,r);
imshow(J)

Crop Indexed Image Specifying Crop Rectangle

Load indexed image with its associated map into the workspace.

load trees

Crop indexed image, specifying crop rectangle.

X2 = imcrop(X,map,[30 30 50 75]);

Display original image and cropped image.

subplot(1,2,1)
imshow(X,map)
title('Original Image')
subplot(1,2,2)
imshow(X2,map)
title('Cropped Image')

Input Arguments

I — Image to be cropped

numeric matrix | numeric array | logical matrix | categorical matrix

Image to be cropped, specified as one of the following.

• m-by-n numeric matrix representing a grayscale image

• m-by-n-by-3 numeric array representing a truecolor image

• m-by-n logical matrix representing a binary mask.

• m-by-n categorical matrix representing a label image.

  Note

  For categorical input, you must specify a crop rectangle, rect. The interactive syntaxes do not support categorical input.

When you use an interactive syntax, imcrop calls the imshow function and accepts whatever image classes imshow accepts.

Data Types: single | double | int8 | int16 | uint8 | uint16 | logical | categorical

X — Indexed image to be cropped

matrix of integers

Indexed image to be cropped, specified as a matrix of integers.

Data Types: single | double | int8 | int16 | uint8 | uint16 | logical

cmap — Colormap

c-by-3 numeric matrix

Colormap associated with the indexed image X, specified as a c-by-3 numeric matrix. Each row is a three-element RGB triplet that specifies the red, green, and blue components of a single color of the colormap. Values with data type single or double must be in the range [0, 1].

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

rect — Size and position of crop rectangle

4-element numeric vector | Rectangle object

Size and position of the crop rectangle in spatial coordinates, specified as a 4-element numeric vector of the form [xmin ymin width height] or an images.spatialref.Rectangle object.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

h — Input image

handle

Input image, specified as a handle to a figure, axes, uipanel, or image graphics object. If h is an axes or figure handle, then imcrop uses the first image returned by findobj(H,'Type','image').

xref — Image limits in world coordinates along x-dimension

2-element numeric vector

Image limits in world coordinates along the x-dimension, specified as a 2-element numeric vector of the form [xmin xmax] where xmax is greater than xmin. The value of xref sets the image XData.

yref — Image limits in world coordinates along y-dimension

2-element numeric vector

Image limits in world coordinates along the y-dimension, specified as a 2-element numeric vector of the form [ymin ymax] where ymax is greater than ymin. The value of yref sets the image YData.

Output Arguments

Icropped — Cropped image

numeric array | numeric matrix | logical matrix | categorical matrix

Cropped image, returned as a numeric array, numeric matrix, logical matrix, or categorical matrix.

• If you specify an input image I, then the output image has the same data type as the input image.

• If you do not specify an input image, then the output image generally has the same data type as the input image. However, if the input image has data type int16 or single, then the output image has data type double.

Xcropped — Cropped indexed image

numeric matrix

Cropped indexed image, returned as a numeric matrix.

rectout — Size and position of crop rectangle

4-element numeric vector

Size and position of the crop rectangle, returned as a 4-element numeric vector of the form [xmin ymin width height].

xrefout — Image limits in world coordinates along x-dimension

2-element numeric vector

Image limits in world coordinates along the x-dimension, returned as a 2-element numeric vector of the form [xmin xmax]. If you specify image limits in a world coordinate system using xref, then xrefout is equal to xref. Otherwise, xrefout is equal to the original image XData.

yrefout — Image limits in world coordinates along y-dimension

2-element numeric vector

Image limits in world coordinates along the y-dimension, returned as a 2-element numeric vector of the form [ymin ymax]. If you specify image limits in a world coordinate system using yin, then yrefout is equal to yin. Otherwise, yrefout is equal to the original image YData.

More About

Interactive Behavior

The Crop Image tool is a moveable, resizeable rectangle that you can position over the image and perform the crop operation interactively using the mouse.

When the Crop Image tool is active in a figure, 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. You can also choose Crop Image from the context menu. The figure illustrates the Crop Image tool with the context menu displayed.

Interactive Behavior	Description
Delete 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.
Resize the Crop Image tool.	Select any of the resize handles on the crop rectangle. The pointer changes to a double-headed arrow . Click and drag the mouse to resize the crop rectangle.
Move 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.
Change 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.
Crop 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.
Retrieve 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 4-element position vector ([xmin ymin width height]) to the clipboard.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• imcrop supports the generation of C code (requires MATLAB Coder™). For more information, see Code Generation for Image Processing.

• The interactive syntaxes are not supported, including:

  • Icropped = imcrop

  • Icropped = imcrop(I)

  • Xcropped = imcrop(X,cmap)

  • Icropped = imcrop(h)

• Indexed images are not supported, including the non-interactive syntax Xcropped = imcrop(X,cmap,rect);

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• The interactive syntaxes are not supported, including:

  • Icropped = imcrop

  • Icropped = imcrop(I)

  • Xcropped = imcrop(X,cmap)

  • Icropped = imcrop(h)

• Indexed images are not supported, including the non-interactive syntax Xcropped = imcrop(X,cmap,rect);

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

Usage notes and limitations:

• The interactive syntaxes are not supported, including:

  • Icropped = imcrop

  • Icropped = imcrop(I)

  • Xcropped = imcrop(X,cmap)

  • Icropped = imcrop(h)

For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Usage notes and limitations:

• The interactive syntaxes are not supported, including:

  • Icropped = imcrop

  • Icropped = imcrop(I)

  • Xcropped = imcrop(X,cmap)

  • Icropped = imcrop(h)

• Categorical images are not supported.

For more information, see Image Processing on a GPU.

Version History

Introduced before R2006a

R2021b: Support for thread-based environments

imcrop now supports thread-based environments.

R2021a: Support for GPU acceleration

imcrop now supports GPU acceleration (requires Parallel Computing Toolbox™).