Cameras¶

inchesToMm(inchesValue)¶

Converts inches (as a float) to mm

Parameters:: inchesValue (float) – value in inches
Returns:: mmValue: value in mm
Return type:: mmValue: float

mmToInches(mmValue)¶

mm to inches (as a float)

Parameters:: mmValue (float) – value in mm
Return inchesValue:: value in inches
Rtype inchesValue:: float

cameraShape(cameraTransform)¶

Returns the camera shape node given the camera transform

Parameters:: cameraTransform (str) – Name of the maya camera transform node
Returns:: Name of the maya camera shape node
Return type:: str

cameraTransform(cameraShape)¶

Returns the camera transform node given the camera shape

Parameters:: cameraShape (str) – Name of the maya camera shape node
Return cameraTransform:: Name of the maya camera transform node
Rtype cameraTransform:: str

cameraShapeList(cameraTransformList)¶

Returns the camera shape node list given a camera transform node list

Parameters:: cameraTransformList (list(str)) – List of maya camera transform node names
Return camShapeList:: List of many camera shape node names
Rtype camShapeList:: list(str)

cameraTransformList(cameraShapeList)¶

Returns the camera transform node list given a camera shape node list

Parameters:: cameraShapeList (list(str)) – List of many camera shape node names
Return cameraTransformList:: List of maya camera transform node names
Rtype cameraTransformList:: list(str)

duplicateCamera(camera)¶

Duplicate Camera

Parameters:: camera –
Returns:: Returns long string
Return type:

createCameraZxy(camName='', message=True)¶

Creates a new Maya camera with the default rotation order set to zxy rather than xyz

Parameters:: message (bool) – Report the message to the user?
Return cameraName:: The name of the camera created [cameraTransform, cameraShape]
Rtype cameraName:: [str, str]

createCameraNodesZxy(camName='', message=True)¶

Creates a new Maya camera with the default rotation order set to zxy rather than xyz

Parameters:: message (bool) – Report the message to the user?
Return cameraName:: The dag nodes of the camera and the cameraShape
Rtype cameraName:: [, str]

lookThrough(cameraTransform)¶

Look through this camera, helper function, use the straight cmds one liner

Parameters:: cameraTransform (str) – A camera transform name

getFocusCamera(prioritizeUnderCursor=True, message=True)¶

returns the camera that is under the cursor, or if error return the camera in the active window (with focus)

Parameters:: message (bool) – report a potential fail message to the user?
Return camera:: The name of the Maya camera transform under the current panel
Rtype camera:: str

getFocusCameraShape(prioritizeUnderCursor=True, message=True)¶

returns the camera shape under the cursor, or if error return the camera in the active window (with focus)

Parameters:: message (bool) – report a potential fail message to the user?
Return cameraShape:: The name of the Maya camera shape under the current panel
Rtype cameraShape:: str

selectCamInView(message=True)¶

Selects the camera under the pointer or if an error, get the camera in active panel, if error return message

Use this on a hotkey

Return camera:: camera transform name that was selected, empty string if None
Rtype camera:: str

filterCameraType(camShapeList, camType='all')¶

from a camera shape list filter out the cameras by type:

CAM_TYPE_ALL = “all” CAM_TYPE_PERSP = “perspective” CAM_TYPE_ORTHOGRAPHIC = “orthographic”

All will return the whole list.

Parameters:

camShapeList (list(str)) – A list of camera shape nodes
camType (str) – Which type to filter, “all”, “perspective” or “orthographic”

Returns:

A list of camera shape nodes now filtered

Return type:

list(str)

cameraTransformsSelected(longName=True)¶

From the selection only return the camera transform nodes as a list, will be an empty list if none.

Parameters:: longName (bool) – Forces long names rather than unique names if False
Return camTransformList:: camera transform nodes as a list of names, will be empty list if None in selection
Rtype camTransformList:: list(str)

cameraShapesSelected(longName=True)¶

From the selection only return the camera shape nodes as a list, will be an empty list if none.

Parameters:: longName (bool) – Forces long names rather than unique names if False
Return camShapeList:: camera shape nodes as a list of names, will be empty list if None in selection
Rtype camShapeList:: list(str)

cameraShapesAll(longName=True)¶

Returns all camera shapes in the whole scene

Parameters:: longName (bool) – Forces long names rather than unique names if False
Return camShapeList:: all camera shape names in the scene
Rtype camShapeList:: list

cameraTransformsAll(camType='all', longname=True)¶

Returns all camera transforms in the whole scene:

CAM_TYPE_ALL = “all” returns all CAM_TYPE_PERSP = “perspective” CAM_TYPE_ORTHOGRAPHIC = “orthographic”

Parameters:: camType (str) – Which type to filter, “all”, “perspective” or “orthographic”
Return camTransformList:: all camera transform names in the scene
Rtype camTransformList:: list[str]

allCamTransformsDag(camType='all')¶

Returns all camera transforms in the whole scene

Same as AllCamTransforms except it returns the dag node

Parameters:: camType –
Returns:
Return type:: list[zoo.libs.maya.zapi.DagNode]

getStartupCamShapes(includeLeftBot=True)¶

Returns all the startup cameras in the scene as shape node name list [“perspShape”, “topShape”, “sideShape”, “frontShape”, “leftShape”, “bottomShape”]

:return List of default maya camera shape nodes, returns long names :rtype: list[str]

camFromCamShape(camShape)¶

Get the camera transform from the camShape

Parameters:: camShape –
Returns:
Return type:

getStartupCamTransforms()¶

Returns all the startup cameras in the scene as transform node name list [“persp”, “top”, “side”, “front”, “left”, “bottom”] returns long names

Return startupCamTransforms:: list of startup (maya default) camera transform names
Rtype startupCamTransforms:: list

getUserCamShapes()¶

Returns all the camera shape nodes in the scene while filtering out the maya default cams returns long names

Return userCamShapes:: list of camera shape node names that aren’t Maya default
Rtype userCamShapes:: list

getUserCamTransforms(camType='all')¶

Returns all the camera transform nodes in the scene while filtering out the maya default cams returns long names:

CAM_TYPE_ALL = “all” returns all CAM_TYPE_PERSP = “perspective” CAM_TYPE_ORTHOGRAPHIC = “orthographic”

Parameters:: camType (str) – Which type to filter, “all”, “perspective” or “orthographic”
Return cameraTransformList:: All the camera transforms that aren’t maya default cams
Rtype cameraTransformList:: list

getPerspCameraTransforms()¶: “Returns all camera transforms of the perspective cameras in the scene.

cycleThroughCameras(limitPerspective=True, message=True)¶

Cycles through cameras (lookthru) in the scene

Parameters:

limitPerspective (bool) – If True will ignore orthographic cameras
message (bool) – Report a message to the user

Returns:

Return type:

toggleCamResGate(camShape=None, resGateOnly=True)¶

Toggles the resolution gate On/Off on a cameraShape of if None then auto find the current camera.

If filmgateOnly is False will:

Sets the filmFit to “Overscan” Sets the res gate overscan of 1.05 Sets film gate to match resolution gate Opacity is set to 50 percent grey

Parameters:

camShape (str) – The cameraShape node to toggle
resGateOnly (bool) – Will only toggle the film gate

Returns:

Returns if it was turned on or off

resolutionGate(camShape)¶

Gets the resolution gate of the camera shape and returns it as a boolean

Parameters:: camShape –
Returns:
Return type:

filmGate(camShape)¶

Shows the film gate display True or False (1 or 0)

Parameters:: camShape (str) – A maya camShape node
Return value:: Shows the film gate display True or False (1 or 0)
Rtype value:: bool

gateMask(camShape)¶

Gets the gate display

Parameters:: camShape (str) – A maya camShape node
Return gateMaskValue:: Shows the gate display True or False (1 or 0)
Rtype gateMaskValue:: bool

setCamResGate(camShape, on=True, resGateOnly=True, message=True)¶

Sets camera resolution gate visibility

Parameters:

camShape (str) – A maya camera shape node
on (bool) – True sets the resolution gate on
resGateOnly (bool) – Only sets the resGate, does not set the Zoo defaults
message (bool) – Report a message to the user?

toggleOverscan()¶: Toggles the camera overscan attribute of the camera between 1 and 1.05

setCurrCamClipPlanes(nearClip, farClip)¶

Sets the Near and Far clip planes on the current camera

Parameters:

nearClip (float) – The near clip plane for the camera
farClip (float) – The far clip plane for the camera

createZooApertureAttrs(camShape)¶

Adds the custom attributes “zooApertureWidthInches” and “zooApertureHeightInches” and set their values from the Maya camera settings.

The attrs are used to store and measure the film gate size (camera sensor size) by zoo tools which will override Maya’s settings.

Parameters:: camShape (str) – The name of the camera’s shape node
Returns:: inchesWidth: value in inches
Return type:: inchesWidth: float
Returns:: inchesHeight: value in inches
Return type:: inchesHeight: float

matchResolutionFilmGate(camShape, fitResGate=3, getZooGate=True, matchGates=True)¶

Automatically sets the aspect ratio of the camera to the render globals by doing the math on verticalFilmAperture and horizontalFilmAperture.

Parameters:

camShape (str) – The name of the camera’s shape node
fitResGate (int) – Sets the Fit Resolution Gate setting, usually to “overscan”

setZooResolutionGate(camShape, resolutionGate=True, overscan=1.05, matchResGateRatios=True, gateMaskOpacity=0.5, affectGateMask=True, fitResGate=3)¶

Sets resolution gate with default Zoo settings:

overscan

gateMaskOpacity

matchResGateRatios

gateMaskOpacity

fitResGate

Parameters:

camShape (str) – A maya camShape node
resolutionGate (bool) – Show the resolution in the window or not
overscan (float) – Space between the resolution gate and the window.
matchResGateRatios – Automatically sets the camera’s film back to match the resolution
gateMaskOpacity (float) – The opacity of the mask around the camera if a mask is on
affectGateMask (float) – If True set the gateMaskOpacity

matchResolutionInsideFilmGate(camShape, resolutionWidth, resolutionHeight, resRatio, gateWidth, gateHeight, gateRatio)¶

Takes into consideration the camera’s sensor (film gate) settings in mm and automatically fits the resolution to fit inside of the sensor aspect ratio

Parameters:

camShape (str) – The camera shape name
resolutionWidth (float) – The scene resolution width
resolutionHeight (float) – The scene resolution height
resRatio (float) – The aspect ratio width/height of the resolution Eg. 1.7777
gateWidth (float) – The current film gate width
gateHeight (float) – The current film gate height
gateRatio (float) – The aspect ratio width/height of the film gate Eg. 1.7777

matchCamFilmBackRatio(camShape, ratio, keepVerticalSensorSize=False, useZooGate=True)¶

Matches the aspect ratio of the film gate to the scene resolution ratio

Sets horizontalFilmAperture or verticalFilmAperture (width height)

If useZooGate:

Will use the Zoo Tools stored attributes instead of Maya’s default to do all the calculations Zoo messes with Maya’s sensor size, so it needs to stores and query it separately

Parameters:

camShape (str) – A maya camShape node
ratio (float) – The aspect ratio width/height of the camera Eg. 1.7777
keepVerticalSensorSize (float) – The vertical height sensor size of the camera is kept, otherwise horizontal
useZooGate (float) – The vertical height sensor size of the camera is kept, otherwise horizontal

unmatchCamFilmBackRatio(camShape)¶

Unmatches the film gate only after it has been set by zoo tools. Requires Zoo custom attrs on cameras.

Parameters:: camShape (str) – A maya camShape node

zooMatchGateBoolValue(camShape)¶

Returns the value of the Zoo Aperture Boolean, a custom attribute that tracks the Match Gate state.

Parameters:: camShape (str) – A maya camShape node
Return zooMatchBoolValue:: True if the cams are currently matched, False if not.
Rtype zooMatchBoolValue:: bool

setSensorSizeInches(camShape, width, height, setZooGate=True)¶

Sets the sensor size (film gate) aperture width and height settings,

If setZooGate True:

Checks for the zoo custom attribute ZOO_APERTURE_BOOL if on then sets with matchResolutionFilmGate(camShape)

Parameters:

camShape (str) – A maya camShape node
width (float) – The width of the sensor size (film gate) in inches
height (float) – The height of the sensor size (film gate) in inches
setZooGate (bool) – If True will set with the Match Gate Zoo custom attributes

setSensorSizeMm(camShape, width, height, setZooGate=True)¶

Sets the sensor size (film gate) aperture width and height settings,

If setZooGate True:

Checks for the zoo custom attribute ZOO_APERTURE_BOOL if on then sets with matchResolutionFilmGate(camShape)

Parameters:

camShape (str) – A maya camShape node
width (float) – The width of the sensor size (film gate) in mm
height (float) – The height of the sensor size (film gate) in mm
setZooGate (bool) – If True will set with the Match Gate Zoo custom attributes

setCamResolutionGate(camShape, resolutionGate)¶

Sets the “resolutionGate” attribute on a camera shape. Show the resolution in the window or not

Parameters:

camShape (str) – A maya camShape node
resolutionGate (bool) – Show the resolution in the window or not

setCamFilmGate(camShape, value)¶

Shows the film gate display True or False (1 or 0)

Parameters:

camShape (str) – A maya camShape node
value (bool) – Shows the film gate display True or False (1 or 0)

setGateMask(camShape, value)¶

Shows the gate display True or False (1 or 0)

Parameters:

camShape (str) – A maya camShape node
value (bool) – Shows the gate display True or False (1 or 0)

setCamGateMaskOpacity(camShape, gateMaskOpacity)¶

Sets the “gateMaskOpacity” attribute on a camera shape. The opacity of the mask around the camera if on.

Parameters:

camShape (str) – A maya cameraShape node
gateMaskOpacity (float) – The opacity of the mask around the camera if a mask is on

setCamOverscan(camShape, overscan=1.05)¶

Sets the “Overscan” attribute on a camera shape. Space between the resolution gate and the window.

Parameters:

camShape (str) – A maya cameraShape node
overscan (float) – Space between the resolution gate and the window.

setCamFitResGate(camShape, fitResolutionGate=3)¶

Sets the “Fit Resolution Gate” setting on a camera shape:

CAM_FIT_RES_FILL = 0 CAM_FIT_RES_HORIZONTAL = 1 CAM_FIT_RES_VERTICAL = 2 CAM_FIT_RES_OVERSCAN = 3

Parameters:

camShape (str) – A maya cameraShape node
fitResolutionGate (int) – Integer of the setting to set 0 - 3

setCamClipPlanes(camShape, nearClip, farClip)¶

Sets the Near and Far clip planes on a camera shape node

Parameters:

camShape (str) – A maya cameraShape node
nearClip (float) – The near clip plane for the camera
farClip (float) – The far clip plane for the camera

setCamMaskColor(camShape, srgbFloat=(0.5, 0.5, 0.5))¶

Sets the camera gate mask color in SRGB Float range

Color passed in as SRG and is applied as linear color (Maya takes linear)

Parameters:

camShape (str) – A maya camera shape node name
srgbFloat (tuple(float)) – A SRGB float color in 0 - 1.0 range eg (0.5, 0.5, 0.5)

setPespectiveMode(camShape, perspMode)¶

Parameters:

camShape (basestring) –
perspMode (bool) –

Returns:

Return type:

setFocalLength(camShape, focalLength)¶

sensorSizeInches(camShape, getZooGate=True)¶

Returns the camera shape setting “Camera Aperture (mm)” height and width

If getZooGate:

Use zooTools custom attributes to query the camera’s sensor size (film back), and does not use Maya’s Also creates the custom attributes if they don’t exist

Parameters:

camShape (str) – The name of the camera shape node
getZooGate (str) – If the Zoo Tools custom attributes exist will use those values, if not will create/set attrs

Return widthInches:

Height in mm value

Rtype widthInches:

float

Return heightInches:

Width in mm value

Rtype heightInches:

float

sensorSizeMm(camShape, getZooGate=True)¶: See documentation for sensorSizeInches() only returns in mm instead of inches

calculateResSize(resolutionWidth, resolutionHeight, sensorWidth, sensorHeight, fitWidth=True)¶

Parameters:

resolutionWidth –
resolutionHeight –
sensorWidth –
sensorHeight –
fitWidth –

Returns:

Return type:

resolutionSizeInches(camShape, getZooGate=True)¶

Calculates the cropped sensor size, or the actual resolution (rendered) sensor size in inches.

This is only a read/get function there is no set equivalent.

Parameters:

camShape (str) – The name of the camera shape node
getZooGate (str) – If the Zoo Tools custom attributes exist will use those values, if not will create/set attrs

Return width:

The resolution width in inches

Rtype width:

float

Return height:

The resolution height in inches

Rtype height:

float

resolutionSizeMm(camShape, getZooGate=True)¶: See documentation for resolutionSizeInches() only returns in mm instead of inches

camClipPlanes(camShape)¶

Get the camClipPlanes and

Parameters:: camShape (basestring) – Cam shape as long name
Return camClipPlanes:: The near and far clip planes as floats
Rtype camClipPlanes:: tuple [float, float]

camFitResGate(camShape)¶

Get the fit resolution attribute value as an index

Parameters:: camShape (basestring) – Cam shape as long name
Return filmFitValue:: The value of the Fit Resolution Gate combo box in the attr editor
Rtype filmFitValue:: int

focalLength(camShape)¶

Get the focal length of the camShape

Parameters:: camShape (basestring) – Cam shape as long name
Return focalLength:: The focal length of the current camera
Rtype focalLength:: float

isPerspective(camShape)¶

Returns if camShape is perspective or orthographic. Perspective if true, false if ortho

Parameters:: camShape (basestring) – Cam shape as long name
Return isPerspective:: True if the cmaera is a perspective cam, False if Orthographic
Rtype isPerspective:: bool

maskOpacity(camShape)¶

Get the mask opacity from the cam shape

Parameters:: camShape (basestring) – Cam shape as long name
Return maskOpacity:: The opacity of the mask
Rtype maskOpacity:: float

overscan(camShape)¶

Get overscan of cam shape

Parameters:: camShape (basestring) – Cam shape as long name
Return overscan:: The amount of mask overscan on the camera
Rtype overscan:: float

camMaskColor(camShape)¶

Get Mask Color from cam shape

Parameters:: camShape (basestring) – Cam shape as long name
Return camMaskColor:: The color of the mask in linear float (0.3, 1.0, 0.0) etc
Rtype camMaskColor:: list(float)

renderGlobalsWidthHeight()¶

Returns the width and height of the render globals

Return width:: The height of the render settings in pixels
Return type:: int
Return height:: The width of the render settings in pixels
Return type:: int
Return ratio:: The ratio of the camera width/height Eg. 1.77
Return type:: float

setGlobalsWidthHeight(width, height, matchCurrentCam=False, fitResGate=3, updateAllMatchedCams=True, message=True)¶

Sets the width and height of the render globals

Optional sets the aspect ratio of the camera film back of the current camera

Return width:

The height of the render settings in pixels

Return type:

int

Return height:

The width of the render settings in pixels

Return type:

int

Parameters:

matchCurrentCam (bool) – Change the ratio of the current camera?
message (bool) – Report the message to the user?

openTearOffCam(camera='persp', width=450, height=400)¶

Opens a tear off window looking through the designated camera. Checks the scene to see if the camera exists.

Parameters:

camera (str) – The name of the camera transform node
width (int) – The width of the window to open in pixels
height (int) – The height of the window to open in pixels

setDefaultDisplayAndCameras(focalLength=80, antiAlias=True, ambientOcclusion=True, adjustAspect=-1, nearClip=0.9, farClip=5000)¶

Sets all perspective cameras to 80mm lens and matches the aspect ration of the camera filmback, also adjusts clipping planes to medium values and turns on AO and antialiasing on in the viewport.

Parameters:

focalLength (float) – Set the focal length to all persp cameras to this value, if zero or None will skip
antiAlias (bool) – Turns anti aliasing on or off
ambientOcclusion (bool) – Turns viewport ambient occlusion on or off
adjustAspect (bool) – Automatically sets the aspect ratio of the camera to the render globals.
nearClip (float) – The near clip plane of all perspective cams, if zero or None will skip setting the clip planes
farClip (float) – The far clip plane of all perspective cams, if zero or None will skip setting the clip planes

nodeLocked(name)¶

Focuspuller¶

deleteCameraFocusAttrs(cameraTransform)¶

Removes attributes in case they already exist on a focus puller camera.

Parameters:: cameraTransform (str) – A maya camera name

focusDistanceConnected(camera_name)¶

Checks to see if the focusDistance attribute has keys or connections

Parameters:: camera_name (str) – Transform name of a maya camera
Return isConnected:: True if the focusDistance attr of the shape node is connected.
Rtype isConnected:: bool

buildSetup(camera_name)¶

Parameters:: camera_name (str) – The Camera that will used
Returns:
Return type:: dict

onlyZTranslate(point_constraint, plane_ctrl, visible=True)¶

Hides all attrs on the plane control except for translateZ and visibility.

Parameters:

point_constraint (str) – The point constraint between the camera and the plane control group
plane_ctrl (str) – The plane control
visible (bool) – Are the controls visible

Returns:

Return type:

gettingShape(camera_name)¶: Returning the Camera shape node :param camera_name: the camera name :type camera_name: str :return: camera shape node :rtype: str

setDepthOfField(camera_name, plane_ctrl)¶

Parameters:

camera_name (str) – The camera name
plane_ctrl (str) – the plane control name

Returns:

multiply divide node

Return type:

node

creatingObjPlane(focusPlane, focusPlaneGrp)¶

Creates the grid plane object

Parameters:

focusPlane (str) – The focus plane control
focusPlaneGrp (str) – The focus plane control’s group

Return objPlane_name:

The grid plane’s transform node

Rtype objPlane_name:

str

triggerSelection(triggerName, selectName)¶

Imageplanes¶

findLayer(layerName, matchAnyPartOfName=True)¶

Returns a list of layer names that match layerName

If matchAnyPartOfName the search will look for layerName

Parameters:

layerName (str) – The name of the layer to return, if found in the scene
matchAnyPartOfName (bool) – if True the search will look for layerName

Return layers:

A list of layers found, or epty list if not found

Rtype layers:

list

setLayerVisibility(layerName, value, matchAnyPartOfName=True)¶

Sets the visibility value of the given layer

Parameters:

layerName (str) – The name of the Maya layer
value (bool) – True the layer is visible False is hidden
matchAnyPartOfName (bool) – if True the search will look for layerName

toggleLayerVis(layerName, matchAnyPartOfName=True, message=True)¶

Toggles the visibility of a Maya Layer

Parameters:

layerName (str) – The name of the Maya layer
matchAnyPartOfName – if True the search will look for layerName
message (bool) – Report the message to the user?

Return layers:

A list of layers found, or epty list if not found

Rtype layers:

list

toggleLayerReference(layerName, matchAnyPartOfName=True, message=True)¶

Toggles the Reference state of a Maya Layer

Parameters:

layerName (str) – The name of the Maya layer
matchAnyPartOfName (bool) – if True the search will look for layerName
message (bool) – Report the message to the user?

Return layers:

A list of layers found, or epty list if not found

Rtype layers:

list

toggleVisImagePlaneLayer(matchAnyPartOfName=True, message=True)¶: Auto function that toggles the layer named IMAGE_PLANE_LYR, see toggleLayerVis() for documentation

toggleRefImagePlaneLayer(matchAnyPartOfName=True, message=True)¶: Auto function that toggles the layer named IMAGE_PLANE_LYR, see toggleLayerReference() for documentation

getImagePlaneTransform(imagePlaneShape)¶

Returns the transform of an image plane

Parameters:: imagePlaneShape (str) – Name of an image plane shape node
Return imagePlaneTransform:: Name of the image plane’s transform node
Rtype imagePlaneTransform:: str

getImagePlaneShape(imagePlaneTransform)¶

Returns the shape of an image plane

Parameters:: imagePlaneTransform (str) – Name of a image plane transform node
Return imagePlaneShape:: Name of the image plane’s shape node
Rtype imagePlaneShape:: str

getImagePlaneAttrs(imagePlaneShape)¶

Returns a dictionary of all the image place major attribute values as found in IP_FLOAT_ATTRS and “imageName”

Parameters:: imagePlaneShape (str) – Name of the image plane shape node
Return imagePlaneAttrDict:: A dictionary containing the attribute names as keys and their value
Rtype imagePlaneAttrDict:: dict

getImagePlaneAttrsAuto()¶

returns the image plane dictionary of attributes as keys:

IP_FLOAT_ATTRS + [“imageName”]

Return imagePlaneAttrDict:: A dictionary containing the attribute names as keys and their value
Rtype imagePlaneAttrDict:: dict

getImagePlaneAttrsWithScaleAuto(message=True)¶

returns the image plane dictionary of attributes as keys:

IP_FLOAT_ATTRS + [“imageName”] + [“scale”]

The attribute “scale” does not exist on image planes so we do some math to figure it’s value.

Return imagePlaneAttrDict:: A dictionary containing the attribute names as keys and their value
Rtype imagePlaneAttrDict:: dict

setImagePlaneAttrs(iPShape, iPShapeAttrDict)¶

Sets the main attributes of an image plane from a imagePlaneAttrDict.

Attribute names are found in IP_FLOAT_ATTRS and the attribute “imageName”

Parameters:

iPShape (str) – Name of the image plane shape node
iPShapeAttrDict (dict) – A dictionary containing the attribute names as keys and their value

setImagePlaneAttrsAuto(iPShapeAttrDict)¶

Runs setImagePlaneAttrs() while automatically finding the current image plane, if None found then returns None.

Parameters:: iPShapeAttrDict (dict) – A dictionary containing the attribute names as keys and their value

returnSelectedImagePlane(message=True)¶

Returns the image plane shape node name from a selected image plane shape or transform node

Parameters:: message (bool) – Report the message to the user?
Return imagePlane:: image plane shape node name
Rtype imagePlane:: str

imagePlanesConnectedToCamera(camShape)¶

Returns a list of image planes connected to a camera shape node, will be an empty list if None.

Parameters:: camShape (str) – maya camera shape node name
Return imagePlaneList:: list of image planes connected to the camera
Rtype imagePlaneList:: list

autoImagePlaneInfo(message=True)¶

Automatically gets the image plan either:

From the selected image plane (either transform or shape node selection)

From the camera with focus and the first connected image plane

Returns: iPShape, iPTransform, camShape Returns: “”, “”, “” if nothing found

Parameters:: message (bool) – Report the message to the user
Return iPShape:: The name of the image plane shape node
Rtype iPShape:: str
Return iPTransform:: The name of the image plane transform node
Rtype iPTransform:: str
Return camShape:: The name of the camera shape node with focus
Rtype camShape:: str

imagePlaneScaleData(iPShape)¶

calculateDefaultImagePlaneScale(iPShape)¶

Gets the scale values when set to 1.0 will fill the camera.

This function calculates the imagePlaneShape.sizeX and imagePlaneShape.sizeY values returning the imagePlaneShape.scaleX and imagePlaneShape.scaleY values which need to be calculated manually.

The cameraAperture attributes are the camera canvas .horizontalFilmAperture x .verticalFilmAperture Then the image width x height With the both ratios of cameraAperture and imageSizes you can figure the longest image edge that fits the camera. The max image edge will use the corresponding aperture value as it’s default. Then the opposite dimension can be calculated.

Auto calculates the near and far clip planes from the attached camera

Parameters:: iPShape (str) – The name of a maya image plane shape node
Return scaleX:: The value of imagePlaneShape.scaleX if it fits 100%
Rtype scaleX:: float
Return scaleY:: The value of imagePlaneShape.scaleY if it fits 100%
Rtype scaleY:: float

calculateCurrentSingleScale(iPShape)¶: Gets the scale values when set to 1.0 will fill the camera.

moveScaleImagePlane(iPShape, scale, offsetX, offsetY)¶

Moves/scales an image plane

Scale is relative to the longest edge

Parameters:

iPShape (str) – Name of the image plane shape node
scale (float) – Scale is relative to the longest edge 0.0 - 1.0
offsetX (float) – The offset in X units
offsetY (float) – The offset in Y units

moveScaleImagePlaneAuto(scale, offsetX, offsetY)¶

Moves/scales an image plane via selection or the camera with focus

Scale is relative to the longest edge

Parameters:

scale (float) – Scale is relative to the longest edge 0.0 - 1.0
offsetX (float) – The offset in X units
offsetY (float) – The offset in Y units

rotImagePlane(iPShape, rotate)¶

Rotates an image plane shape

Parameters:: rotate (float) – Rotation absolute value in degrees

rotImagePlaneAuto(rotate)¶

Rotates an image plane by automatically finding it via selection or from the focused camera

Parameters:: rotate (float) – Rotation absolute value in degrees

scaleImagePlane(iPShape, scale)¶

scaleImagePlaneAuto(scale, message=True)¶

scales the image plane found automatically via the selection or from the camera with focus

Scale is calculated where 1.0 fits the camera fully.

Parameters:

scale (float) – Scale is calculated where 1.0 fits the camera fully. Absolute value
message (bool) – return the message to the user?

opacityImagePlane(iPShape, alphaGain)¶

opacityImagePlaneAuto(alphaGain, message=True)¶

Sets the alphaGain attr of the image plane found automatically via the selection or from the camera with focus

Parameters:

alphaGain (float) – The opacity (inverse transparency) of the image plane. 1.0 is opaque, 0.0 is transparent
message (bool) – return the message to the user?

offsetXImagePlane(iPShape, offsetX)¶

offsetXImagePlaneAuto(offsetX, message=True)¶

Sets the alphaGain attr of the image plane found automatically via the selection or from the camera with focus

Parameters:

offsetX (float) – The offsetX attr value of the image plane. -.5 is left and +.5 is right
message (bool) – return the message to the user?

offsetYImagePlane(iPShape, offsetY)¶

offsetYImagePlaneAuto(offsetY, message=True)¶

Sets the alphaGain attr of the image plane found automatically via the selection or from the camera with focus

Parameters:

offsetY (float) – The offsetY attr value of the image plane. -0.5 is down and +0.5 is up
message (bool) – return the message to the user?

placeInFrontAuto(message=True, divideDistance=5000)¶

Sets the image plane depth automatically based on the camera, moves it to the front with:

nearDepth + (farDepth / divideDistance)

Parameters:

divideDistance – return
message (bool) – report the message to the user

placeBehindAuto(message=True, divideDistance=100)¶

Sets the image plane depth automatically based on the camera, moves it to the far distance with:

farDepth - (farDepth / divideDistance)

Parameters:

divideDistance – return
message (bool) – report the message to the user

setImagePlaneSettings(offsetX=None, offsetY=None, alphaGain=None, rotate=None, scale=None, message=True, iPShape=None)¶

Same as the other settings except doing it all at once.

Classes should be used, but using this instead for now

Returns:

animateImagePlane(fadeLength=6, minScale=0.4, offsetX=-0.45, offsetY=0.3, message=True)¶

Sets up an animated image plane ready for modelling or sculpting. This is not an image plane sequence

Keys 7 frames:

Frame 1: Image plane is small and top left in frame Frame 2: Image plane is far back, behind the model Frames will then fade from transparent to opaque base on Frame Fades value, default over 6 frames

Parameters:

fadeLength (float) – the amount of frames to fade the opacity of the image up from frame 3 to + fadeLength
minScale (float) – The size of the image plane scaled from the max fit size
offsetX (float) – The pos X offset of the image in x coords when up in the left corn of screen
offsetY (float) – The pos Y offset of the image in x coords when up in the left corn of screen
message (bool) – Report the message to the user?

createImagePlane(camShape='', iPName='', matchToFilmGate=True)¶

Builds an image plane on a cameraShape

camShape can be “” in which imagePlane will not be attached to a camera

Parameters:

camShape (str) – The name of the camera shape node, if “” will not be attached to a camera
iPName (str) – The name of the image plane node to create, if “” then auto build name with Maya defaults

Return iPTransform:

The name of the image plane transform node created

Rtype iPTransform:

str

Return iPShape:

The name of the image plane shape node created

Rtype iPShape:

str

finalizeImagePlaneCreation(addToLayer, iPShape, camShape, moveToFarClip, detachOrthographic)¶

Used in createImagePlaneAuto() and rebuildImagePlane() to finish the image plane build or change:

if addToLayer: adds to a layer

if detachOrthographic: and camShape is an orthographic camera then disconnect it

if moveToFarClip the image plane to the far clip plane

See documentation in createImagePlaneAuto()

createImagePlaneAuto(iPName='', iPPath='', forceCreate=False, message=True, addToLayer='imagePlanes_lyr', moveToFarClip=True, detachOrthographic=True)¶

Creates an image plane if one is not already selected or attached to the current active viewport

forceCreate = True will create a new image plane even if one already exists.

Image planes are created on the current active perspective camera, or if orthographic are disconnected

Parameters:

iPName (str) – The name of the image plane node to create, if “” then auto build name with Maya defaults
iPPath (str) – full path to an image to be assigned or changed on the image plane
forceCreate (bool) – Always create a new image plane, if False will attempt to find existing image plane fist
message (bool) – Report the message to the user?

Return imagePlane:

An image plane shape node name

Rtype imagePlane:

str

rebuildImagePlane(iPShape, iPTransform, imagePath, forceCreate, message, addToLayer, moveToFarClip, detachOrthographic, iPPath)¶

Rebuilds an image plane while keeping the main settings,

To fix bug in 2020.0 only :/ used in createImagePlaneAuto()

See createImagePlaneAuto() for documentation