Class Imaging

Namespace: Ranorex

Assembly: Ranorex.Core.dll

Provides methods to create screenshots of elements, to search for images, and for image processing.

public class Imaging : MarshalByRefObject

Inheritance: object

MarshalByRefObject

Imaging

Inherited Members: MarshalByRefObject.MemberwiseClone(bool)

MarshalByRefObject.GetLifetimeService()

MarshalByRefObject.InitializeLifetimeService()

MarshalByRefObject.CreateObjRef(Type)

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Constructors

Imaging()

public Imaging()

Properties

UseMultiThreading

Gets a sets a value disabling or enabling multi-threading for Contains(Element, Bitmap) or Find(Element, Bitmap) operations. True by default.

public static bool UseMultiThreading { get; set; }

Property Value

bool

Remarks

If this is set to false operations related to Contains(Element, Bitmap) or Find(Element, Bitmap) will take longer, if this is set to true the processor may be fully utilized until the operation finishes and other tasks may take longer.

Methods

CaptureCompressedImage(Adapter)

Captures a compressed image of an adapter.

public static CompressedImage CaptureCompressedImage(Adapter adapter)

Parameters

adapter Adapter: The adapter to capture.

Returns

CompressedImage: The captured compressed image.

CaptureCompressedImage(Element)

Captures a compressed image of an element.

public static CompressedImage CaptureCompressedImage(Element element)

Parameters

element Element: The element to capture.

Returns

CompressedImage: The captured compressed image.

CaptureDesktopImage(Element)

Captures an image of element from the desktop.

public static Bitmap CaptureDesktopImage(Element element)

Parameters

element Element: The element to capture or null to capture the whole desktop.

Returns

Bitmap: The captured image.

CaptureDesktopImage(Rectangle)

Captures an image region from the desktop.

public static Bitmap CaptureDesktopImage(Rectangle rect)

Parameters

rect Rectangle: The region to capture.

Returns

Bitmap: The captured image region.

CaptureDesktopImageWithSurroundingArea(Element, Point?, Color)

Captures an image of the of the element and its surrounding area from the desktop.

public static Bitmap CaptureDesktopImageWithSurroundingArea(Element element, Point? mousePoint, Color highlightColor)

Parameters

element Element: The element to capture within its periphery.
mousePoint Point?: A point specifying the screen coordinates of the current mouse cursor or null in order not to capture the mouse cursor.
highlightColor Color: The color used to highlight the element within its surrounding area or Empty to not highlight the element.

Returns

Bitmap: The captured image.

Exceptions

ArgumentNullException: element is a null reference.

CaptureDesktopImagesWithSurroundingArea(Element, Point?, Color, Color, int, out Bitmap)

Captures an image of the of the element and its surrounding area from the desktop, creating two images, with different borders and sizes.

public static Bitmap CaptureDesktopImagesWithSurroundingArea(Element element, Point? mousePoint, Color highlightColor1, Color highlightColor2, int alpha, out Bitmap elemImage)

Parameters

element Element: The element to capture within its periphery.
mousePoint Point?: A point specifying the screen coordinates of the current mouse cursor or null in order not to capture the mouse cursor.
highlightColor1 Color: The color used to highlight the element within its surrounding area or Empty to not highlight the element.
highlightColor2 Color: The color used to highlight the element within its surrounding area or Empty to not highlight the element, used for elemImage.
alpha int: The alpha value used for blending the non-highlighted area with the background.
elemImage Bitmap: The captured image of the element rectangle without surround areas or borders.

Returns

Bitmap: The captured image.

Exceptions

ArgumentNullException: element is a null reference.

CaptureImage(Element)

Captures an image of an element.

public static Bitmap CaptureImage(Element element)

Parameters

element Element: The element to capture.

Returns

Bitmap: The captured image.

Remarks

Note that the element must be visible to capture a useful image.

CaptureImage(Element, int, bool)

Captures an image of an element.

public static Bitmap CaptureImage(Element element, int delay, bool ensureVisible)

Parameters

element Element: The element to capture.
delay int: Capture wait delay.
ensureVisible bool: If true, the element is made visible before any capturing is done.

Returns

Bitmap: The captured image.

Remarks

Note that the element must be visible to capture a useful image.

CaptureImageAuto(Element)

Captures an image of the element even if it is hidden by other elements. If this does not succeed, the visible portion of the element is captured using a screenshot.

public static Bitmap CaptureImageAuto(Element element)

Parameters

element Element: The element to capture.

Returns

Bitmap: The captured image.

CaptureImageAuto(Element, bool)

Captures an image of the element even if it is hidden by other elements. If this does not succeed, the visible portion of the element is captured using a screenshot.

public static Bitmap CaptureImageAuto(Element element, bool ensureVisibleIfNeeded)

Parameters

element Element: The element to capture.
ensureVisibleIfNeeded bool: If capturing the image hidden does not succeed, this value specified if the element should be made visible before capturing the screenshot.

Returns

Bitmap: The captured image.

CaptureImageHidden(Element)

Captures an image of the element even if it is hidden by other elements.

public static Bitmap CaptureImageHidden(Element element)

Parameters

element Element: The element to capture.

Returns

Bitmap: The captured image.

Exceptions

ArgumentNullException: element is a null reference.

CaptureImageHidden(IntPtr)

Captures an image of the window even if it is hidden by other windows.

public static Bitmap CaptureImageHidden(IntPtr handle)

Parameters

handle IntPtr: The handle of the window to capture.

Returns

Bitmap: The captured image or null if capturing a hidden image fails.

Remarks

This methods does not consider the UseDesktopImageCapture property.

Compare(Element, Bitmap, FindOptions)

Compares the specified feature with (a screenshot of) the element and returns whether their similarity is greater than or equal to the value specified by options.Similarity.

public static bool Compare(Element element, Bitmap feature, Imaging.FindOptions options)

Parameters

element Element: The element to make a screenshot of.
feature Bitmap: The image to compare the screenshot with.
options Imaging.FindOptions: The options for the image comparison. The Preprocessing options are applied to both images, the Clipping rectangle only to the screenshot of the element. The Similarity defines the minimum similarity the images need to have.

Returns

bool: True if the similarity of the two (preprocessed) images is greater than or equal to options.Similarity.

Remarks

False will be returned if the feature and the screenshot of the element (after clipping using the rectangle value of options.Clipping) do not have the same size.

Exceptions

RanorexException: If capturing a screenshot of the element fails.
ArgumentNullException: If element is null.
ArgumentNullException: If feature is null.
ArgumentException: If the bitmap format of the feature cannot be converted to that of the screenshot of the element.

Compare(Bitmap, Bitmap)

Compares imageA and imageB and returns their similarity.

public static double Compare(Bitmap imageA, Bitmap imageB)

Parameters

imageA Bitmap: The first image.
imageB Bitmap: The second image.

Returns

double: The similarity of the two images.

Remarks

A similarity of zero will be returned if the two images do not have the same size. No preprocessing or clipping is done on the specified images.

Exceptions

ArgumentNullException: If imageA is null.
ArgumentNullException: If imageB is null.
ArgumentException: If the bitmap format of the imageB cannot be converted to that of the imageA.

Compare(Bitmap, Bitmap, FindOptions)

Compares image and feature and returns whether their similarity is greater than or equal to the value specified by options.Similarity.

public static bool Compare(Bitmap image, Bitmap feature, Imaging.FindOptions options)

Parameters

image Bitmap: The first image.
feature Bitmap: The second image.
options Imaging.FindOptions: The options for the image comparison. The Preprocessing options are applied to both images, the Clipping rectangle only to image. The Similarity defines the minimum similarity the images need to have.

Returns

bool: True if the similarity of the two (preprocessed) images is greater than or equal to options.Similarity.

Remarks

False will be returned if the two images (after clipping image using the rectangle value of options.Clipping) do not have the same size.

Exceptions

ArgumentNullException: If image is null.
ArgumentNullException: If feature is null.
ArgumentException: If the bitmap format of the feature cannot be converted to that of the image.

Compare(Bitmap, Bitmap, double)

Compares imageA and imageB and returns whether their similarity is greater than or equal to similarity.

public static bool Compare(Bitmap imageA, Bitmap imageB, double similarity)

Parameters

imageA Bitmap: The first image.
imageB Bitmap: The second image.
similarity double: The minimum similarity of the two images in order to return true.

Returns

bool: True if the similarity of the two images is greater than or equal to similarity.

Remarks

False will be returned if the two images do not have the same size. If similarity is smaller than or equal to zero, true is returned.

Exceptions

ArgumentNullException: If imageA is null.
ArgumentNullException: If imageB is null.
ArgumentException: If the bitmap format of the imageB cannot be converted to that of the imageA.

Contains(Element, Bitmap)

Searches for the specified feature in (a screenshot of) the element using Default Imaging.FindOptions and returns whether the feature is found.

public static bool Contains(Element element, Bitmap feature)

Parameters

element Element: The element to make a screenshot of in which will be searched.
feature Bitmap: The image to search for.

Returns

bool: True if the feature is found, otherwise false.

Exceptions

RanorexException: If capturing a screenshot of the element fails.
ArgumentNullException: If element is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the screenshot of the element.
ArgumentException: If the bitmap format of the feature cannot be converted to that (color image, Format24bppRgb) of the screenshot of the element.

Contains(Element, Bitmap, FindOptions)

Searches for the specified feature in (a screenshot of) the element and returns whether the feature is found.

public static bool Contains(Element element, Bitmap feature, Imaging.FindOptions options)

Parameters

element Element: The element to make a screenshot of in which will be searched.
feature Bitmap: The image to search for.
options Imaging.FindOptions: A Imaging.FindOptions instance that defines the options for the search.

Returns

bool: True if the feature is found, otherwise false.

Exceptions

RanorexException: If capturing a screenshot of the element fails.
ArgumentNullException: If element is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the screenshot of the element.
ArgumentException: If the bitmap format of the feature cannot be converted to that (color image, Format24bppRgb) of the screenshot of the element.

Contains(Bitmap, Bitmap)

Searches for the specified feature in the image using Default Imaging.FindOptions and returns whether the feature is found.

public static bool Contains(Bitmap image, Bitmap feature)

Parameters

image Bitmap: The image to search in.
feature Bitmap: The image to search for.

Returns

bool: True if the feature is found, otherwise false.

Exceptions

ArgumentNullException: If image is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the image.
ArgumentException: If the bitmap format of the feature cannot be converted to that of the image.

Contains(Bitmap, Bitmap, FindOptions)

Searches for the specified feature in the image and returns whether the feature is found.

public static bool Contains(Bitmap image, Bitmap feature, Imaging.FindOptions options)

Parameters

image Bitmap: The image to search in.
feature Bitmap: The image to search for.
options Imaging.FindOptions: A Imaging.FindOptions instance that defines the options for the search.

Returns

bool: True if the feature is found, otherwise false.

Exceptions

ArgumentNullException: If image is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the image.
ArgumentException: If the bitmap format of the feature cannot be converted to that of the image.

Crop(Bitmap, Rectangle)

Crops the given image by the specified rectangle.

public static Bitmap Crop(Bitmap image, Rectangle cropRect)

Parameters

image Bitmap: An image.
cropRect Rectangle: The bounds of the sub-image in image to return.

Returns

Bitmap: The cropped image.

Find(Element, Bitmap)

Searches for the specified feature in (a screenshot of) the element and returns a list of Imaging.Matches using Default Imaging.FindOptions.

public static List<Imaging.Match> Find(Element element, Bitmap feature)

Parameters

element Element: The element to make a screenshot of in which will be searched.
feature Bitmap: The image to search for.

Returns

List<Imaging.Match>: A list of Imaging.Matches found.

Exceptions

RanorexException: If capturing a screenshot of the element fails.
ArgumentNullException: If element is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the screenshot of the element.
ArgumentException: If the bitmap format of the feature cannot be converted to that (color image, Format24bppRgb) of the screenshot of the element.

Find(Element, Bitmap, FindOptions)

Searches for the specified feature in (a screenshot of) the element and returns a list of Imaging.Matches.

public static List<Imaging.Match> Find(Element element, Bitmap feature, Imaging.FindOptions options)

Parameters

element Element: The element to make a screenshot of in which will be searched.
feature Bitmap: The image to search for.
options Imaging.FindOptions: A Imaging.FindOptions instance that defines the options for the search.

Returns

List<Imaging.Match>: A list of Imaging.Matches found.

Exceptions

RanorexException: If capturing a screenshot of the element fails.
ArgumentNullException: If element is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the screenshot of the element.
ArgumentException: If the bitmap format of the feature cannot be converted to that (color image, Format24bppRgb) of the screenshot of the element.

Find(Bitmap, Bitmap)

Searches for the specified feature in the image and returns a list of Imaging.Matches using Default Imaging.FindOptions.

public static List<Imaging.Match> Find(Bitmap image, Bitmap feature)

Parameters

image Bitmap: The image to search in.
feature Bitmap: The image to search for.

Returns

List<Imaging.Match>: A list of Imaging.Matches found.

Exceptions

ArgumentNullException: If image is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the image.
ArgumentException: If the bitmap format of the feature cannot be converted to that of the image.

Find(Bitmap, Bitmap, FindOptions)

Searches for the specified feature in the image and returns a list of Imaging.Matches.

public static List<Imaging.Match> Find(Bitmap image, Bitmap feature, Imaging.FindOptions options)

Parameters

image Bitmap: The image to search in.
feature Bitmap: The image to search for.
options Imaging.FindOptions: A Imaging.FindOptions instance that defines the options for the search.

Returns

List<Imaging.Match>: A list of Imaging.Matches found.

Exceptions

ArgumentNullException: If image is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the image.
ArgumentException: If the bitmap format of the feature cannot be converted to that of the image.

FindSingle(Element, Bitmap)

Searches for the specified feature in (a screenshot of) the element using Default Imaging.FindOptions.

public static Imaging.Match FindSingle(Element element, Bitmap feature)

Parameters

element Element: The element to make a screenshot of in which will be searched.
feature Bitmap: The image to search for.

Returns

Imaging.Match: The first or best Imaging.Match found (as specified in the Default options).

Exceptions

RanorexException: If capturing a screenshot of the element fails.
ArgumentNullException: If element is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the screenshot of the element.
ArgumentException: If the bitmap format of the feature cannot be converted to that (color image, Format24bppRgb) of the screenshot of the element.
ImageNotFoundException: If the feature could not be found.

FindSingle(Element, Bitmap, FindOptions)

Searches for the specified feature in (a screenshot of) the element.

public static Imaging.Match FindSingle(Element element, Bitmap feature, Imaging.FindOptions options)

Parameters

element Element: The element to make a screenshot of in which will be searched.
feature Bitmap: The image to search for.
options Imaging.FindOptions: A Imaging.FindOptions instance that defines the options for the search.

Returns

Imaging.Match: The first or best Imaging.Match found (as specified in the options).

Exceptions

RanorexException: If capturing a screenshot of the element fails.
ArgumentNullException: If element is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the screenshot of the element.
ArgumentException: If the bitmap format of the feature cannot be converted to that (color image, Format24bppRgb) of the screenshot of the element.
ImageNotFoundException: If the feature could not be found.

FindSingle(Bitmap, Bitmap)

Searches for the specified feature in the image using Default Imaging.FindOptions.

public static Imaging.Match FindSingle(Bitmap image, Bitmap feature)

Parameters

image Bitmap: The image to search in.
feature Bitmap: The image to search for.

Returns

Imaging.Match: The first or best Imaging.Match found (as specified in the Default options).

Exceptions

ArgumentNullException: If image is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the image.
ArgumentException: If the bitmap format of the feature cannot be converted to that of the image.
ImageNotFoundException: If the feature could not be found.

FindSingle(Bitmap, Bitmap, FindOptions)

Searches for the specified feature in the image.

public static Imaging.Match FindSingle(Bitmap image, Bitmap feature, Imaging.FindOptions options)

Parameters

image Bitmap: The image to search in.
feature Bitmap: The image to search for.
options Imaging.FindOptions: A Imaging.FindOptions instance that defines the options for the search.

Returns

Imaging.Match: The first or best Imaging.Match found (as specified in the options).

Exceptions

ArgumentNullException: If image is null.
ArgumentNullException: If feature is null.
ArgumentException: If the feature is greater in size than the image.
ArgumentException: If the bitmap format of the feature cannot be converted to that of the image.
ImageNotFoundException: If the feature could not be found.

Load(string)

Loads a bitmap file.

public static Bitmap Load(string filename)

Parameters

filename string: The filename of the bitmap.

Returns

Bitmap: The loaded bitmap.

Exceptions

ArgumentException: If a bitmap cannot be loaded from the specified file.

Resize(Bitmap, double)

Resizes the input image.

public static Bitmap Resize(Bitmap input, double factor)

Parameters

input Bitmap: An image.
factor double: The factor by which the image should be resized.

Returns

Bitmap: The resized image.

Exceptions

ArgumentNullException: If input is null.
ArgumentOutOfRangeException: If width or height of the output image are not positive.

Resize(Bitmap, double, double)

Resizes the input image.

public static Bitmap Resize(Bitmap input, double widthFactor, double heightFactor)

Parameters

input Bitmap: An image.
widthFactor double: The factor by which the width of the image should be resized.
heightFactor double: The factor by which the height of the image should be resized.

Returns

Bitmap: The resized image.

Exceptions

ArgumentNullException: If input is null.
ArgumentOutOfRangeException: If width or height of the output image are not positive.

Resize(Bitmap, int, int)

Resizes the input image.

public static Bitmap Resize(Bitmap input, int width, int height)

Parameters

input Bitmap: An image.
width int: The width the image should be resized to.
height int: The height the image should be resized to.

Returns

Bitmap: The resized image with the specified width and height.

Exceptions

ArgumentNullException: If input is null.
ArgumentOutOfRangeException: If width or height are not positive.

TryFindSingle(Element, Bitmap, FindOptions, out Match)

Tries to find the specified feature in (a screenshot of) the element.

public static bool TryFindSingle(Element element, Bitmap feature, Imaging.FindOptions options, out Imaging.Match match)

Parameters

element Element: The element to make a screenshot of in which will be searched.
feature Bitmap: The image to search for.
options Imaging.FindOptions: A Imaging.FindOptions instance that defines the options for the search.
match Imaging.Match: The first or best Imaging.Match found (as specified in the options), null if the search failed for any reason or no match was found.

Returns

bool: True if a match was found, false otherwise.

TryFindSingle(Element, Bitmap, out Match)

Tries to find the specified feature in (a screenshot of) the element using Default Imaging.FindOptions.

public static bool TryFindSingle(Element element, Bitmap feature, out Imaging.Match match)

Parameters

element Element: The element to make a screenshot of in which will be searched.
feature Bitmap: The image to search for.
match Imaging.Match: The first or best Imaging.Match found (as specified in the Default options), null if the search failed for any reason or no match was found.

Returns

bool: True if a match was found, false otherwise.

TryFindSingle(Bitmap, Bitmap, FindOptions, out Match)

Tries to find the specified feature in the image.

public static bool TryFindSingle(Bitmap image, Bitmap feature, Imaging.FindOptions options, out Imaging.Match match)

Parameters

image Bitmap: The image to search in.
feature Bitmap: The image to search for.
options Imaging.FindOptions: A Imaging.FindOptions instance that defines the options for the search.
match Imaging.Match: The first or best Imaging.Match found (as specified in the options), null if the search failed for any reason or no match was found.

Returns

bool: True if a match was found, false otherwise.

TryFindSingle(Bitmap, Bitmap, out Match)

Tries to find the specified feature in the image using Default Imaging.FindOptions.

public static bool TryFindSingle(Bitmap image, Bitmap feature, out Imaging.Match match)

Parameters

image Bitmap: The image to search in.
feature Bitmap: The image to search for.
match Imaging.Match: The first or best Imaging.Match found (as specified in the Default options), null if the search failed for any reason or no match was found.

Returns

bool: True if a match was found, false otherwise.

Table of Contents

Class Imaging

Constructors

Imaging()

Properties

UseMultiThreading

Property Value

Remarks

Methods

CaptureCompressedImage(Adapter)

Parameters

Returns

CaptureCompressedImage(Element)

Parameters

Returns

CaptureDesktopImage(Element)

Parameters

Returns

CaptureDesktopImage(Rectangle)

Parameters

Returns

CaptureDesktopImageWithSurroundingArea(Element, Point?, Color)

Parameters

Returns

Exceptions

CaptureDesktopImagesWithSurroundingArea(Element, Point?, Color, Color, int, out Bitmap)

Parameters

Returns

Exceptions

CaptureImage(Element)

Parameters

Returns

Remarks

CaptureImage(Element, int, bool)

Parameters

Returns

Remarks

CaptureImageAuto(Element)

Parameters

Returns

CaptureImageAuto(Element, bool)

Parameters

Returns

CaptureImageHidden(Element)

Parameters

Returns

Exceptions

CaptureImageHidden(IntPtr)

Parameters

Returns

Remarks

Compare(Element, Bitmap, FindOptions)

Parameters

Returns

Remarks

Exceptions

Compare(Bitmap, Bitmap)

Parameters

Returns

Remarks

Exceptions

Compare(Bitmap, Bitmap, FindOptions)

Parameters

Returns

Remarks

Exceptions

Compare(Bitmap, Bitmap, double)

Parameters

Returns

Remarks

Exceptions

Contains(Element, Bitmap)

Parameters

Returns

Exceptions

Contains(Element, Bitmap, FindOptions)

Parameters

Returns

Exceptions

Contains(Bitmap, Bitmap)