--- title: NSImage framework: appkit role: symbol role_heading: Class path: appkit/nsimage --- # NSImage A high-level interface for manipulating image data. ## Declaration ```swift class NSImage ``` ## Overview Overview You use instances of NSImage to load existing images, create new images, and draw the resulting image data into your views. Although you use this class predominantly for image-related operations, the class itself knows little about the underlying image data. Instead, it works in conjunction with one or more image representation objects (subclasses of NSImageRep) to manage and render the image data. For the most part, these interactions are transparent. The class serves many purposes, providing support for the following tasks: Loading images stored on disk or at a specified URL. Drawing images into a view or graphics context. Providing the contents of a CALayer object. Creating new images based on a series of captured drawing commands. Producing versions of the image in a different format. The NSImage class itself is capable of managing image data in a variety of formats. The specific list of formats is dependent on the version of the operating system but includes many standard formats such as TIFF, JPEG, GIF, PNG, and PDF among others. AppKit manages each format using a specific type of image representation object, whose job is to manage the actual image data. You can get a list of supported formats using the methods described in Determining Supported Types of Images. Using Images with Core Animation Layers Although you can assign an NSImage object directly to the contents property of a CALayer object, doing so may not always yield the best results. Instead of using your image object, you can use the layerContents(forContentsScale:) method to obtain an object that you can use for your layer’s contents. The image created by that method serves as the contents of a layer, which also supports all of the layer’s gravity modes. By contrast, the NSImage class supports only the resize, resizeAspect, and resizeAspectFill modes. Before calling the layerContents(forContentsScale:) method, use the recommendedLayerContentsScale(_:) method to get the recommended scale factor for the resulting image. The code listing below shows a typical example that uses the scale factor of a window’s backing store as the desired scale factor. From that scale factor, the code gets the scale factor for the specified image object and creates an object that you assign to the layer. You might use this code for images that fit the layer bounds precisely or for which you rely on the contentsGravity property of the layer to position or scale the image. Listing 1. Assigning an image to a layer static void updateLayerWithImageInWindow1(NSImage *image, CALayer *layer, NSWindow *window) { CGFloat desiredScaleFactor = [window backingScaleFactor]; CGFloat actualScaleFactor = [image recommendedLayerContentsScale:desiredScaleFactor]; id layerContents = [image layerContentsForContentsScale:actualScaleFactor]; [layer setContents:layerContents]; [layer setContentsScale:actualScaleFactor]; } ## Topics ### Creating Images by Name - [Configuring and displaying symbol images in your UI](uikit/configuring-and-displaying-symbol-images-in-your-ui.md) - [init(named:)](appkit/nsimage/init(named:).md) - [init(systemSymbolName:accessibilityDescription:)](appkit/nsimage/init(systemsymbolname:accessibilitydescription:).md) - [init(systemSymbolName:variableValue:accessibilityDescription:)](appkit/nsimage/init(systemsymbolname:variablevalue:accessibilitydescription:).md) - [init(symbolName:variableValue:)](appkit/nsimage/init(symbolname:variablevalue:).md) - [init(symbolName:bundle:variableValue:)](appkit/nsimage/init(symbolname:bundle:variablevalue:).md) - [init(resource:)](appkit/nsimage/init(resource:).md) - [setName(_:)](appkit/nsimage/setname(_:).md) - [name()](appkit/nsimage/name().md) - [NSImage.Name](appkit/nsimage/name-swift.typealias.md) - [init(imageLiteralResourceName:)](appkit/nsimage/init(imageliteralresourcename:).md) ### Creating Dynamically Drawn Images - [init(size:flipped:drawingHandler:)](appkit/nsimage/init(size:flipped:drawinghandler:).md) ### Creating Images from Resource Files - [init(byReferencingFile:)](appkit/nsimage/init(byreferencingfile:).md) - [init(byReferencing:)](appkit/nsimage/init(byreferencing:).md) - [init(contentsOfFile:)](appkit/nsimage/init(contentsoffile:).md) - [init(contentsOf:)](appkit/nsimage/init(contentsof:).md) ### Creating Images from Existing Data - [init(data:)](appkit/nsimage/init(data:).md) - [init(dataIgnoringOrientation:)](appkit/nsimage/init(dataignoringorientation:).md) - [init(cgImage:size:)](appkit/nsimage/init(cgimage:size:)-8oznv.md) - [init(pasteboard:)](appkit/nsimage/init(pasteboard:).md) - [init(coder:)](appkit/nsimage/init(coder:).md) ### Creating Empty Images - [init(size:)](appkit/nsimage/init(size:).md) ### Creating Symbol Images - [withSymbolConfiguration(_:)](appkit/nsimage/withsymbolconfiguration(_:).md) - [NSImage.SymbolConfiguration](appkit/nsimage/symbolconfiguration-swift.class.md) ### Getting the Symbol Image Configuration - [symbolConfiguration](appkit/nsimage/symbolconfiguration-swift.property.md) ### Managing Loading and Drawing of Images - [delegate](appkit/nsimage/delegate.md) - [NSImageDelegate](appkit/nsimagedelegate.md) ### Setting Attributes of Images - [size](appkit/nsimage/size.md) - [isTemplate](appkit/nsimage/istemplate.md) - [isTemplate](appkit/nsimage/istemplate.md) ### Determining Supported Types of Images - [canInit(with:)](appkit/nsimage/caninit(with:).md) - [imageTypes](appkit/nsimage/imagetypes.md) - [imageUnfilteredTypes](appkit/nsimage/imageunfilteredtypes.md) ### Working with Representations of Images - [addRepresentation(_:)](appkit/nsimage/addrepresentation(_:).md) - [addRepresentations(_:)](appkit/nsimage/addrepresentations(_:).md) - [representations](appkit/nsimage/representations.md) - [removeRepresentation(_:)](appkit/nsimage/removerepresentation(_:).md) - [bestRepresentation(for:context:hints:)](appkit/nsimage/bestrepresentation(for:context:hints:).md) - [NSImageRep.HintKey](appkit/nsimagerep/hintkey.md) - [NSImage.LayoutDirection](appkit/nsimage/layoutdirection.md) ### Setting the Representation Selection Criteria for Images - [prefersColorMatch](appkit/nsimage/preferscolormatch.md) - [usesEPSOnResolutionMismatch](appkit/nsimage/usesepsonresolutionmismatch.md) - [matchesOnMultipleResolution](appkit/nsimage/matchesonmultipleresolution.md) ### Drawing Images - [draw(in:)](appkit/nsimage/draw(in:).md) - [draw(at:from:operation:fraction:)](appkit/nsimage/draw(at:from:operation:fraction:).md) - [draw(in:from:operation:fraction:)](appkit/nsimage/draw(in:from:operation:fraction:).md) - [draw(in:from:operation:fraction:respectFlipped:hints:)](appkit/nsimage/draw(in:from:operation:fraction:respectflipped:hints:).md) - [drawRepresentation(_:in:)](appkit/nsimage/drawrepresentation(_:in:).md) - [NSCompositingOperation](appkit/nscompositingoperation.md) ### Managing Drawing Options - [isValid](appkit/nsimage/isvalid.md) - [backgroundColor](appkit/nsimage/backgroundcolor.md) - [capInsets](appkit/nsimage/capinsets.md) - [resizingMode](appkit/nsimage/resizingmode-swift.property.md) - [NSImage.ResizingMode](appkit/nsimage/resizingmode-swift.enum.md) ### Working with Alignment Metadata - [alignmentRect](appkit/nsimage/alignmentrect.md) ### Managing Caching Options - [cacheMode](appkit/nsimage/cachemode-swift.property.md) - [recache()](appkit/nsimage/recache().md) - [NSImage.CacheMode](appkit/nsimage/cachemode-swift.enum.md) ### Producing TIFF Data for Images - [tiffRepresentation](appkit/nsimage/tiffrepresentation.md) - [tiffRepresentation(using:factor:)](appkit/nsimage/tiffrepresentation(using:factor:).md) ### Producing Core Graphics Images - [cgImage(forProposedRect:context:hints:)](appkit/nsimage/cgimage(forproposedrect:context:hints:).md) ### Hit-Testing Images - [hitTest(_:withDestinationRect:context:hints:flipped:)](appkit/nsimage/hittest(_:withdestinationrect:context:hints:flipped:).md) ### Managing Image Accessibility - [accessibilityDescription](appkit/nsimage/accessibilitydescription.md) ### Using Images with Core Animation - [layerContents(forContentsScale:)](appkit/nsimage/layercontents(forcontentsscale:).md) - [recommendedLayerContentsScale(_:)](appkit/nsimage/recommendedlayercontentsscale(_:).md) ### Managing Axis Matching - [matchesOnlyOnBestFittingAxis](appkit/nsimage/matchesonlyonbestfittingaxis.md) ### Localizing Images - [withLocale(_:)](appkit/nsimage/withlocale(_:).md) - [locale](appkit/nsimage/locale.md) ### Deprecated - [Deprecated Symbols](appkit/nsimage-deprecated-symbols.md) ### Enumerations - [NSImage.DynamicRange](appkit/nsimage/dynamicrange.md) ### Initializers - [init(CGImage:size:)](appkit/nsimage/init(cgimage:size:)-15zeh.md) - [init(byReferencingURL:)](appkit/nsimage/init(byreferencingurl:).md) - [init(contentsOfURL:)](appkit/nsimage/init(contentsofurl:).md) ### Default Implementations - [NSPasteboardReading Implementations](appkit/nsimage/nspasteboardreading-implementations.md) ## Relationships ### Inherits From - [NSObject](objectivec/nsobject-swift.class.md) ### Conforms To - [AttachableAsImage](testing/attachableasimage.md) - [CVarArg](swift/cvararg.md) - [Copyable](swift/copyable.md) - [CustomDebugStringConvertible](swift/customdebugstringconvertible.md) - [CustomStringConvertible](swift/customstringconvertible.md) - [Equatable](swift/equatable.md) - [Escapable](swift/escapable.md) - [Hashable](swift/hashable.md) - [NSCoding](foundation/nscoding.md) - [NSCopying](foundation/nscopying.md) - [NSItemProviderReading](foundation/nsitemproviderreading.md) - [NSItemProviderWriting](foundation/nsitemproviderwriting.md) - [NSObjectProtocol](objectivec/nsobjectprotocol.md) - [NSPasteboardReading](appkit/nspasteboardreading.md) - [NSPasteboardWriting](appkit/nspasteboardwriting.md) - [NSSecureCoding](foundation/nssecurecoding.md) - [Sendable](swift/sendable.md) - [SendableMetatype](swift/sendablemetatype.md) - [Transferable](coretransferable/transferable.md) ## See Also ### Images - [Providing images for different appearances](uikit/providing-images-for-different-appearances.md) - [Supporting Continuity Camera in Your Mac App](appkit/supporting-continuity-camera-in-your-mac-app.md) - [Supporting HDR images in your app](uikit/supporting-hdr-images-in-your-app.md) - [Applying Apple HDR effect to your photos](appkit/applying-apple-hdr-effect-to-your-photos.md) - [NSImageDelegate](appkit/nsimagedelegate.md) - [NSImageRep](appkit/nsimagerep.md)