Class Imaging.FindOptions

Namespace

Ranorex

Assembly

Ranorex.Core.dll

Defines options for image find methods (see Find(Element, Bitmap) and FindSingle(Element, Bitmap) methods).

public sealed class Imaging.FindOptions : IFormattable, IEquatable<Imaging.FindOptions>

Inheritance

object

Imaging.FindOptions

Implements

IFormattable

IEquatable<Imaging.FindOptions>

Inherited Members

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetType()

Constructors

FindOptions()

Creates a new instance.

public FindOptions()

FindOptions(Preprocessings)

Creates a new instance.

public FindOptions(Imaging.Preprocessings preprocessing)

Parameters

preprocessing Imaging.Preprocessings

Sets the Preprocessing property.

FindOptions(double)

Creates a new instance.

public FindOptions(double similarity)

Parameters

similarity double

Sets the Similarity property.

FindOptions(double, Preprocessings)

Creates a new instance.

public FindOptions(double similarity, Imaging.Preprocessings preprocessing)

Parameters

similarity double

Sets the Similarity property.

preprocessing Imaging.Preprocessings

Sets the Preprocessing property.

FindOptions(double, Preprocessings, Rectangle)

Creates a new instance.

public FindOptions(double similarity, Imaging.Preprocessings preprocessing, Rectangle clipping)

Parameters

similarity double

Sets the Similarity property.

preprocessing Imaging.Preprocessings

Sets the Preprocessing property.

clipping Rectangle

Sets the Clipping property.

FindOptions(double, Preprocessings, Rectangle, bool)

Creates a new instance.

public FindOptions(double similarity, Imaging.Preprocessings preprocessing, Rectangle clipping, bool bestMatch)

Parameters

similarity double

Sets the Similarity property.

preprocessing Imaging.Preprocessings

Sets the Preprocessing property.

clipping Rectangle

Sets the Clipping property.

bestMatch bool

Sets the BestMatch property.

FindOptions(double, Preprocessings, Rectangle, bool, double)

Creates a new instance.

public FindOptions(double similarity, Imaging.Preprocessings preprocessing, Rectangle clipping, bool bestMatch, double downsizeTargetCosts)

Parameters

similarity double

Sets the Similarity property.

preprocessing Imaging.Preprocessings

Sets the Preprocessing property.

clipping Rectangle

Sets the Clipping property.

bestMatch bool

Sets the BestMatch property.

downsizeTargetCosts double

Sets the DownsizeTargetCosts property.

FindOptions(double, Preprocessings, Rectangle, bool, double, Duration)

Creates a new instance.

public FindOptions(double similarity, Imaging.Preprocessings preprocessing, Rectangle clipping, bool bestMatch, double downsizeTargetCosts, Duration timeout)

Parameters

similarity double

Sets the Similarity property.

preprocessing Imaging.Preprocessings

Sets the Preprocessing property.

clipping Rectangle

Sets the Clipping property.

bestMatch bool

Sets the BestMatch property.

downsizeTargetCosts double

Sets the DownsizeTargetCosts property.

timeout Duration

Sets the Timeout property.

FindOptions(double, Preprocessings, Rectangle, bool, double, Duration, IList<Rectangle>)

Creates a new instance.

public FindOptions(double similarity, Imaging.Preprocessings preprocessing, Rectangle clipping, bool bestMatch, double downsizeTargetCosts, Duration timeout, IList<Rectangle> ignoreRectangles)

Parameters

similarity double

Sets the Similarity property.

preprocessing Imaging.Preprocessings

Sets the Preprocessing property.

clipping Rectangle

Sets the Clipping property.

bestMatch bool

Sets the BestMatch property.

downsizeTargetCosts double

Sets the DownsizeTargetCosts property.

timeout Duration

Sets the Timeout property.

ignoreRectangles IList<Rectangle>

Sets the IgnoreRectangles property.

FindOptions(Rectangle)

Creates a new instance.

public FindOptions(Rectangle clipping)

Parameters

clipping Rectangle

Sets the Clipping property.

Properties

BestMatch

Gets or set a value specifying if the best (true) or the first (false) match found in a call to FindSingle(Element, Bitmap) should be returned.

public bool BestMatch { get; set; }

Property Value

bool

Clipping

Gets or sets a clipping rectangle in the image that defines the region where the search takes place, i.e. not the whole image is searched but only this rectangle inside it.

public Rectangle Clipping { get; set; }

Property Value

Rectangle

Remarks

The clipping rectangle will always be applied to the first argument of a method, i.e. for the FindSingle(Bitmap, Bitmap) method the value of this property is only applied to the image argument.

Default

Gets or set the default options for image find methods.

public static Imaging.FindOptions Default { get; set; }

Property Value

Imaging.FindOptions

Remarks

Change the default options by assigning a new instance to this property. Changing a property value on the instance returned by this property won't change the default options, but only the returned instance; i.e.

Ranorex.Imaging.FindOptions.Default.Similarity = 0.95;

won't change the default value for Similarity, but the following line will:

Ranorex.Imaging.FindOptions.Default = new Ranorex.Imaging.FindOptions(0.95);

Exceptions

ArgumentNullException

If setting this property to null.

DownsizeTargetCosts

Gets or sets a value that defines the estimated costs (time) for searching an image. If Downsize is set as a preprocessing step, the image and feature bitmaps are tried to be downsized so that the estimated search costs match this value.

public double DownsizeTargetCosts { get; set; }

Property Value

double

Remarks

The time to search for an image is proportional to the product of the areas of the image and the feature bitmap. By settings this value and the Downsize as a preprocessing step, you can adjust the estimated search time. Note, that a reduced search time generally reduces the size of the downsized images and thus their quality and the similarity of the search matches.

Image and feature will only be downsized to a minimum of 30% of their original size.

IgnoreRectangles

Gets or sets a list of ignoring rectangles in the image which define regions the search ignores, i.e. the whole image is searched except the defined region.

[TypeConverter(typeof(CollectionConverter))]
public IList<Rectangle> IgnoreRectangles { get; }

Property Value

IList<Rectangle>

Preprocessing

Gets or sets the preprocessing steps that are performed to the image and the feature bitmaps before searching.

[Browsable(false)]
public Imaging.Preprocessings Preprocessing { get; set; }

Property Value

Imaging.Preprocessings

Similarity

Gets or sets the minimum similarity that the feature needs to have with the image to be considered a match.

[Browsable(false)]
public double Similarity { get; set; }

Property Value

double

Remarks

A smaller similarity causes the search to take longer as more pixels need to be processed before a point in the image can be certain to be no match.

Exceptions

ArgumentOutOfRangeException

If the value lies outside the interval 0.0 and 1.0.

Timeout

Gets or sets the timeout used to search for the specified feature.

[Browsable(false)]
public Duration Timeout { get; set; }

Property Value

Duration

Remarks

The timeout specifies the time to iteratively search for the specified feature, i.e. when to stop searching anew. The timeout will not abort a search iteration, i.e. if a single search iteration takes 5 seconds and the timeout is set to 8 seconds, the search will return after 10 seconds (after performing two search iterations).

Additionally, the timeout only applies to searches done on elements, not on bitmaps directly, because only then the searched image can be updated.

Methods

Clone()

Creates a new Imaging.FindOptions instance with the same values as this instance.

public Imaging.FindOptions Clone()

Returns

Imaging.FindOptions

A new instance that is a clone of this instance.

Equals(FindOptions)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(Imaging.FindOptions other)

Parameters

other Imaging.FindOptions

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Exceptions

NotImplementedException

Equals(FindOptions, FindOptions)

Returns true if the two instances are equal.

public static bool Equals(Imaging.FindOptions a, Imaging.FindOptions b)

Parameters

a Imaging.FindOptions

An instance.

b Imaging.FindOptions

Another instance.

Returns

bool

True if the two instances are equal, otherwise false.

Equals(object)

Determines whether this instance is equal to obj.

public override bool Equals(object obj)

Parameters

obj object

Another instance.

Returns

bool

True if this instance is equal to obj, otherwise false.

GetHashCode()

Returns a static, very poor performing hash code!

public override int GetHashCode()

Returns

int

A hash code for this instance.

Remarks

Since Imaging.FindOptions instances are not immutable, the only way to satisfy all Equals(object) and GetHashCode() requirements is to return a static number for all Imaging.FindOptions instances. Consequently, the performance of a hash table storing Imaging.FindOptions instances will be very poor (hash table degenerates to list)!

Parse(string)

Parses the given string and returns a new Imaging.FindOptions instance.

public static Imaging.FindOptions Parse(string findOptionsString)

Parameters

findOptionsString string

A string representing the find options.

Returns

Imaging.FindOptions

A new Imaging.FindOptions corresponding to the given string.

Exceptions

ArgumentNullException

If findOptionsString is null.

FormatException

If findOptionsString has an invalid format.

ToString()

Returns a string representation of the instance.

public override string ToString()

Returns

string

A string representation of the instance.

Remarks

Calling this method is equivalent to calling ToString(string) with the format parameter "G".

ToString(string)

Returns a string representation of the instance using the specified format.

public string ToString(string format)

Parameters

format string

The string specifying the format to use or null to use the default format (G).

Returns

string

A string representation of the instance.

Remarks

The following string values are valid for format:

Format String	Description and Associated Properties
g	General format, containing nomination of values.
s	Short format, no nomination of values.

ToString(string, IFormatProvider)

Returns a string representation of the instance using the specified format.

public string ToString(string format, IFormatProvider formatProvider)

Parameters

format string

The string specifying the format to use or null to use the default format (G).

formatProvider IFormatProvider

Not used.

Returns

string

A string representation of the instance.

Remarks

The following string values are valid for format:

Format String	Description and Associated Properties
g	General format, containing nomination of values.
s	Short format, no nomination of values.

TryParse(string, out FindOptions)

Tries parsing the given string to a Imaging.FindOptions instance.

public static bool TryParse(string findOptionsString, out Imaging.FindOptions findOptions)

Parameters

findOptionsString string

A string representing the find options.

findOptions Imaging.FindOptions

When this method returns, contains a Imaging.FindOptions instance if parsing succeeded, null otherwise.

Returns

bool

True if parsing succeeded, otherwise false.

Operators

operator ==(FindOptions, FindOptions)

Implements the operator ==.

public static bool operator ==(Imaging.FindOptions a, Imaging.FindOptions b)

Parameters

a Imaging.FindOptions

A Imaging.FindOptions instance.

b Imaging.FindOptions

Another Imaging.FindOptions instance.

Returns

bool

True if the two instances are equal.

operator !=(FindOptions, FindOptions)

Implements the operator !=.

public static bool operator !=(Imaging.FindOptions a, Imaging.FindOptions b)

Parameters

a Imaging.FindOptions

A Imaging.FindOptions instance.

b Imaging.FindOptions

Another Imaging.FindOptions instance.

Returns

bool

True if the two instances are not equal.