Function

CGImageCreateWithImageInRect

Creates a bitmap image using the data contained within a subregion of an existing bitmap image.

Declaration

CGImageRef CGImageCreateWithImageInRect(CGImageRef image, CGRect rect);

Parameters

image

The image from which to extract the subimage.

rect

A rectangle specifying the portion of the image to keep.

Return Value

A CGImageRef object that specifies a subimage of the image. If the rect parameter defines an area that is not in the image, returns NULL.

Discussion

Cropping removes content around the designated rectangle; it cuts out the desired area of the input image and returns an image of the cropped size.

Figure 1

Cropping an image

Butterfly photo with background cropped out

CGImageCreateWithImageInRect performs the following tasks to create the subimage:

  • It calls the CGRectIntegral function to adjust the rect parameter to integral bounds.

  • It intersects the rect with a rectangle whose origin is (0,0) and size is equal to the size of the image specified by the image parameter.

  • It reads the pixels within the resulting rectangle, treating the first pixel within as the origin of the subimage.

If W and H are the width and height of image, respectively, then the point (0,0) corresponds to the first pixel of the image data. The point (W–1, 0) is the last pixel of the first row of the image data, while (0, H–1) is the first pixel of the last row of the image data and (W–1, H–1) is the last pixel of the last row of the image data.

The resulting image retains a reference to the original image, which means you may release the original image after calling this function. In Swift, you do not need to release the original image reference explicitly.

Listing 1

Cropping an image using CGImageCreateWithImageInRect

- (UIImage*) cropImage:(UIImage*)inputImage
                toRect:(CGRect)cropRect
             viewWidth:(CGFloat)viewWidth
            viewHeight:(CGFloat)viewHeight
{
    // viewWidth, viewHeight are dimensions of imageView
    const CGFloat imageViewScale = MAX(inputImage.size.width/_viewWidth, inputImage.size.height/_viewHeight);

    // Scale cropRect to handle images larger than shown-on-screen size
    cropRect.origin.x *= imageViewScale;
    cropRect.origin.y *= imageViewScale;
    cropRect.size.width *= imageViewScale;
    cropRect.size.height *= imageViewScale;
    
    // Perform cropping in Core Graphics
    CGImageRef cutImageRef = CGImageCreateWithImageInRect(inputImage.CGImage, cropRect);
    
    // Convert back to UIImage
    UIImage* croppedImage = [UIImage imageWithCGImage:cutImageRef];
    
    // Clean up reference pointers
    CGImageRelease(cutImageRef);
    
    return croppedImage;
}

If you already use CIImage, or if you are post-processing images as CIImage data in Core Image, such as chaining together multiple filters to the cropped result, it may be more efficient to crop CIImage directly in the Core Image framework using the CICrop filter; in this case, use the convenience function imageByCroppingToRect:.

See Also

Creating Bitmap Images

CGImageCreate

Creates a bitmap image from data supplied by a data provider.

CGImageCreateCopy

Creates a copy of a bitmap image.

CGImageCreateCopyWithColorSpace

Creates a copy of a bitmap image, replacing its colorspace.

CGImageCreateWithJPEGDataProvider

Creates a bitmap image using JPEG-encoded data supplied by a data provider.

CGImageCreateWithPNGDataProvider

Creates a bitmap image using PNG-encoded data supplied by a data provider.

CGImageCreateWithMask

Creates a bitmap image from an existing image and an image mask.

CGImageCreateWithMaskingColors

Creates a bitmap image by masking an existing bitmap image with the provided color values.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software