Package org.sikuli.script

Class Image

  • public class Image
extends Element
    This class hides the complexity behind image names given as string.
    Image does not have public nor public constructors: use create()
    It's companion is ImagePath that maintains a list of places, where image files are loaded from.
    An Image object:
    - has a name, either given or taken from the basename
    - keeps it's in memory buffered image in a configurable cache avoiding reload from source
    - remembers, where it was found when searched the last time
    - can be sourced from the filesystem, from jars, from the web and from other in memory images
    - will have features for basic image manipulation and presentation
    - contains the stuff to communicate with the underlying OpenCV based search engine

    This class maintains
    - a list of all images ever loaded in this session with their source reference and a ref to the image object
    - a list of all images currently having their content in memory (buffered image) (managed as a configurable cache)
    The caching can be configured using Settings.setImageCache(int)

    • Field Detail

      • wasRecaptured

        public boolean wasRecaptured

    • Constructor Detail

      • Image

        public Image​(BufferedImage img)
        create a new image from a buffered image
        can only be reused with the object reference
        Parameters:
        img - BufferedImage

      • Image

        public Image​(BufferedImage img,
             String name)
        create a new image from a buffered image
        giving it a descriptive name for printout and logging
        can only be reused with the object reference
        Parameters:
        img - BufferedImage
        name - descriptive name

      • Image

        public Image​(ScreenImage img)
        create a new image from a Sikuli ScreenImage (captured)
        can only be reused with the object reference
        Parameters:
        img - ScreenImage

      • Image

        public Image​(ScreenImage img,
             String name)
        create a new image from a Sikuli ScreenImage (captured)
        giving it a descriptive name for printout and logging
        can only be reused with the object reference
        Parameters:
        img - ScreenImage
        name - descriptive name

    • Method Detail

      • getDefaultInstance4py

        public static Image getDefaultInstance4py()

      • reinit

        public static void reinit​(Image img)

      • isValid

        public boolean isValid()
        check whether image is available for Finder.find()
        This is for backward compatibility
        The new ImageFinder uses isUsable()
        Returns:
        true if lodable from file or is an in memory image

      • isUseable

        public boolean isUseable()
        checks, wether the Image can be used with the new ImageFinder
        Returns:
        true/false

      • getFilename

        public String getFilename()
        Returns:
        the image's absolute filename or null if jar, http or in memory image

      • hasIOException

        public boolean hasIOException()

      • setHasIOException

        public void setHasIOException​(boolean state)

      • getURL

        public URL getURL()
        Returns:
        the evaluated url for this image (might be null)

      • setFileURL

        public Image setFileURL​(URL fileURL)

      • isFile

        public boolean isFile()

      • isAbsolute

        public boolean isAbsolute()
        Returns:
        true if image was given with absolute filepath

      • setIsAbsolute

        public Image setIsAbsolute​(boolean val)

      • get

        public BufferedImage get()
        return the image's BufferedImage (load it if not in cache)
        Returns:
        BufferedImage (might be null)

      • getSize

        public Dimension getSize()
        Returns:
        size of image

      • resize

        public BufferedImage resize​(float factor)
        resize the loaded image with factor using OpenCV ImgProc.resize()

        Uses CUBIC as the interpolation algorithm.

        Parameters:
        factor - resize factor
        Returns:
        a new BufferedImage resized (width*factor, height*factor)

      • resize

        public BufferedImage resize​(float factor,
                            Image.Interpolation interpolation)
        resize the loaded image with factor using OpenCV ImgProc.resize()
        Parameters:
        factor - resize factor
        interpolation - algorithm used for pixel interpolation
        Returns:
        a new BufferedImage resized (width*factor, height*factor)

      • resize

        public static BufferedImage resize​(BufferedImage bimg,
                                   float factor)
        resize the given image with factor using OpenCV ImgProc.resize()

        Uses CUBIC as the interpolation algorithm.

        Parameters:
        bimg - given image
        factor - resize factor
        Returns:
        a new BufferedImage resized (width*factor, height*factor)

      • resize

        public static BufferedImage resize​(BufferedImage bimg,
                                   float factor,
                                   Image.Interpolation interpolation)
        resize the given image with factor using OpenCV ImgProc.resize()
        Parameters:
        bimg - given image
        factor - resize factor
        interpolation - algorithm used for pixel interpolation
        Returns:
        a new BufferedImage resized (width*factor, height*factor)

      • resize

        public static void resize​(org.opencv.core.Mat mat,
                          float factor)
        resize the given image (as cvMat in place) with factor using OpenCV ImgProc.resize()

        Uses CUBIC as the interpolation algorithm.

        Parameters:
        mat - given image as cvMat
        factor - resize factor

      • resize

        public static void resize​(org.opencv.core.Mat mat,
                          float factor,
                          Image.Interpolation interpolation)
        resize the given image (as cvMat in place) with factor using OpenCV ImgProc.resize()
        Parameters:
        mat - given image as cvMat
        factor - resize factor
        interpolation - algorithm used for pixel interpolation.

      • isText

        public boolean isText()
        Returns:
        true if the given image name did not give a valid image so it might be text to search

      • setIsText

        public Image setIsText​(boolean val)

      • getNameGiven

        public String getNameGiven()

      • isBundled

        public boolean isBundled()
        INTERNAL USE: image is contained in a bundle (.sikuli)
        Returns:
        true/false

      • isPattern

        public boolean isPattern()
        true if this image contains pattern aspects
        only useable with the new ImageFinder
        Returns:
        true if yes, false otherwise

      • setIsPattern

        public Image setIsPattern​(boolean imageIsPattern)

      • getOffset

        public Location getOffset()
        Get the value of offset
        Returns:
        the value of offset

      • setOffset

        public Image setOffset​(Location offset)
        Set the value of offset
        Parameters:
        offset - new value of offset
        Returns:
        the image

      • getSimilarity

        public double getSimilarity()
        Get the value of similarity
        Returns:
        the value of similarity

      • setSimilarity

        public Image setSimilarity​(double similarity)
        Set the value of similarity
        Parameters:
        similarity - new value of similarity
        Returns:
        the image

      • getSub

        public Image getSub​(int part)
        create a sub image from this image
        Parameters:
        part - (the constants Region.XXX as used with Region.get(int))
        Returns:
        the sub image

      • getSub

        public Image getSub​(int x,
                    int y,
                    int w,
                    int h)
        create a sub image from this image
        Parameters:
        x - pixel column
        y - pixel row
        w - width
        h - height
        Returns:
        the new image

      • create

        public static Image create​(Image imgSrc)
        create a new Image as copy of the given Image
        Parameters:
        imgSrc - given Image
        Returns:
        new Image

      • create

        public static Image create​(String fName)
        create a new image from a filename
        file ending .png is added if missing (currently valid: png, jpg, jpeg)
        relative filename: [...path.../]name[.png] is searched on current image path
        absolute filename is taken as is if image exists, it is loaded to cache
        already loaded image with same name (given path) is reused (taken from cache)

        if image not found, it might be a text to be searched (imageIsText = true)

        Parameters:
        fName - image filename
        Returns:
        an Image object (might not be valid - check with isValid())

      • create

        public static Image create​(File imageFile)
        create a new image from the given file
        file ending .png is added if missing (currently valid: png, jpg, jpeg)
        relative filename: [...path.../]name[.png] is searched on current image path
        absolute filename is taken as is if image exists, it is loaded to cache
        already loaded image with same name (given path) is reused (taken from cache)

        if image not found, it might be a text to be searched (imageIsText = true)

        Parameters:
        imageFile - a Java File object
        Returns:
        an Image object (might not be valid - check with isValid())

      • create

        public static Image create​(Pattern p)
        create a new Image with Pattern aspects from an existing Pattern
        Parameters:
        p - a Pattern
        Returns:
        the new Image

      • create

        public static Image create​(URL url)
        create a new image from the given url
        file ending .png is added if missing
        filename: ...url-path.../name[.png] is loaded from the url and and cached
        already loaded image with same url is reused (reference) and taken from cache
        Parameters:
        url - image file URL
        Returns:
        the image

      • createThumbNail

        public static Image createThumbNail​(String fName)
        FOR INTERNAL USE: from IDE - suppresses load error message
        Parameters:
        fName - image filename
        Returns:
        this

      • isValidImageFilename

        public static boolean isValidImageFilename​(String fname)

      • getValidImageFilename

        public static String getValidImageFilename​(String fname)

      • clearCache

        public static void clearCache​(int maxSize)

      • purge

        public static void purge()

      • unCache

        public static void unCache​(String fileName)

      • dump

        public static void dump()
        Print the current state of the cache

      • dump

        public static void dump​(int lvl)
        Print the current state of the cache, verbosity depends on debug level
        Parameters:
        lvl - debug level used here

      • reset

        public static void reset()
        clears all caches (should only be needed for debugging)

      • remove

        public File remove()

      • delete

        public void delete()

      • backup

        public boolean backup()

      • restore

        public boolean restore()

      • reload

        public static void reload​(String fpImage)

      • setIDEshouldReload

        public static void setIDEshouldReload​(Image img)

      • getIDEshouldReload

        public static boolean getIDEshouldReload()

      • isRecaptured

        public boolean isRecaptured()

      • save

        public void save​(String name)

      • getWaitAfter

        public int getWaitAfter()
        Get the value of waitAfter
        Returns:
        the value of waitAfter

      • setWaitAfter

        public Image setWaitAfter​(int waitAfter)
        Set the value of waitAfter
        Parameters:
        waitAfter - new value of waitAfter
        Returns:
        the image

      • getLastSeen

        public Rectangle getLastSeen()
        if the image was already found before
        Returns:
        the rectangle where it was found

      • getLastSeenScore

        public double getLastSeenScore()
        if the image was already found before
        Returns:
        the similarity score

      • setLastSeen

        public Image setLastSeen​(Rectangle lastSeen,
                         double sim)
        Internal Use: set the last seen info after a find
        Parameters:
        lastSeen - Match
        sim - SimilarityScore
        Returns:
        the image

      • setRows

        public Image setRows​(int n)
        store info: this image is divided vertically into n even rows
        a preparation for using getRow()
        Parameters:
        n - number of rows
        Returns:
        the top row

      • setCols

        public Image setCols​(int n)
        store info: this image is divided horizontally into n even columns
        a preparation for using getCol()
        Parameters:
        n - number of Columns
        Returns:
        the leftmost column

      • getRows

        public int getRows()
        Returns:
        number of eventually defined rows in this image or 0

      • getRowH

        public int getRowH()
        Returns:
        height of eventually defined rows in this image or 0

      • getCols

        public int getCols()
        Returns:
        number of eventually defined columns in this image or 0

      • getColW

        public int getColW()
        Returns:
        width of eventually defined columns in this image or 0

      • setRaster

        public Image setRaster​(int r,
                       int c)
        store info: this image is divided into a raster of even cells
        a preparation for using getCell()
        Parameters:
        r - number of rows
        c - number of columns
        Returns:
        the top left cell

      • getRow

        public Image getRow​(int r)
        get the specified row counting from 0, if rows or raster are setup
        negative counts reverse from the end (last = -1)
        values outside range are 0 or last respectively
        Parameters:
        r - row number
        Returns:
        the row as new image or the image itself, if no rows are setup

      • getCol

        public Image getCol​(int c)
        get the specified column counting from 0, if columns or raster are setup
        negative counts reverse from the end (last = -1)
        values outside range are 0 or last respectively
        Parameters:
        c - column number
        Returns:
        the column as new image or the image itself, if no columns are setup

      • getCell

        public Image getCell​(int r,
                     int c)
        get the specified cell counting from (0, 0), if a raster is setup
        negative counts reverse from the end (last = -1)
        values outside range are 0 or last respectively
        Parameters:
        r - row number
        c - column number
        Returns:
        the cell as new image or the image itself, if no raster is setup

      • text

        public static String text​(String imgFile)
        convenience method: get text from given image file
        Parameters:
        imgFile - image filename
        Returns:
        the text or null

      • textLine

        public static String textLine​(String imgFile)
        convenience method: get text from given image file supposing it is one line of text
        Parameters:
        imgFile - image filename
        Returns:
        the text or empty string

      • textWord

        public static String textWord​(String imgFile)
        convenience method: get text from given image file supposing it is one word
        Parameters:
        imgFile - image filename
        Returns:
        the text or empty string

      • textChar

        public static String textChar​(String imgFile)
        convenience method: get text from given image file supposing it is one character
        Parameters:
        imgFile - image filename
        Returns:
        the text or empty string