[size=150]Working with Image Channels[/size]
We added or changed the following Draft.Image methods to work with arbitrary Image channels:
- Draft.Image.CreateImage( width, height, channels )
- Draft.Image.GetChannelNames()
- Draft.Image.HasChannel( channel )
- Draft.Image.Copy( image, left, bottom, channels )
- Draft.Image.RemoveChannel( channel )
- Draft.Image.RenameChannel( oldChannel, newChannel )
[size=150]Image Class[/size]
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.), whereas Member functions require to be invoked from an instance of a Draft.Image object (by calling .).
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.
[size=150]Properties[/size]
width – An integer value indicating the width of the image.
height – An integer value indicating the height of the image.
[size=150]Static Functions[/size]
CreateImage
Type: Static Function
Description: Returns a new image of the specified size with RGBA channels.
Arguments:
[list]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, New in Draft 1.1) A list of channels to create in the image. (Defaults to [‘R’, ‘G’, ‘B’, ‘A’].)
Usage:
newImage = Draft.Image.CreateImage( 800, 600 )
[/list:u]
ReadFromFile
Type: Static Function
Description: Returns a new image from a file on disk, (supports various image types determined by file extension).
Arguments:
[list]filename – A string value indicating where on the machine to find the image file.
imageInfo – (Optional, New in Draft 1.1) A Draft.ImageInfo that will be populated with properties from the image file.
Usage:
imageFromFile = Draft.Image.ReadFromFile( "//path/to/image/file.png" )
[/list:u]
CreateAnnotation
Type: Static Function
Description: Returns a new image consisting of the specified text. The provided AnnotationInfo object describes the various text parameters. CreateAnnotation also sets the values in the AnnotationInfo object’s FontMetric property.
Arguments:
[list]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( "This is the text that will be in the image", 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 )
[/list:u]
Anaglyph
Type: Static Function
Description: Returns an anaglyph of the speficied type created from the two left/right input images.
Arguments:
[list]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" )
[/list:u]
[size=150]Member Functions[/size]
WriteToFile
Type: Member Function
Description: Writes the image to a file on disk, (supports various image types determined by file extension).
Arguments:
[list]filename – A string value indicating where to save the file to.
imageInfo – (Optional, New in Draft 1.1) A Draft.ImageInfo that sets properties of the saved file.
Usage:
someImage = Draft.Image.CreateImage( 800, 600 )
someImage.WriteToFile( "//path/to/save/location.png" )[/list:u]
Crop
Type: Member Function
Description: Crops the image to the given bounds.
Arguments:
[list]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 )[/list:u]
Resize
Type: Member Function
Description: Resizes the image to the given size.
Arguments:
[list]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:
[list]‘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[/list:u]
Usage:
someImage = Draft.Image.CreateImage( 800, 600 )
someImage.Resize( 1920, 1080 )
someImage = Draft.Image.CreateImage( 800, 600 )
someImage.Resize( 1920, 1080, 'distort' )
someImage = Draft.Image.CreateImage( 800, 600 )
someImage.Resize( 1920, 1080, 'fit', 'stretch' )[/list:u]
SetChannel
Type: Member Function
Description: Set an image channel to the specified value.
Arguments:
[list]channel – the channel to set. Typical channels 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 )[/list:u]
RemoveChannel
New in Draft 1.1
Type: Member Function
Description: Remove an existing channel from the image.
Arguments:
[list]channel – the channel to remove. 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' )[/list:u]
RenameChannel
New in Draft 1.1
Type: Member Function
Description: Rename an existing channel in the image.
Arguments:
[list]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' )[/list:u]
HasChannel
New in Draft 1.1
Type: Member Function
Description: Determine whether a channel exists in the image.
Arguments:
[list]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'[/list:u]
GetChannelNames
New in Draft 1.1
Type: Member Function
Description: Get a list of channels in the image.
Arguments: (none)
Usage:
[list]image = Draft.Image.ReadFromFile( 'image.png' )
channelNames = image.GetChannelNames()[/list:u]
ApplyGamma
New in Draft 1.1
Type: Member Function
Description: Apply a gamma correction to the image.
Arguments:
[list]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 )[/list:u]
Copy
New in Draft 1.1
Type: Member Function
Description: Copy image channels from another image to this image.
Arguments:
[list]image – A Draft.Image that will be copied from.
left – An integer number of pixels that denotes how far from the left the image should be offset.
bottom – An integer number of pixels that denotes how far from the bottom the image should be offset.
channels – A list of channels to copy from image to this image. The channels must exist in both images. (Default is all channels.)
Usage:
someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someOtherImage = Draft.Image.ReadFromFile( "//path/to/some/other/image/file.png" )
someImage.Copy( someOtherImage, channels=['A'] )[/list:u]
Composite
Type: Member Function
Description: Composites an image with the current image at the given location using the specified compositing operation.
Arguments:
[list]image – A Draft.Image that will be composited with the image on which this function was invoked.
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:
someImage = Draft.Image.CreateImage( 800, 600 )
someOtherImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.Composite( someOtherImage, 0, 0.33, Draft.CompositeOperator.OverCompositeOp )[/list:u]
CompositeWithAnchor
Type: Member Function
Description: Composites an image with the current image using the specified positional anchor to determine the location of the image being composited.
Arguments:
[list]image – A Draft.Image that will be composited with the image on which this function was invoked.
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:
someImage = Draft.Image.CreateImage( 800, 600 )
someOtherImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.CompositeWithAnchor( someOtherImage, Draft.Anchor.NorthWest, Draft.CompositeOperator.OverCompositeOp )[/list:u]
CompositeWithGravity
Type: Member Function
Description: Deprecated. Please see CompositeWithAnchor instead. Composites an image with the current image using the specified positional gravity to determine the location of the image being composited.
Arguments:
[list]image – A Draft.Image that will be composited with the image on which this function was invoked.
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:
someImage = Draft.Image.CreateImage( 800, 600 )
someOtherImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.CompositeWithGravity( someOtherImage, Draft.PositionalGravity.NorthWestGravity, Draft.CompositeOperator.OverCompositeOp )[/list:u]
CompositeWithPositionAndAnchor
Type: Member Function
Description: Composites an image with the current image at the given location using the specified compositing operation and positional anchor.
Arguments:
[list]image – A Draft.Image that will be composited with the image on which this function was invoked.
left – A float value that denotes how far from the left (as a percentage of the width) the composite operation should take place.
bottom – A float value that denotes how far from the bottom (as a percentage of the height) the composite operation should take place.
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 (Left, Bottom).
operation – A Draft.CompositeOperator enum value indicating the type of operation to perform.
Usage:
someImage = Draft.Image.CreateImage( 800, 600 )
someOtherImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.CompositeWithPositionAndAnchor( someOtherImage, 0, 0.66, Draft.Anchor.NorthWest, Draft.CompositeOperator.OverCompositeOp )[/list:u]
CompositeWithPositionAndGravity
Type: Member Function
Description: Deprecated. Please see CompositeWithPositionAndAnchor instead. Composites an image with the current image at the given location using the specified compositing operation and positional gravity.
Arguments:
[list]image – A Draft.Image that will be composited with the image on which this function was invoked.
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.
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:
someImage = Draft.Image.CreateImage( 800, 600 )
someOtherImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.CompositeWithPositionAndGravity( someOtherImage, 0, 0.66, Draft.PositionalGravity.NorthWestGravity, Draft.CompositeOperator.OverCompositeOp )[/list:u]
Premultiply
Type: Member Function
Description: Premultiply the image’s R, G, and B channels by the A (alpha) channel. The image is modified in-place.
Arguments: (none)
Usage:
[list]someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.Premultiply()[/list:u]
Unpremultiply
Type: Member Function
Description: Unpremultiply the image’s R, G, and B channels by the A (alpha) channel. The image is modified in-place.
Arguments: (none)
Usage:
[list]someImage = Draft.Image.ReadFromFile( "//path/to/some/image/file.png" )
someImage.Unpremultiply()[/list:u]