Go to: Related nodes. Attributes.

Image Plane is an object in the scene that can display images or textures. Each image plane is attached to a specific camera, and provides a background or environment for scenes seen through that camera.

A single camera can have multiple image planes. And a single image plane can be attached to more than one camera.

Image planes can use single image files, a numbered sequence of image files (such as a saved animation), or a movie file, or a texture. Environment maps (such as Env Sky or Env Ball) work particularly well on image planes.

In the table below, important attributes have their names listed in bold in the description column.

Node nameParentsClassificationMFn typeCompatible function sets
imagePlaneshapeauxiliary/camera:imageplane:drawdb/geometry/imagePlanekImagePlanekBase
kNamedObject
kDependencyNode
kDagNode
kShape
kImagePlane

Related nodes

cameraView

Attributes (76)

Attribute quick index omitted (too many attributes to show them all).

Long name (short name)TypeDefaultFlags
alphaGain (ag) double1.0outputinputconnectablestorablekeyable
Alpha Gain is a multiplier that is applied to the alpha value. Increase this to make the semi-transparent areas of the image more opaque. Decrease this to make them more transparent.
alreadyPremult (pre) boolfalseoutputinputconnectablestorable
Indicates whether or not the image plane's stored color has already been premultiplied by its alpha. If it has, then Maya will not re-multiply the two. Note, this flag only affects rendering in the software renderer.
colorManagementConfigFileEnabled (cmcf) boolfalseoutputinputconnectablehidden
Whether the OCIO configuration file is being used or not.
colorManagementConfigFilePath (cmcp) stringTmultiSharedObject::create<TdataString>""outputinputconnectablehidden
The OCIO config file path being used.
colorManagementEnabled (cme) boolfalseoutputinputconnectablehidden
Whether color management is being used or not.
colorSpace (cs) stringTmultiSharedObject::create<TdataString>""outputinputconnectablestorable
The color space name
compositeDepth (cmp) booltrueoutputinputconnectablestorable
Indicates whether or not the image plane's color should be composited into the final image.
coverage (cov) short2-1, -1outputinputconnectablestorable
Coverage controls the amount of the image that will be used in the image plane. This is only used when the Type is set to Image File. The coverage is measured in pixels. You can specify how many horizontal and vertical pixels of the source image will be used. See also Coverage Origin (below).
coverageX (cvx) short0outputinputconnectablestorable
Coverage X: The width in pixels of the area on the source image to be used.
coverageY (cvy) short0outputinputconnectablestorable
Coverage Y: The height in pixels of the area on the source image to be used.
coverageOrigin (co) short20, 0outputinputconnectablestorable
Coverage Origin controls the lower-left-corner of the area of the input image that will be used on the image plane. 0, 0, is the lower-left corner of the image. See also Coverage (above)
coverageOriginX (cox) short0outputinputconnectablestorable
Coverage Origin X: The pixel position of the left edge of the area of the source image to be used.
coverageOriginY (coy) short0outputinputconnectablestorable
Coverage Origin Y: The pixel position of the bottom edge of the area of the source image to be used.
depth (d) distance (double)100cmoutputinputconnectablestorablekeyable
Depth controls the distance of the plane from the camera. This attribute is only meaningful when Locked To Camera is on.
depthBias (dg) distance (double)0.0cmoutputinputconnectablestorable
Offsets the depth buffer by the specified amount. Values are clamped to the near and far clip plane.
depthFile (df) stringfalseoutputinputconnectablestorable
Allows the user to specify a separate file to obtain depth information. Only Maya IFF and EXR files are supported.
depthOversample (osp) boolfalseoutputinputconnectablestorable
Indicates if we should oversample the depth buffer. Users can specify a depth buffer that is larger than the image buffer using the 'depthFile' attribute. Depth files should be integral multiples larger than the width and height of the actual image.
depthScale (ds) double1.0outputinputconnectablestorable
Scales the depth information the z values are multipled by the scale value before rendering. Values are clamped to the near and far clip planes.
displayOnlyIfCurrent (dic) boolfalseoutputinputconnectablestorable
Display Only If Current. If this is turned on, then you will only see the image plane when you are looking through the camera that the plane is attached to.

For example, if you attach an image plane to your perspective camera, and you don't want to see it in your ortho views, turn this attribute ON.

displayMode (dm) enum3outputinputconnectablestorable
Display Mode controls how the image plane will be displayed both in the 3d view, and when rendered. Choices are:
    None: The image plane is not shown.

    Outline: The image plane is displayed as a rectangle with an X through it. (If you render in this mode, the image plane will show up as though it were in RGB mode)

    RGB: The image is displayed. Any alpha channel (transparency) is ignored. If you are displaying an SGI or QuickTime movie file with no alpha channel, you should use this setting.

    RGBA: The image is displayed. The alpha channel controls the transparency of the image. (Areas where the alpha channel are brighter are more opaque)

    Luminance: The image is diplayed in greyscale, like a black-and-white television. Transparency (alpha) is ignored.

    Alpha: The alpha (transparency) channel is displayed as a monochrome image.

fit (f) enum1outputinputconnectablestorable
Fit controls how the image file will be fit into the image plane. If the image file being used has the same aspect ratio as the image plane (determined by the Size attribute), then there is no problem; the image will fit exactly without any squashing or stretching. If the aspect ratios don't match, then this attribute determines which fitting algorithm will be used. Choices are:
    Fill: The image will be made as small as it can while still completely filling the image plane. Whatever excess hangs off the sides or the top and bottom will be cropped. Fill guarantees that the image will completely fill the plane, without being squashed or stretched.

    Best: The image will be made as large as it can be, while still fitting completely within the defined image plane. (Effectively, this is the same as chooing Horizontal or Vertical, whichever one will result in no part of the image being cropped). Best guarantees that you will see the entire image, with no cropping and no squashing or stretching.

    Horizontal: The image is sized so that its horizontal dimension exactly fits the horizontal dimension of the image plane. The image keeps its own aspect ratio. Horizontal fit will crop the top and bottom of the image to make it fit.

    Vertical: The image is sized so that its vertical dimension exactly fits the vertical dimension of the image plane. The image keeps its own aspect ratio. Vertical fit will crop the left and right sides of the image to make it fit.

    To Size: The image is squashed or stretched, forced to fit into the image plane both horizontally and vertically.

frameCache (fc) integer24outputinputconnectablestorable
Specifies how many frames to cache on the image plane node. This attribute is used when you have a sequence of images and want to cache the images when they are read from disk. By default this value is set to 24.
frameExtension (fe) integer1outputinputconnectablestorablekeyable
Frame Extension. This is only used when Use Frame Extension is ON. The frame extension in Image Name is replaced by the number here. Animate this attribute to use a sequence of image files (such as a saved animation) in the image plane.

Example: say you have saved images named "pic.1.iff" up to "pic.99.iff". You want them to show on the image plane between frames 100 and 300 of your animation. To do this:

  • Set Image Name to "pic.1.iff"
  • Turn Frame Extension ON.
  • Go to frame 100. Set Frame Extension to 1. Keyframe it.
  • Go to frame 300. Set Frame Extension to 99. Keyframe it.

Tip: You can also use an expression for this attribute. For example, if you want the frame number of the image to always be the same as the current frame number, then just type "=frame" into the Frame Extension field in the attribute editor.

frameIn (fin) integer-1outputinputconnectablestorablekeyable
Specifies the initial frame of the movie. This is used to clip the movie to a smaller clip. This is taken before the frame offset. This attribute is only used with the movie type format.
frameOffset (fo) integer0outputinputconnectablestorablekeyable
Specifies an offset of the keyed Frame Extension value. This attribute is only meaningful if Use Frame Extension is turned on.
frameOut (fot) integer-1outputinputconnectablestorablekeyable
Specifies the end (last) frame of the movie. This is used to clip the move into a smaller region. A default value of 0 will be replaced on file load to the length of the movie. This attribute is only used with the movie type format.
frameVisibility (fvt) boolfalseoutputinputconnectablestorablekeyable
Frame Visibility. Turn this off if you want to hide the image plane's wireframe.
height (h) distance (double)0.0cmoutputinputconnectablestorablekeyable
Height controls the height of the image plane in world space. This attribute is only meaningful when Locked To Camera is turned off.
ignoreColorSpaceFileRules (ifr) boolfalseoutputinputconnectablestorable
Determines whether the color space attribute should be set when color management color space file rules are run.
imageCenter (ic) double30.0, 0.0, 0.0outputinputconnectablestorable
Center controls the world-space position of the center of the image plane. This attribute is only meaningful when Locked To Camera is turned off.
imageCenterX (icx) distance (double)0.0cmoutputinputconnectablestorablekeyable
X component of Center
imageCenterY (icy) distance (double)0.0cmoutputinputconnectablestorablekeyable
Y component of Center
imageCenterZ (icz) distance (double)0.0cmoutputinputconnectablestorablekeyable
Z component of Center
imageName (imn) stringnullptroutputinputconnectablestorable
Image Name is only used if Type is set to Image File. Set this attribute to the file name of the image to be used in the image plane. If you want to use a sequence of images (such as a saved animation) then set this to the name of the first file in the sequence. (see also Use Frame Extension and Frame Extension).

You can also specify a movie file here. Maya can use SGI movie files using one of these compressions: Uncompressed Video, RLE, RLE24, JPEG, MVC1, or MVC2. Maya can also use QuickTime movie files using one of these compressions: Uncompressed Video, QuickTime Video, QuickTime Animation, or Indeo. If you specify a movie file, you must use the Frame Extension attributes.

lockedToCamera (dlc) booltrueoutputinputconnectablestorable
Locked To Camera. If this is turned on, then the image plane is locked to the camera's position, so that as the camera moves, the image plane moves with it. If this is turned off, the image plane stays in a fixed location, but it still always faces the camera. This is normally turned on.

Tip: Use this attribute to trace images. Attach an image plane to an ortho camera, and load an image into it. Then turn off Locked to Camera. Now you can use tools such as the Maya curve tool to trace what's in the image. You can pan around and zoom in and out as you need to.

lookThroughCamera (ltc) Messagen/aoutputinputconnectable
The current look through camera for free image plane.
maintainRatio (mr) booltrueoutputinputconnectablestorablekeyable
Maintain Ratio. Turn this on if you want to maintain the image's width and height ratio.
maxShadingSamples (msa) integer1outputinputconnectablestorable
Specifies the max number of shading samples can be taken for this surface during rendering.
offset (o) double20.0, 0.0outputinputconnectablestorable
Offset controls how much the center of the image plane is offset from the centre of the viewing frustum of the camera. Offset is always measured in inches on the camera aperture. This attribute is only meaningful when Locked To Camera is on.
offsetX (ox) double0.0outputinputconnectablestorablekeyable
Horizontal component of Offset
offsetY (oy) double0.0outputinputconnectablestorablekeyable
Vertical component of Offset
outputFrameExtension (ofe) integer0outputconnectable
The final frame number used in image loading, the frame number start from 1.
  • Image Sequences : outputFrameExtension = frameExtension + frameOffset
  • Movie Files : outputFrameExtension = clamp(frameExtension, frameIn, frameOut) + aFrameOffset
outputImage (oim) ctypeDatan/aoutputinputhidden
The loaded bitmap from the media file "resolvedFilePath:outputFrameExtension". The bitmap does not contain color or geometry transformations like "rotate", "colorGain" or "colorOffset". These transformations are applied at render time. Data blocks and evaluation cache can hold this shared_ptr with read permission. Only `compute(outputImage)` is the valid writer/producer of this shared_ptr.
outputImageDimensions (oid) long3outputconnectable
(width,height,frames) of the media file "resolvedFilePath". Use this attribute to read the meta data of "resolvedFilePath" instead of loading all the pixels. For invalid files, this attribute will be evaluate to (0,0,0).
outputImageWidth (oiw) integer0outputconnectable
Width of the loaded media file "resolvedFilePath". For invalid files, this attribute will be evaluate to 0.
outputImageHeight (oih) integer0outputconnectable
Height of the loaded media file "resolvedFilePath". For invalid files, this attribute will be evaluate to 0.
outputImageFrames (oif) integer0outputconnectable
Number of frames of the loaded movie file "resolvedFilePath". For single frame image files, this attribute will be evaluate to 1. For invalid files, this attribute will be evaluate to 0.
outputImageFlags (oig) integer0outputconnectable
Misc flags of the loaded media file "resolvedFilePath".
  • bit 0 : if alpha channel is used.
resolvedFilePath (rfp) stringnullptroutputconnectable
The absolute media file path to load.
  • For image sequences, this include the final frame extension number, like "/c/data/image.0001.png".
  • For movie, this is the absolute path pointing to aImageName, like "/c/data/movie.mov".
colorGain (cg) float31.0, 1.0, 1.0outputinputstorable
Color Gain is a multiplier applied to the colors in the image plane. Use this to control the relative brightness of the image.
colorGainR (cgr) float0.0outputinputstorable
The red component of Color Gain
colorGainG (cgg) float0.0outputinputstorable
The green component of Color Gain
colorGainB (cgb) float0.0outputinputstorable
The blue component of Color Gain
colorOffset (cof) float30.0, 0.0, 0.0outputinputstorable
Color Offset is an additive value applied to the colors in the image plane. Increase this to make the whole image uniformly brighter.
colorOffsetR (cor) float0.0outputinputstorable
The red component of Color Offset
colorOffsetG (cog) float0.0outputinputstorable
The green component of Color Offset
colorOffsetB (cob) float0.0outputinputstorable
The blue component of Color Offset
rotate (r) angle (double)0.0degoutputinputconnectablestorable
Rotation of the image plane around the view vector. This attribute is only meaningful when Locked To Camera is on.
separateDepth (sd) boolfalseoutputinputconnectablestorable
Indicates that we should read depth information from the file specified in the 'depthFile' attribute.
shadingSamples (ssa) integer1outputinputconnectablestorable
Specifies the minimum number of shading samples should be taken for this surface during rendering.
shadingSamplesOverride (sso) booltrueoutputinputconnectablestorable
The flag to control if this surface should override global shading sample settings.
size (s) double23.6cm 2.4cmoutputinputconnectablestorable
Size controls the width and height of the image plane. This attribute is only meaningful when Locked To Camera is on.

Note: Size is always measured in inches, so matter what your current units are set to. It is measured on the camera's aperture.

sizeX (sx) double0.0outputinputconnectablestorablekeyable
Size X: Image plane width
sizeY (sy) double0.0outputinputconnectablestorablekeyable
Size Y: Image plane height.
sourceTexture (stx) Messagen/aoutputinputconnectablehidden
Source Texture. If the Type attribute is set to Texture, then this attribute is connected to the texture node used by the image plane. Note that the Texture node must have an attribute named Out Color.
squeezeCorrection (sqc) double1.0outputinputconnectablestorable
Squeeze Correction applies a horizontal scaling to an image. Increase Squeeze Correction to squeeze the image more, and descrease it to spread the image wider.

This can be useful when your background images were scanned in from film that was shot using an anamorphic film format, such as Panavision. Set Squeeze Correction to 0.5, and the compressed film images will be expanded to twice their width.

textureFilter (tf) enum0outputinputconnectablestorable
TextureFilter controls the filter of the image on the Image plane. Allowed values are Nearest(Unfiltered), Bilinear,Mipmap Nearest,Mipmap Linear, Mipmap Bilinear and MipMap Trilinear. Some attributes are not available when using the Texture setting.
type (t) enum0outputinputconnectablestorable
Type controls the source of the image on the Image plane. Allowed values are Image File and Texture. Some attributes are not available when using the Texture setting.
useDepthMap (udm) boolfalseoutputinputconnectablestorable
Determines whether a depth map should be used for this image plane. This is only supported for Maya IFF and EXR image files.
useFrameExtension (ufe) boolfalseoutputinputconnectablestorable
Use Frame Extension. Turn this ON when you are using a sequence of image files (such as a saved animation) for the image plane, or if you are using an SGI or QuickTime movie file. When this is on, the system will substitute the frame number in the Image Name with the number from the Frame Extension attribute (see below).
viewNameStr (vns) stringTmultiSharedObject::create<TdataString>"<N/A>"outputinputconnectablestorable
The view name used for color management.
viewNameUsed (vnu) boolfalseoutputinputconnectablestorable
Enable or not the use of the view name
visibleInReflections (vir) boolfalseoutputinputconnectablestorable
Visible In Reflections. Turn this on if you are doing Ray Tracing, and you want the image plane to sppear in reflected surfaces.
visibleInRefractions (vif) boolfalseoutputinputconnectablestorable
Visible In Refractions. Turn this on if you are doing Ray Tracing, and you want the image plane to sppear when seen through a transparent refractive surface.
width (w) distance (double)0.0cmoutputinputconnectablestorablekeyable
Width controls the width of the image plane in world space. This attribute is only meaningful when Locked To Camera is turned off.
workingSpace (ws) stringTmultiSharedObject::create<TdataString>""outputinputconnectablehidden
Target working space used for color management.