Actiona Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Image ======
This object represents an image.

===== Functions =====

==== Image ====
Constructor function.

=== Syntax ===
<code javascript>
var myObject = new Image();
</code>
<code javascript>
var myObject = new Image(otherImage);
</code>
<code javascript>
var myObject = new Image(filename);
</code>

=== Arguments ===
  - otherImage - (Image) other Image to copy
  - filename - (string) a valid image filename 
=== Exceptions ===
  * (ParameterTypeError) incorrect parameter type
  * (ParameterCountError) incorrect parameter count

=== Example ===
Create a empty Image.
<code javascript>
var myObject = new Image();
</code>
Create a Image representing a copy of **otherImage**.
<code javascript>
var myObject = new Image(otherImage);
</code>

==== takeScreenshot ====
Take a screenshot of the whole screen or only of **window** and store the result in a new Image.

=== Syntax ===
<code javascript>
var myObject = Image.takeScreenshot();
</code>
<code javascript>
var myObject = Image.takeScreenshot(window);
</code>

=== Arguments ===
  - window - ([[en:code:core:window|Window]]) the window to screenshot

=== Exceptions ===
  * (InvalidWindowError) invalid window

==== takeScreenshotUsingScreenIndex ====
Take a screenshot of one screen and store the result in a new Image. [//Added in Actionaz 3.7.0.//]

=== Syntax ===
<code javascript>
var myObject = Image.takeScreenshotUsingScreenIndex(0);
</code>

=== Arguments ===
  - screenIndex - (integer) the index of the screen to screenshot

=== Exceptions ===
  * (InvalidScreenIndexError) invalid screen index

===== Methods =====

==== clone ====
Returns a copy of this Image.

=== Syntax ===
<code javascript>
myObject.clone();
</code>

=== Returns ===
  * (Image) a copy of this Image

=== Example ===
<code javascript>
var copyOfMyObject = myObject.clone();
</code>

==== equals ====
Returns true if this Image and another are referencing the same image.

=== Syntax ===
<code javascript>
myObject.equals(other);
</code>

=== Arguments ===
  - other - (Image) another Image

=== Returns ===
  * (bool) true if **other** is referencing the same image

=== Example ===
<code javascript>
if(myFirstObject.equals(mySecondObject))
	//Do something
</code>

==== toString ====
Returns a string representing this Image.

=== Syntax ===
<code javascript>
myObject.toString();
</code>

=== Returns ===
  * (string) a string representing this Image

=== Example ===
<code javascript>
Console.print(myObject.toString());
</code>

=== Notes ===
This method is automatically called when trying to convert a Image to a string.

==== setData ====
Sets the data of this Image.

=== Syntax ===
<code javascript>
myObject.setData(data);
</code>

=== Arguments ===
  - data - ([[en:code:core:rawdata|RawData]]) RawData of the image

=== Returns ===
  * (Image) this Image

=== Exceptions ===
  * (ImageDataError) invalid image data

=== Notes ===
Supported image formats are BMP, GIF, JPG, JPEG, PNG, PBM, PGM, PPM, TIFF, XBM and XPM.

==== data ====
Returns the data of this Image as [[en:code:core:rawdata|RawData]] in the BMP format.

=== Syntax ===
<code javascript>
myObject.data();
</code>

=== Returns ===
  * ([[en:code:core:rawdata|RawData]]) this Image as RawData

=== Exceptions ===
  * (ImageDataError) unable to get the image data

==== loadFromFile ====
Loads the Image from a file.

=== Syntax ===
<code javascript>
myObject.loadFromFile(filename);
</code>

=== Arguments ===
  - filename - (string) filename to load

=== Returns ===
  * (Image) this Image

=== Exceptions ===
  * (LoadImageError) unable to load the image

=== Notes ===
Supported image formats are BMP, GIF, JPG, JPEG, PNG, PBM, PGM, PPM, TIFF, XBM and XPM.

==== saveToFile ====
Saves the Image to a file.

=== Syntax ===
<code javascript>
myObject.saveToFile(filename);
</code>

=== Arguments ===
  - filename - (string) filename to save to

=== Returns ===
  * (Image) this Image

=== Exceptions ===
  * (SaveImageError) unable to save the image

=== Notes ===
Supported image formats are BMP, JPG, JPEG, PNG, PPM, TIFF, XBM and XPM.

==== applyFilter ====
Applies a filter on this Image.

=== Syntax ===
<code javascript>
myObject.applyFilter(filter);
</code>
<code javascript>
myObject.applyFilter(filter, options);
</code>

=== Arguments ===
  - filter - ([[#filter|Filter]]) the filter to use
  - options - (object) filter options
    * filterChannels - (string) the color channel(s) to perform the filtering on. A string consisting of zero or one entity of each of the characters r,g,b,a
    * filterBorderPolicy - (string) used with the convolution filter. Values are "mirror", "extend" or "wrap"
    * convolutionDivisor - (integer) the convolution divisor
    * convolutionBias - (integer) the convolution bias
    * radius - (number) the radius
    * force - (number) the force (use it, Luke!)
    * center - (object) the center
      * x - (integer) the x coordinate
      * y - (integer) the y coordinate 

=== Returns ===
  * (Image) this Image

=== Exceptions ===
  * (ApplyFilterError) unable to apply the filter

==== pixel ====
Returns a pixel from this Image.

=== Syntax ===
<code javascript>
myObject.pixel(x, y);
</code>

=== Arguments ===
  - x - (integer) x coordinate of the pixel to return
  - y - (integer) y coordinate of the pixel to return

=== Returns ===
  * ([[en:code:core:color|Color]]) the pixel

==== setPixel ====
Sets a pixel from this Image.

=== Syntax ===
<code javascript>
myObject.pixel(x, y, color);
</code>
<code javascript>
myObject.pixel(x, y, colorString);
</code>
<code javascript>
myObject.pixel(x, y, red, green, blue);
</code>

=== Arguments ===
  - x - (integer) x coordinate of the pixel to set
  - y - (integer) y coordinate of the pixel to set
  - color - ([[en:code:core:color|Color]]) color of the pixel to set
  - red - (integer) red value of the color to set
  - green - (integer) green value of the color to set
  - blue - (integer) blue value of the color to set

=== Returns ===
  * (Image) this Image

==== mirror ====
Mirror this Image.

=== Syntax ===
<code javascript>
myObject.mirror(mirrorOrientation);
</code>

=== Arguments ===
  - mirrorOrientation - ([[#mirrororientation|MirrorOrientation]]) mirror orientation

=== Returns ===
  * (Image) this Image

==== setSize ====
Resizes this Image.

=== Syntax ===
<code javascript>
myObject.setSize(size);
</code>
<code javascript>
myObject.setSize(width, height);
</code>

=== Arguments ===
  - size - ([[en:code:core:size|Size]]) the new Image size
  - width - (integer) the new width of this Image
  - height - (integer) the new height of this Image

=== Returns ===
  * (Image) this Image

==== size ====
Returns the size of this Image.

=== Syntax ===
<code javascript>
myObject.size();
</code>

=== Returns ===
  * ([[en:code:core:size|Size]]) the size of this Image

==== width ====
Returns the width of this Image.

=== Syntax ===
<code javascript>
myObject.width();
</code>

=== Returns ===
  * (integer) the width of this Image

==== height ====
Returns the height of this Image.

=== Syntax ===
<code javascript>
myObject.height();
</code>

=== Returns ===
  * (integer) the height of this Image

==== copy ====
Returns a copy of this Image or only a part of it.

=== Syntax ===
<code javascript>
myObject.copy();
</code>
<code javascript>
myObject.copy(rect);
</code>

=== Arguments ===
  - rect - ([[en:code:core:rect|Rect]]) the section of this Image to copy

=== Returns ===
  * (Image) a new copy of this Image

==== findSubImage ====
Searches for another image contained in this one.

//Added in Actionaz 3.0.1.//

=== Syntax ===
<code javascript>
myObject.findSubImage(otherImage);
</code>
<code javascript>
myObject.findSubImage(otherImage, options);
</code>

=== Arguments ===
  - otherImage - (Image) the Image to find
  - options - (object) search options
    * confidenceMinimum - (integer) the minimum confidence percentage, 100 means perfect match (default: 70)
    * downPyramidCount - (integer) the number of pyramids to use. A pyramid is a subdivision of the image used to accelerate the search. Choose 1 here if the searched image is not very different from this image. (default: 2)
    * method - ([[#method|Method]]) the search method to use (default: CorrelationCoefficient) [//Added in Actionaz 3.7.0.//]

=== Returns ===
  * (object) the matching point, or null if no matching point can be found
    * position - ([[en:code:core:point|Point]]) the matching image center
    * confidence - (integer) the confidence percentage

=== Exceptions ===
  * (FindSubImageError) an error occured while searching for a sub-image
  * (ParameterTypeError) incorrect parameter type

=== Example ===
<code javascript>
//Searches for an object on the screen
var screenShot = Image.takeScreenshot();
var imageToFind = new Image("object.png");

var searchResult = screenShot.findSubImage(imageToFind);
if(searchResult)
    Console.print("Matching image found, position: " + searchResult.position + ", confidence: " + searchResult.confidence);
else
    Console.print("No matching image found.");
</code>

==== findSubImages ====
Searches for images contained in this one.

//Added in Actionaz 3.0.1.//

=== Syntax ===
<code javascript>
myObject.findSubImages(otherImage);
</code>
<code javascript>
myObject.findSubImages(otherImage, options);
</code>

=== Arguments ===
  - otherImage - (Image) the Image to find
  - options - (object) search options
    * confidenceMinimum - (integer) the minimum confidence percentage, 100 means perfect match (default: 70)
    * downPyramidCount - (integer) the number of pyramids to use. A pyramid is a subdivision of the image used to accelerate the search. Choose 1 here if the searched image is not very different from this image. (default: 2)
    * searchExpansion - (integer) the number of pixels to shift when searching for another matching image (default: 15)
    * maximumMatches - (integer) the maximal number of matches (default: 10)
    * method - ([[#method|Method]]) the search method to use (default: CorrelationCoefficient) [//Added in Actionaz 3.7.0.//]

=== Returns ===
  * (array of objects) the matching points, or null if no matching point can be found
    * position - ([[en:code:core:point|Point]]) the matching image center
    * confidence - (integer) the confidence percentage

=== Exceptions ===
  * (FindSubImageError) an error occured while searching for a sub-image
  * (ParameterTypeError) incorrect parameter type

=== Example ===
<code javascript>
//Searches for objects on the screen
var screenShot = Image.takeScreenshot();
var imageToFind = new Image("object.png");

var searchResult = screenShot.findSubImages(imageToFind);
if(searchResult)
{
    Console.print("Matching images found\n");
    
    for(var i = 0; i < searchResult.length; ++i)
    {
        Console.print("position: " + searchResult[i].position + ", confidence: " + searchResult[i].confidence + "\n");
    }
}
else
    Console.print("No matching images found.");
</code>
==== findSubImageAsync ====
Searches for another image contained in this one in asynchronous mode.

//Added in Actionaz 3.0.1.//

=== Syntax ===
<code javascript>
myObject.findSubImageAsync(otherImage, callback);
</code>
<code javascript>
myObject.findSubImageAsync(otherImage, callback, options);
</code>

=== Arguments ===
  - otherImage - (Image) the Image to find
  - callback(object) - (function) the function that will be called when the search ends
    * position - ([[en:code:core:point|Point]]) the matching image center
    * confidence - (integer) the confidence percentage
  - options - (object) search options
    * confidenceMinimum - (integer) the minimum confidence percentage, 100 means perfect match (default: 70)
    * downPyramidCount - (integer) the number of pyramids to use. A pyramid is a subdivision of the image used to accelerate the search. Choose 1 here if the searched image is not very different from this image. (default: 2)
    * searchExpansion - (integer) the number of pixels to shift when searching for another matching image (default: 15)
    * method - ([[#method|Method]]) the search method to use (default: CorrelationCoefficient) [//Added in Actionaz 3.7.0.//]

=== Returns ===
  * (Image) this Image

=== Exceptions ===
  * (FindSubImageError) an error occured while searching for a sub-image
  * (ParameterTypeError) incorrect parameter type

=== Example ===
<code javascript>
//Searches for an object on the screen
var screenShot = Image.takeScreenshot();
var imageToFind = new Image("object.png");

screenShot.findSubImageAsync(imageToFind, function(searchResult)
{
    if(searchResult)
        Console.print("Matching image found, position: " + searchResult.position + ", confidence: " + searchResult.confidence);
    else
        Console.print("No matching image found.");
});
</code>
==== findSubImagesAsync ====
Searches for images contained in this one in asynchronous mode.

//Added in Actionaz 3.0.1.//

=== Syntax ===
<code javascript>
myObject.findSubImagesAsync(otherImage, callback);
</code>
<code javascript>
myObject.findSubImagesAsync(otherImage, callback, options);
</code>

=== Arguments ===
  - otherImage - (Image) the Image to find
  - callback(object) - (function) the function that will be called when the search ends
    * position - ([[en:code:core:point|Point]]) the matching image center
    * confidence - (integer) the confidence percentage
  - options - (object) search options
    * confidenceMinimum - (integer) the minimum confidence percentage, 100 means perfect match (default: 70)
    * downPyramidCount - (integer) the number of pyramids to use. A pyramid is a subdivision of the image used to accelerate the search. Choose 1 here if the searched image is not very different from this image. (default: 2)
    * searchExpansion - (integer) the number of pixels to shift when searching for another matching image (default: 15)
    * maximumMatches - (integer) the maximal number of matches (default: 10)
    * method - ([[#method|Method]]) the search method to use (default: CorrelationCoefficient) [//Added in Actionaz 3.7.0.//]

=== Returns ===
  * (Image) this Image

=== Exceptions ===
  * (FindSubImageError) an error occured while searching for a sub-image
  * (ParameterTypeError) incorrect parameter type

=== Example ===
<code javascript>
//Searches for objects on the screen
var screenShot = Image.takeScreenshot();
var imageToFind = new Image("object.png");

screenShot.findSubImagesAsync(imageToFind, function(searchResult)
{
    if(searchResult)
    {
        Console.print("Matching images found\n");
    
        for(var i = 0; i < searchResult.length; ++i)
        {
            Console.print("position: " + searchResult[i].position + ", confidence: " + searchResult[i].confidence + "\n");
        }
    }
    else
        Console.print("No matching images found.");
});
</code>
===== Enumerations =====

==== Filter ====
Image filters.

=== Values ===
  - ConvolutionFilter: the convolution filter
  - GaussianBlur: a gaussian blur
  - Defocus: blurs the image
  - Highlight: highlight the image
  - Sharpen: sharpens the image
  - SharpenMore: sharpens the image
  - SharpenEvenMore: sharpens the image
  - EdgeDetect: edge detection filter
  - BigEdge: edge detection filter (thicker edges)
  - Emboss: embosses the image (no color preservation)
  - EmbossColor: embosses the image (color preservation)
  - Negative: negates a color channel
  - RemoveChannel: remove a color channel
  - Punch: distorts the image

==== MirrorOrientation ====
Mirror orientation.

=== Values ===
  - Vertical: a vertical mirror
  - Horizontal: an horizontal mirror

==== Method ====
Search method. [//Added in Actionaz 3.7.0.//]

=== Values ===
  - CorrelationCoefficient: correlation coefficient, best for most use cases
  - CrossCorrelation: cross correlation
  - SquaredDifference: squared difference