Package org.sikuli.script

Class Image

java.lang.Object
org.sikuli.script.Element
org.sikuli.script.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 Details

  • Constructor Details

    • 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 Details

    • 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

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • 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)

    • setBimg

      public Image setBimg​(BufferedImage bimg)

    • getSubimage

      public static BufferedImage getSubimage​(BufferedImage bimg, Rectangle rect)

    • createSubimage

      public static BufferedImage createSubimage​(BufferedImage bimg, Rectangle rect)

    • 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​(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​(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)

    • getNameAsText

      public String getNameAsText()

    • 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​(Region reg)

    • 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()

    • purge

      public static void purge​(ImagePath.PathEntry path)

    • 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)

    • save

      public void save​(String name, String path)

    • 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