Description
Copy all or a portion of an image to a new image.
-
Return Type
-
A McImage object.
A new McImage.
-
Syntax
-
object.CopyToNewImage ([SourceRect], [Name], [ImageCreationFlags], [vType], [Channel], [CopyAoiToNewImage], [MaskNewImageByAoi], [FramesToCopy], [ImportFilter])
The CopyToNewImage Method syntax has these parts: |
| object | An expression evaluating to an object of type McImage. | | SourceRect | Optional. A Variant value. If given, either a LONGRECT or an array of 4 values in the order Left, Top, Right, Bottom, specifying the source rectangle for the copy. If this argument is missing, then the source rectange is the bounding rectangle of any AOI or the whole image if there is no AOI. This rectangle may be larger than the image, in which case it is clipped to the image bounds, but it must intersect at least some portion of the image.
| | Name | Optional. A String value. If non-empty, the name to be given the new image.
| | ImageCreationFlags | Optional. A mcImageCreateFlags enumeration, as described in settings. Flag to pass to the McImages.Add method. See mcImageCreateFlags for the list of supported flags. The mcImportPropertiesFlags to control which properties, if any are copied into the new image, are specified separately by the ImportFilter argument.
| | vType | Optional. A Variant value. is copied into the new image. For example, if a source RGB image is copied to a destination HSI image with the Channel argument given as 2, then the destination will be a monochrome image holding the I (intensity) channel of the RGB-to-HSI converted image.
| | Channel | Optional. A Long value. The default value of -1 means all channels are copied to a new image of the specified vType. If a channel from 0 up to vType.NumberOfChannels-1 is specified, then only that channel is copied. In this case the new image will be a monochrome image having the same pixel bit-depth as the vType argument.
The Channel is interpreted as a channel in any given destination vType, not the source McImage.Type; that is, the source image is cast to the destination vType and then the Channel (or all channels if -1) from that
| | CopyAoiToNewImage | Optional. A Boolean value. If True (the default), then any AOI that does not exactly cover the new image is made the AOI of the new image. If False, then the new image will have no AOI.
| | MaskNewImageByAoi | Optional. A Boolean value. If True (the default), any multiple or irregular source AOI is used to mask the portion of the image copied. Areas not copied are black. If False, then no AOI masking is done and a rectangular portion of the source image is always copied without masking.
| | FramesToCopy | Optional. A Variant value. If given, a selector giving the frame indices of the frames to copy (this selector may be formatted in the same way that the ActiveFrameRange property is to indicate one or more frames in the order they are to be copied). If missing, the ActiveFrameRange property is used, unless UseActiveFrameRange is False, in which case only the ActiveFrame is copied.
| | ImportFilter | Optional. A mcImportPropertiesFlags enumeration, as described in settings. Controls which properties of this image are to be imported into the new image. By default, all properties except the ColorMap and the File are copied.
|
Settings The settings for ImageCreationFlags are:
|
 | mcicfDefault | 0 | |
| mcicfContiguous | 1 |
If set, frames are allocated contiguously, and you cannot add to the FrameCount at a later time.
|
| mcicfNoInit | 2 |
Default is to initialize to 0 (black), this flag suppresses initialization.
|
| mcicfNoAddToCollection | 4 |
If set, the image is created, but not added to the collection (see Notes).
|
| mcicfNotVisible | 8 |
If set, the image is created, possibly added to collection (see above), but not made visible.
|
| mcipfNoImportProperties | 8388608 |
Suppress ImportProperties for functions creating an image from another.
|
The settings for ImportFilter are:
|
| mcipfImage | 4096 |
Import standard McImage properties.
|
| mcipfUserProperties | 8192 |
Import public McImage.Properties (in default name space).
|
| mcipfLookupTables | 16384 |
Import McImage.LookupTables.
|
| mcipfPseudoColor | 32768 |
Import McPseudoColor.
|
| mcipfSpatialCalibration | 65536 |
Import McImage.SpatialCalibration.
|
| mcipfIntensityCalibration | 131072 |
Import McImage.IntensityCalibration.
|
| mcipfColorMap | 262144 |
Import McImage.ColorMap. Ignored if the image is not indexed color.
|
| mcipfNoEvent | 8388608 |
Suppress the BeforeImportProperties and AfterImportProperties events.
|
| mcipfBWBestFit | 16777216 |
Set a best fit display range when importing lookup tables.
|
| mcipfBWTrueRange | 33554432 |
Set the display range to the actual dynamic range.
|
| mcipfAll | 520192 |
Import all properties and attributes, do not suppress events.
|
| mcipfAllExceptSpatial | 454656 |
Import all properties not spatially related. Useful if the image is resized.
|
| mcipfAllExceptIntensity | 389120 |
Import all properties not intensity related. Useful if the image is converted.
|
| mcipfDefault | 12288 |
Import a minimal set of properties, image and user properties only. Useful if the image is related to the original image, but not closely.
|
| mcipfNone | 0 |
Suppress importing any properties. Will still fire event unless mcipfNoEvent is also specified, in case someone handling events wants to copy some properties.
|
| mcipfMask | 268431360 |
All existing flags combined together.
|
Remarks
This is a general method for copying all or a portion of this image to a new, optionally named, image. The new image may optionally contain only one color channel from this image, or it may be converted to a new type. The copy can be masked by the Aoi and the Aoi itself may also be copied.
At least one frame must be selected for copying. The ActiveFrame in the new image is made to be the same frame as this image's ActiveFrame, if possible.
If you need to do an image copy that also involves an unusual luminance range cast, then setting the CastingSourceRange before calling CopyToNewImage might be necessary. However, you do not need to change CastingSourceRange and then call CopyToNewImage just to convert the luminance range of one image AOI to another range in another image, because the ConvertEx method takes source and destination luminance range arguments that will do the job for you.
|
CopyToNewImage Method
