# Image¶

class Draft.Image((object)arg1) → None

The Draft.Image class contains all of Draft’s image-related functionality. It contains two types of functions: Static functions, and Member functions. Static functions can be invoked without an instance (by calling Draft.Image.<function name>), whereas Member functions require to be invoked from an instance of a Draft.Image object (by calling <someImage>.<function name>).

The Static functions are used to create new instances of the Draft.Image class, whereas the Member functions are used to modify pre-existing instances of the Draft.Image. The sample code snippets should clarify this distinction function in case you are unsure.

static Anaglyph((Image)leftImage, (Image)rightImage, (str)anaglyphType) → Image :

Returns an anaglyph of the specified type created from the two left/right input images.

Arguments:

leftImage
A Draft.Image containing the left-eye image.
rightImage
A Draft.Image containing the right-eye image.
anaglyphType
A string value containing the anaglyph type; can be either “LSA” or “PS”.

Usage:

anaglyphImage = Draft.Image.Anaglyph( leftEye, rightEye, "LSA" )

ApplyGamma((Image)self, (float)gamma) → None :

Apply the specified gamma correction to the image.

New in version 1.1.

Arguments:

gamma
A decimal value indicating the gamma that should be applied.

Usage:

someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.ApplyGamma( 2.2 )

Composite((Image)self, (Image)image, (float)left, (float)bottom, (CompositeOperator)operation) → None :

Composites an image with the current image at the given location using the specified compositing operation.

Arguments:

image
A Draft.Image that will be copied from.
left
A float value that denotes how far from the left the composite operation should take place.
bottom
A float value that denotes how far from the bottom the composite operation should take place.
operation
A Draft.CompositeOperator enum value indicating the type of operation to perform.

Usage:

img1 = Draft.Image.CreateImage( 800, 600 )
img1.Composite( img2, 0, 0.33, Draft.CompositeOperator.OverCompositeOp )

CompositeWithAnchor((Image)self, (Image)image, (Anchor)anchor, (CompositeOperator)operation) → None :

Composites an image with the current image using the specified positional anchor to determine the location of the image being composited.

Arguments:

image
A Draft.Image that will be copied from.
anchor
A Draft.Anchor enum value used to determine the location on the current image where Image will be composited.
operation
A Draft.CompositeOperator enum value indicating the type of operation to perform.

Usage:

img1 = Draft.Image.CreateImage( 800, 600 )
compOp = Draft.CompositeOperator.OverCompositeOp
img1.CompositeWithAnchor( img2, Draft.Anchor.NorthWest, compOp )

CompositeWithGravity((Image)self, (Image)image, (PositionalGravity)gravity, (CompositeOperator)operation) → None :

Deprecated since version beta14: Use Draft.Image.CompositeWithAnchor() instead.

Composites an image with the current image using the specified positional gravity to determine the location of the image being composited.

Arguments:

image
A Draft.Image that will be copied from.
gravity
A Draft.PositionalGravity enum value used to determine the location of the image being composited.
operation
A Draft.CompositeOperator enum value indicating the type of operation to perform.

Usage:

img1 = Draft.Image.CreateImage( 800, 600 )
compOp = Draft.CompositeOperator.OverCompositeOp
gravity = Draft.PositionalGravity.NorthWestGravity
img1.CompositeWithGravity( img2, gravity, compOp )

CompositeWithPositionAndAnchor((Image)self, (Image)image, (float)x, (float)y, (Anchor)anchor, (CompositeOperator)operation) → None :

Composites an image with the current image at the given location using the specified compositing operation and positional anchor.

Arguments:

image
A Draft.Image that will be copied from.
x
A float value that denotes how far from the left (as a percentage of the width) to position the anchor for the composite operation.
y
A float value that denotes how far from the bottom (as a percentage of the height) to position the anchor for the composite operation.
anchor
A Draft.Anchor enum value used to determine the location of the image being composited. The anchor specifies which location of the image being composited will be anchored at the location specified by ( x, y ).
operation
A Draft.CompositeOperator enum value indicating the type of operation to perform.

Usage:

img1 = Draft.Image.CreateImage( 800, 600 )
compOp = Draft.CompositeOperator.OverCompositeOp
anchor = Draft.Anchor.NorthWest
img1.CompositeWithPositionAndAnchor( img2, 0, 0.66, anchor, compOp )

CompositeWithPositionAndGravity((Image)self, (Image)image, (float)x, (float)y, (PositionalGravity)gravity, (CompositeOperator)operation) → None :

Deprecated since version beta14: Use Draft.Image.CompositeWithPositionAndAnchor() instead.

Composites an image with the current image at the given location using the specified compositing operation and positional gravity.

Arguments:

image
A Draft.Image that will be copied from.
x
A float value that denotes how far from the left (as a percentage of the width) to position the anchor for the composite operation.
y
A float value that denotes how far from the bottom (as a percentage of the height) to position the anchor for the composite operation.
gravity
A Draft.PositionalGravity enum value used to determine the location on the current image where Image will be composited.
operation
A Draft.CompositeOperator enum value indicating the type of operation to perform.

Usage:

img1 = Draft.Image.CreateImage( 800, 600 )
compOp = Draft.CompositeOperator.OverCompositeOp
gravity = Draft.PositionalGravity.NorthWestGravity
img1.CompositeWithPositionAndGravity( img2, 0, 0.66, gravity, compOp )

Copy((Image)self, (Image)image[, (int)left=0[, (int)bottom=0[, (object)channels=None]]]) → None :

Copy the other image onto self, with the specified offset applied to the bottom left corner of image.

New in version 1.1.

Arguments:

image
A Draft.Image that will be copied from.
left
Optional. An integer number of pixels that denotes how far from the left the image should be offset. (Default is 0.)
bottom
Optional. An integer number of pixels that denotes how far from the bottom the image should be offset. (Default is 0.)
channels
Optional. A list of channels to copy from image to this image, or None. The channels must exist in both images. If None, then both images must have the same channels, and all channels are copied. (Default is all channels.)

Usage:

img1 = Draft.Image.ReadFromFile( "//path/to/some/image.png" )
img1.Copy( img2, channels=['A'] )

static CreateAnnotation((unicode)text, (AnnotationInfo)textInfo) → Image :

Returns a new image consisting of the specified text. The provided Draft.AnnotationInfo object describes the various text parameters. CreateAnnotation also sets the values in the AnnotationInfo object’s Draft.FontTypeMetric property.

Arguments:

text
A string value providing the contents of the annotation.
textInfo
A Draft.AnnotationInfo value providing parameters describing how to draw the text.

Usage:

textInfo = Draft.AnnotationInfo()
textImage = Draft.Image.CreateAnnotation( "Annotation text.", textInfo )


Note

In order to prevent clipping of certain characters in certain fonts, we added a small amount of padding to the left and right edges of the image. The amount added is proportional to the font size, and can be computed using:

math.ceil( 0.16 * textInfo.PointSize )

static CreateImage( (int)width, (int)height [, (list)channels=['R', 'G', 'B', 'A']]) → Image :

Returns a new image of the specified size with the specified channels (RGBA channels by default).

Arguments:

width
An integer value denoting the width of the image to create.
height
An integer value denoting the height of the image to create.
channels
Optional. A list of channels to create in the image. (Defaults to [‘R’, ‘G’, ‘B’, ‘A’].)

Changed in version 1.1: Added the optional channel parameter.

Usage:

newImage = Draft.Image.CreateImage( 800, 600 )

Crop((Image)self, (int)left, (int)bottom, (int)right, (int)top) → None :

Crops the image to the given bounds.

Arguments:

left
An integer value denoting the left bound of the crop.
bottom
An integer value denoting the bottom bound of the crop.
right
An integer value denoting the right bound of the crop.
top
An integer value denoting the top bound of the crop.

Usage:

someImage = Draft.Image.CreateImage( 800, 600 )
someImage.Crop( 100, 150, 200, 250 )

GetChannelNames((Image)self) → list :

Get a list of all the channels in the image.

New in version 1.1.

Arguments: (none)

Usage:

image = Draft.Image.ReadFromFile( 'image.png' )
channelNames = image.GetChannelNames()

GetFileChannelMap((Image)self) → dict :

Return a dictionary representing the image’s file channel map. Each dictionary entry is made of two strings separated by a colon. The first string corresponds to the channel name, typically ‘R’, ‘G’, ‘B’ and ‘A’, and the second string corresponds to the channel bit depth. An ‘ui’ is appended to the bit depth string to specify that the channel represents an index, and an ‘f’ to specify that the channel is of type float.

New in version 1.5.

Arguments: (none)

Usage:

someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.exr" )
fileChannelMap = someImage.GetFileChannelMap()

HasChannel((Image)self, (str)channel) → bool :

Determine whether a channel exists in the image. Returns True if the image has channel, and False otherwise.

New in version 1.1.

Arguments:

channel
The name of the channel to check for.

Usage:

image = Draft.Image.ReadFromFile( 'image.png' )
if image.HasChannel( 'A' ):
print 'image has an alpha channel'
else:
print 'image does not have an alpha channel'

Premultiply((Image)self) → None :

Premultiply the image’s R, G, and B channels by the A (alpha) channel. The image is modified in-place.

Arguments: (none)

Usage:

someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.Premultiply()

static ReadFromFile((unicode)filename[, (ImageInfo)imageInfo=<Draft.ImageInfo object at 0x0000000005A33308>]) → Image :

Returns a new image from a file on disk. Supports various image types determined by file extension.

Arguments:

filename
A string value indicating where on the machine to find the image file.
imageInfo
Optional. A Draft.ImageInfo that will be populated with properties from the image file.

Changed in version 1.1: Added the optional imageInfo parameter.

Usage:

imageFromFile = Draft.Image.ReadFromFile( "//path/to/image/file.png" )

RemoveChannel((Image)self, (str)channel) → None :

Remove an existing channel from the image.

New in version 1.1.

Arguments:

channel
The channel to set. Typical channels are ‘R’, ‘G’, ‘B’, and ‘A’.

Usage:

someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
if someImage.HasChannel( 'A' ):
someImage.RemoveChannel( 'A' )

RenameChannel((Image)self, (str)oldChannel, (str)newChannel) → None :

Rename the existing specified channel in the image.

New in version 1.1.

Arguments:

oldChannel
The name of the existing channel to copy from.
newChannel
The name of the new channel to copy to. This channel must not exist in the image.

Usage:

image = Draft.Image.ReadFromFile( 'stereo.exr' )
image.RemoveChannel( 'R' )
image.RenameChannel( 'right.R', 'R' )

Resize((Image)self, (int)width, (int)height[, (str)type='fit'[, (str)border='transparent']]) → None :

Resizes the image to the given size.

Arguments:

width
An integer value denoting the width to which the image will be re-sized.
height
An integer value denoting the height to which the image will be re-sized.
type

Optional. A string that specifies how the image data should be scaled to fit the new size. (Default is ‘fit’.) Valid type values are:

‘none’
Don’t scale the image data.
‘width’
Scale the image to fit the new width, without changing the aspect ratio.
‘height’
Scale the image to fit the new height, without changing the aspect ratio.
‘fit’
Scale the image as large as possible while staying inside the new image, without changing the aspect ratio.
‘fill’
Scale the image as small as possible while covering the new image, without changing the aspect ratio.
‘distort’
Scale the image to match the new width and height, changing the aspect ratio if necessary.
border

Optional. A string that specifies how the border around a resized image should be set. (Default is ‘transparent’.) Border argument doesn’t do anything if the type is ‘fill’. Valid border values are:

‘transparent’
Set the border to be transparent.
‘stretch’
Stretch the left, right, top and bottom edges of the image to the edge of the resized frame.

Usage:

someImage = Draft.Image.CreateImage( 800, 600 )
someImage.Resize( 1920, 1080 )


or:

someImage = Draft.Image.CreateImage( 800, 600 )
someImage.Resize( 1920, 1080, 'distort' )


or:

someImage = Draft.Image.CreateImage( 800, 600 )
someImage.Resize( 1920, 1080, 'fit', 'stretch' )

SetChannel((Image)self, (str)channel, (float)value) → None :

Set the channel to the given value. If the channel does not already exist, then it will be created.

Arguments:

channel
The channel to set. Typical channel names are ‘R’, ‘G’, ‘B’, and ‘A’.
value
The value to assign to the channel. Typically in the range from 0.0 to 1.0.

Usage:

someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.SetChannel( 'A', 1.0 )

SetFileChannelMap((Image)self, (dict)fileChannelMap) → None :

Set the image’s file channel map using a dictionary. A valid dictionary entry is made of two strings separated by a colon. The first string corresponds to the channel name, typically ‘R’, ‘G’, ‘B’ and ‘A’, and the second string corresponds to the channel bit depth. Append an ‘ui’ to the bit depth string to specify that the channel represents an index, and an ‘f’ to specify that the channel is of type float.

New in version 1.5.

Arguments:

fileChannelMap
A dictionary indicating the image’s file channel map.

Usage:

someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.exr" )
fileChannelMap = { 'R':'16f', 'G':'16f', 'B':'16f', 'ID':'32ui' }
someImage.SetFileChannelMap( fileChannelMap )

SetToColor((Image)self, (ColorRGBA)color) → None :

Set the image to the given color.

Arguments:

color
A Draft.ColorRGBA indicating the color that the image should be set to.

Usage:

someImage = Draft.Image.CreateImage( 800, 600 )
someImage.SetToColor( Draft.ColorRGBA( 1.0, 0.0, 0.0, 1.0 ) )

ToBytes((Image)self) → str :

Get an ARGB32 string representing the image.

New in version 1.5.

Arguments: (none)

Usage:

someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
imageString = someImage.ToBytes()
imageQT = QImage( imageString, width, height, QImage.Format_ARGB32 )

Unpremultiply((Image)self) → None :

Reverse the effects of Premultiply: unpremultiply the image’s R, G, and B channels by the A (alpha) channel. The image is modified in-place.

Arguments: (none)

Usage:

someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.Unpremultiply()

WriteToFile((Image)self, (unicode)filename[, (ImageInfo)imageInfo=<Draft.ImageInfo object at 0x0000000005A33258>]) → None :

Writes the image to a file on disk. Supports various image types determined by file extension.

Arguments:

filename
A string value indicating where to save the file to.
imageInfo
Optional. A Draft.ImageInfo that will be populated with properties from the image file.

Changed in version 1.1: Added the optional imageInfo parameter.

Usage:

someImage = Draft.Image.CreateImage( 800, 600 )
someImage.WriteToFile( "//path/to/save/location.png" )

height

An integer value indicating the height of the image.

width

An integer value indicating the width of the image.