SimpleCV Package

SimpleCV Package

Camera Module

class SimpleCV.Camera.AVTCamera(camera_id=-1, properties={}, threaded=False)

Bases: SimpleCV.Camera.FrameSource

SUMMARY AVTCamera is a ctypes wrapper for the Prosilica/Allied Vision cameras, such as the “manta” series.

These require the PvAVT binary driver from Allied Vision: http://www.alliedvisiontec.com/us/products/1108.html

Note that as of time of writing the new VIMBA driver is not available for Mac/Linux - so this uses the legacy PvAVT drive

Props to Cixelyn, whos py-avt-pvapi module showed how to get much of this working https://bitbucket.org/Cixelyn/py-avt-pvapi

All camera properties are directly from the PvAVT manual – if not specified it will default to whatever the camera state is. Cameras can either by

EXAMPLE >>> cam = AVTCamera(0, {“width”: 656, “height”: 492}) >>> >>> img = cam.getImage() >>> img.show()

class AVTCameraInfo

Bases: _ctypes.Structure

AVTCameraInfo is an internal ctypes.Structure-derived class which contains metadata about cameras on the local network.

Properties include: * UniqueId * CameraName * ModelName * PartNumber * SerialNumber * FirmwareVersion * PermittedAccess * InterfaceId * InterfaceType

CameraName

Structure/Union member

FirmwareVersion

Structure/Union member

InterfaceId

Structure/Union member

InterfaceType

Structure/Union member

ModelName

Structure/Union member

PartNumber

Structure/Union member

PermittedAccess

Structure/Union member

SerialNumber

Structure/Union member

StructVer

Structure/Union member

UniqueId

Structure/Union member

class AVTCamera.AVTFrame(buffersize)

Bases: _ctypes.Structure

AncillaryBuffer

Structure/Union member

AncillaryBufferSize

Structure/Union member

AncillarySize

Structure/Union member

BayerPattern

Structure/Union member

BitDepth

Structure/Union member

Context

Structure/Union member

Format

Structure/Union member

FrameCount

Structure/Union member

Height

Structure/Union member

ImageBuffer

Structure/Union member

ImageBufferSize

Structure/Union member

ImageSize

Structure/Union member

RegionX

Structure/Union member

RegionY

Structure/Union member

Status

Structure/Union member

TimestampHi

Structure/Union member

TimestampLo

Structure/Union member

Width

Structure/Union member

AVTCamera.getAllProperties()

SUMMARY This returns a dict with the name and current value of the documented PvAVT attributes

CAVEAT: it addresses each of the properties individually, so this may take time to run if there’s network latency

EXAMPLE >>>c = AVTCamera(0) >>>props = c.getAllProperties() >>>print props[‘ExposureValue’]

AVTCamera.getImage()

SUMMARY Extract an Image from the Camera, returning the value. No matter what the image characteristics on the camera, the Image returned will be RGB 8 bit depth, if camera is in greyscale mode it will be 3 identical channels.

EXAMPLE >>>c = AVTCamera() >>>c.getImage().show()

AVTCamera.getProperty(name)

SUMMARY This retrieves the value of the AVT Camera attribute

There are around 140 properties for the AVT Camera, so reference the AVT Camera and Driver Attributes pdf that is provided with the driver for detailed information

Note that the error codes are currently ignored, so empty values may be returned.

EXAMPLE >>>c = AVTCamera() >>>print c.getProperty(“ExposureValue”)

AVTCamera.listAllCameras()

SUMMARY List all cameras attached to the host

RETURNS List of AVTCameraInfo objects, otherwise empty list

AVTCamera.restart()

This tries to restart the camera thread

AVTCamera.runCommand(command)

SUMMARY Runs a PvAVT Command on the camera

Valid Commands include: * FrameStartTriggerSoftware * AcquisitionAbort * AcquisitionStart * AcquisitionStop * ConfigFileLoad * ConfigFileSave * TimeStampReset * TimeStampValueLatch

RETURNS

0 on success

EXAMPLE >>>c = AVTCamera() >>>c.runCommand(“TimeStampReset”)

AVTCamera.setProperty(name, value, skip_buffer_size_check=False)

SUMMARY This sets the value of the AVT Camera attribute.

There are around 140 properties for the AVT Camera, so reference the AVT Camera and Driver Attributes pdf that is provided with the driver for detailed information

By default, we will also refresh the height/width and bytes per frame we’re expecting – you can manually bypass this if you want speed

Returns the raw PvAVT error code (0 = success)

Example >>>c = AVTCamera() >>>c.setProperty(“ExposureValue”, 30000) >>>c.getImage().show()

AVTCamera.setupASyncMode()
AVTCamera.setupSyncMode()
AVTCamera.threaded = False
AVTCamera.unbuffer()
class SimpleCV.Camera.AVTCameraThread(camera)

Bases: threading.Thread

camera = None
framerate = 0
lock = None
logger = None
run()
stop()
stopped()
verbose = False
class SimpleCV.Camera.Camera(camera_index=-1, prop_set={}, threaded=True, calibrationfile='')

Bases: SimpleCV.Camera.FrameSource

SUMMARY

The Camera class is the class for managing input from a basic camera. Note that once the camera is initialized, it will be locked from being used by other processes. You can check manually if you have compatible devices on linux by looking for /dev/video* devices.

This class wrappers OpenCV’s cvCapture class and associated methods. Read up on OpenCV’s CaptureFromCAM method for more details if you need finer control than just basic frame retrieval

capture = ''
getAllProperties()

SUMMARY

Return all properties from the camera.

RETURNS

A dict of all the camera properties.

getImage()

SUMMARY

Retrieve an Image-object from the camera. If you experience problems with stale frames from the camera’s hardware buffer, increase the flushcache number to dequeue multiple frames before retrieval

We’re working on how to solve this problem.

RETURNS

A SimpleCV Image from the camera.

EXAMPLES

>>> cam = Camera()
>>> while True:
>>>    cam.getImage().show()
getProperty(prop)

SUMMARY

Retrieve the value of a given property, wrapper for cv.GetCaptureProperty

Warning

For most web cameras only the width and height properties are supported. Support for all of the other parameters varies by camera and operating system.

PARAMETERS

  • prop - The property to retrive.

RETURNS

The specified property. If it can’t be found the method returns False.

EXAMPLE

>>> cam = Camera()
>>> prop = cam.getProperty("width")
prop_map = {'width': 3, 'saturation': 12, 'gain': 14, 'brightness': 10, 'exposure': 15, 'hue': 13, 'contrast': 11, 'height': 4}
pygame_buffer = ''
pygame_camera = False
thread = ''
class SimpleCV.Camera.DigitalCamera(id=0)

Bases: SimpleCV.Camera.FrameSource

SUMMARY

The DigitalCamera takes a point-and-shoot camera or high-end slr and uses it as a Camera. The current frame can always be accessed with getPreview()

Requires the PiggyPhoto Library: https://github.com/alexdu/piggyphoto

EXAMPLE

>>> cam = DigitalCamera()
>>> pre = cam.getPreview()
>>> pre.findBlobs().show()
>>>
>>> img = cam.getImage()
>>> img.show()
camera = None
device = None
getImage()

SUMMARY

Retrieve an Image-object from the camera with the highest quality possible. RETURNS

A SimpleCV Image.

EXAMPLES >>> cam = DigitalCamera() >>> cam.getImage().show()

getPreview()

SUMMARY

Retrieve an Image-object from the camera with the preview quality from the camera. RETURNS

A SimpleCV Image.

EXAMPLES >>> cam = DigitalCamera() >>> cam.getPreview().show()

usbid = None
class SimpleCV.Camera.FrameBufferThread(group=None, target=None, name=None, args=(), kwargs=None, verbose=None)

Bases: threading.Thread

SUMMARY

This is a helper thread which continually debuffers the camera frames. If you don’t do this, cameras may constantly give you a frame behind, which causes problems at low sample rates. This makes sure the frames returned by your camera are fresh.

run()
class SimpleCV.Camera.FrameSource

SUMMARY

An abstract Camera-type class, for handling multiple types of video input. Any sources of images inheirit from it

calibrate(imageList, grid_sz=0.03, dimensions=(8, 5))

SUMMARY

Camera calibration will help remove distortion and fisheye effects It is agnostic of the imagery source, and can be used with any camera

The easiest way to run calibration is to run the calibrate.py file under the tools directory for SimpleCV. This will walk you through the calibration process.

PARAMETERS

  • imageList - is a list of images of color calibration images.
  • grid_sz - is the actual grid size of the calibration grid, the unit used will be the calibration unit value (i.e. if in doubt use meters, or U.S. standard)
  • dimensions - is the the count of the interior corners in the calibration grid. So for a grid where there are 4x4 black grid squares has seven interior corners.

RETURNS

The camera’s intrinsic matrix.

EXAMPLE

See :py:module:calibrate.py

capturetime = ''
getAllProperties()
getCameraMatrix()

SUMMARY

This function returns a cvMat of the camera’s intrinsic matrix. If there is no matrix defined the function returns None.

getImage()
getImageUndistort()

SUMMARY

Using the overridden getImage method we retrieve the image and apply the undistortion operation.

RETURNS

The latest image from the camera after applying undistortion.

EXAMPLE

>>> cam = Camera()
>>> cam.loadCalibration("mycam.xml")
>>> while True:
>>>    img = cam.getImageUndistort()
>>>    img.show()
getProperty(p)
live()

SUMMARY

This shows a live view of the camera.

EXAMPLE

To use it’s as simple as:

>>> cam = Camera()
>>> cam.live()

Left click will show mouse coordinates and color Right click will kill the live image

loadCalibration(filename)

SUMMARY

Load a calibration matrix from file. The filename should be the stem of the calibration files names. e.g. If the calibration files are MyWebcamIntrinsic.xml and MyWebcamDistortion.xml then load the calibration file “MyWebcam”

PARAMETERS

  • filename - The file name, without an extension, to which to save the calibration data.

RETURNS

Returns true if the file was loaded , false otherwise.

EXAMPLE

See :py:module:calibrate.py

saveCalibration(filename)

SUMMARY

Save the calibration matrices to file. The file name should be without the extension. The default extension is .xml.

PARAMETERS

  • filename - The file name, without an extension, to which to save the calibration data.

RETURNS

Returns true if the file was saved , false otherwise.

EXAMPLE

See :py:module:calibrate.py

undistort(image_or_2darray)

SUMMARY

If given an image, apply the undistortion given by the camera’s matrix and return the result.

If given a 1xN 2D cvmat or a 2xN numpy array, it will un-distort points of measurement and return them in the original coordinate system.

PARAMETERS

  • image_or_2darray - an image or an ndarray.

RETURNS

The undistorted image or the undistorted points. If the camera is un-calibrated we return None.

EXAMPLE

>>> img = cam.getImage()
>>> result = cam.undistort(img)
class SimpleCV.Camera.JpegStreamCamera(url)

Bases: SimpleCV.Camera.FrameSource

SUMMARY

The JpegStreamCamera takes a URL of a JPEG stream and treats it like a camera. The current frame can always be accessed with getImage()

Requires the Python Imaging Library: http://www.pythonware.com/library/pil/handbook/index.htm

EXAMPLE

Using your Android Phone as a Camera. Softwares like IP Webcam can be used.

>>> cam = JpegStreamCamera("http://192.168.65.101:8080/videofeed") # your IP may be different.
>>> img = cam.getImage()
>>> img.show()
camthread = ''
getImage()

SUMMARY

Return the current frame of the JpegStream being monitored

url = ''
class SimpleCV.Camera.JpegStreamReader(group=None, target=None, name=None, args=(), kwargs=None, verbose=None)

Bases: threading.Thread

SUMMARY

A Threaded class for pulling down JPEG streams and breaking up the images. This is handy for reading the stream of images from a IP CAmera.

currentframe = ''
run()
url = ''
class SimpleCV.Camera.Kinect(device_number=0)

Bases: SimpleCV.Camera.FrameSource

SUMMARY

This is an experimental wrapper for the Freenect python libraries you can getImage() and getDepth() for separate channel images

getDepth()

SUMMARY

This method returns the Kinect depth image.

RETURNS

The Kinect’s depth camera image as a grayscale image.

EXAMPLE

>>> k = Kinect()
>>> while True:
>>>   d = k.getDepth()
>>>   img = k.getImage()
>>>   result = img.sideBySide(d)
>>>   result.show()
getDepthMatrix()
getImage()

SUMMARY

This method returns the Kinect camera image.

RETURNS

The Kinect’s color camera image.

EXAMPLE

>>> k = Kinect()
>>> while True:
>>>   k.getImage().show()
class SimpleCV.Camera.Scanner(id=0, properties={'mode': 'color'})

Bases: SimpleCV.Camera.FrameSource

SUMMARY

The Scanner lets you use any supported SANE-compatable scanner as a SimpleCV camera List of supported devices: http://www.sane-project.org/sane-supported-devices.html

Requires the PySANE wrapper for libsane. The sane scanner object is available for direct manipulation at Scanner.device

This scanner object is heavily modified from https://bitbucket.org/DavidVilla/pysane

Constructor takes an index (default 0) and a list of SANE options (default is color mode).

EXAMPLE

>>> scan = Scanner(0, { "mode": "gray" })
>>> preview = scan.getPreview()
>>> stuff = preview.findBlobs(minsize = 1000)
>>> topleft = (np.min(stuff.x()), np.min(stuff.y()))
>>> bottomright = (np.max(stuff.x()), np.max(stuff.y()))
>>> scan.setROI(topleft, bottomright)
>>> scan.setProperty("resolution", 1200) #set high resolution
>>> scan.setProperty("mode", "color")
>>> img = scan.getImage()
>>> scan.setROI() #reset region of interest
>>> img.show()
device = None
getAllProperties()

SUMMARY

Return a list of all properties and values from the scanner RETURNS

Dictionary of active options and values. Inactive options appear as “None”

EXAMPLES >>> scan = Scanner() >>> print scan.getAllProperties()

getImage()

SUMMARY

Retrieve an Image-object from the scanner. Any ROI set with setROI() is taken into account. RETURNS

A SimpleCV Image. Note that whatever the scanner mode is, SimpleCV will return a 3-channel, 8-bit image.

EXAMPLES >>> scan = Scanner() >>> scan.getImage().show()

getPreview()

SUMMARY

Retrieve a preview-quality Image-object from the scanner. RETURNS

A SimpleCV Image. Note that whatever the scanner mode is, SimpleCV will return a 3-channel, 8-bit image.

EXAMPLES >>> scan = Scanner() >>> scan.getPreview().show()

getProperty(prop)

SUMMARY Returns a single property value from the SANE device equivalent to Scanner.device.PROPERTY

RETURNS Value for option or None if missing/inactive

EXAMPLES >>> scan = Scanner() >>> print scan.getProperty(‘mode’) color

kind = None
manufacturer = None
max_x = None
max_y = None
model = None
printProperties()

SUMMARY

Print detailed information about the SANE device properties RETURNS

Nothing

EXAMPLES >>> scan = Scanner() >>> scan.printProperties()

px2mm(pixels=1)

SUMMARY Helper function to convert native scanner resolution to millimeter units

RETURNS Float value

EXAMPLES >>> scan = Scanner() >>> scan.px2mm(scan.device.resolution) #return DPI in DPMM

setProperty(prop, val)

SUMMARY Assigns a property value from the SANE device equivalent to Scanner.device.PROPERTY = VALUE

RETURNS None

EXAMPLES >>> scan = Scanner() >>> print scan.getProperty(‘mode’) color >>> scan.setProperty(“mode”) = “gray”

setROI(topleft=(0, 0), bottomright=(-1, -1))

SUMMARY Sets an ROI for the scanner in the current resolution. The two parameters, topleft and bottomright, will default to the device extents, so the ROI can be reset by calling setROI with no parameters.

The ROI is set by SANE in resolution independent units (default MM) so resolution can be changed after ROI has been set.

RETURNS None

EXAMPLES >>> scan = Scanner() >>> scan.setROI((50, 50), (100,100)) >>> scan.getImage().show() # a very small crop on the scanner

usbid = None
class SimpleCV.Camera.ScreenCamera

SUMMARY ScreenCapture is a camera class would allow you to capture all or part of the screen and return it as a color image.

Requires the pyscreenshot Library: https://github.com/vijaym123/pyscreenshot

EXAMPLE >>> sc = ScreenCamera() >>> res = sc.getResolution() >>> print res >>> >>> img = sc.getImage() >>> img.show()

getImage()

DESCRIPTION

getImage function returns a Image object capturing the current screenshot of the screen.

PARAMETERS None

RETURNS Returns the region of interest if setROI is used. else returns the original capture of the screenshot.

EXAMPLE >>> sc = ScreenCamera() >>> img = sc.getImage() >>> img.show()

getResolution()

DESCRIPTION

returns the resolution of the screenshot of the screen.

PARAMETERS None

RETURNS returns the resolution.

EXAMPLE

>>> img = ScreenCamera()
>>> res = img.getResolution()
>>> print res
setROI(roi)

DESCRIPTION To set the region of interest.

PARAMETERS * roi - tuple - It is a tuple of size 4. where region of interest is to the center of the screen.

RETURNS None

EXAMPLE >>> sc = ScreenCamera() >>> res = sc.getResolution() >>> sc.setROI(res[0]/4,res[1]/4,res[0]/2,res[1]/2) >>> img = sc.getImage() >>> s.show()

class SimpleCV.Camera.StereoCamera

Stereo Camera is a class dedicated for calibration stereo camera. It also has functionalites for rectification and getting undistorted Images.

This class can be used to calculate various parameters related to both the camera’s :
-> Camera Matrix -> Distortion coefficients -> Rotation and Translation matrix -> Rectification transform (rotation matrix) -> Projection matrix in the new (rectified) coordinate systems -> Disparity-to-depth mapping matrix (Q)
get3DImage(leftIndex, rightIndex, Q, method='BM', state=None)

SUMMARY

This method returns the 3D depth image using reprojectImageTo3D method.

PARAMETERS

  • leftIndex - Index of left camera

  • rightIndex - Index of right camera

  • Q - reprojection Matrix (disparity to depth matrix)

  • method - Stereo Correspondonce method to be used.
    • “BM” - Stereo BM
    • “SGBM” - Stereo SGBM
  • state - dictionary corresponding to parameters of

    stereo correspondonce. SADWindowSize - odd int nDisparity - int minDisparity - int preFilterCap - int preFilterType - int (only BM) speckleRange - int speckleWindowSize - int P1 - int (only SGBM) P2 - int (only SGBM) fullDP - Bool (only SGBM) uniquenessRatio - int textureThreshold - int (only BM)

RETURNS

SimpleCV.Image representing 3D depth Image also StereoCamera.Image3D gives OpenCV 3D Depth Image of CV_32F type.

EXAMPLE

>>> lImage = Image("l.jpg")
>>> rImage = Image("r.jpg")
>>> stereo = StereoCamera()
>>> Q = cv.Load("Q.yml")
>>> stereo.get3DImage(1, 2, Q).show()
>>> state = {"SADWindowSize":9, "nDisparity":112, "minDisparity":-39}
>>> stereo.get3DImage(1, 2, Q, "BM", state).show()
>>> stereo.get3DImage(1, 2, Q, "SGBM", state).show()
getImagesUndistort(imgLeft, imgRight, calibration, rectification, WinSize=(352, 288))

SUMMARY Rectify two images from the calibration and rectification parameters.

PARAMETERS * imgLeft - Image captured from left camera and needs to be rectified. * imgRight - Image captures from right camera and need to be rectified. * calibration - A calibration tuple of the format (CM1, CM2, D1, D2, R, T, E, F) * rectification - A rectification tuple of the format (R1, R2, P1, P2, Q, roi)

RETURNS returns rectified images in a tuple -> (imgLeft,imgRight) >>> StereoCam = StereoCamera() >>> calibration = StereoCam.loadCalibration(fname=”Stereo1”) >>> rectification = StereoCam.stereoRectify(loadedCalibration) >>> imgLeft = camLeft.getImage() >>> imgRight = camRight.getImage() >>> rectLeft,rectRight = StereoCam.getImagesUndistort(imgLeft,imgRight,calibration,rectification)

loadCalibration(fname='Stereo', dir='.')

SUMMARY

loadCalibration is a method to load the StereoCalibration parameters such as CM1, CM2, D1, D2, R, T, E, F of stereo pair. This method loads from calibration files and return calibration on success else return false.

PARAMETERS

fname - is the prefix of the calibration files. dir - is the directory in which files are present.

RETURNS

a tuple of the form (CM1, CM2, D1, D2, R, T, E, F) on success. CM1 - Camera Matrix for left camera CM2 - Camera Matrix for right camera D1 - Vector of distortion coefficients for left camera D2 - Vector of distortion coefficients for right camera R - Rotation matrix between the left and the right camera coordinate systems T - Translation vector between the left and the right coordinate systems of the cameras E - Essential matrix F - Fundamental matrix else returns false

EXAMPLE

>>> StereoCam = StereoCamera()
>>> loadedCalibration = StereoCam.loadCalibration(fname="Stereo1")
saveCalibration(calibration=None, fname='Stereo', cdir='.')

SUMMARY

saveCalibration is a method to save the StereoCalibration parameters such as CM1, CM2, D1, D2, R, T, E, F of stereo pair. This method returns True on success and saves the calibration in the following format. StereoCM1.txt StereoCM2.txt StereoD1.txt StereoD2.txt StereoR.txt StereoT.txt StereoE.txt StereoF.txt

PARAMETERS

calibration - is a tuple os the form (CM1, CM2, D1, D2, R, T, E, F) CM1 -> Camera Matrix for left camera, CM2 -> Camera Matrix for right camera, D1 -> Vector of distortion coefficients for left camera, D2 -> Vector of distortion coefficients for right camera, R -> Rotation matrix between the left and the right camera coordinate systems, T -> Translation vector between the left and the right coordinate systems of the cameras, E -> Essential matrix, F -> Fundamental matrix

RETURNS

return True on success and saves the calibration files.

EXAMPLE

>>> StereoCam = StereoCamera()
>>> calibration = StereoCam.StereoCalibration(1,2,nboards=40)
>>> StereoCam.saveCalibration(calibration,fname="Stereo1")
stereoCalibration(camLeft, camRight, nboards=30, chessboard=(8, 5), gridsize=0.027, WinSize=(352, 288))

SUMMARY

Stereo Calibration is a way in which you obtain the parameters that will allow you to calculate 3D information of the scene. Once both the camera’s are initialized. Press [Space] once chessboard is identified in both the camera’s. Press [esc] key to exit the calibration process.

PARAMETERS

  • camLeft - Left camera index.
  • camRight - Right camera index.
  • nboards - Number of samples or multiple views of the chessboard in different positions and orientations with your stereo camera.
  • chessboard - A tuple of Cols, Rows in the chessboard (used for calibration).
  • gridsize - chessboard grid size in real units
  • WinSize - This is the window resolution.

RETURNS

A tuple of the form (CM1, CM2, D1, D2, R, T, E, F) on success CM1 - Camera Matrix for left camera, CM2 - Camera Matrix for right camera, D1 - Vector of distortion coefficients for left camera, D2 - Vector of distortion coefficients for right camera, R - Rotation matrix between the left and the right camera coordinate systems, T - Translation vector between the left and the right coordinate systems of the cameras, E - Essential matrix, F - Fundamental matrix

EXAMPLE

>>> StereoCam = StereoCamera()
>>> calibration = StereoCam.StereoCalibration(1,2,nboards=40)

Note

Press space to capture the images.

stereoRectify(calib=None, WinSize=(352, 288))

SUMMARY

Computes rectification transforms for each head of a calibrated stereo camera.

PARAMETERS

calibration - is a tuple os the form (CM1, CM2, D1, D2, R, T, E, F) CM1 - Camera Matrix for left camera, CM2 - Camera Matrix for right camera, D1 - Vector of distortion coefficients for left camera, D2 - Vector of distortion coefficients for right camera, R - Rotation matrix between the left and the right camera coordinate systems, T - Translation vector between the left and the right coordinate systems of the cameras, E - Essential matrix, F - Fundamental matrix

RETURNS

On success returns a a tuple of the format -> (R1, R2, P1, P2, Q, roi) R1 - Rectification transform (rotation matrix) for the left camera. R2 - Rectification transform (rotation matrix) for the right camera. P1 - Projection matrix in the new (rectified) coordinate systems for the left camera. P2 - Projection matrix in the new (rectified) coordinate systems for the right camera. Q - disparity-to-depth mapping matrix.

EXAMPLE

>>> StereoCam = StereoCamera()
>>> calibration = StereoCam.loadCalibration(fname="Stereo1")
>>> rectification = StereoCam.stereoRectify(calibration)
class SimpleCV.Camera.StereoImage(imgLeft, imgRight)

SUMMARY

This class is for binaculor Stereopsis. That is exactrating 3D information from two differing views of a scene(Image). By comparing the two images, the relative depth information can be obtained.

  • Fundamental Matrix : F : a 3 x 3 numpy matrix, is a relationship between any two images of the same scene that constrains where the projection of points from the scene can occur in both images. see : http://en.wikipedia.org/wiki/Fundamental_matrix_(computer_vision)
  • Homography Matrix : H : a 3 x 3 numpy matrix,
  • ptsLeft : The matched points on the left image.
  • ptsRight : The matched points on the right image.

-findDisparityMap and findDepthMap - provides 3D information.

for more information on stereo vision, visit : http://en.wikipedia.org/wiki/Computer_stereo_vision

EXAMPLE >>> img1 = Image(‘sampleimages/stereo_view1.png’) >>> img2 = Image(‘sampleimages/stereo_view2.png’) >>> stereoImg = StereoImage(img1,img2) >>> stereoImg.findDisparityMap(method=”BM”,nDisparity=20).show()

Eline(point, F, whichImage)

SUMMARY

This method returns, line feature object.

PARAMETERS

  • point - Input point (x, y)
  • F - Fundamental matrix.
  • whichImage - Index of the image (1 or 2) that contains the point

RETURNS

epipolar line, in the form of line feature object.

EXAMPLE

>>> img1 = Image("sampleimages/stereo_view1.png")
>>> img2 = Image("sampleimages/stereo_view2.png")
>>> stereoImg = StereoImage(img1,img2)
>>> F,pts1,pts2 = stereoImg.findFundamentalMat()
>>> point = pts2[0]
>>> epiline = mapper.Eline(point,F, 1) #find corresponding Epipolar line in the left image.
findDisparityMap(nDisparity=16, method='BM')

The method generates disparity map from set of stereo images.

PARAMETERS

  • method :

    BM - Block Matching algorithm, this is a real time algorithm. SGBM - Semi Global Block Matching algorithm, this is not a real time algorithm. GC - Graph Cut algorithm, This is not a real time algorithm.

  • nDisparity - Maximum disparity value. This should be multiple of 16

  • scale - Scale factor

RETURNS

Return None if it fails. Returns Disparity Map Image

EXAMPLE >>> img1 = Image(“sampleimages/stereo_view1.png”) >>> img2 = Image(“sampleimages/stereo_view2.png”) >>> stereoImg = StereoImage(img1,img2) >>> disp = stereoImg.findDisparityMap(method=”BM”)

findFundamentalMat(thresh=500.0, minDist=0.15)

SUMMARY

This method returns the fundamental matrix F such that (P_2).T F P_1 = 0

PARAMETERS

  • thresh - The feature quality metric. This can be any value between about 300 and 500. Higher values should return fewer, but higher quality features.
  • minDist - The value below which the feature correspondence is considered a match. This is the distance between two feature vectors. Good values are between 0.05 and 0.3

RETURNS Return None if it fails. * F - Fundamental matrix as ndarray. * matched_pts1 - the matched points (x, y) in img1 * matched_pts2 - the matched points (x, y) in img2

EXAMPLE >>> img1 = Image(“sampleimages/stereo_view1.png”) >>> img2 = Image(“sampleimages/stereo_view2.png”) >>> stereoImg = StereoImage(img1,img2) >>> F,pts1,pts2 = stereoImg.findFundamentalMat()

NOTE If you deal with the fundamental matrix F directly, be aware of (P_2).T F P_1 = 0 where P_2 and P_1 consist of (y, x, 1)

findHomography(thresh=500.0, minDist=0.15)

SUMMARY

This method returns the homography H such that P2 ~ H P1

PARAMETERS

  • thresh - The feature quality metric. This can be any value between about 300 and 500. Higher values should return fewer, but higher quality features.
  • minDist - The value below which the feature correspondence is considered a match. This is the distance between two feature vectors. Good values are between 0.05 and 0.3

RETURNS

Return None if it fails. * H - homography as ndarray. * matched_pts1 - the matched points (x, y) in img1 * matched_pts2 - the matched points (x, y) in img2

EXAMPLE >>> img1 = Image(“sampleimages/stereo_view1.png”) >>> img2 = Image(“sampleimages/stereo_view2.png”) >>> stereoImg = StereoImage(img1,img2) >>> H,pts1,pts2 = stereoImg.findHomography()

NOTE If you deal with the homography H directly, be aware of P2 ~ H P1 where P2 and P1 consist of (y, x, 1)

get3DImage(Q, method='BM', state=None)

SUMMARY

This method returns the 3D depth image using reprojectImageTo3D method.

PARAMETERS

  • Q - reprojection Matrix (disparity to depth matrix)

  • method - Stereo Correspondonce method to be used.
    • “BM” - Stereo BM
    • “SGBM” - Stereo SGBM
  • state - dictionary corresponding to parameters of

    stereo correspondonce. SADWindowSize - odd int nDisparity - int minDisparity - int preFilterCap - int preFilterType - int (only BM) speckleRange - int speckleWindowSize - int P1 - int (only SGBM) P2 - int (only SGBM) fullDP - Bool (only SGBM) uniquenessRatio - int textureThreshold - int (only BM)

RETURNS

SimpleCV.Image representing 3D depth Image also StereoImage.Image3D gives OpenCV 3D Depth Image of CV_32F type.

EXAMPLE

>>> lImage = Image("l.jpg")
>>> rImage = Image("r.jpg")
>>> stereo = StereoImage(lImage, rImage)
>>> Q = cv.Load("Q.yml")
>>> stereo.get3DImage(Q).show()
>>> state = {"SADWindowSize":9, "nDisparity":112, "minDisparity":-39}
>>> stereo.get3DImage(Q, "BM", state).show()
>>> stereo.get3DImage(Q, "SGBM", state).show()
get3DImageFromDisparity(disparity, Q)

SUMMARY

This method returns the 3D depth image using reprojectImageTo3D method.

PARAMETERS * disparity - Disparity Image * Q - reprojection Matrix (disparity to depth matrix)

RETURNS

SimpleCV.Image representing 3D depth Image also StereoCamera.Image3D gives OpenCV 3D Depth Image of CV_32F type.

EXAMPLE

>>> lImage = Image("l.jpg")
>>> rImage = Image("r.jpg")
>>> stereo = StereoCamera()
>>> Q = cv.Load("Q.yml")
>>> disp = stereo.findDisparityMap()
>>> stereo.get3DImageFromDisparity(disp, Q)
projectPoint(point, H, whichImage)

SUMMARY

This method returns the corresponding point (x, y)

PARAMETERS

  • point - Input point (x, y)

  • whichImage - Index of the image (1 or 2) that contains the point

  • H - Homography that can be estimated

    using StereoCamera.findHomography()

RETURNS

Corresponding point (x, y) as tuple

EXAMPLE

>>> img1 = Image("sampleimages/stereo_view1.png")
>>> img2 = Image("sampleimages/stereo_view2.png")
>>> stereoImg = StereoImage(img1,img2)
>>> F,pts1,pts2 = stereoImg.findFundamentalMat()
>>> point = pts2[0]
>>> projectPoint = stereoImg.projectPoint(point,H ,1) #finds corresponding  point in the left image.
class SimpleCV.Camera.VirtualCamera(s, st, start=1)

Bases: SimpleCV.Camera.FrameSource

SUMMARY

The virtual camera lets you test algorithms or functions by providing a Camera object which is not a physically connected device.

Currently, VirtualCamera supports “image”, “imageset” and “video” source types.

USAGE

  • For image, pass the filename or URL to the image
  • For the video, the filename
  • For imageset, you can pass either a path or a list of [path, extension]
  • For directory you treat a directory to show the latest file, an example would be where a security camera logs images to the directory, calling .getImage() will get the latest in the directory
findLastestImage(directory='.', extension='png')

SUMMARY

This function finds the latest file in a directory with a given extension.

PARAMETERS

directory - The directory you want to load images from (defaults to current directory) extension - The image extension you want to use (defaults to .png)

RETURNS

The filename of the latest image

USAGE

>>> cam = VirtualCamera('imgs/', 'png') #find all .png files in 'img' directory
>>> cam.getImage() # Grab the latest image from that directory
getFrame(frame)

SUMMARY

Get the provided numbered frame from the video source. Available for only video sources.

PARAMETERS

frame - the number of the frame

RETURNS

Image

EXAMPLES

>>> cam = VirtualCamera("filename.avi", "video", 120)
>>> cam.getFrame(400).show()
getFrameNumber()

SUMMARY

Get the current frame number of the video source. Available for only video sources.

RETURNS

  • int - number of the frame

EXAMPLES

>>> cam = VirtualCamera("filename.avi", "video", 120)
>>> i=0
>>> while i<60:
    ... cam.getImage().show()
    ... i+=1
>>> cam.skipFrames(100)
>>> cam.getFrameNumber()
getImage()

SUMMARY

Retrieve an Image-object from the virtual camera. RETURNS

A SimpleCV Image from the camera.

EXAMPLES

>>> cam = VirtualCamera()
>>> while True:
>>>    cam.getImage().show()
lastmtime = 0
rewind(start=None)

SUMMARY

Rewind the Video source back to the given frame. Available for only video sources.

PARAMETERS

start - the number of the frame that you want to rewind to.
if not provided, the video source would be rewound to the starting frame number you provided or rewound to the beginning.

RETURNS

None

EXAMPLES

>>> cam = VirtualCamera("filename.avi", "video", 120)
>>> i=0
>>> while i<60:
    ... cam.getImage().show()
    ... i+=1
>>> cam.rewind()
skipFrames(n)

SUMMARY

Skip n number of frames. Available for only video sources.

PARAMETERS

n - number of frames to be skipped.

RETURNS

None

EXAMPLES

>>> cam = VirtualCamera("filename.avi", "video", 120)
>>> i=0
>>> while i<60:
    ... cam.getImage().show()
    ... i+=1
>>> cam.skipFrames(100)
>>> cam.getImage().show()
source = ''
sourcetype = ''
SimpleCV.Camera.pverr(errcode)

Color Module

class SimpleCV.Color.Color

SUMMARY

Color is a class that stores commonly used colors in a simple and easy to remember format, instead of requiring you to remember a colors specific RGB value.

EXAMPLES

To use the color in your code you type: Color.RED

To use Red, for instance if you want to do a line.draw(Color.RED)

AQUAMARINE = (127, 255, 212)
AZURE = (0, 127, 255)
BACKGROUND = (0, 0, 0)
BEIGE = (245, 245, 220)
BLACK = (0, 0, 0)
BLUE = (0, 0, 255)
CHARCOAL = (70, 70, 70)
CRIMSON = (220, 20, 60)
CYAN = (0, 255, 255)
DEFAULT = (0, 0, 0)
FOREGROUND = (255, 255, 255)
FORESTGREEN = (34, 139, 34)
FUCHSIA = (255, 119, 255)
GOLD = (255, 215, 0)
GRAY = (128, 128, 128)
GREEN = (0, 128, 0)
HOTPINK = (252, 15, 192)
INDIGO = (75, 0, 130)
IVORY = (255, 255, 240)
KHAKI = (195, 176, 145)
LEGO_BLUE = (0, 50, 150)
LEGO_ORANGE = (255, 150, 40)
LIME = (191, 255, 0)
MAROON = (128, 0, 0)
MAYBE_BACKGROUND = (64, 64, 64)
MAYBE_FOREGROUND = (192, 192, 192)
MEDIUMBLUE = (0, 0, 205)
NAVYBLUE = (0, 0, 128)
OLIVE = (128, 128, 0)
ORANGE = (255, 165, 0)
PLUM = (132, 49, 121)
PUCE = (204, 136, 153)
RED = (255, 0, 0)
ROYALBLUE = (8, 76, 158)
SALMON = (250, 128, 114)
SILVER = (192, 192, 192)
TAN = (210, 180, 140)
TEAL = (0, 128, 128)
VIOLET = (181, 126, 220)
WATERSHED_BG = (128, 128, 128)
WATERSHED_FG = (255, 255, 255)
WATERSHED_UNSURE = (0, 0, 0)
WHEAT = (245, 222, 179)
WHITE = (255, 255, 255)
YELLOW = (255, 255, 0)
colorlist = [(0, 0, 0), (255, 255, 255), (0, 0, 255), (255, 255, 0), (255, 0, 0), (181, 126, 220), (255, 165, 0), (0, 128, 0), (128, 128, 128), (255, 255, 240), (245, 245, 220), (245, 222, 179), (210, 180, 140), (195, 176, 145), (192, 192, 192), (70, 70, 70), (0, 0, 128), (8, 76, 158), (0, 0, 205), (0, 127, 255), (0, 255, 255), (127, 255, 212), (0, 128, 128), (34, 139, 34), (128, 128, 0), (191, 255, 0), (255, 215, 0), (250, 128, 114), (252, 15, 192), (255, 119, 255), (204, 136, 153), (132, 49, 121), (75, 0, 130), (128, 0, 0), (220, 20, 60), (0, 0, 0)]
classmethod getHueFromBGR(color_tuple)

SUMMARY

Get corresponding Hue value of the given BGR values

PARAMETERS

  • tuple - a BGR tuple to convert to HSV.

RETURNS

floating value of Hue ranging from 0 to 180

EXAMPLE

>>> i = Image("lenna")
>>> color_tuple = tuple(reversed(i[100,300]))
>>> hue = Color.getHueFromRGB(color_tuple)
classmethod getHueFromRGB(tuple)

SUMMARY

Get corresponding Hue value of the given RGB values

PARAMETERS

  • tuple - an rgb tuple to convert to HSV.

RETURNS

floating value of Hue ranging from 0 to 180

EXAMPLE

>>> i = Image("lenna")
>>> hue = Color.getHueFromRGB(i[100,300])
classmethod getRandom()

SUMMARY

Returns a random color in tuple format.

RETURNS

A random color tuple.

EXAMPLE

>>> img = Image("lenna")
>>> kp = img.findKeypoints()
>>> for k in kp:
>>>    k.draw(color=Color.getRandom())
>>> img.show()
classmethod hsv(tuple)

SUMMARY

Convert any color to HSV, OpenCV style (0-180 for hue)

PARAMETERS

  • tuple - an rgb tuple to convert to HSV.

RETURNS

A color tuple in HSV format.

EXAMPLE

>>> c = Color.RED
>>> hsvc = Color.hsv(c)
classmethod hueToBGR(h)

SUMMARY

Get corresponding BGR values of the given Hue

PARAMETERS

  • int - a hue int to convert to BGR

RETURNS

A color tuple in BGR format.

EXAMPLE

>>> c = Color.huetoBGR(0)
classmethod hueToRGB(h)

SUMMARY

Get corresponding RGB values of the given Hue

PARAMETERS

  • int - a hue int to convert to RGB

RETURNS

A color tuple in RGB format.

EXAMPLE

>>> c = Color.huetoRGB(0)
class SimpleCV.Color.ColorCurve(curve_vals)

SUMMARY

ColorCurve is a color spline class for performing color correction. It can takeas parameters a SciPy Univariate spline, or an array with at least 4 point pairs. Either of these must map in a 255x255 space. The curve can then be used in the applyRGBCurve, applyHSVCurve, and applyInstensityCurve functions.

EXAMPLE

>>> clr = ColorCurve([[0,0], [100, 120], [180, 230], [255, 255]])
>>> image.applyIntensityCurve(clr)

the only property, mCurve is a linear array with 256 elements from 0 to 255

mCurve = ''
class SimpleCV.Color.ColorMap(color, startmap, endmap)

SUMMARY

A ColorMap takes in a tuple of colors along with the start and end points and it lets you map colors with a range of numbers.

If only one Color is passed second color by default is set to White

PARAMETERS

  • color - Tuple of colors which need to be mapped
  • startmap * - This is the starting of the range of number with which we map the colors
  • endmap * - This is the end of the range of the nmber with which we map the colors

EXAMPLE

This is useful for color coding elements by an attribute:

>>> blobs = image.findBlobs()
>>> cm = ColorMap(color = (Color.RED,Color.YELLOW,Color.BLUE),min(blobs.area()),max(blobs.area()))
>>>  for b in blobs:
>>>    b.draw(cm[b.area()])
color = ()
colordistance = 0
endcolor = ()
endmap = 0
startmap = 0
valuerange = 0

ColorModel Module

class SimpleCV.ColorModel.ColorModel(data=None, isBackground=True)

SUMMARY

The color model is used to model the color of foreground and background objects by using a a training set of images.

You can create the color model with any number of “training” images, or add images to the model with add() and remove(). Then for your data images, you can useThresholdImage() to return a segmented picture.

add(data)

SUMMARY

Add an image, array, or tuple to the color model.

PARAMETERS

  • data - An image, array, or tupple of values to the color model.

RETURNS

Nothings.

EXAMPLE

>>> cm = ColorModel()
>>> cm.add(Image("lenna))>>> 
cm.clear()
contains(c)

SUMMARY

Return true if a particular color is in our color model.

PARAMETERS

  • c - A three value color tupple.

RETURNS

Returns True if the color is in the model, False otherwise.

EXAMPLE

>>> cm = ColorModel()
>>> cm.add(Color.RED)
>>> cm.add(Color.BLUE)
>>> if( cm.contains(Color.RED) )
>>>   print "Yo - we gots red y'all."
load(filename)

SUMMARY

Load the color model from the specified file.

TO DO

This should be converted to pickle.

PARAMETERS

  • filename - The file name and path to load the data from.

RETURNS

Nothing.

EXAMPLE

>>> cm = ColorModel()
>>> cm.load("myColors.txt")
>>> cm.add(Color.RED)
>>> cm.add(Color.BLUE)
>>> cm.save("mymodel)
mBits = 1
mData = {}
mIsBackground = True
remove(data)

SUMMARY

Remove an image, array, or tuple from the model.

PARAMETERS

  • data - An image, array, or tupple of value.

RETURNS

Nothings.

EXAMPLE

>>> cm = ColorModel()
>>> cm.add(Image("lenna))>>> 
cm.remove(Color.BLACK)
reset()

SUMMARY Resets the color model. I.e. clears it out the stored values.

RETURNS

Nothing.

EXAMPLE

>>> cm = ColorModel()
>>> cm.add(Image("lenna))>>> 
cm.clear()
save(filename)

SUMMARY

Save a color model file.

PARAMETERS

  • filename - The file name and path to save the data to.

RETURNS

Nothing.

EXAMPLE

>>> cm = ColorModel()
>>> cm.add(Color.RED)
>>> cm.add(Color.BLUE)
>>> cm.save("mymodel.txt")

TO DO

This should be converted to pickle.

setIsBackground()

SUMMARY

Set our model as being background imagery. I.e. things in the model are the background and will be marked as black during the threhsold operation.

RETURNS

Nothing.

setIsForeground()

SUMMARY

Set our model as being foreground imagery. I.e. things in the model are the foreground and will be marked as white during the threhsold operation.

RETURNS

Nothing.

threshold(img)

SUMMARY

Perform a threshold operation on the given image. This involves iterating over the image and comparing each pixel to the model. If the pixel is in the model it is set to be either the foreground (white) or background (black) based on the setting of mIsBackground.

PARAMETERS

  • img - the image to perform the threshold on.

RETURNS

The thresholded image.

EXAMPLE

>>> cm = ColorModel()
>>> cm.add(color.RED)
>>> cm.add(color.BLUE)
>>> result = cm.threshold(Image("lenna")
>>> result.show()

Display Module

class SimpleCV.Display.Display(resolution=(640, 480), flags=0, title='SimpleCV', displaytype='standard', headless=False)

SUMMARY

WindowStream opens a window (Pygame Display Surface) to which you can write images. The default resolution is 640, 480 – but you can also specify 0,0 which will maximize the display. Flags are pygame constants, including:

By default display will attempt to scale the input image to fit neatly on the screen with minimal distorition. This means that if the aspect ratio matches the screen it will scale cleanly. If your image does not match the screen aspect ratio we will scale it to fit nicely while maintining its natural aspect ratio.

Because SimpleCV performs this scaling there are two sets of input mouse coordinates, the (mousex,mousey) which scale to the image, and (mouseRawX, mouseRawY) which do are the actual screen coordinates.

  • pygame.FULLSCREEN: create a fullscreen display.
  • pygame.DOUBLEBUF: recommended for HWSURFACE or OPENGL.
  • pygame.HWSURFACE: hardware accelerated, only in FULLSCREEN.
  • pygame.OPENGL: create an opengl renderable display.
  • pygame.RESIZABLE: display window should be sizeable.
  • pygame.NOFRAME: display window will have no border or controls.

Display should be used in a while loop with the isDone() method, which checks events and sets the following internal state controls:

  • mouseX: the x position of the mouse cursor on the input image.
  • mouseY: the y position of the mouse curson on the input image.
  • mouseRawX: The position of the mouse on the screen.
  • mouseRawY: The position of the mouse on the screen.

NOTES

The mouse position on the screen is not the mouse position on the image. If you are trying to draw on the image or take in coordinates use mousex and mousey as these values are scaled along with the image.

  • mouseLeft: the state of the left button.
  • mouseRight: the state of the right button.
  • mouseMiddle: the state of the middle button.
  • mouseWheelUp: scroll wheel has been moved up.
  • mouseWheelDown: the wheel has been clicked towards the bottom of the mouse.

EXAMPLE

>>> display = Display(resolution = (800, 600)) #create a new display to draw images on
>>> cam = Camera() #initialize the camera
>>> done = False # setup boolean to stop the program
>>> while not display.isDone():
>>>  cam.getImage().flipHorizontal().save(display) # get image, flip it so it looks mirrored, save to display
>>>  time.sleep(0.01) # Let the program sleep for 1 millisecond so the computer can do other things
>>>  if display.mouseLeft:
>>>      display.done = True
checkEvents(returnStrings=False)

SUMMARY

CheckEvents checks the pygame event queue and sets the internal display values based on any new generated events.

Warning

This method must be called (or isDone() or isNotDone()) to perform mouse event checking.

PARAMETERS

returnStrings - pygame returns an enumerated int by default, when this is set to true we return a list of strings.

RETURNS

A list of key down events. Parse them with pg.K_<lowercase_letter>

displaytype = None
done = False
eventhandler = ''
imgh = 0
imgw = 0
isDone()

SUMMARY

Checks the event queue and returns True if a quit event has been issued.

RETURNS

True on a quit event, False otherwise.

EXAMPLE

>>> disp = Display()
>>> cam = Camera()
>>> while not disp.isDone():
>>>   img = cam.getImage()
>>>   img.save(disp)
isNotDone()

SUMMARY

Checks the event queue and returns False as long as the quit event hasn’t been issued.

RETURNS

False on a quit event, True otherwise.

EXAMPLE

>>> disp = Display()
>>> cam = Camera()
>>> while disp.isNotDone():
>>>   img = cam.getImage()
>>>   img.save(disp)
lastLeftButton = 0
lastRightButton = 0
leftButtonDown = None
leftButtonDownPosition()

SUMMARY

Returns the position where the left mouse button went down.

Warning

You must call checkEvents() or isDone() in your main display loop for this method to work.

RETURNS

An (x,y) mouse postion tuple where the mouse went up.

EXAMPLE

>>> disp = Display((600,800))
>>> cam = Camera()
>>> while(disp.isNotDone()):
>>>   img = cam.getImage()
>>>   dwn = disp.leftButtonDownPosition()
>>>   up = disp.leftButtonUpPosition()
>>>   if( up is not None and dwn is not None):
>>>     bb = disp.pointsToBoundingBox(up,dwn)
>>>     img.drawRectangle(bb[0],bb[1],bb[2],bb[3])
>>>   img.save(disp)

SEE ALSO

leftButtonUpPostion() rightButtonUpPostion() rightButtonDownPostion() pointsToBoundingBox() checkEvents()

leftButtonUp = None
leftButtonUpPosition()

SUMMARY

Returns the position where the left mouse button went up.

Warning

You must call checkEvents() or isDone() in your main display loop for this method to work.

RETURNS

An (x,y) mouse postion tuple where the mouse went up.

EXAMPLE

>>> disp = Display((600,800))
>>> cam = Camera()
>>> while(disp.isNotDone()):
>>>   img = cam.getImage()
>>>   dwn = disp.leftButtonDownPosition()
>>>   up = disp.leftButtonUpPosition()
>>>   if( up is not None and dwn is not None):
>>>     bb = disp.pointsToBoundingBox(up,dwn)
>>>     img.drawRectangle(bb[0],bb[1],bb[2],bb[3])
>>>   img.save(disp)

SEE ALSO

rightButtonUpPostion() leftButtonDownPostion() rightButtonDownPostion() pointsToBoundingBox()

mouseLeft = 0
mouseMiddle = 0
mouseRawX = 0
mouseRawY = 0
mouseRight = 0
mouseWheelDown = 0
mouseWheelUp = 0
mouseX = 0
mouseY = 0
mq = ''
pointsToBoundingBox(pt0, pt1)

SUMMARY

Given two screen cooridnates return the bounding box in x,y,w,h format. This is helpful for drawing regions on the display.

RETURNS

The bounding box from two coordinates as a ( x,y,w,h) tuple.

EXAMPLE

>>> disp = Display((600,800))
>>> cam = Camera()
>>> while(disp.isNotDone()):
>>>   img = cam.getImage()
>>>   dwn = disp.leftButtonDownPosition()
>>>   up = disp.leftButtonUpPosition()
>>>   if( up is not None and dwn is not None):
>>>     bb = disp.pointsToBoundingBox(up,dwn)
>>>     img.drawRectangle(bb[0],bb[1],bb[2],bb[3])
>>>   img.save(disp)

SEE ALSO

leftButtonUpPostion() leftButtonDownPostion() rightButtonDownPostion() rightButtonUpPostion() checkEvents()

pressed = []
quit()

quit the pygame instance

Example: >>> img = Image(“simplecv”) >>> d = img.show() >>> time.sleep(5) >>> d.quit()

resolution = ''
rightButtonDown = None
rightButtonDownPosition()

SUMMARY

Returns the position where the right mouse button went down.

Warning

You must call checkEvents() or isDone() in your main display loop for this method to work.

RETURNS

An (x,y) mouse postion tuple where the mopuse went down.

EXAMPLE

>>> disp = Display((600,800))
>>> cam = Camera()
>>> while(disp.isNotDone()):
>>>   img = cam.getImage()
>>>   dwn = disp.rightButtonDownPosition()
>>>   up = disp.rightButtonUpPosition()
>>>   if( up is not None and dwn is not None):
>>>     bb = disp.pointsToBoundingBox(up,dwn)
>>>     img.drawRectangle(bb[0],bb[1],bb[2],bb[3])
>>>   img.save(disp)

SEE ALSO

leftButtonUpPostion() leftButtonDownPostion() rightButtonDownPostion() pointsToBoundingBox() checkEvents()

rightButtonUp = None
rightButtonUpPosition()

SUMMARY

Returns the position where the right mouse button went up.

Warning

You must call checkEvents() or isDone() in your main display loop for this method to work.

RETURNS

An (x,y) mouse postion tuple where the mouse went up.

EXAMPLE

>>> disp = Display((600,800))
>>> cam = Camera()
>>> while(disp.isNotDone()):
>>>   img = cam.getImage()
>>>   dwn = disp.rightButtonDownPosition()
>>>   up = disp.rightButtonUpPosition()
>>>   if( up is not None and dwn is not None):
>>>     bb = disp.pointsToBoundingBox(up,dwn)
>>>     img.drawRectangle(bb[0],bb[1],bb[2],bb[3])
>>>   img.save(disp)
>>> disp = Display((600,800))
>>> dwn = disp.rightButtonDownPosition()
>>> up = disp.rightButtonUpPosition()
>>> bb = disp.pointsToBoundingBox(up,dwn)
>>> #draw bb

SEE ALSO

leftButtonUpPostion() leftButtonDownPostion() rightButtonDownPostion() pointsToBoundingBox() checkEvents()

screen = ''
sourceoffset = ''
sourceresolution = ''
writeFrame(img, fit=True)

SUMMARY

writeFrame copies the given Image object to the display, you can also use Image.save()

Write frame trys to fit the image to the display with the minimum ammount of distortion possible. When fit=True write frame will decide how to scale the image such that the aspect ratio is maintained and the smallest amount of distorition possible is completed. This means the axis that has the minimum scaling needed will be shrunk or enlarged to match the display.

PARAMETERS

  • img - the SimpleCV image to save to the display.
  • fit - When fit=False write frame will crop and center the image as best it can. If the image is too big it is cropped and centered. If it is too small it is centered. If it is too big along one axis that axis is cropped and the other axis is centered if necessary.

RETURNS

Nothing.

EXAMPLE

>>> img = Image("lenna")
>>> disp = Display((512,512))
>>> disp.writeFrame(img)
xoffset = 0
xscale = 1.0
yoffset = 0
yscale = 1.0

DrawingLayer Module

class SimpleCV.DrawingLayer.DrawingLayer((width, height))

DrawingLayer gives you a way to mark up Image classes without changing the image data itself. This class wraps pygame’s Surface class and provides basic drawing and text rendering functions

Example: image = Image(“/path/to/image.png”) image2 = Image(“/path/to/image2.png”) image.dl().blit(image2) #write image 2 on top of image

bezier(points, steps, color=(0, 0, 0), alpha=-1)

Draw a bezier curve based on a control point and the a number of stapes

color - The object’s color as a simple CVColor object, if no value is sepcified
the default is used.
alpha - The alpha blending for the object. If this value is -1 then the
layer default value is used. A value of 255 means opaque, while 0 means transparent
Parameters:
points - list steps - Int color - Color object or Color Tuple alpha - Int
blit(img, coordinates=(0, 0))

Blit one image onto the drawing layer at upper left coordinates

Parameters:
img - Image coordinates - Tuple
centeredRectangle(center, dimensions, color=(0, 0, 0), width=1, filled=False, alpha=-1)

Draw a rectangle given the center (x,y) of the rectangle and dimensions (width, height)

color - The object’s color as a simple CVColor object, if no value is sepcified
the default is used.
alpha - The alpha blending for the object. If this value is -1 then the
layer default value is used. A value of 255 means opaque, while 0 means transparent.

w - The line width in pixels. This does not work if antialiasing is enabled.

filled -The rectangle is filled in

rameters:
center - Tuple dimenions - Tuple color - Color object or Color Tuple width - Int filled - Boolean alpha - Int
circle(center, radius, color=(0, 0, 0), width=1, filled=False, alpha=-1, antialias=True)

Draw a circle given a location and a radius.

color - The object’s color as a simple CVColor object, if no value is sepcified
the default is used.
alpha - The alpha blending for the object. If this value is -1 then the
layer default value is used. A value of 255 means opaque, while 0 means transparent.

width - The line width in pixels. This does not work if antialiasing is enabled.

filled -The object is filled in

Parameters:
center - Tuple radius - Int color - Color object or Color Tuple width - Int filled - Boolean alpha - Int antialias - Int
clear()

This method removes all of the drawing on this layer (i.e. the layer is erased completely)

ellipse(center, dimensions, color=(0, 0, 0), width=1, filled=False, alpha=-1)

Draw an ellipse given a location and a dimensions.

color - The object’s color as a simple CVColor object, if no value is sepcified
the default is used.
alpha - The alpha blending for the object. If this value is -1 then the
layer default value is used. A value of 255 means opaque, while 0 means transparent.

width - The line width in pixels. This does not work if antialiasing is enabled.

filled -The object is filled in

Parameters:
center - Tuple dimensions - Tuple color - Color object or Color tuple width - Int filled - Boolean alpha - Int
ezViewText(text, location, fgcolor=(255, 255, 255), bgcolor=(0, 0, 0))

ezViewText works just like text but it sets both the foreground and background color and overwrites the image pixels. Use this method to make easily viewable text on a dynamic video stream.

fgcolor - The color of the text.

bgcolor - The background color for the text are.

getDefaultAlpha()

Returns the default alpha value.

height = 0
line(start, stop, color=(0, 0, 0), width=1, antialias=True, alpha=-1)

Draw a single line from the (x,y) tuple start to the (x,y) tuple stop. Optional parameters:

color - The object’s color as a simple CVColor object, if no value is sepcified
the default is used.
alpha - The alpha blending for the object. If this value is -1 then the
layer default value is used. A value of 255 means opaque, while 0 means transparent.

width - The line width in pixels.

antialias - Draw an antialiased object of width one.

Parameters:
start - Tuple stop - Tuple color - Color object or Color Tuple width - Int antialias - Boolean alpha - Int
lines(points, color=(0, 0, 0), antialias=True, alpha=-1, width=1)

Draw a set of lines from the list of (x,y) tuples points. Lines are draw between each successive pair of points.

Optional parameters:

color - The object’s color as a simple CVColor object, if no value is sepcified
the default is used.
alpha - The alpha blending for the object. If this value is -1 then the
layer default value is used. A value of 255 means opaque, while 0 means transparent.

width - The line width in pixels.

antialias - Draw an antialiased object of width one.

Parameters:
points - Tuple color - Color object or Color Tuple antialias - Boolean alpha - Int width - Int
listFonts()

This method returns a list of strings corresponding to the fonts available on the current system.

polygon(points, color=(0, 0, 0), width=1, filled=False, antialias=True, alpha=-1)

Draw a polygon from a list of (x,y)

color - The object’s color as a simple CVColor object, if no value is sepcified
the default is used.
alpha - The alpha blending for the object. If this value is -1 then the
layer default value is used. A value of 255 means opaque, while 0 means transparent.

width - The width in pixels. This does not work if antialiasing is enabled.

filled -The object is filled in

antialias - Draw the edges of the object antialiased. Note this does not work when the object is filled.

rectangle(topLeft, dimensions, color=(0, 0, 0), width=1, filled=False, alpha=-1)

Draw a rectangle given the topLeft the (x,y) coordinate of the top left corner and dimensions (w,h) tge width and height

color - The object’s color as a simple CVColor object, if no value is sepcified
the default is used.
alpha - The alpha blending for the object. If this value is -1 then the
layer default value is used. A value of 255 means opaque, while 0 means transparent.

w - The line width in pixels. This does not work if antialiasing is enabled.

filled -The rectangle is filled in

rectangle2pts(pt0, pt1, color=(0, 0, 0), width=1, filled=False, alpha=-1)

Draw a rectangle given two (x,y) points

color - The object’s color as a simple CVColor object, if no value is sepcified
the default is used.
alpha - The alpha blending for the object. If this value is -1 then the
layer default value is used. A value of 255 means opaque, while 0 means transparent.

w - The line width in pixels. This does not work if antialiasing is enabled.

filled -The rectangle is filled in

renderToOtherLayer(otherLayer)

Add this layer to another layer.

Parameters:
otherLayer - Pygame Surface
renderToSurface(surf)

Blit this layer to another surface.

Parameters:
surf - Pygame Surface
replaceOverlay(overlay)

This method allows you to set the surface manually.

Parameters:
overlay - Pygame Surface
selectFont(fontName)

This method attempts to set the font from a font file. It is advisable to use one of the fonts listed by the listFonts() method. The input is a string with the font name.

setDefaultAlpha(alpha)

This method sets the default alpha value for all methods called on this layer. The default value starts out at 255 which is completely transparent.

setDefaultColor(color)

This method sets the default rendering color.

Parameters:
color - Color object or Color Tuple
setFontBold(doBold)

This method sets and unsets the current font to be bold.

setFontItalic(doItalic)

This method sets and unsets the current font to be italic.

setFontSize(sz)

This method sets the font size roughly in points. A size of 10 is almost too small to read. A size of 20 is roughly 10 pixels high and a good choice.

Parameters:
sz = Int
setFontUnderline(doUnderline)

This method sets and unsets the current font to be underlined

setLayerAlpha(alpha)

This method sets the alpha value of the entire layer in a single pass. This is helpful for merging layers with transparency.

sprite(img, pos=(0, 0), scale=1.0, rot=0.0, alpha=255)

sprite draws a sprite (a second small image) onto the current layer. The sprite can be loaded directly from a supported image file like a gif, jpg, bmp, or png, or loaded as a surface or SCV image.

pos - the (x,y) position of the upper left hand corner of the sprite

scale - a scale multiplier as a float value. E.g. 1.1 makes the sprite 10% bigger

rot = a rotation angle in degrees

alpha = an alpha value 255=opaque 0=transparent.

text(text, location, color=(0, 0, 0), alpha=-1)

Write the a text string at a given location

text - A text string to print.

location-The location to place the top right corner of the text

color - The object’s color as a simple CVColor object, if no value is sepcified
the default is used.
alpha - The alpha blending for the object. If this value is -1 then the
layer default value is used. A value of 255 means opaque, while 0 means transparent.
Parameters:
text - String location - Tuple color - Color object or Color tuple alpha - Int
textDimensions(text)

The textDimensions function takes a string and returns the dimensions (width, height) of this text being rendered on the screen.

width = 0

EXIF Module

class SimpleCV.EXIF.EXIF_header(file, endian, offset, fake_exif, strict, debug=0)
canon_decode_tag(value, dict)
decode_maker_note()
dump_IFD(ifd, ifd_name, dict={36864: ('ExifVersion', <function make_string at 0x4e46488>), 37377: ('ShutterSpeedValue', ), 37378: ('ApertureValue', ), 36867: ('DateTimeOriginal', ), 36868: ('DateTimeDigitized', ), 37381: ('MaxApertureValue', ), 37382: ('SubjectDistance', ), 37383: ('MeteringMode', {0: 'Unidentified', 1: 'Average', 2: 'CenterWeightedAverage', 3: 'Spot', 4: 'MultiSpot', 5: 'Pattern'}), 37384: ('LightSource', {0: 'Unknown', 1: 'Daylight', 2: 'Fluorescent', 3: 'Tungsten', 9: 'Fine Weather', 10: 'Flash', 11: 'Shade', 12: 'Daylight Fluorescent', 13: 'Day White Fluorescent', 14: 'Cool White Fluorescent', 15: 'White Fluorescent', 17: 'Standard Light A', 18: 'Standard Light B', 19: 'Standard Light C', 20: 'D55', 21: 'D65', 22: 'D75', 255: 'Other'}), 37385: ('Flash', {0: 'No', 1: 'Fired', 5: 'Fired (?)', 7: 'Fired (!)', 9: 'Fill Fired', 13: 'Fill Fired (?)', 15: 'Fill Fired (!)', 16: 'Off', 24: 'Auto Off', 25: 'Auto Fired', 29: 'Auto Fired (?)', 31: 'Auto Fired (!)', 32: 'Not Available'}), 37386: ('FocalLength', ), 41483: ('FlashEnergy', ), 41484: ('SpatialFrequencyResponse', ), 40962: ('ExifImageWidth', ), 41486: ('FocalPlaneXResolution', ), 41487: ('FocalPlaneYResolution', ), 41488: ('FocalPlaneResolutionUnit', ), 529: ('YCbCrCoefficients', ), 530: ('YCbCrSubSampling', ), 531: ('YCbCrPositioning', {1: 'Centered', 2: 'Co-sited'}), 532: ('ReferenceBlackWhite', ), 41493: ('ExposureIndex', ), 512: ('JPEGProc', ), 41495: ('SensingMethod', {1: 'Not defined', 2: 'One-chip color area', 3: 'Two-chip color area', 4: 'Three-chip color area', 5: 'Color sequential area', 7: 'Trilinear', 8: 'Color sequential linear'}), 37380: ('ExposureBiasValue', ), 59932: ('Padding', ), 40965: ('InteroperabilityOffset', ), 34850: ('ExposureProgram', {0: 'Unidentified', 1: 'Manual', 2: 'Program Normal', 3: 'Aperture Priority', 4: 'Shutter Priority', 5: 'Program Creative', 6: 'Program Action', 7: 'Portrait Mode', 8: 'Landscape Mode'}), 34852: ('SpectralSensitivity', ), 34853: ('GPSInfo', ), 34855: ('ISOSpeedRatings', ), 34856: ('OECF', ), 41991: ('GainControl', {0: 'None', 1: 'Low gain up', 2: 'High gain up', 3: 'Low gain down', 4: 'High gain down'}), 41992: ('Contrast', {0: 'Normal', 1: 'Soft', 2: 'Hard'}), 513: ('JPEGInterchangeFormat', ), 41993: ('Saturation', {0: 'Normal', 1: 'Soft', 2: 'Hard'}), 41994: ('Sharpness', {0: 'Normal', 1: 'Soft', 2: 'Hard'}), 41995: ('DeviceSettingDescription', ), 41996: ('SubjectDistanceRange', ), 514: ('JPEGInterchangeFormatLength', ), 37396: ('SubjectArea', ), 37500: ('MakerNote', ), 37510: ('UserComment', <function make_string_uc at 0x4e46500>), 33421: ('CFARepeatPatternDim', ), 33422: ('CFAPattern', ), 33423: ('BatteryLevel', ), 37520: ('SubSecTime', ), 37521: ('SubSecTimeOriginal', ), 37522: ('SubSecTimeDigitized', ), 33432: ('Copyright', ), 33434: ('ExposureTime', ), 40091: ('XPTitle', ), 40092: ('XPComment', ), 33437: ('FNumber', ), 40094: ('XPKeywords', ), 40095: ('XPSubject', ), 50341: ('PrintIM', ), 37121: ('ComponentsConfiguration', {0: '', 1: 'Y', 2: 'Cb', 3: 'Cr', 4: 'Red', 5: 'Green', 6: 'Blue'}), 37122: ('CompressedBitsPerPixel', ), 37379: ('BrightnessValue', ), 256: ('ImageWidth', ), 257: ('ImageLength', ), 258: ('BitsPerSample', ), 259: ('Compression', {32896: 'IT8LW', 1: 'Uncompressed', 2: 'CCITT 1D', 3: 'T4/Group 3 Fax', 4: 'T6/Group 4 Fax', 5: 'LZW', 6: 'JPEG (old-style)', 7: 'JPEG', 8: 'Adobe Deflate', 9: 'JBIG B&W', 10: 'JBIG Color', 32908: 'PixarFilm', 32898: 'IT8BL', 32771: 'CCIRLEW', 34712: 'JPEG 2000', 34713: 'Nikon NEF Compressed', 32773: 'PackBits', 32769: 'Epson ERF Compressed', 32897: 'IT8MP', 32809: 'Thunderscan', 32946: 'Deflate', 32947: 'DCS', 32909: 'PixarLog', 34661: 'JBIG', 65000: 'Kodak DCR Compressed', 34676: 'SGILog', 34677: 'SGILog24', 65535: 'Pentax PEF Compressed', 32766: 'Next', 32895: 'IT8CTPAD'}), 262: ('PhotometricInterpretation', ), 263: ('Thresholding', ), 266: ('FillOrder', ), 269: ('DocumentName', ), 270: ('ImageDescription', ), 271: ('Make', ), 272: ('Model', ), 273: ('StripOffsets', ), 274: ('Orientation', {1: 'Horizontal (normal)', 2: 'Mirrored horizontal', 3: 'Rotated 180', 4: 'Mirrored vertical', 5: 'Mirrored horizontal then rotated 90 CCW', 6: 'Rotated 90 CW', 7: 'Mirrored horizontal then rotated 90 CW', 8: 'Rotated 90 CCW'}), 277: ('SamplesPerPixel', ), 278: ('RowsPerStrip', ), 279: ('StripByteCounts', ), 282: ('XResolution', ), 283: ('YResolution', ), 284: ('PlanarConfiguration', ), 285: ('PageName', <function make_string at 0x4e46488>), 41728: ('FileSource', {1: 'Film Scanner', 2: 'Reflection Print Scanner', 3: 'Digital Camera'}), 40961: ('ColorSpace', {1: 'sRGB', 2: 'Adobe RGB', 65535: 'Uncalibrated'}), 296: ('ResolutionUnit', {1: 'Not Absolute', 2: 'Pixels/Inch', 3: 'Pixels/Centimeter'}), 301: ('TransferFunction', ), 42240: ('Gamma', ), 305: ('Software', ), 306: ('DateTime', ), 315: ('Artist', ), 41729: ('SceneType', {1: 'Directly Photographed'}), 318: ('WhitePoint', ), 319: ('PrimaryChromaticities', ), 41985: ('CustomRendered', {0: 'Normal', 1: 'Custom'}), 18246: ('Rating', ), 40960: ('FlashPixVersion', <function make_string at 0x4e46488>), 342: ('TransferRange', ), 41730: ('CVAPattern', ), 40963: ('ExifImageLength', ), 41986: ('ExposureMode', {0: 'Auto Exposure', 1: 'Manual Exposure', 2: 'Auto Bracket'}), 34665: ('ExifOffset', ), 41492: ('SubjectLocation', ), 34675: ('InterColorProfile', ), 41987: ('WhiteBalance', {0: 'Auto', 1: 'Manual'}), 41988: ('DigitalZoomRatio', ), 40093: ('XPAuthor', ), 33723: ('IPTC/NAA', ), 41989: ('FocalLengthIn35mmFilm', ), 41990: ('SceneCaptureType', {0: 'Standard', 1: 'Landscape', 2: 'Portrait', 3: 'Night)'})}, relative=0, stop_tag='UNDEF')
extract_TIFF_thumbnail(thumb_ifd)
first_IFD()
list_IFDs()
n2s(offset, length)
next_IFD(ifd)
olympus_decode_tag(value, dict)
s2n(offset, length, signed=0)
class SimpleCV.EXIF.IFD_Tag(printable, tag, field_type, values, field_offset, field_length)
class SimpleCV.EXIF.Ratio(num, den)
reduce()
SimpleCV.EXIF.gcd(a, b)
SimpleCV.EXIF.make_string(seq)
SimpleCV.EXIF.make_string_uc(seq)
SimpleCV.EXIF.nikon_ev_bias(seq)
SimpleCV.EXIF.olympus_special_mode(v)
SimpleCV.EXIF.process_file(f, stop_tag='UNDEF', details=True, strict=False, debug=False)
SimpleCV.EXIF.s2n_intel(str)
SimpleCV.EXIF.s2n_motorola(str)
SimpleCV.EXIF.usage(exit_status)

Font Module

class SimpleCV.Font.Font(fontface='ubuntu', fontsize=16)

The Font class allows you to create a font object to be used in drawing or writing to images. There are some defaults available, to see them, just type Font.printFonts()

getFont()

Get the font from the object to be used in drawing

Returns: PIL Image Font

getFonts()

This returns the list of fonts built into SimpleCV

getSize()

Gets the size of the current font

Returns: Integer

printFonts()

This prints a list of fonts built into SimpleCV

setFont(new_font='ubuntu')

Set the name of the font listed in the font family if the font isn’t listed in the font family then pass it the absolute path of the truetype font file. Example: Font.setFont(“/home/simplecv/my_font.ttf”)

setSize(size)

Set the font point size. i.e. 16pt

ImageClass Module

class SimpleCV.ImageClass.ColorSpace

SUMMARY

The colorspace class is used to encapsulate the color space of a given image. This class acts like C/C++ style enumerated type.

See: http://stackoverflow.com/questions/2122706/detect-color-space-with-opencv

BGR = 1
GRAY = 2
HLS = 4
HSV = 5
RGB = 3
UNKNOWN = 0
XYZ = 6
YCrCb = 7
class SimpleCV.ImageClass.Image(source=None, camera=None, colorSpace=0, verbose=True, sample=False, cv2image=False, webp=False)

SUMMARY

The Image class is the heart of SimpleCV and allows you to convert to and from a number of source types with ease. It also has intelligent buffer management, so that modified copies of the Image required for algorithms such as edge detection, etc can be cached and reused when appropriate.

Image are converted into 8-bit, 3-channel images in RGB colorspace. It will automatically handle conversion from other representations into this standard format. If dimensions are passed, an empty image is created.

EXAMPLE

>>> i = Image("/path/to/image.png")
>>> i = Camera().getImage()

You can also just load the SimpleCV logo using:

>>> img = Image("simplecv")
>>> img = Image("logo")
>>> img = Image("logo_inverted")
>>> img = Image("logo_transparent")

Or you can load an image from a URL:

>>> img = Image("http://www.simplecv.org/image.png")
InverseDFT(raw_dft_image)

SUMMARY

This method provides a way of performing an inverse discrete Fourier transform on a real/imaginary image pair and obtaining the result as a SimpleCV image. This method is helpful if you wish to perform custom filter development.

PARAMETERS

  • raw_dft_image - A list object with either one or three IPL images. Each image should have a 64f depth and contain two channels (the real and the imaginary).

RETURNS

A simpleCV image.

EXAMPLE

Note that this is an example, I don’t recommend doing this unless you know what you are doing.

>>> raw = img.getRawDFT()
>>> cv.SomeOperation(raw)
>>> result = img.InverseDFT(raw)
>>> result.show()

SEE ALSO

rawDFTImage() getDFTLogMagnitude() applyDFTFilter() highPassFilter() lowPassFilter() bandPassFilter() InverseDFT() applyButterworthFilter() InverseDFT() applyGaussianFilter() applyUnsharpMask()

adaptiveScale(resolution, fit=True)

SUMMARY

Adapative Scale is used in the Display to automatically adjust image size to match the display size. This method attempts to scale an image to the desired resolution while keeping the aspect ratio the same. If fit is False we simply crop and center the image to the resolution. In general this method should look a lot better than arbitrary cropping and scaling.

PARAMETERS

  • resolution - The size of the returned image as a (width,height) tuple.
  • fit - If fit is true we try to fit the image while maintaining the aspect ratio. If fit is False we crop and center the image to fit the resolution.

RETURNS

A SimpleCV Image.

EXAMPLE

This is typically used in this instance:

>>> d = Display((800,600))
>>> i = Image((640, 480))
>>> i.save(d)

Where this would scale the image to match the display size of 800x600

addDrawingLayer(layer=None)

SUMMARY

Push a new drawing layer onto the back of the layer stack

PARAMETERS

  • layer - The new drawing layer to add.

RETURNS

The index of the new layer as an integer.

EXAMPLE

>>> img = Image("Lenna")
>>> myLayer = DrawingLayer((img.width,img.height))
>>> img.addDrawingLayer(myLayer)

SEE ALSO

DrawingLayer insertDrawinglayer() addDrawinglayer() dl() toPygameSurface() getDrawingLayer() removeDrawingLayer() clearLayers() layers() mergedLayers() applyLayers() drawText() drawRectangle() drawCircle() blit()

anonymize(block_size=10, features=None, transform=None)

SUMMARY

Anonymize, for additional privacy to images.

PARAMETERS

  • features - A list with the Haar like feature cascades that should be matched.
  • block_size - The size of the blocks for the pixelize function.
  • transform - A function, to be applied to the regions matched instead of pixelize.
  • This function must take two arguments: the image and the region it’ll be applied to,
  • as in region = (x, y, width, height).

RETURNS

Returns the image with matching regions pixelated.

EXAMPLE

>>> img = Image("lenna")
>>> anonymous = img.anonymize()
>>> anonymous.show()
>>> def my_function(img, region):
>>>     x, y, width, height = region
>>>     img = img.crop(x, y, width, height)
>>>     return img
>>>
>>>img = Image("lenna")
>>>transformed = img.anonymize(transform = my_function)
applyBinaryMask(mask, bg_color=(0, 0, 0))

SUMMARY

Apply a binary mask to the image. The white areas of the mask will be kept, and the black areas removed. The removed areas will be set to the color of bg_color.

PARAMETERS

  • mask - the binary mask image. White areas are kept, black areas are removed.
  • bg_color - the color of the background on the mask.

RETURNS

A binary (black/white) image mask as a SimpleCV Image.

EXAMPLE

>>> img = Image("lenna")
>>> mask = img.createBinaryMask(color1=(0,128,128),color2=(255,255,255)
>>> result = img.applyBinaryMask(mask)
>>> result.show()

SEE ALSO

createBinaryMask() createAlphaMask() applyBinaryMask() blit() threshold()

applyButterworthFilter(dia=400, order=2, highpass=False, grayscale=False)

SUMMARY

Creates a butterworth filter of 64x64 pixels, resizes it to fit image, applies DFT on image using the filter. Returns image with DFT applied on it

PARAMETERS

  • dia - int Diameter of Butterworth low pass filter
  • order - int Order of butterworth lowpass filter
  • highpass: BOOL True: highpass filterm False: lowpass filter
  • grayscale: BOOL

EXAMPLE

>>> im = Image("lenna")
>>> img = im.applyButterworth(dia=400,order=2,highpass=True,grayscale=False)

Output image: http://i.imgur.com/5LS3e.png

>>> img = im.applyButterworth(dia=400,order=2,highpass=False,grayscale=False)

Output img: http://i.imgur.com/QlCAY.png

>>> im = Image("grayscale_lenn.png") #take image from here: http://i.imgur.com/O0gZn.png
>>> img = im.applyButterworth(dia=400,order=2,highpass=True,grayscale=True)

Output img: http://i.imgur.com/BYYnp.png

>>> img = im.applyButterworth(dia=400,order=2,highpass=False,grayscale=True)

Output img: http://i.imgur.com/BYYnp.png

SEE ALSO

rawDFTImage() getDFTLogMagnitude() applyDFTFilter() highPassFilter() lowPassFilter() bandPassFilter() InverseDFT() applyButterworthFilter() InverseDFT() applyGaussianFilter() applyUnsharpMask()

applyDFTFilter(flt, grayscale=False)

SUMMARY

This function allows you to apply an arbitrary filter to the DFT of an image. This filter takes in a gray scale image, whiter values are kept and black values are rejected. In the DFT image, the lower frequency values are in the corners of the image, while the higher frequency components are in the center. For example, a low pass filter has white squares in the corners and is black everywhere else.

PARAMETERS

  • grayscale - if this value is True we perfrom the operation on the DFT of the gray version of the image and the result is gray image. If grayscale is true we perform the operation on each channel and the recombine them to create the result.
  • flt - A grayscale filter image. The size of the filter must match the size of the image.

RETURNS

A SimpleCV image after applying the filter.

EXAMPLE

>>>  filter = Image("MyFilter.png")
>>>  myImage = Image("MyImage.png")
>>>  result = myImage.applyDFTFilter(filter)
>>>  result.show()

SEE ALSO

rawDFTImage() getDFTLogMagnitude() applyDFTFilter() highPassFilter() lowPassFilter() bandPassFilter() InverseDFT() applyButterworthFilter() InverseDFT() applyGaussianFilter() applyUnsharpMask()

TODO

Make this function support a separate filter image for each channel.

applyGaussianFilter(dia=400, highpass=False, grayscale=False)

SUMMARY

Creates a gaussian filter of 64x64 pixels, resizes it to fit image, applies DFT on image using the filter. Returns image with DFT applied on it

PARAMETERS

  • dia - int - diameter of Gaussian filter
  • highpass: BOOL True: highpass filter False: lowpass filter
  • grayscale: BOOL

EXAMPLE

>>> im = Image("lenna")
>>> img = im.applyGaussianfilter(dia=400,highpass=True,grayscale=False)

Output image: http://i.imgur.com/DttJv.png

>>> img = im.applyGaussianfilter(dia=400,highpass=False,grayscale=False)

Output img: http://i.imgur.com/PWn4o.png

>>> im = Image("grayscale_lenn.png") #take image from here: http://i.imgur.com/O0gZn.png
>>> img = im.applyGaussianfilter(dia=400,highpass=True,grayscale=True)

Output img: http://i.imgur.com/9hX5J.png

>>> img = im.applyGaussianfilter(dia=400,highpass=False,grayscale=True)

Output img: http://i.imgur.com/MXI5T.png

SEE ALSO

rawDFTImage() getDFTLogMagnitude() applyDFTFilter() highPassFilter() lowPassFilter() bandPassFilter() InverseDFT() applyButterworthFilter() InverseDFT() applyGaussianFilter() applyUnsharpMask()

applyHLSCurve(hCurve, lCurve, sCurve)

SUMMARY

Apply a color correction curve in HSL space. This method can be used to change values for each channel. The curves are ColorCurve class objects.

PARAMETERS

  • hCurve - the hue ColorCurve object.
  • lCurve - the lightnes / value ColorCurve object.
  • sCurve - the saturation ColorCurve object

RETURNS

A SimpleCV Image

EXAMPLE

>>> img = Image("lenna")
>>> hc = ColorCurve([[0,0], [100, 120], [180, 230], [255, 255]])
>>> lc = ColorCurve([[0,0], [90, 120], [180, 230], [255, 255]])
>>> sc = ColorCurve([[0,0], [70, 110], [180, 230], [240, 255]])
>>> img2 = img.applyHLSCurve(hc,lc,sc)

SEE ALSO

ColorCurve applyRGBCurve()

applyIntensityCurve(curve)

SUMMARY

Intensity applied to all three color channels

PARAMETERS

  • curve - a ColorCurve object.

RETURNS

A SimpleCV Image

EXAMPLE

>>> img = Image("lenna")
>>> rc = ColorCurve([[0,0], [100, 120], [180, 230], [255, 255]])
>>> gc = ColorCurve([[0,0], [90, 120], [180, 230], [255, 255]])
>>> bc = ColorCurve([[0,0], [70, 110], [180, 230], [240, 255]])
>>> img2 = img.applyRGBCurve(rc,gc,bc)

SEE ALSO

ColorCurve applyHLSCurve()

applyLUT(rLUT=None, bLUT=None, gLUT=None)

SUMMARY

Apply LUT allows you to apply a LUT (look up table) to the pixels in a image. Each LUT is just an array where each index in the array points to its value in the result image. For example rLUT[0]=255 would change all pixels where the red channel is zero to the value 255.

PARAMETERS

  • rLUT - a tuple or np.array of size (256x1) with dtype=uint8.
  • gLUT - a tuple or np.array of size (256x1) with dtype=uint8.
  • bLUT - a tuple or np.array of size (256x1) with dtype=uint8.

Warning

The dtype is very important. Will throw the following error without it: error: dst.size() == src.size() && dst.type() == CV_MAKETYPE(lut.depth(), src.channels())

RETURNS

The SimpleCV image remapped using the LUT.

EXAMPLE

This example saturates the red channel:

>>> rlut = np.ones((256,1),dtype=uint8)*255
>>> img=img.applyLUT(rLUT=rlut)

NOTE:

-==== BUG NOTE ====- This method seems to error on the LUT map for some versions of OpenCV. I am trying to figure out why. -KAS

applyLayers(indicies=-1)

SUMMARY

Render all of the layers onto the current image and return the result. Indicies can be a list of integers specifying the layers to be used.

PARAMETERS

  • indicies - Indicies can be a list of integers specifying the layers to be used.

RETURNS

The image after applying the drawing layers.

EXAMPLE

>>> img = Image("Lenna")
>>> myLayer1 = DrawingLayer((img.width,img.height))
>>> myLayer2 = DrawingLayer((img.width,img.height))
>>> #Draw some stuff
>>> img.insertDrawingLayer(myLayer1,1) # on top
>>> img.insertDrawingLayer(myLayer2,2) # on the bottom
>>> derp = img.applyLayers()

SEE ALSO

DrawingLayer dl() toPygameSurface() getDrawingLayer() removeDrawingLayer() layers() drawText() drawRectangle() drawCircle() blit()

applyPixelFunction(theFunc)

SUMMARY

apply a function to every pixel and return the result The function must be of the form int (r,g,b)=func((r,g,b))

PARAMETERS

  • theFunc - a function pointer to a function of the form (r,g.b) = theFunc((r,g,b))

RETURNS

A simpleCV image after mapping the function to the image.

EXAMPLE

>>> def derp(pixels):
>>>     return (int(b*.2),int(r*.3),int(g*.5))
>>>
>>> img = Image("lenna")
>>> img2 = img.applyPixelFunction(derp)
applyRGBCurve(rCurve, gCurve, bCurve)

SUMMARY

Apply a color correction curve in RGB space. This method can be used to change values for each channel. The curves are ColorCurve class objects.

PARAMETERS

  • rCurve - the red ColorCurve object.
  • gCurve - the green ColorCurve object.
  • bCurve - the blue ColorCurve object.

RETURNS

A SimpleCV Image

EXAMPLE

>>> img = Image("lenna")
>>> rc = ColorCurve([[0,0], [100, 120], [180, 230], [255, 255]])
>>> gc = ColorCurve([[0,0], [90, 120], [180, 230], [255, 255]])
>>> bc = ColorCurve([[0,0], [70, 110], [180, 230], [240, 255]])
>>> img2 = img.applyRGBCurve(rc,gc,bc)

SEE ALSO

ColorCurve applyHLSCurve()

applyUnsharpMask(boost=1, dia=400, grayscale=False)

SUMMARY

This method applies unsharp mask or highboost filtering on image depending upon the boost value provided. DFT is applied on image using gaussian lowpass filter. A mask is created subtracting the DFT image from the original iamge. And then mask is added in the image to sharpen it. unsharp masking => image + mask highboost filtering => image + (boost)*mask

PARAMETERS

  • boost - int boost = 1 => unsharp masking, boost > 1 => highboost filtering
  • dia - int Diameter of Gaussian low pass filter
  • grayscale - BOOL

EXAMPLE

Gaussian Filters:

>>> im = Image("lenna")
>>> img = im.applyUnsharpMask(2,grayscale=False) #highboost filtering

output image: http://i.imgur.com/A1pZf.png

>>> img = im.applyUnsharpMask(1,grayscale=False) #unsharp masking

output image: http://i.imgur.com/smCdL.png

>>> im = Image("grayscale_lenn.png") #take image from here: http://i.imgur.com/O0gZn.png
>>> img = im.applyUnsharpMask(2,grayscale=True) #highboost filtering

output image: http://i.imgur.com/VtGzl.png

>>> img = im.applyUnsharpMask(1,grayscale=True) #unsharp masking

output image: http://i.imgur.com/bywny.png

SEE ALSO

rawDFTImage() getDFTLogMagnitude() applyDFTFilter() highPassFilter() lowPassFilter() bandPassFilter() InverseDFT() applyButterworthFilter() InverseDFT() applyGaussianFilter() applyUnsharpMask()

area()

Returns the area of the Image.

bandPassFilter(xCutoffLow, xCutoffHigh, yCutoffLow=None, yCutoffHigh=None, grayscale=False)

SUMMARY

This method applies a simple band pass DFT filter. This filter enhances the a range of frequencies and removes all of the other frequencies. This allows a user to precisely select a set of signals to display . The frequencies are defined as going between 0.00 and 1.00 and where 0 is the lowest frequency in the image and 1.0 is the highest possible frequencies. Each of the frequencies are defined with respect to the horizontal and vertical signal. This filter isn’t perfect and has a harsh cutoff that causes ringing artifacts.

PARAMETERS

  • xCutoffLow - The horizontal frequency at which we perform the cutoff of the low frequency signals. A separate frequency can be used for the b,g, and r signals by providing a list of values. The frequency is defined between zero to one, where zero is constant component and 1 is the highest possible frequency in the image.
  • xCutoffHigh - The horizontal frequency at which we perform the cutoff of the high frequency signals. Our filter passes signals between xCutoffLow and xCutoffHigh. A separate frequency can be used for the b, g, and r channels by providing a list of values. The frequency is defined between zero to one, where zero is constant component and 1 is the highest possible frequency in the image.
  • yCutoffLow - The low frequency cutoff in the y direction. If none are provided we use the same values as provided for x.
  • yCutoffHigh - The high frequency cutoff in the y direction. If none are provided we use the same values as provided for x.
  • grayscale - if this value is True we perfrom the operation on the DFT of the gray version of the image and the result is gray image. If grayscale is true we perform the operation on each channel and the recombine them to create the result.

RETURNS

A SimpleCV Image after applying the filter.

EXAMPLE

>>> img = Image("SimpleCV/sampleimages/RedDog2.jpg")
>>> img.getDFTLogMagnitude().show()
>>> lpf = img.bandPassFilter([0.2,0.2,0.05],[0.3,0.3,0.2])
>>> lpf.show()
>>> lpf.getDFTLogMagnitude().show()

NOTES

This filter is far from perfect and will generate a lot of ringing artifacts.

See: http://en.wikipedia.org/wiki/Ringing_(signal)

SEE ALSO

rawDFTImage() getDFTLogMagnitude() applyDFTFilter() highPassFilter() lowPassFilter() bandPassFilter() InverseDFT() applyButterworthFilter() InverseDFT() applyGaussianFilter() applyUnsharpMask()

bilateralFilter(diameter=5, sigmaColor=10, sigmaSpace=10, grayscale=False)

SUMMARY

Smooths the image, using bilateral filtering. Potential of bilateral filtering is for the removal of texture. The optional parameter are diameter, sigmaColor, sigmaSpace.

Bilateral Filter see : http://en.wikipedia.org/wiki/Bilateral_filter see : http://homepages.inf.ed.ac.uk/rbf/CVonline/LOCAL_COPIES/MANDUCHI1/Bilateral_Filtering.html

Parameters

  • diameter - A tuple for the window of the form (diameter,diameter). By default window = (3x3). ( for OpenCV versions <= 2.3.0)
    • Diameter of each pixel neighborhood that is used during filtering. ( for OpenCV versions >= 2.3.0)
  • sigmaColor - Filter the specified value in the color space. A larger value of the parameter means that farther colors within the pixel neighborhood (see sigmaSpace ) will be mixed together, resulting in larger areas of semi-equal color.

  • sigmaSpace - Filter the specified value in the coordinate space. A larger value of the parameter means that farther pixels will influence each other as long as their colors are close enough

NOTE For OpenCV versions <= 2.3.0 – this acts as Convience function derived from the smooth() method. Which internally calls cv.Smooth. – where aperture(window) is (diameter,diameter) – sigmaColor and sigmanSpace become obsolete

For OpenCV versions higher than 2.3.0. i.e >= 2.3.0 – cv.bilateralFilter function is called – If the sigmaColor and sigmaSpace values are small (< 10), the filter will not have much effect, whereas if they are large (> 150), they will have a very strong effect, making the image look ‘cartoonish’ – It is recommended to use diamter=5 for real time applications, and perhaps diameter=9 for offile applications that needs heavy noise filtering.

binarize(thresh=-1, maxv=255, blocksize=0, p=5)

SUMMARY

Do a binary threshold the image, changing all values below thresh to maxv and all above to black. If a color tuple is provided, each color channel is thresholded separately.

If threshold is -1 (default), an adaptive method (OTSU’s method) is used. If then a blocksize is specified, a moving average over each region of block*block pixels a threshold is applied where threshold = local_mean - p.

PARAMETERS

  • thresh - the threshold as an integer or an (r,g,b) tuple , where pixels below (darker) than thresh are set to to max value, and all values above this value are set to black. If this parameter is -1 we use Otsu’s method.
  • maxv - The maximum value for pixels below the threshold. Ordinarily this should be 255 (white)
  • blocksize - the size of the block used in the adaptive binarize operation.

Warning

This parameter must be an odd number.

  • p - The difference from the local mean to use for thresholding in Otsu’s method.

RETURNS

A binary (two colors, usually black and white) SimpleCV image. This works great for the findBlobs family of functions.

EXAMPLE

Example of a vanila threshold versus an adaptive threshold:

>>> img = Image("orson_welles.jpg")
>>> b1 = img.binarize(128)
>>> b2 = img.binarize(blocksize=11,p=7)
>>> b3 = b1.sideBySide(b2)
>>> b3.show()

NOTES

Otsu’s Method Description<http://en.wikipedia.org/wiki/Otsu’s_method>

SEE ALSO

threshold() findBlobs() invert() dilate() erode()

binarizeFromPalette(palette_selection)

SUMMARY

This method uses the color palette to generate a binary (black and white) image. Palaette selection is a list of color tuples retrieved from img.getPalette(). The provided values will be drawn white while other values will be black.

PARAMETERS

palette_selection - color triplets selected from our palette that will serve turned into blobs These values can either be a 3xN numpy array, or a list of RGB triplets.

RETURNS

This method returns a black and white images, where colors that are close to the colors in palette_selection are set to white

EXAMPLE

>>> img = Image("lenna")
>>> p = img.getPalette()
>>> b = img.binarizeFromPalette( (p[0],p[1],[6]) )
>>> b.show()

SEE ALSO

rePalette() drawPaletteColors() palettize() getPalette() binarizeFromPalette() findBlobsFromPalette()

blit(img, pos=None, alpha=None, mask=None, alphaMask=None)

SUMMARY

Blit aka bit blit - which in ye olden days was an acronym for bit-block transfer. In other words blit is when you want to smash two images together, or add one image to another. This method takes in a second SimpleCV image, and then allows you to add to some point on the calling image. A general blit command will just copy all of the image. You can also copy the image with an alpha value to the source image is semi-transparent. A binary mask can be used to blit non-rectangular image onto the souce image. An alpha mask can be used to do and arbitrarily transparent image to this image. Both the mask and alpha masks are SimpleCV Images.

PARAMETERS

  • img - an image to place ontop of this image.
  • pos - an (x,y) position tuple of the top left corner of img on this image. Note that these values can be negative.
  • alpha - a single floating point alpha value (0=see the bottom image, 1=see just img, 0.5 blend the two 50/50).
  • mask - a binary mask the same size as the input image. White areas are blitted, black areas are not blitted.
  • alphaMask - an alpha mask where each grayscale value maps how much of each image is shown.

RETURNS

A SimpleCV Image. The size will remain the same.

EXAMPLE

>>> topImg = Image("top.png")
>>> bottomImg = Image("bottom.png")
>>> mask = Image("mask.png")
>>> aMask = Image("alpphaMask.png")
>>> bottomImg.blit(top,pos=(100,100)).show()
>>> bottomImg.blit(top,alpha=0.5).show()
>>> bottomImg.blit(top,pos=(100,100),mask=mask).show()
>>> bottomImg.blit(top,pos=(-10,-10)alphaMask=aMask).show()

SEE ALSO

createBinaryMask() createAlphaMask()

blur(window='', grayscale=False)

SUMMARY

Smoothes an image using the normalized box filter. The optional parameter is window.

see : http://en.wikipedia.org/wiki/Blur

Parameters

  • window - should be in the form a tuple (win_x,win_y).
    • By default it is set to 3x3, i.e window = (3x3).

NOTE For OpenCV versions <= 2.3.0 – this acts as Convience function derived from the smooth() method. Which internally calls cv.Smooth

For OpenCV versions higher than 2.3.0. i.e >= 2.3.0 – cv.blur function is called

bresenham_line((x, y), (x2, y2))

Brensenham line algorithm

cribbed from: http://snipplr.com/view.php?codeview&id=22482

This is just a helper method

camera = ''
channelMixer(channel='r', weight=(100, 100, 100))

SUMMARY

Mixes channel of an RGB image based on the weights provided. The output is given at the channel provided in the parameters. Basically alters the value of one channelg of an RGB image based in the values of other channels and itself. If the image is not RGB then first converts the image to RGB and then mixes channel

PARAMETERS

  • channel - The output channel in which the values are to be replaced.

It can have either ‘r’ or ‘g’ or ‘b’

  • weight - The weight of each channel in calculation of the mixed channel.

It is a tuple having 3 values mentioning the percentage of the value of the channels, from -200% to 200%

RETURNS

A SimpleCV RGB Image with the provided channel replaced with the mixed channel.

EXAMPLE

>>> img = Image("lenna")
>>> img2 = img.channelMixer()
>>> Img3 = img.channelMixer(channel = 'g', weights = (3,2,1))

NOTE

Read more at http://docs.gimp.org/en/plug-in-colors-channel-mixer.html

clear()

SUMMARY

This is a slightly unsafe method that clears out the entire image state it is usually used in conjunction with the drawing blobs to fill in draw a single large blob in the image.

clearLayers()

SUMMARY

Remove all of the drawing layers.

RETURNS

None.

EXAMPLE

>>> img = Image("Lenna")
>>> myLayer1 = DrawingLayer((img.width,img.height))
>>> myLayer2 = DrawingLayer((img.width,img.height))
>>> img.insertDrawingLayer(myLayer1,1) # on top
>>> img.insertDrawingLayer(myLayer2,2) # on the bottom
>>> img.clearLayers()

SEE ALSO

DrawingLayer dl() toPygameSurface() getDrawingLayer() removeDrawingLayer() layers() mergedLayers() applyLayers() drawText() drawRectangle() drawCircle() blit()

colorDistance(color=(0, 0, 0))

SUMMARY

Returns an image representing the distance of each pixel from a given color tuple, scaled between 0 (the given color) and 255. Pixels distant from the given tuple will appear as brighter and pixels closest to the target color will be darker.

By default this will give image intensity (distance from pure black)

PARAMETERS

  • color - Color object or Color Tuple

RETURNS

A SimpleCV Image.

EXAMPLE

>>> img = Image("logo")
>>> img2 = img.colorDistance(color=Color.BLACK)
>>> img2.show()

SEE ALSO

binarize() hueDistance() findBlobsFromMask()

convolve(kernel=[[1, 0, 0], [0, 1, 0], [0, 0, 1]], center=None)

SUMMARY

Convolution performs a shape change on an image. It is similiar to something like a dilate. You pass it a kernel in the form of a list, np.array, or cvMat

PARAMETERS

  • kernel - The convolution kernel. As a cvArray, cvMat, or Numpy Array.
  • center - If true we use the center of the kernel.

RETURNS

The image after we apply the convolution.

EXAMPLE

>>> img = Image("sampleimages/simplecv.png")
>>> kernel = [[1,0,0],[0,1,0],[0,0,1]]
>>> conv = img.convolve()

SEE ALSO

http://en.wikipedia.org/wiki/Convolution

copy()

SUMMARY

Return a full copy of the Image’s bitmap. Note that this is different from using python’s implicit copy function in that only the bitmap itself is copied. This method essentially performs a deep copy.

RETURNS

A copy of this SimpleCV image.

EXAMPLE

>>> img = Image("logo")
>>> img2 = img.copy()
createAlphaMask(hue=60, hue_lb=None, hue_ub=None)

SUMMARY

Generate a grayscale or binary mask image based either on a hue or an RGB triplet that can be used like an alpha channel. In the resulting mask, the hue/rgb_color will be treated as transparent (black).

When a hue is used the mask is treated like an 8bit alpha channel. When an RGB triplet is used the result is a binary mask. rgb_thresh is a distance measure between a given a pixel and the mask value that we will add to the mask. For example, if rgb_color=(0,255,0) and rgb_thresh=5 then any pixel winthin five color values of the rgb_color will be added to the mask (e.g. (0,250,0),(5,255,0)....)

Invert flips the mask values.

PARAMETERS

  • hue - a hue used to generate the alpha mask.
  • hue_lb - the upper value of a range of hue values to use.
  • hue_ub - the lower value of a range of hue values to use.

RETURNS

A grayscale alpha mask as a SimpleCV Image.

>>> img = Image("lenna")
>>> mask = img.createAlphaMask(hue_lb=50,hue_ub=70)
>>> mask.show()

SEE ALSO

createBinaryMask() createAlphaMask() applyBinaryMask() blit() threshold()

createBinaryMask(color1=(0, 0, 0), color2=(255, 255, 255))

SUMMARY

Generate a binary mask of the image based on a range of rgb values. A binary mask is a black and white image where the white area is kept and the black area is removed.

This method is used by specifying two colors as the range between the minimum and maximum values that will be masked white.

PARAMETERS

  • color1 - The starting color range for the mask..
  • color2 - The end of the color range for the mask.

RETURNS

A binary (black/white) image mask as a SimpleCV Image.

EXAMPLE

>>> img = Image("lenna")
>>> mask = img.createBinaryMask(color1=(0,128,128),color2=(255,255,255)
>>> mask.show()

SEE ALSO

createBinaryMask() createAlphaMask() blit() threshold()

crop(x, y=None, w=None, h=None, centered=False, smart=False)

SUMMARY

Consider you want to crop a image with the following dimension:

(x,y)
+--------------+
|              |
|              |h
|              |
+--------------+
      w      (x1,y1)

Crop attempts to use the x and y position variables and the w and h width and height variables to crop the image. When centered is false, x and y define the top and left of the cropped rectangle. When centered is true the function uses x and y as the centroid of the cropped region.

You can also pass a feature into crop and have it automatically return the cropped image within the bounding outside area of that feature

Or parameters can be in the form of a
  • tuple or list : (x,y,w,h) or [x,y,w,h]
  • two points : (x,y),(x1,y1) or [(x,y),(x1,y1)]

PARAMETERS

  • x - An integer or feature.
    • If it is a feature we crop to the features dimensions.
    • This can be either the top left corner of the image or the center cooridnate of the the crop region.
    • or in the form of tuple/list. i,e (x,y,w,h) or [x,y,w,h]
    • Otherwise in two point form. i,e [(x,y),(x1,y1)] or (x,y)
  • y - The y coordinate of the center, or top left corner of the crop region.
    • Otherwise in two point form. i,e (x1,y1)
  • w - Int - the width of the cropped region in pixels.

  • h - Int - the height of the cropped region in pixels.

  • centered - Boolean - if True we treat the crop region as being the center coordinate and a width and height. If false we treat it as the top left corner of the crop region.

  • smart - Will make sure you don’t try and crop outside the image size, so if your image is 100x100 and you tried a crop like img.crop(50,50,100,100), it will autoscale the crop to the max width.

RETURNS

A SimpleCV Image cropped to the specified width and height.

EXAMPLE

>>> img = Image('lenna')
>>> img.crop(50,40,128,128).show()
>>> img.crop((50,40,128,128)).show() #roi
>>> img.crop([50,40,128,128]) #roi
>>> img.crop((50,40),(178,168)) # two point form
>>> img.crop([(50,40),(178,168)]) # two point form
>>> img.crop([x1,x2,x3,x4,x5],[y1,y1,y3,y4,y5]) # list of x's and y's
>>> img.crop([(x,y),(x,y),(x,y),(x,y),(x,y)] # list of (x,y)
>>> img.crop(x,y,100,100, smart=True)
**SEE ALSO**

embiggen() regionSelect()

depth = 0
dilate(iterations=1)

SUMMARY

Apply a morphological dilation. An dilation has the effect of smoothing blobs while intensifying the amount of noise blobs. This implementation uses the default openCV 3X3 square kernel Erosion is effectively a local maxima detector, the kernel moves over the image and takes the maxima value inside the kernel.

PARAMETERS

  • iterations - the number of times to run the dilation operation.

RETURNS

A SimpleCV image.

EXAMPLE

>>> img = Image("lenna")
>>> derp = img.binarize()
>>> derp.dilate(3).show()

SEE ALSO

erode() binarize() morphOpen() morphClose() morphGradient() findBlobsFromMask()

dl(index=-1)

SUMMARY

Alias for getDrawingLayer()

drawCircle(ctr, rad, color=(0, 0, 0), thickness=1)

SUMMARY

Draw a circle on the image.

PARAMETERS

  • ctr - The center of the circle as an (x,y) tuple.
  • rad - The radius of the circle in pixels
  • color - A color tuple (default black)
  • thickness - The thickness of the circle, -1 means filled in.

RETURNS

Warning

This is an inline operation. Nothing is returned, but a circle is drawn on the images’s drawing layer.

EXAMPLE

>>> img = Image("lenna")
>>> img.drawCircle((img.width/2,img.height/2),r=50,color=Colors.RED,width=3)
>>> img.show()

NOTES

Warning

Note that this function is depricated, try to use DrawingLayer.circle() instead.

SEE ALSO

drawLine() drawText() dl() drawRectangle() DrawingLayer

drawKeypointMatches(template, thresh=500.0, minDist=0.15, width=1)

SUMMARY

Draw keypoints draws a side by side representation of two images, calculates keypoints for both images, determines the keypoint correspondences, and then draws the correspondences. This method is helpful for debugging keypoint calculations and also looks really cool :) . The parameters mirror the parameters used for findKeypointMatches to assist with debugging

PARAMETERS

  • template - A template image.
  • quality - The feature quality metric. This can be any value between about 300 and 500. Higher values should return fewer, but higher quality features.
  • minDist - The value below which the feature correspondence is considered a match. This is the distance between two feature vectors. Good values are between 0.05 and 0.3
  • width - The width of the drawn line.

RETURNS

A side by side image of the template and source image with each feature correspondence draw in a different color.

EXAMPLE

>>> img = cam.getImage()
>>> template = Image("myTemplate.png")
>>> result = img.drawKeypointMatches(self,template,300.00,0.4):

NOTES

If you would prefer to work with the raw keypoints and descriptors each image keeps a local cache of the raw values. These are named:

self._mKeyPoints # A tuple of keypoint objects See: http://opencv.itseez.com/modules/features2d/doc/common_interfaces_of_feature_detectors.html#keypoint-keypoint self._mKPDescriptors # The descriptor as a floating point numpy array self._mKPFlavor = “NONE” # The flavor of the keypoints as a string.

SEE ALSO

drawKeypointMatches() findKeypoints() findKeypointMatch()

drawLine(pt1, pt2, color=(0, 0, 0), thickness=1)

SUMMARY Draw a line on the image.

PARAMETERS

  • pt1 - the first point for the line (tuple).
  • pt2 - the second point on the line (tuple).
  • color - a color tuple (default black).
  • thickness the thickness of the line in pixels.

RETURNS

Warning

This is an inline operation. Nothing is returned, but a circle is drawn on the images’s drawing layer.

EXAMPLE

>>> img = Image("lenna")
>>> img.drawLine((0,0),(img.width,img.height),color=Color.RED,thickness=3)
>>> img.show()

NOTES

Warning

Note that this function is depricated, try to use DrawingLayer.line() instead.

SEE ALSO

drawText() dl() drawCircle() drawRectangle()

drawPaletteColors(size=(-1, -1), horizontal=True, bins=10, hue=False)

SUMMARY

This method returns the visual representation (swatches) of the palette in an image. The palette is orientated either horizontally or vertically, and each color is given an area proportional to the number of pixels that have that color in the image. The palette is arranged as it is returned from the clustering algorithm. When size is left to its default value, the palette size will match the size of the orientation, and then be 10% of the other dimension. E.g. if our image is 640X480 the horizontal palette will be (640x48) likewise the vertical palette will be (480x64)

If a Hue palette is used this method will return a grayscale palette.

PARAMETERS

  • bins - an integer number of bins into which to divide the colors in the image.
  • hue - if hue is true we do only cluster on the image hue values.
  • size - The size of the generated palette as a (width,height) tuple, if left default we select a size based on the image so it can be nicely displayed with the image.
  • horizontal - If true we orientate our palette horizontally, otherwise vertically.

RETURNS

A palette swatch image.

EXAMPLE

>>> p = img1.drawPaletteColors()
>>> img2 = img1.sideBySide(p,side="bottom")
>>> img2.show()

NOTES

The hue calculations should be siginificantly faster than the generic RGB calculation as it works in a one dimensional space. Sometimes the underlying scipy method freaks out about k-means initialization with the following warning:

Warning

One of the clusters is empty. Re-run kmean with a different initialization. This shouldn’t be a real problem.

SEE ALSO

rePalette() drawPaletteColors() palettize() getPalette() binarizeFromPalette() findBlobsFromPalette()

drawPoints(pts, color=(255, 0, 0), sz=3, width=-1)

DESCRIPTION

A quick and dirty points rendering routine.

PARAMETERS

  • pts - pts a list of (x,y) points.
  • color - a color for our points.
  • sz - the circle radius for our points.
  • width - if -1 fill the point, otherwise the size of point border

RETURNS

None - This is an inplace operation.

EXAMPLE

>>> img = Image("lenna")
>>> img.drawPoints([(10,10),(30,30)])
>>> img.show()
drawRectangle(x, y, w, h, color=(255, 0, 0), width=1, alpha=255)

SUMMARY

Draw a rectangle on the screen given the upper left corner of the rectangle and the width and height.

PARAMETERS

  • x - the x position.
  • y - the y position.
  • w - the width of the rectangle.
  • h - the height of the rectangle.
  • color - an RGB tuple indicating the desired color.
  • width - the width of the rectangle, a value less than or equal to zero means filled in completely.
  • alpha - the alpha value on the interval from 255 to 0, 255 is opaque, 0 is completely transparent.

RETURNS

None - this operation is in place and adds the rectangle to the drawing layer.

EXAMPLE

>>> img = Image("lenna")
>>> img.drawREctange( 50,50,100,123)
>>> img.show()

SEE ALSO

dl() drawCircle() drawRectangle() applyLayers() DrawingLayer

drawRotatedRectangle(boundingbox, color=(255, 0, 0), width=1)

SUMMARY

Draw the minimum bouding rectangle. This rectangle is a series of four points.

TODO

KAT FIX THIS

drawSIFTKeyPointMatch(template, distance=200, num=-1, width=1)

SUMMARY

Draw SIFT keypoints draws a side by side representation of two images, calculates keypoints for both images, determines the keypoint correspondences, and then draws the correspondences. This method is helpful for debugging keypoint calculations and also looks really cool :) . The parameters mirror the parameters used for findKeypointMatches to assist with debugging

PARAMETERS

  • template - A template image.

  • distance - This can be any value between about 100 and 500. Lower value should

    return less number of features but higher quality features.

  • num - Number of features you want to draw. Features are sorted according to the

    dist from min to max.

  • width - The width of the drawn line.

RETURNS

A side by side image of the template and source image with each feature correspondence draw in a different color.

EXAMPLE

>>> img = cam.getImage()
>>> template = Image("myTemplate.png")
>>> result = img.drawSIFTKeypointMatch(self,template,300.00):

SEE ALSO

drawKeypointMatches() findKeypoints() findKeypointMatch()

drawText(text='', x=None, y=None, color=(0, 0, 255), fontsize=16)

SUMMARY

This function draws the string that is passed on the screen at the specified coordinates.

The Default Color is blue but you can pass it various colors

The text will default to the center of the screen if you don’t pass it a value

PARAMETERS

  • text - String - the text you want to write. ASCII only please.
  • x - Int - the x position in pixels.
  • y - Int - the y position in pixels.
  • color - Color object or Color Tuple
  • fontsize - Int - the font size - roughly in points.

RETURNS

Nothing. This is an in place function. Text is added to the Images drawing layer.

EXAMPLE

>>> img = Image("lenna")
>>> img.drawText("xamox smells like cool ranch doritos.", 50,50,color=Color.BLACK,fontsize=48)
>>> img.show()

SEE ALSO

dl() drawCircle() drawRectangle()

edgeIntersections(pt0, pt1, width=1, canny1=0, canny2=100)

SUMMARY

Find the outermost intersection of a line segment and the edge image and return a list of the intersection points. If no intersections are found the method returns an empty list.

PARAMETERS

  • pt0 - an (x,y) tuple of one point on the intersection line.

  • pt1 - an (x,y) tuple of the second point on the intersection line.

  • width - the width of the line to use. This approach works better when

    for cases where the edges on an object are not always closed and may have holes.

  • canny1 - the lower bound of the Canny edge detector parameters.

  • canny2 - the upper bound of the Canny edge detector parameters.

RETURNS

A list of two (x,y) tuples or an empty list.

EXAMPLE

>>> img = Image("SimpleCV")
>>> a = (25,100)
>>> b = (225,110)
>>> pts = img.edgeIntersections(a,b,width=3)
>>> e = img.edges(0,100)
>>> e.drawLine(a,b,color=Color.RED)
>>> e.drawCircle(pts[0],10,color=Color.GREEN)
>>> e.drawCircle(pts[1],10,color=Color.GREEN)
>>> e.show()

img = Image(“SimpleCV”) a = (25,100) b = (225,100) pts = img.edgeIntersections(a,b,width=3) e = img.edges(0,100) e.drawLine(a,b,color=Color.RED) e.drawCircle(pts[0],10,color=Color.GREEN) e.drawCircle(pts[1],10,color=Color.GREEN) e.show()

edgeSnap(pointList, step=1)

SUMMARY

Given a List of points finds edges closet to the line joining two successive points, edges are returned as a FeatureSet of Lines.

Note : Image must be binary, it is assumed that prior conversion is done

Parameters

  • pointList - List of points to be checked for nearby edges.
  • step - Number of points to skip if no edge is found in vicinity.

    Keep this small if you want to sharply follow a curve

RETURNS

  • FeatureSet * - A FeatureSet of Lines

EXAMPLE

>>> image = Image("logo").edges()
>>> edgeLines = image.edgeSnap([(50,50),(230,200)])
>>> edgeLines.draw(color = Color.YELLOW,width = 3)
edges(t1=50, t2=100)

SUMMARY

Finds an edge map Image using the Canny edge detection method. Edges will be brighter than the surrounding area.

The t1 parameter is roughly the “strength” of the edge required, and the value between t1 and t2 is used for edge linking.

For more information:

PARAMETERS

  • t1 - Int - the lower Canny threshold.
  • t2 - Int - the upper Canny threshold.

RETURNS

A SimpleCV image where the edges are white on a black background.

EXAMPLE

>>> cam = Camera()
>>> while True:
>>>    cam.getImage().edges().show()

SEE ALSO

findLines()

embiggen(size=None, color=(0, 0, 0), pos=None)

SUMMARY

Make the canvas larger but keep the image the same size.

PARAMETERS

  • size - width and heigt tuple of the new canvas.
  • color - the color of the canvas
  • pos - the position of the top left corner of image on the new canvas, if none the image is centered.

RETURNS

The enlarged SimpleCV Image.

EXAMPLE

>>> img = Image("lenna")
>>> img = img.embiggen((1024,1024),color=Color.BLUE)
>>> img.show()
equalize()

SUMMARY

Perform a histogram equalization on the image.

RETURNS

Returns a grayscale SimpleCV image.

EXAMPLE

>>> img = Image("lenna")
>>> img = img.equalize()
erode(iterations=1)

SUMMARY

Apply a morphological erosion. An erosion has the effect of removing small bits of noise and smothing blobs.

This implementation uses the default openCV 3X3 square kernel

Erosion is effectively a local minima detector, the kernel moves over the image and takes the minimum value inside the kernel. iterations - this parameters is the number of times to apply/reapply the operation

PARAMETERS

  • iterations - the number of times to run the erosion operation.

RETURNS

A SimpleCV image.

EXAMPLE

>>> img = Image("lenna")
>>> derp = img.binarize()
>>> derp.erode(3).show()

SEE ALSO dilate() binarize() morphOpen() morphClose() morphGradient() findBlobsFromMask()

filehandle = ''
filename = ''
findAndRecognizeFaces(recognizer, cascade=None)

SUMMARY

Predict the class of the face in the image using FaceRecognizer.

PARAMETERS

  • recognizer - Trained FaceRecognizer object

  • cascade -haarcascade which would identify the face

    in the image.

EXAMPLES

>>> cam = Camera()
>>> img = cam.getImage()
>>> recognizer = FaceRecognizer()
>>> recognizer.load("training.xml")
>>> feat = img.findAndRecognizeFaces(recognizer, "face.xml")
>>> for feature, label in feat:
    ... i = feature.crop()
    ... i.drawText(str(label))
    ... i.show()
findBarcode(doZLib=True, zxing_path='')

SUMMARY

This function requires zbar and the zbar python wrapper to be installed or zxing and the zxing python library.

ZBAR

To install please visit: http://zbar.sourceforge.net/

On Ubuntu Linux 12.04 or greater: sudo apt-get install python-zbar

ZXING

If you have the python-zxing library installed, you can find 2d and 1d barcodes in your image. These are returned as Barcode feature objects in a FeatureSet. The single parameter is the ZXing_path along with setting the doZLib flag to False. You do not need the parameter if you don’t have the ZXING_LIBRARY env parameter set.

You can clone python-zxing at:

http://github.com/oostendo/python-zxing

INSTALLING ZEBRA CROSSING

  • Download the latest version of zebra crossing from: http://code.google.com/p/zxing/

  • unpack the zip file where ever you see fit

    >>> cd zxing-x.x, where x.x is the version number of zebra crossing
    >>> ant -f core/build.xml
    >>> ant -f javase/build.xml
    

    This should build the library, but double check the readme

  • Get our helper library

    >>> git clone git://github.com/oostendo/python-zxing.git
    >>> cd python-zxing
    >>> python setup.py install
    
  • Our library does not have a setup file. You will need to add

    it to your path variables. On OSX/Linux use a text editor to modify your shell file (e.g. .bashrc)

    export ZXING_LIBRARY=<FULL PATH OF ZXING LIBRARY - (i.e. step 2)> for example:

    export ZXING_LIBRARY=/my/install/path/zxing-x.x/

    On windows you will need to add these same variables to the system variable, e.g.

    http://www.computerhope.com/issues/ch000549.htm

  • On OSX/Linux source your shell rc file (e.g. source .bashrc). Windows users may need to restart.

  • Go grab some barcodes!

Warning

Users on OSX may see the following error:

RuntimeWarning: tmpnam is a potential security risk to your program

We are working to resolve this issue. For normal use this should not be a problem.

Returns

A FeatureSet of Barcode objects. If no barcodes are detected the method returns None.

EXAMPLE

>>> bc = cam.getImage()
>>> barcodes = img.findBarcodes()
>>> for b in barcodes:
>>>     b.draw()

SEE ALSO

FeatureSet Barcode

findBlobs(threshval=-1, minsize=10, maxsize=0, threshblocksize=0, threshconstant=5, appx_level=3)

SUMMARY

Find blobs will look for continuous light regions and return them as Blob features in a FeatureSet. Parameters specify the binarize filter threshold value, and minimum and maximum size for blobs. If a threshold value is -1, it will use an adaptive threshold. See binarize() for more information about thresholding. The threshblocksize and threshconstant parameters are only used for adaptive threshold.

PARAMETERS

  • threshval - the threshold as an integer or an (r,g,b) tuple , where pixels below (darker) than thresh are set to to max value, and all values above this value are set to black. If this parameter is -1 we use Otsu’s method.

  • minsize - the minimum size of the blobs, in pixels, of the returned blobs. This helps to filter out noise.

  • maxsize - the maximim size of the blobs, in pixels, of the returned blobs.

  • threshblocksize - the size of the block used in the adaptive binarize operation. TODO - make this match binarize

  • appx_level - The blob approximation level - an integer for the maximum distance between the true edge and the approximation edge - lower numbers yield better approximation.

    Warning

    This parameter must be an odd number.

  • threshconstant - The difference from the local mean to use for thresholding in Otsu’s method. TODO - make this match binarize

RETURNS

Returns a featureset (basically a list) of blob features. If no blobs are found this method returns None.

EXAMPLE

>>> img = Image("lenna")
>>> fs = img.findBlobs()
>>> if( fs is not None ):
>>>     fs.draw()

NOTES

Warning

For blobs that live right on the edge of the image OpenCV reports the position and width height as being one over for the true position. E.g. if a blob is at (0,0) OpenCV reports its position as (1,1). Likewise the width and height for the other corners is reported as being one less than the width and height. This is a known bug.

SEE ALSO threshold() binarize() invert() dilate() erode() findBlobsFromPalette() smartFindBlobs()

findBlobsFromMask(mask, threshold=128, minsize=10, maxsize=0, appx_level=3)

SUMMARY

This method acts like findBlobs, but it lets you specifiy blobs directly by providing a mask image. The mask image must match the size of this image, and the mask should have values > threshold where you want the blobs selected. This method can be used with binarize, dialte, erode, floodFill, edges etc to get really nice segmentation.

PARAMETERS

  • mask - The mask image, areas lighter than threshold will be counted as blobs. Mask should be the same size as this image.
  • threshold - A single threshold value used when we binarize the mask.
  • minsize - The minimum size of the returned blobs.
  • maxsize - The maximum size of the returned blobs, if none is specified we peg this to the image size.
  • appx_level - The blob approximation level - an integer for the maximum distance between the true edge and the approximation edge - lower numbers yield better approximation.

RETURNS

A featureset of blobs. If no blobs are found None is returned.

EXAMPLE

>>> img = Image("Foo.png")
>>> mask = img.binarize().dilate(2)
>>> blobs = img.findBlobsFromMask(mask)
>>> blobs.show()

SEE ALSO

findBlobs() binarize() threshold() dilate() erode()

findBlobsFromPalette(palette_selection, dilate=0, minsize=5, maxsize=0, appx_level=3)

SUMMARY

This method attempts to use palettization to do segmentation and behaves similar to the findBlobs blob in that it returs a feature set of blob objects. Once a palette has been extracted using getPalette() we can then select colors from that palette to be labeled white within our blobs.

PARAMETERS

  • palette_selection - color triplets selected from our palette that will serve turned into blobs These values can either be a 3xN numpy array, or a list of RGB triplets.
  • dilate - the optional number of dilation operations to perform on the binary image prior to performing blob extraction.
  • minsize - the minimum blob size in pixels
  • maxsize - the maximim blob size in pixels.
  • appx_level - The blob approximation level - an integer for the maximum distance between the true edge and the approximation edge - lower numbers yield better approximation.

RETURNS

If the method executes successfully a FeatureSet of Blobs is returned from the image. If the method fails a value of None is returned.

EXAMPLE

>>> img = Image("lenna")
>>> p = img.getPalette()
>>> blobs = img.findBlobsFromPalette( (p[0],p[1],[6]) )
>>> blobs.draw()
>>> img.show()

SEE ALSO

rePalette() drawPaletteColors() palettize() getPalette() binarizeFromPalette() findBlobsFromPalette()

findBlobsFromWatershed(mask=None, erode=2, dilate=2, useMyMask=False, invert=False, minsize=20, maxsize=None)

SUMMARY

Implements the watershed algorithm on the input image with an optional mask and t hen uses the mask to find blobs.

Read more:

Watershed: “http://en.wikipedia.org/wiki/Watershed_(image_processing)”

PARAMETERS

  • mask - an optional binary mask. If none is provided we do a binarize and invert.
  • erode - the number of times to erode the mask to find the foreground.
  • dilate - the number of times to dilate the mask to find possible background.
  • useMyMask - if this is true we do not modify the mask.
  • invert - invert the resulting mask before finding blobs.
  • minsize - minimum blob size in pixels.
  • maxsize - the maximum blob size in pixels.

RETURNS

A feature set of blob features.

EXAMPLE

>>> img = Image("/sampleimages/wshed.jpg")
>>> mask = img.threshold(100).dilate(3)
>>> blobs = img.findBlobsFromWatershed(mask)
>>> blobs.show()

SEE ALSO Color.WATERSHED_FG - The watershed foreground color Color.WATERSHED_BG - The watershed background color Color.WATERSHED_UNSURE - The watershed not sure if fg or bg color.

findChessboard(dimensions=(8, 5), subpixel=True)

SUMMARY

Given an image, finds a chessboard within that image. Returns the Chessboard featureset. The Chessboard is typically used for calibration because of its evenly spaced corners.

The single parameter is the dimensions of the chessboard, typical one can be found in SimpleCV oolsCalibGrid.png

PARAMETERS

  • dimensions - A tuple of the size of the chessboard in width and height in grid objects.
  • subpixel - Boolean if True use sub-pixel accuracy, otherwise use regular pixel accuracy.

RETURNS

A FeatureSet of Chessboard objects. If no chessboards are found None is returned.

EXAMPLE

>>> img = cam.getImage()
>>> cb = img.findChessboard()
>>> cb.draw()

SEE ALSO

FeatureSet Chessboard

findCircle(canny=100, thresh=350, distance=-1)

SUMMARY

Perform the Hough Circle transform to extract _perfect_ circles from the image canny - the upper bound on a canny edge detector used to find circle edges.

PARAMETERS

  • thresh - the threshold at which to count a circle. Small parts of a circle get added to the accumulator array used internally to the array. This value is the minimum threshold. Lower thresholds give more circles, higher thresholds give fewer circles.
  • distance - the minimum distance between each successive circle in pixels. 10 is a good starting value.

RETURNS

A feature set of Circle objects.

EXAMPLE

>>> img = Image("lenna")
>>> circs = img.findCircles()
>>> for c in circs:
>>>    print c
findCorners(maxnum=50, minquality=0.04, mindistance=1.0)

SUMMARY

This will find corner Feature objects and return them as a FeatureSet strongest corners first. The parameters give the number of corners to look for, the minimum quality of the corner feature, and the minimum distance between corners.

PARAMETERS

  • maxnum - The maximum number of corners to return.
  • minquality - The minimum quality metric. This shoudl be a number between zero and one.
  • mindistance - The minimum distance, in pixels, between successive corners.

RETURNS

A featureset of Corner features or None if no corners are found.

EXAMPLE

Standard Test:

>>> img = Image("sampleimages/simplecv.png")
>>> corners = img.findCorners()
>>> if corners: True

True

Validation Test:

>>> img = Image("sampleimages/black.png")
>>> corners = img.findCorners()
>>> if not corners: True

True

SEE ALSO

Corner findKeypoints()

findFeatures(method='szeliski', threshold=1000)

SUMMARY

Find szeilski or Harris features in the image. Harris features correspond to Harris corner detection in the image.

Read more:

Harris Features: http://en.wikipedia.org/wiki/Corner_detection szeliski Features: http://research.microsoft.com/en-us/um/people/szeliski/publications.htm

PARAMETERS

  • method - Features type
  • threshold - threshold val

RETURNS

A list of Feature objects corrseponding to the feature points.

EXAMPLE

>>> img = Image("corner_sample.png")
>>> fpoints = img.findFeatures("harris", 2000)
>>> for f in fpoints:
    ... f.draw()
>>> img.show()

SEE ALSO

drawKeypointMatches() findKeypoints() findKeypointMatch()

findFloodFillBlobs(points, tolerance=None, lower=None, upper=None, fixed_range=True, minsize=30, maxsize=-1)

SUMMARY

This method lets you use a flood fill operation and pipe the results to findBlobs. You provide the points to seed floodFill and the rest is taken care of.

floodFill works just like ye olde paint bucket tool in your favorite image manipulation program. You select a point (or a list of points), a color, and a tolerance, and floodFill will start at that point, looking for pixels within the tolerance from your intial pixel. If the pixel is in tolerance, we will convert it to your color, otherwise the method will leave the pixel alone. The method accepts both single values, and triplet tuples for the tolerance values. If you require more control over your tolerance you can use the upper and lower values. The fixed range parameter let’s you toggle between setting the tolerance with repect to the seed pixel, and using a tolerance that is relative to the adjacent pixels. If fixed_range is true the method will set its tolerance with respect to the seed pixel, otherwise the tolerance will be with repsect to adjacent pixels.

PARAMETERS

  • points - A tuple, list of tuples, or np.array of seed points for flood fill.
  • tolerance - The color tolerance as a single value or a triplet.
  • color - The color to replace the floodFill pixels with
  • lower - If tolerance does not provide enough control you can optionally set the upper and lower values around the seed pixel. This value can be a single value or a triplet. This will override the tolerance variable.
  • upper - If tolerance does not provide enough control you can optionally set the upper and lower values around the seed pixel. This value can be a single value or a triplet. This will override the tolerance variable.
  • fixed_range - If fixed_range is true we use the seed_pixel +/- tolerance If fixed_range is false, the tolerance is +/- tolerance of the values of the adjacent pixels to the pixel under test.
  • minsize - The minimum size of the returned blobs.
  • maxsize - The maximum size of the returned blobs, if none is specified we peg this to the image size.

RETURNS

A featureset of blobs. If no blobs are found None is returned.

An Image where the values similar to the seed pixel have been replaced by the input color.

EXAMPLE

>>> img = Image("lenna")
>>> blerbs = img.findFloodFillBlobs(((10,10),(20,20),(30,30)),tolerance=30)
>>> blerbs.show()

SEE ALSO

findBlobs() floodFill()

findGridLines()

SUMMARY

Return Grid Lines as a Line Feature Set

PARAMETERS

None

RETURNS

Grid Lines as a Feature Set

EXAMPLE

>>>> img = Image(‘something.png’) >>>> img.grid([20,20],(255,0,0)) >>>> lines = img.findGridLines()

findHaarFeatures(cascade, scale_factor=1.2, min_neighbors=2, use_canny=1, min_size=(20, 20), max_size=(1000, 1000))

SUMMARY

A Haar like feature cascase is a really robust way of finding the location of a known object. This technique works really well for a few specific applications like face, pedestrian, and vehicle detection. It is worth noting that this approach IS NOT A MAGIC BULLET . Creating a cascade file requires a large number of images that have been sorted by a human.vIf you want to find Haar Features (useful for face detection among other purposes) this will return Haar feature objects in a FeatureSet.

For more information, consult the cv.HaarDetectObjects documentation.

To see what features are available run img.listHaarFeatures() or you can provide your own haarcascade file if you have one available.

Note that the cascade parameter can be either a filename, or a HaarCascade loaded with cv.Load(), or a SimpleCV HaarCascade object.

PARAMETERS

  • cascade - The Haar Cascade file, this can be either the path to a cascade file or a HaarCascased SimpleCV object that has already been loaded.
  • scale_factor - The scaling factor for subsequent rounds of the Haar cascade (default 1.2) in terms of a percentage (i.e. 1.2 = 20% increase in size)
  • min_neighbors - The minimum number of rectangles that makes up an object. Ususally detected faces are clustered around the face, this is the number of detections in a cluster that we need for detection. Higher values here should reduce false positives and decrease false negatives.
  • use-canny - Whether or not to use Canny pruning to reject areas with too many edges (default yes, set to 0 to disable)
  • min_size - Minimum window size. By default, it is set to the size of samples the classifier has been trained on ((20,20) for face detection)
  • max_size - Maximum window size. By default, it is set to the size of samples the classifier has been trained on ((1000,1000) for face detection)

RETURNS

A feature set of HaarFeatures

EXAMPLE

>>> faces = HaarCascade("./SimpleCV/Features/HaarCascades/face.xml","myFaces")
>>> cam = Camera()
>>> while True:
>>>     f = cam.getImage().findHaarFeatures(faces)
>>>     if( f is not None ):
>>>          f.show()

NOTES

OpenCV Docs: - http://opencv.willowgarage.com/documentation/python/objdetect_cascade_classification.html

Wikipedia: - http://en.wikipedia.org/wiki/Viola-Jones_object_detection_framework - http://en.wikipedia.org/wiki/Haar-like_features

The video on this pages shows how Haar features and cascades work to located faces: - http://dismagazine.com/dystopia/evolved-lifestyles/8115/anti-surveillance-how-to-hide-from-machines/

findKeypointClusters(num_of_clusters=5, order='dsc', flavor='surf')

This function is meant to try and find interesting areas of an image. It does this by finding keypoint clusters in an image. It uses keypoint (ORB) detection to locate points of interest and then uses kmeans clustering to get the X,Y coordinates of those clusters of keypoints. You provide the expected number of clusters and you will get back a list of the X,Y coordinates and rank order of the number of Keypoints around those clusters

PARAMETERS * num_of_clusters - The number of clusters you are looking for (default: 5) * order - The rank order you would like the points returned in, dsc or asc, (default: dsc) * flavor - The keypoint type, or ‘corner’ for just corners

EXAMPLE

>>> img = Image('simplecv')
>>> clusters = img.findKeypointClusters()
>>> clusters.draw()
>>> img.show()

RETURNS

FeatureSet

findKeypointMatch(template, quality=500.0, minDist=0.2, minMatch=0.4)

SUMMARY

findKeypointMatch allows you to match a template image with another image using SURF keypoints. The method extracts keypoints from each image, uses the Fast Local Approximate Nearest Neighbors algorithm to find correspondences between the feature points, filters the correspondences based on quality, and then, attempts to calculate a homography between the two images. This homography allows us to draw a matching bounding box in the source image that corresponds to the template. This method allows you to perform matchs the ordinarily fail when using the findTemplate method. This method should be able to handle a reasonable changes in camera orientation and illumination. Using a template that is close to the target image will yield much better results.

Warning

This method is only capable of finding one instance of the template in an image. If more than one instance is visible the homography calculation and the method will fail.

PARAMETERS

  • template - A template image.
  • quality - The feature quality metric. This can be any value between about 300 and 500. Higher values should return fewer, but higher quality features.
  • minDist - The value below which the feature correspondence is considered a match. This is the distance between two feature vectors. Good values are between 0.05 and 0.3
  • minMatch - The percentage of features which must have matches to proceed with homography calculation. A value of 0.4 means 40% of features must match. Higher values mean better matches are used. Good values are between about 0.3 and 0.7

RETURNS

If a homography (match) is found this method returns a feature set with a single KeypointMatch feature. If no match is found None is returned.

EXAMPLE

>>> template = Image("template.png")
>>> img = camera.getImage()
>>> fs = img.findKeypointMatch(template)
>>> if( fs is not None ):
>>>      fs.draw()
>>>      img.show()

NOTES

If you would prefer to work with the raw keypoints and descriptors each image keeps a local cache of the raw values. These are named:

self._mKeyPoints # A Tuple of keypoint objects
self._mKPDescriptors # The descriptor as a floating point numpy array
self._mKPFlavor = “NONE” # The flavor of the keypoints as a string.

SEE ALSO

_getRawKeypoints() _getFLANNMatches() drawKeypointMatches() findKeypoints()

findKeypoints(min_quality=300.0, flavor='SURF', highQuality=False)

SUMMARY

This method finds keypoints in an image and returns them as a feature set. Keypoints are unique regions in an image that demonstrate some degree of invariance to changes in camera pose and illumination. They are helpful for calculating homographies between camera views, object rotations, and multiple view overlaps.

We support four keypoint detectors and only one form of keypoint descriptors. Only the surf flavor of keypoint returns feature and descriptors at this time.

PARAMETERS

RETURNS

A feature set of KeypointFeatures. These KeypointFeatures let’s you draw each feature, crop the features, get the feature descriptors, etc.

EXAMPLE

>>> img = Image("aerospace.jpg")
>>> fs = img.findKeypoints(flavor="SURF",min_quality=500,highQuality=True)
>>> fs = fs.sortArea()
>>> fs[-1].draw()
>>> img.draw()

NOTES

If you would prefer to work with the raw keypoints and descriptors each image keeps a local cache of the raw values. These are named:

_getRawKeypoints() _getFLANNMatches() drawKeypointMatches() findKeypoints()

findLines(threshold=80, minlinelength=30, maxlinegap=10, cannyth1=50, cannyth2=100)

SUMMARY

findLines will find line segments in your image and returns line feature objects in a FeatureSet. This method uses the Hough (pronounced “HUFF”) transform.

See http://en.wikipedia.org/wiki/Hough_transform

PARAMETERS

  • threshold - which determines the minimum “strength” of the line.
  • minlinelength - how many pixels long the line must be to be returned.
  • maxlinegap - how much gap is allowed between line segments to consider them the same line .
  • cannyth1 - thresholds used in the edge detection step, refer to _getEdgeMap() for details.
  • cannyth2 - thresholds used in the edge detection step, refer to _getEdgeMap() for details.

RETURNS

Returns a FeatureSet of Line objects. If no lines are found the method returns None.

EXAMPLE

>>> img = Image("lenna")
>>> lines = img.findLines()
>>> lines.draw()
>>> img.show()

SEE ALSO FeatureSet Line edges()

findMotion(previous_frame, window=11, method='BM', aggregate=True)

SUMMARY

findMotion performs an optical flow calculation. This method attempts to find motion between two subsequent frames of an image. You provide it with the previous frame image and it returns a feature set of motion fetures that are vectors in the direction of motion.

PARAMETERS

  • previous_frame - The last frame as an Image.
  • window - The block size for the algorithm. For the the HS and LK methods this is the regular sample grid at which we return motion samples. For the block matching method this is the matching window size.
  • method - The algorithm to use as a string. Your choices are:
  • aggregate - If aggregate is true, each of our motion features is the average of motion around the sample grid defined by window. If aggregate is false we just return the the value as sampled at the window grid interval. For block matching this flag is ignored.

RETURNS

A featureset of motion objects.

EXAMPLES

>>> cam = Camera()
>>> img1 = cam.getImage()
>>> img2 = cam.getImage()
>>> motion = img2.findMotion(img1)
>>> motion.draw()
>>> img2.show()

SEE ALSO

Motion FeatureSet

findSkintoneBlobs(minsize=10, maxsize=0, dilate_iter=1)

SUMMARY

Find Skintone blobs will look for continuous regions of Skintone in a color image and return them as Blob features in a FeatureSet. Parameters specify the binarize filter threshold value, and minimum and maximum size for blobs. If a threshold value is -1, it will use an adaptive threshold. See binarize() for more information about thresholding. The threshblocksize and threshconstant parameters are only used for adaptive threshold.

PARAMETERS

  • minsize - the minimum size of the blobs, in pixels, of the returned blobs. This helps to filter out noise.
  • maxsize - the maximim size of the blobs, in pixels, of the returned blobs.
  • dilate_iter - the number of times to run the dilation operation.

RETURNS

Returns a featureset (basically a list) of blob features. If no blobs are found this method returns None.

EXAMPLE

>>> img = Image("lenna")
>>> fs = img.findSkintoneBlobs()
>>> if( fs is not None ):
>>>     fs.draw()

NOTES It will be really awesome for making UI type stuff, where you want to track a hand or a face.

SEE ALSO threshold() binarize() invert() dilate() erode() findBlobsFromPalette() smartFindBlobs()

findTemplate(template_image=None, threshold=5, method='SQR_DIFF_NORM', grayscale=True)

SUMMARY

This function searches an image for a template image. The template image is a smaller image that is searched for in the bigger image. This is a basic pattern finder in an image. This uses the standard OpenCV template (pattern) matching and cannot handle scaling or rotation

Template matching returns a match score for every pixel in the image. Often pixels that are near to each other and a close match to the template are returned as a match. If the threshold is set too low expect to get a huge number of values. The threshold parameter is in terms of the number of standard deviations from the mean match value you are looking

For example, matches that are above three standard deviations will return 0.1% of the pixels. In a 800x600 image this means there will be 800*600*0.001 = 480 matches.

This method returns the locations of wherever it finds a match above a threshold. Because of how template matching works, very often multiple instances of the template overlap significantly. The best approach is to find the centroid of all of these values. We suggest using an iterative k-means approach to find the centroids.

PARAMETERS

  • template_image - The template image.
  • threshold - Int
  • method -
    • SQR_DIFF_NORM - Normalized square difference
    • SQR_DIFF - Square difference
    • CCOEFF -
    • CCOEFF_NORM -
    • CCORR - Cross correlation
    • CCORR_NORM - Normalize cross correlation
  • grayscale - Boolean - If false, template Match is found using BGR image.

EXAMPLE

>>> image = Image("/path/to/img.png")
>>> pattern_image = image.crop(100,100,100,100)
>>> found_patterns = image.findTemplate(pattern_image)
>>> found_patterns.draw()
>>> image.show()

RETURNS

This method returns a FeatureSet of TemplateMatch objects.

findTemplateOnce(template_image=None, threshold=0.2, method='SQR_DIFF_NORM', grayscale=True)

SUMMARY

This function searches an image for a single template image match.The template image is a smaller image that is searched for in the bigger image. This is a basic pattern finder in an image. This uses the standard OpenCV template (pattern) matching and cannot handle scaling or rotation

This method returns the single best match if and only if that match less than the threshold (greater than in the case of some methods).

PARAMETERS

  • template_image - The template image.
  • threshold - Int
  • method -
    • SQR_DIFF_NORM - Normalized square difference
    • SQR_DIFF - Square difference
    • CCOEFF -
    • CCOEFF_NORM -
    • CCORR - Cross correlation
    • CCORR_NORM - Normalize cross correlation
  • grayscale - Boolean - If false, template Match is found using BGR image.

EXAMPLE

>>> image = Image("/path/to/img.png")
>>> pattern_image = image.crop(100,100,100,100)
>>> found_patterns = image.findTemplateOnce(pattern_image)
>>> found_patterns.draw()
>>> image.show()

RETURNS

This method returns a FeatureSet of TemplateMatch objects.

fitContour(initial_curve, window=(11, 11), params=(0.1, 0.1, 0.1), doAppx=True, appx_level=1)

SUMMARY

This method tries to fit a list of points to lines in the image. The list of points is a list of (x,y) tuples that are near (i.e. within the window size) of the line you want to fit in the image. This method uses a binary such as the result of calling edges.

This method is based on active contours. Please see this reference: http://en.wikipedia.org/wiki/Active_contour_model

PARAMETERS

  • initial_curve - region of the form [(x0,y0),(x1,y1)...] that are the initial conditions to fit.
  • window - the search region around each initial point to look for a solution.
  • params - The alpha, beta, and gamma parameters for the active contours algorithm as a list [alpha,beta,gamma].
  • doAppx - post process the snake into a polynomial approximation. Basically this flag will clean up the output of the contour algorithm.
  • appx_level - how much to approximate the snake, higher numbers mean more approximation.

DISCUSSION

THIS SECTION IS QUOTED FROM: http://users.ecs.soton.ac.uk/msn/book/new_demo/Snakes/ There are three components to the Energy Function:

  • Continuity
  • Curvature
  • Image (Gradient)

Each Weighted by Specified Parameter:

Total Energy = Alpha*Continuity + Beta*Curvature + Gamma*Image

Choose different values dependent on Feature to extract:

  • Set alpha high if there is a deceptive Image Gradient
  • Set beta high if smooth edged Feature, low if sharp edges
  • Set gamma high if contrast between Background and Feature is low

RETURNS

A list of (x,y) tuples that approximate the curve. If you do not use approximation the list should be the same length as the input list length.

EXAMPLE

>>> img = Image("lenna")
>>> edges = img.edges(t1=120,t2=155)
>>> guess = [(311,284),(313,270),(320,259),(330,253),(347,245)]
>>> result = edges.fitContour(guess)
>>> img.drawPoints(guess,color=Color.RED)
>>> img.drawPoints(result,color=Color.GREEN)
>>> img.show()
fitLinePoints(guesses, window=(11, 11), samples=20, params=(0.1, 0.1, 0.1))

DESCRIPTION

This method uses the snakes / active contour approach in an attempt to fit a series of points to a line that may or may not be exactly linear.

PARAMETERS

  • guesses - A set of lines that we wish to fit to. The lines are specified as a list of tuples of (x,y) tuples. E.g. [((x0,y0),(x1,y1))....]
  • window - The search window in pixels for the active contours approach.
  • samples - The number of points to sample along the input line, these are the initial conditions for active contours method.
  • params - the alpha, beta, and gamma values for the active contours routine.

RETURNS

A list of fitted contour points. Each contour is a list of (x,y) tuples.

EXAMPLE

>>> img = Image("lsq.png")
>>> guesses = [((313,150),(312,332)),((62,172),(252,52)),((102,372),(182,182)),((372,62),(572,162)),((542,362),(462,182)),((232,412),(462,423))]
>>> r = img.fitLinePoints(guesses)
>>> for rr in r:
>>>    img.drawLine(rr[0],rr[1],color=Color.RED,width=3)
>>> for g in guesses:
>>>    img.drawLine(g[0],g[1],color=Color.YELLOW)
>>> img.show()
fitLines(guesses, window=10, threshold=128)

SUMMARY

Fit lines in a binary/gray image using an initial guess and the least squares method. The lines are returned as a line feature set.

PARAMETERS

  • guesses - A list of tuples of the form ((x0,y0),(x1,y1)) where each of the lines is an approximate guess.
  • window - A window around the guess to search.
  • threshold - the threshold above which we count a pixel as a line

RETURNS

A feature set of line features, one per guess.

EXAMPLE

>>> img = Image("lsq.png")
>>> guesses = [((313,150),(312,332)),((62,172),(252,52)),((102,372),(182,182)),((372,62),(572,162)),((542,362),(462,182)),((232,412),(462,423))]
>>> l = img.fitLines(guesses,window=10)
>>> l.draw(color=Color.RED,width=3)
>>> for g in guesses:
>>>    img.drawLine(g[0],g[1],color=Color.YELLOW)
>>> img.show()
flipHorizontal()

SUMMARY

Horizontally mirror an image.

Warning

Note that flip does not mean rotate 180 degrees! The two are different.

RETURNS

The flipped SimpleCV image.

EXAMPLE

>>> img = Image("lenna")
>>> upsidedown = img.flipHorizontal()

SEE ALSO

flipVertical() rotate()

flipVertical()

SUMMARY

Vertically mirror an image.

Warning

Note that flip does not mean rotate 180 degrees! The two are different.

RETURNS

The flipped SimpleCV image.

EXAMPLE

>>> img = Image("lenna")
>>> upsidedown = img.flipHorizontal()

SEE ALSO

rotate() flipHorizontal()

floodFill(points, tolerance=None, color=(255, 255, 255), lower=None, upper=None, fixed_range=True)

SUMMARY

FloodFill works just like ye olde paint bucket tool in your favorite image manipulation program. You select a point (or a list of points), a color, and a tolerance, and floodFill will start at that point, looking for pixels within the tolerance from your intial pixel. If the pixel is in tolerance, we will convert it to your color, otherwise the method will leave the pixel alone. The method accepts both single values, and triplet tuples for the tolerance values. If you require more control over your tolerance you can use the upper and lower values. The fixed range parameter let’s you toggle between setting the tolerance with repect to the seed pixel, and using a tolerance that is relative to the adjacent pixels. If fixed_range is true the method will set its tolerance with respect to the seed pixel, otherwise the tolerance will be with repsect to adjacent pixels.

PARAMETERS

  • points - A tuple, list of tuples, or np.array of seed points for flood fill
  • tolerance - The color tolerance as a single value or a triplet.
  • color - The color to replace the floodFill pixels with
  • lower - If tolerance does not provide enough control you can optionally set the upper and lower values around the seed pixel. This value can be a single value or a triplet. This will override the tolerance variable.
  • upper - If tolerance does not provide enough control you can optionally set the upper and lower values around the seed pixel. This value can be a single value or a triplet. This will override the tolerance variable.
  • fixed_range - If fixed_range is true we use the seed_pixel +/- tolerance If fixed_range is false, the tolerance is +/- tolerance of the values of the adjacent pixels to the pixel under test.

RETURNS

An Image where the values similar to the seed pixel have been replaced by the input color.

EXAMPLE

>>> img = Image("lenna")
>>> img2 = img.floodFill(((10,10),(54,32)),tolerance=(10,10,10),color=Color.RED)
>>> img2.show()

SEE ALSO

floodFillToMask() findFloodFillBlobs()

floodFillToMask(points, tolerance=None, color=(255, 255, 255), lower=None, upper=None, fixed_range=True, mask=None)

SUMMARY

floodFillToMask works sorta paint bucket tool in your favorite image manipulation program. You select a point (or a list of points), a color, and a tolerance, and floodFill will start at that point, looking for pixels within the tolerance from your intial pixel. If the pixel is in tolerance, we will convert it to your color, otherwise the method will leave the pixel alone. Unlike regular floodFill, floodFillToMask, will return a binary mask of your flood fill operation. This is handy if you want to extract blobs from an area, or create a selection from a region. The method takes in an optional mask. Non-zero values of the mask act to block the flood fill operations. This is handy if you want to use an edge image to “stop” the flood fill operation within a particular region.

The method accepts both single values, and triplet tuples for the tolerance values. If you require more control over your tolerance you can use the upper and lower values. The fixed range parameter let’s you toggle between setting the tolerance with repect to the seed pixel, and using a tolerance that is relative to the adjacent pixels. If fixed_range is true the method will set its tolerance with respect to the seed pixel, otherwise the tolerance will be with repsect to adjacent pixels.

PARAMETERS

  • points - A tuple, list of tuples, or np.array of seed points for flood fill
  • tolerance - The color tolerance as a single value or a triplet.
  • color - The color to replace the floodFill pixels with
  • lower - If tolerance does not provide enough control you can optionally set the upper and lower values around the seed pixel. This value can be a single value or a triplet. This will override the tolerance variable.
  • upper - If tolerance does not provide enough control you can optionally set the upper and lower values around the seed pixel. This value can be a single value or a triplet. This will override the tolerance variable.
  • fixed_range - If fixed_range is true we use the seed_pixel +/- tolerance If fixed_range is false, the tolerance is +/- tolerance of the values of the adjacent pixels to the pixel under test.
  • mask - An optional mask image that can be used to control the flood fill operation. the output of this function will include the mask data in the input mask.

RETURNS

An Image where the values similar to the seed pixel have been replaced by the input color.

EXAMPLE

>>> img = Image("lenna")
>>> mask = img.edges()
>>> mask= img.floodFillToMask(((10,10),(54,32)),tolerance=(10,10,10),mask=mask)
>>> mask.show

SEE ALSO

floodFill() findFloodFillBlobs()

gammaCorrect(gamma=1)

DESCRIPTION

Transforms an image according to Gamma Correction also known as Power Law Transform.

PARAMETERS

  • gamma - A non-negative real number.

RETURNS

A Gamma corrected image.

EXAMPLE

>>> img = Image('SimpleCV/sampleimages/family_watching_television_1958.jpg')
>>> img.show()
>>> img.gammaCorrect(1.5).show()
>>> img.gammaCorrect(0.7).show()
gaussianBlur(window='', sigmaX=0, sigmaY=0, grayscale=False)

SUMMARY

Smoothes an image, typically used to reduce image noise and reduce detail. The optional parameter is window.

see : http://en.wikipedia.org/wiki/Gaussian_blur

Parameters

  • window - should be in the form a tuple (win_x,win_y). Where win_x and win_y should be positive and odd.
    • By default it is set to 3x3, i.e window = (3x3).
  • sigmaX - Gaussian kernel standard deviation in X direction.

  • sigmaY - Gaussian kernel standard deviation in Y direction.

  • grayscale - If true, the effect is applied on grayscale images.

NOTE For OpenCV versions <= 2.3.0 – this acts as Convience function derived from the smooth() method. Which internally calls cv.Smooth

For OpenCV versions higher than 2.3.0. i.e >= 2.3.0 – cv.GaussianBlur function is called

getBitmap()

SUMMARY

Retrieve the bitmap (iplImage) of the Image. This is useful if you want to use functions from OpenCV with SimpleCV’s image class

RETURNS

Returns black OpenCV IplImage from this image.

EXAMPLE

>>> img = Image("lenna")
>>> rawImg  = img.getBitmap()
>>> rawOut  = img.getEmpty()
>>> cv.SomeOpenCVFunc(rawImg,rawOut)

SEE ALSO

getEmpty() getFPMatrix() getPIL() getNumpy() getGrayNumpy() getGrayscaleMatrix()

getColorSpace()

SUMMARY

Returns the value matched in the color space class

RETURNS

Integer corresponding to the color space.

EXAMPLE

>>> if(image.getColorSpace() == ColorSpace.RGB)

SEE ALSO

ColorSpace

getDFTLogMagnitude(grayscale=False)

SUMMARY

This method returns the log value of the magnitude image of the DFT transform. This method is helpful for examining and comparing the results of DFT transforms. The log component helps to “squish” the large floating point values into an image that can be rendered easily.

In the image the low frequency components are in the corners of the image and the high frequency components are in the center of the image.

PARAMETERS

  • grayscale - if grayscale is True we perform the magnitude operation of the grayscale image otherwise we perform the operation on each channel.

RETURNS

Returns a SimpleCV image corresponding to the log magnitude of the input image.

EXAMPLE

>>> img = Image("RedDog2.jpg")
>>> img.getDFTLogMagnitude().show()
>>> lpf = img.lowPassFilter(img.width/10.img.height/10)
>>> lpf.getDFTLogMagnitude().show()

NOTES

SEE ALSO

rawDFTImage() getDFTLogMagnitude() applyDFTFilter() highPassFilter() lowPassFilter() bandPassFilter() InverseDFT() applyButterworthFilter() InverseDFT() applyGaussianFilter() applyUnsharpMask()

getDrawingLayer(index=-1)

SUMMARY

Return a drawing layer based on the provided index. If not provided, will default to the top layer. If no layers exist, one will be created

PARAMETERS

  • index - returns the drawing layer at the specified index.

RETURNS

A drawing layer.

EXAMPLE

>>> img = Image("Lenna")
>>> myLayer1 = DrawingLayer((img.width,img.height))
>>> myLayer2 = DrawingLayer((img.width,img.height))
>>> #Draw on the layers
>>> img.insertDrawingLayer(myLayer1,1) # on top
>>> img.insertDrawingLayer(myLayer2,2) # on the bottom
>>> layer2 =img.getDrawingLayer(2)

SEE ALSO

DrawingLayer addDrawinglayer() dl() toPygameSurface() getDrawingLayer() removeDrawingLayer() clearLayers() layers() mergedLayers() applyLayers() drawText() drawRectangle() drawCircle() blit()

getEXIFData()

SUMMARY

This function extracts the exif data from an image file like JPEG or TIFF. The data is returned as a dict.

RETURNS

A dictionary of key value pairs. The value pairs are defined in the EXIF.py file.

EXAMPLE

>>> img = Image("./SimpleCV/sampleimages/OWS.jpg")
>>> data = img.getEXIFData()
>>> data['Image GPSInfo'].values

NOTES

See Also

EXIF

getEmpty(channels=3)

SUMMARY

Create a new, empty OpenCV bitmap with the specified number of channels (default 3). This method basically creates an empty copy of the image. This is handy for interfacing with OpenCV functions directly.

PARAMETERS

  • channels - The number of channels in the returned OpenCV image.

RETURNS

Returns an black OpenCV IplImage that matches the width, height, and color depth of the source image.

EXAMPLE

>>> img = Image("lenna")
>>> rawImg  = img.getEmpty()
>>> cv.SomeOpenCVFunc(img.getBitmap(),rawImg)

SEE ALSO

getBitmap() getFPMatrix() getPIL() getNumpy() getGrayNumpy() getGrayscaleMatrix()

getFPMatrix()

SUMMARY

Converts the standard int bitmap to a floating point bitmap. This is handy for some OpenCV functions.

RETURNS

Returns the floating point OpenCV CvMat version of this image.

EXAMPLE

>>> img = Image("lenna")
>>> rawImg  = img.getFPMatrix()
>>> rawOut  = img.getEmpty()
>>> cv.SomeOpenCVFunc(rawImg,rawOut)

SEE ALSO

getEmpty() getBitmap() getMatrix() getPIL() getNumpy() getGrayNumpy() getGrayscaleMatrix()

getFREAKDescriptor(flavor='SURF')

SUMMARY

Compute FREAK Descriptor of given keypoints. FREAK - Fast Retina Keypoints. Read more: http://www.ivpe.com/freak.htm

Keypoints can be extracted using following detectors.

  • SURF
  • SIFT
  • BRISK
  • ORB
  • STAR
  • MSER
  • FAST
  • Dense

PARAMETERS

  • flavor - Detector (see above list of detectors) - string

RETURNS

  • FeatureSet* - A feature set of KeyPoint Features.
  • Descriptor* - FREAK Descriptor

EXAMPLE

>>> img = Image("lenna")
>>> fs, des = img.getFREAKDescriptor("ORB")
getGrayHistogramCounts(bins=255, limit=-1)

This function returns a list of tuples of greyscale pixel counts by frequency. This would be useful in determining the dominate pixels (peaks) of the greyscale image.

PARAMETERS

  • bins - The number of bins for the hisogram, defaults to 255 (greyscale)
  • limit - The number of counts to return, default is all

RETURNS

  • List * - A list of tuples of (frequency, value)

EXAMPLE

>>> img = Image("lenna")
>>> counts = img.getGrayHistogramCounts()
>>> counts[0] #the most dominate pixel color tuple of frequency and value
>>> counts[1][1] #the second most dominate pixel color value
getGrayNumpy()

SUMMARY

Return a grayscale Numpy array of the image.

RETURNS

Returns the image, converted first to grayscale and then converted to a 2D numpy array.

EXAMPLE

>>> img = Image("lenna")
>>> rawImg  = img.getGrayNumpy()

SEE ALSO

getEmpty() getBitmap() getMatrix() getPIL() getNumpy() getGrayNumpy() getGrayscaleMatrix()

getGrayNumpyCv2()

SUMMARY

Get a Grayscale Numpy array of the image in width x height y compatible with OpenCV >= 2.3

RETURNS

Returns the grayscale numpy array compatible with OpenCV >= 2.3

EXAMPLE

>>> img = Image("lenna")
>>> rawImg  = img.getNumpyCv2()

SEE ALSO

getEmpty() getBitmap() getMatrix() getPIL() getGrayNumpy() getGrayscaleMatrix() getNumpy() getGrayNumpyCv2()

getGrayPixel(x, y)

SUMMARY

This function returns the gray value for a particular image pixel given a specific row and column.

Warning

This function will always return pixels in RGB format even if the image is BGR format.

PARAMETERS

  • x - Int the x pixel coordinate.
  • y - Int the y pixel coordinate.

RETURNS

A gray value integer between 0 and 255.

EXAMPLE

>>> img = Image(logo)
>>> color = img.getGrayPixel(10,10)

Warning

We suggest that this method be used sparingly. For repeated pixel access use python array notation. I.e. img[x][y].

getGrayscaleMatrix()

SUMMARY

Get the grayscale matrix (cvMat) version of the image, required for some OpenCV algorithms.

RETURNS

Returns the OpenCV CvMat version of this image.

EXAMPLE

>>> img = Image("lenna")
>>> rawImg  = img.getGrayscaleMatrix()
>>> rawOut  = img.getEmpty()
>>> cv.SomeOpenCVFunc(rawImg,rawOut)

SEE ALSO

getEmpty() getBitmap() getFPMatrix() getPIL() getNumpy() getGrayNumpy() getMatrix()

getHorzScanline(row)

SUMMARY

This function returns a single row of RGB values from the image. This is handy if you want to crawl the image looking for an edge.

PARAMETERS

  • row - the row number working from top=0 to bottom=img.height.

RETURNS

A a lumpy numpy array of the pixel values. Ususally this is in BGR format.

EXAMPLE

>>> img = Image("lenna")
>>> myColor = [0,0,0]
>>> sl = img.getHorzScanline(422)
>>> sll = sl.tolist()
>>> for p in sll:
>>>    if( p == myColor ):
>>>        # do something

SEE ALSO

getHorzScanlineGray() getVertScanlineGray() getVertScanline()

getHorzScanlineGray(row)

SUMMARY

This function returns a single row of gray values from the image as a numpy array. This is handy if you want to crawl the image looking for an edge.

PARAMETERS

  • row - the row number working from top=0 to bottom=img.height.

RETURNS

A a lumpy numpy array of the pixel values.

EXAMPLE

>>> img = Image("lenna")
>>> myColor = [255]
>>> sl = img.getHorzScanlineGray(420)
>>> sll = sl.tolist()
>>> for p in sll:
>>>    if( p == myColor ):
>>>        # do something

SEE ALSO

getHorzScanlineGray() getHorzScanline() getVertScanlineGray() getVertScanline()

getLineScan(x=None, y=None, pt1=None, pt2=None, channel=-1)

SUMMARY

This function takes in a channel of an image or grayscale by default and then pulls out a series of pixel values as a linescan object than can be manipulated further.

PARAMETERS

  • x - Take a vertical line scan at the column x.
  • y - Take a horizontal line scan at the row y.
  • pt1 - Take a line scan between two points on the line the line scan values always go in the +x direction
  • pt2 - Second parameter for a non-vertical or horizontal line scan.
  • channel - To select a channel. eg: selecting a channel RED,GREEN or BLUE. If set to -1 it operates with gray scale values

RETURNS

A SimpleCV.LineScan object or None if the method fails.

EXAMPLE

>>>> import matplotlib.pyplot as plt >>>> img = Image(‘lenna’) >>>> a = img.getLineScan(x=10) >>>> b = img.getLineScan(y=10) >>>> c = img.getLineScan(pt1 = (10,10), pt2 = (500,500) ) >>>> plt.plot(a) >>>> plt.plot(b) >>>> plt.plot(c) >>>> plt.show()

getMatrix()

SUMMARY

Get the matrix (cvMat) version of the image, required for some OpenCV algorithms.

RETURNS

Returns the OpenCV CvMat version of this image.

EXAMPLE

>>> img = Image("lenna")
>>> rawImg  = img.getMatrix()
>>> rawOut  = img.getEmpty()
>>> cv.SomeOpenCVFunc(rawImg,rawOut)

SEE ALSO

getEmpty() getBitmap() getFPMatrix() getPIL() getNumpy() getGrayNumpy() getGrayscaleMatrix()

getNumpy()

SUMMARY

Get a Numpy array of the image in width x height x RGB dimensions

RETURNS

Returns the image, converted first to grayscale and then converted to a 3D numpy array.

EXAMPLE

>>> img = Image("lenna")
>>> rawImg  = img.getNumpy()

SEE ALSO

getEmpty() getBitmap() getMatrix() getPIL() getGrayNumpy() getGrayscaleMatrix()

getNumpyCv2()

SUMMARY

Get a Numpy array of the image in width x height x RGB dimensions compatible with OpenCV >= 2.3

RETURNS

Returns the 3D numpy array of the image compatible with OpenCV >= 2.3

EXAMPLE

>>> img = Image("lenna")
>>> rawImg  = img.getNumpyCv2()

SEE ALSO

getEmpty() getBitmap() getMatrix() getPIL() getGrayNumpy() getGrayscaleMatrix() getNumpy() getGrayNumpyCv2()

getPGSurface()

SUMMARY

Returns the image as a pygame surface. This is used for rendering the display

RETURNS

A pygame surface object used for rendering.

getPIL()

SUMMARY

Get a PIL Image object for use with the Python Image Library This is handy for some PIL functions.

RETURNS

Returns the Python Imaging Library (PIL) version of this image.

EXAMPLE

>>> img = Image("lenna")
>>> rawImg  = img.getPIL()

SEE ALSO

getEmpty() getBitmap() getMatrix() getFPMatrix() getNumpy() getGrayNumpy() getGrayscaleMatrix()

getPalette(bins=10, hue=False, centroids=None)

SUMMARY

This method returns the colors in the palette of the image. A palette is the set of the most common colors in an image. This method is helpful for segmentation.

PARAMETERS

  • bins - an integer number of bins into which to divide the colors in the image.
  • hue - if hue is true we do only cluster on the image hue values.
  • centroids - A list of tuples that are the initial k-means estimates. This is handy if you want consisten results from the palettize.

RETURNS

A numpy array of the BGR color tuples.

EXAMPLE

>>> p = img.getPalette(bins=42)
>>> print p[2]

NOTES

The hue calculations should be siginificantly faster than the generic RGB calculation as it works in a one dimensional space. Sometimes the underlying scipy method freaks out about k-means initialization with the following warning:

Warning

One of the clusters is empty. Re-run kmean with a different initialization. This shouldn’t be a real problem.

SEE ALSO

rePalette() drawPaletteColors() palettize() getPalette() binarizeFromPalette() findBlobsFromPalette()

getPixel(x, y)

SUMMARY

This function returns the RGB value for a particular image pixel given a specific row and column.

Warning

this function will always return pixels in RGB format even if the image is BGR format.

PARAMETERS

  • x - Int the x pixel coordinate.
  • y - Int the y pixel coordinate.

RETURNS

A color value that is a three element integer tuple.

EXAMPLE

>>> img = Image(logo)
>>> color = img.getPixel(10,10)

Warning

We suggest that this method be used sparingly. For repeated pixel access use python array notation. I.e. img[x][y].

getPixelsOnLine(pt1, pt2)

SUMMARY

Return all of the pixels on an arbitrary line.

PARAMETERS

  • pt1 - The first pixel coordinate as an (x,y) tuple or list.
  • pt2 - The second pixel coordinate as an (x,y) tuple or list.

RETURNS

Returns a list of RGB pixels values.

EXAMPLE

>>>> img = Image(‘something.png’) >>>> img.getPixelsOnLine( (0,0), (img.width/2,img.height/2) )

getSkintoneMask(dilate_iter=0)

SUMMARY

Find Skintone mask will look for continuous regions of Skintone in a color image and return a binary mask where the white pixels denote Skintone region.

PARAMETERS

  • dilate_iter - the number of times to run the dilation operation.

RETURNS

Returns a binary mask.

EXAMPLE

>>> img = Image("lenna")
>>> mask = img.findSkintoneMask()
>>> mask.show()
getVertScanline(column)

SUMMARY

This function returns a single column of RGB values from the image as a numpy array. This is handy if you want to crawl the image looking for an edge.

PARAMETERS

  • column - the column number working from left=0 to right=img.width.

RETURNS

A numpy array of the pixel values. Ususally this is in BGR format.

EXAMPLE

>>> img = Image("lenna")
>>> myColor = [0,0,0]
>>> sl = img.getVertScanline(423)
>>> sll = sl.tolist()
>>> for p in sll:
>>>    if( p == myColor ):
>>>        # do something

SEE ALSO

getHorzScanlineGray() getHorzScanline() getVertScanlineGray() getVertScanline()

getVertScanlineGray(column)

SUMMARY

This function returns a single column of gray values from the image as a numpy array. This is handy if you want to crawl the image looking for an edge.

PARAMETERS

  • column - the column number working from left=0 to right=img.width.

RETURNS

A a lumpy numpy array of the pixel values.

EXAMPLE

>>> img = Image("lenna")
>>> myColor = [255]
>>> sl = img.getVertScanlineGray(421)
>>> sll = sl.tolist()
>>> for p in sll:
>>>    if( p == myColor ):
>>>        # do something

SEE ALSO

getHorzScanlineGray() getHorzScanline() getVertScanline()

grayPeaks(bins=255, delta=0, lookahead=15)

SUMMARY

Takes the histogram of a grayscale image, and returns the peak grayscale intensity values.

The bins parameter can be used to lump grays together, by default it is set to 255

Returns a list of tuples, each tuple contains the grayscale intensity, and the fraction of the image that has it.

PARAMETERS

  • bins - the integer number of bins, between 1 and 255.

  • delta - the minimum difference betweena peak and the following points,

    before a peak may be considered a peak.Useful to hinder the algorithm from picking up false peaks towards to end of the signal.

  • lookahead - the distance to lookahead from a peakto determine if it is

    an actual peak, should be an integer greater than 0.

RETURNS

A list of (grays,fraction) tuples.

NOTE

Implemented using the techniques used in huetab()

grayscale()

SUMMARY

This method returns a gray scale version of the image. It makes everything look like an old movie.

RETURNS

A grayscale SimpleCV image.

EXAMPLE

>>> img = Image("lenna")
>>> img.grayscale().binarize().show()

SEE ALSO

binarize()

grid(dimensions=(10, 10), color=(0, 0, 0), width=1, antialias=True, alpha=-1)

SUMMARY

Draw a grid on the image

PARAMETERS

  • dimensions - No of rows and cols as an (rows,xols) tuple or list.

  • color - Grid’s color as a tuple or list.

  • width - The grid line width in pixels.

  • antialias - Draw an antialiased object

  • aplha - The alpha blending for the object. If this value is -1 then the

    layer default value is used. A value of 255 means opaque, while 0 means transparent.

RETURNS

Returns the index of the drawing layer of the grid

EXAMPLE

>>>> img = Image(‘something.png’) >>>> img.grid([20,20],(255,0,0)) >>>> img.grid((20,20),(255,0,0),1,True,0)

height = 0
highPassFilter(xCutoff, yCutoff=None, grayscale=False)

SUMMARY

This method applies a high pass DFT filter. This filter enhances the high frequencies and removes the low frequency signals. This has the effect of enhancing edges. The frequencies are defined as going between 0.00 and 1.00 and where 0 is the lowest frequency in the image and 1.0 is the highest possible frequencies. Each of the frequencies are defined with respect to the horizontal and vertical signal. This filter isn’t perfect and has a harsh cutoff that causes ringing artifacts.

PARAMETERS

  • xCutoff - The horizontal frequency at which we perform the cutoff. A separate frequency can be used for the b,g, and r signals by providing a list of values. The frequency is defined between zero to one, where zero is constant component and 1 is the highest possible frequency in the image.
  • yCutoff - The cutoff frequencies in the y direction. If none are provided we use the same values as provided for x.
  • grayscale - if this value is True we perfrom the operation on the DFT of the gray version of the image and the result is gray image. If grayscale is true we perform the operation on each channel and the recombine them to create the result.

RETURNS

A SimpleCV Image after applying the filter.

EXAMPLE

>>> img = Image("SimpleCV/sampleimages/RedDog2.jpg")
>>> img.getDFTLogMagnitude().show()
>>> hpf = img.highPassFilter([0.2,0.1,0.2])
>>> hpf.show()
>>> hpf.getDFTLogMagnitude().show()

NOTES

This filter is far from perfect and will generate a lot of ringing artifacts. * See: http://en.wikipedia.org/wiki/Ringing_(signal) * See: http://en.wikipedia.org/wiki/High-pass_filter#Image

SEE ALSO

rawDFTImage() getDFTLogMagnitude() applyDFTFilter() highPassFilter() lowPassFilter() bandPassFilter() InverseDFT() applyButterworthFilter() InverseDFT() applyGaussianFilter() applyUnsharpMask()

histogram(numbins=50)

SUMMARY

Return a numpy array of the 1D histogram of intensity for pixels in the image Single parameter is how many “bins” to have.

PARAMETERS

  • numbins - An interger number of bins in a histogram.

RETURNS

A list of histogram bin values.

EXAMPLE

>>> img = Image('lenna')
>>> hist = img.histogram()

SEE ALSO

hueHistogram()

horizontalHistogram(bins=10, threshold=128, normalize=False, forPlot=False)

DESCRIPTION

This method generates histogram of the number of grayscale pixels greater than the provided threshold. The method divides the image into a number evenly spaced horizontal bins and then counts the number of pixels where the pixel is greater than the threshold. This method is helpful for doing basic morphological analysis.

PARAMETERS

  • bins - The number of bins to use.
  • threshold - The grayscale threshold. We count pixels greater than this value.
  • normalize - If normalize is true we normalize the bin counts to sum to one. Otherwise we return the number of pixels.
  • forPlot - If this is true we return the bin indicies, the bin counts, and the bin widths as a tuple. We can use these values in pyplot.bar to quickly plot the histogram.

RETURNS

The default settings return the raw bin counts moving from top to bottom on the image. If forPlot is true we return a tuple that contains a list of bin labels, the bin counts, and the bin widths. This tuple can be used to plot the histogram using matplotlib.pyplot.bar function.

EXAMPLE

>>>> import matplotlib.pyplot as plt >>>> img = Image(‘lenna’) >>>> plt.bar(img.horizontalHistogram(threshold=128,bins=10,normalize=False,forPlot=True),color=’y’) >>>> plt.show())

NOTES

See: http://docs.scipy.org/doc/numpy/reference/generated/numpy.histogram.html See: http://matplotlib.org/api/pyplot_api.html?highlight=hist#matplotlib.pyplot.hist

hueDistance(color=(0, 0, 0), minsaturation=20, minvalue=20)

SUMMARY

Returns an image representing the distance of each pixel from the given hue of a specific color. The hue is “wrapped” at 180, so we have to take the shorter of the distances between them – this gives a hue distance of max 90, which we’ll scale into a 0-255 grayscale image.

The minsaturation and minvalue are optional parameters to weed out very weak hue signals in the picture, they will be pushed to max distance [255]

PARAMETERS

  • color - Color object or Color Tuple.
  • minsaturation - the minimum saturation value for color (from 0 to 255).
  • minvalue - the minimum hue value for the color (from 0 to 255).

RETURNS

A simpleCV image.

EXAMPLE

>>> img = Image("logo")
>>> img2 = img.hueDistance(color=Color.BLACK)
>>> img2.show()

SEE ALSO

binarize() hueDistance() morphOpen() morphClose() morphGradient() findBlobsFromMask()

hueHistogram(bins=179)

SUMMARY

Returns the histogram of the hue channel for the image

PARAMETERS

  • numbins - An interger number of bins in a histogram.

RETURNS

A list of histogram bin values.

SEE ALSO

histogram()

huePeaks(bins=179)

SUMMARY

Takes the histogram of hues, and returns the peak hue values, which can be useful for determining what the “main colors” in a picture.

The bins parameter can be used to lump hues together, by default it is 179 (the full resolution in OpenCV’s HSV format)

Peak detection code taken from https://gist.github.com/1178136 Converted from/based on a MATLAB script at http://billauer.co.il/peakdet.html

Returns a list of tuples, each tuple contains the hue, and the fraction of the image that has it.

PARAMETERS

  • bins - the integer number of bins, between 0 and 179.

RETURNS

A list of (hue,fraction) tuples.

insertDrawingLayer(layer, index)

SUMMARY

Insert a new layer into the layer stack at the specified index.

PARAMETERS

  • layer - A drawing layer with crap you want to draw.
  • index - The index at which to insert the layer.

RETURNS

None - that’s right - nothing.

EXAMPLE

>>> img = Image("Lenna")
>>> myLayer1 = DrawingLayer((img.width,img.height))
>>> myLayer2 = DrawingLayer((img.width,img.height))
>>> #Draw on the layers
>>> img.insertDrawingLayer(myLayer1,1) # on top
>>> img.insertDrawingLayer(myLayer2,2) # on the bottom

SEE ALSO

DrawingLayer addDrawinglayer() dl() toPygameSurface() getDrawingLayer() removeDrawingLayer() clearLayers() layers() mergedLayers() applyLayers() drawText() drawRectangle() drawCircle() blit()

integralImage(tilted=False)

SUMMARY

Calculate the integral image and return it as a numpy array. The integral image gives the sum of all of the pixels above and to the right of a given pixel location. It is useful for computing Haar cascades. The return type is a numpy array the same size of the image. The integral image requires 32Bit values which are not easily supported by the SimpleCV Image class.

PARAMETERS

  • tilted - if tilted is true we tilt the image 45 degrees and then calculate the results.

RETURNS

A numpy array of the values.

EXAMPLE

>>> img = Image("logo")
>>> derp = img.integralImage()

SEE ALSO

http://en.wikipedia.org/wiki/Summed_area_table

invert()

SUMMARY

Invert (negative) the image note that this can also be done with the unary minus (-) operator. For binary image this turns black into white and white into black (i.e. white is the new black).

RETURNS

The opposite of the current image.

EXAMPLE

>>> img  = Image("polar_bear_in_the_snow.png")
>>> img.invert().save("black_bear_at_night.png")

SEE ALSO

binarize()

isBGR()

SUMMARY

Returns true if this image uses the BGR colorspace.

RETURNS

True if the image uses the BGR colorspace, False otherwise.

EXAMPLE

>>> if( img.isBGR() ):
>>>    b,g,r = img.splitChannels()

SEE ALSO

toBGR()

isEmpty()

SUMMARY

Checks if the image is empty by checking its width and height.

RETURNS

True if the image’s size is (0, 0), False for any other size.

isGray()

SUMMARY

Returns true if this image uses the Gray colorspace.

RETURNS

True if the image uses the Gray colorspace, False otherwise.

EXAMPLE

>>> if( img.isGray() ):
>>>    print "The image is in Grayscale."

SEE ALSO

toGray()

isHLS()

SUMMARY

Returns true if this image uses the HLS colorspace.

RETURNS

True if the image uses the HLS colorspace, False otherwise.

EXAMPLE

>>> if( img.isHLS() ):
>>>    h,l,s = img.splitChannels()

SEE ALSO

toHLS()

isHSV()

SUMMARY

Returns true if this image uses the HSV colorspace.

RETURNS

True if the image uses the HSV colorspace, False otherwise.

EXAMPLE

>>> if( img.isHSV() ):
>>>    h,s,v = img.splitChannels()

SEE ALSO

toHSV()

isRGB()

SUMMARY

Returns true if this image uses the RGB colorspace.

RETURNS

True if the image uses the RGB colorspace, False otherwise.

EXAMPLE

>>> if( img.isRGB() ):
>>>    r,g,b = img.splitChannels()

SEE ALSO

toRGB()

isXYZ()

SUMMARY

Returns true if this image uses the XYZ colorspace.

RETURNS

True if the image uses the XYZ colorspace, False otherwise.

EXAMPLE

>>> if( img.isXYZ() ):
>>>    x,y,z = img.splitChannels()

SEE ALSO

toXYZ()

isYCrCb()

SUMMARY

Returns true if this image uses the YCrCb colorspace.

RETURNS

True if the image uses the YCrCb colorspace, False otherwise.

EXAMPLE

>>> if( img.isYCrCb() ):
>>>    Y,Cr,Cb = img.splitChannels()

SEE ALSO

toYCrCb()

layers()

SUMMARY

Return the array of DrawingLayer objects associated with the image.

RETURNS

A list of of drawing layers.

SEE ALSO

DrawingLayer addDrawingLayer() dl() toPygameSurface() getDrawingLayer() removeDrawingLayer() mergedLayers() applyLayers() drawText() drawRectangle() drawCircle() blit()

listHaarFeatures()

This is used to list the built in features available for HaarCascade feature detection. Just run this function as:

>>> img.listHaarFeatures()

Then use one of the file names returned as the input to the findHaarFeature() function. So you should get a list, more than likely you will see face.xml, to use it then just

>>> img.findHaarFeatures('face.xml')
live()

SUMMARY

This shows a live view of the camera. * Left click will show mouse coordinates and color. * Right click will kill the live image.

RETURNS

Nothing. In place method.

EXAMPLE

>>> cam = Camera()
>>> cam.live()
logicalAND(img, grayscale=True)

SUMMARY

Perform bitwise AND operation on images

PARAMETERS

img - the bitwise operation to be performed with grayscale

RETURNS

SimpleCV.ImageClass.Image

EXAMPLE

>>> img = Image("something.png")
>>> img1 = Image("something_else.png")
>>> img.logicalAND(img1, grayscale=False)
>>> img.logicalAND(img1)
logicalNAND(img, grayscale=True)

SUMMARY

Perform bitwise NAND operation on images

PARAMETERS

img - the bitwise operation to be performed with grayscale

RETURNS

SimpleCV.ImageClass.Image

EXAMPLE

>>> img = Image("something.png")
>>> img1 = Image("something_else.png")
>>> img.logicalNAND(img1, grayscale=False)
>>> img.logicalNAND(img1)
logicalOR(img, grayscale=True)

SUMMARY

Perform bitwise OR operation on images

PARAMETERS

img - the bitwise operation to be performed with grayscale

RETURNS

SimpleCV.ImageClass.Image

EXAMPLE

>>> img = Image("something.png")
>>> img1 = Image("something_else.png")
>>> img.logicalOR(img1, grayscale=False)
>>> img.logicalOR(img1)
logicalXOR(img, grayscale=True)

SUMMARY

Perform bitwise XOR operation on images

PARAMETERS

img - the bitwise operation to be performed with grayscale

RETURNS

SimpleCV.ImageClass.Image

EXAMPLE

>>> img = Image("something.png")
>>> img1 = Image("something_else.png")
>>> img.logicalXOR(img1, grayscale=False)
>>> img.logicalXOR(img1)
lowPassFilter(xCutoff, yCutoff=None, grayscale=False)

SUMMARY

This method applies a low pass DFT filter. This filter enhances the low frequencies and removes the high frequency signals. This has the effect of reducing noise. The frequencies are defined as going between 0.00 and 1.00 and where 0 is the lowest frequency in the image and 1.0 is the highest possible frequencies. Each of the frequencies are defined with respect to the horizontal and vertical signal. This filter isn’t perfect and has a harsh cutoff that causes ringing artifacts.

PARAMETERS

  • xCutoff - The horizontal frequency at which we perform the cutoff. A separate frequency can be used for the b,g, and r signals by providing a list of values. The frequency is defined between zero to one, where zero is constant component and 1 is the highest possible frequency in the image.
  • yCutoff - The cutoff frequencies in the y direction. If none are provided we use the same values as provided for x.
  • grayscale - if this value is True we perfrom the operation on the DFT of the gray version of the image and the result is gray image. If grayscale is true we perform the operation on each channel and the recombine them to create the result.

RETURNS

A SimpleCV Image after applying the filter.

EXAMPLE

>>> img = Image("SimpleCV/sampleimages/RedDog2.jpg")
>>> img.getDFTLogMagnitude().show()
>>> lpf = img.lowPassFilter([0.2,0.2,0.05])
>>> lpf.show()
>>> lpf.getDFTLogMagnitude().show()

NOTES

This filter is far from perfect and will generate a lot of ringing artifacts. See: http://en.wikipedia.org/wiki/Ringing_(signal) See: http://en.wikipedia.org/wiki/Low-pass_filter

SEE ALSO

rawDFTImage() getDFTLogMagnitude() applyDFTFilter() highPassFilter() lowPassFilter() bandPassFilter() InverseDFT() applyButterworthFilter() InverseDFT() applyGaussianFilter() applyUnsharpMask()

matchSIFTKeyPoints(template, quality=200)

SUMMARY

matchSIFTKeypoint allows you to match a template image with another image using SIFT keypoints. The method extracts keypoints from each image, uses the Fast Local Approximate Nearest Neighbors algorithm to find correspondences between the feature points, filters the correspondences based on quality. This method should be able to handle a reasonable changes in camera orientation and illumination. Using a template that is close to the target image will yield much better results.

PARAMETERS

  • template - A template image.
  • quality - The feature quality metric. This can be any value between about 100 and 500. Lower values should return fewer, but higher quality features.

RETURNS

A Tuple of lists consisting of matched KeyPoints found on the image and matched keypoints found on the template. keypoints are sorted according to lowest distance.

EXAMPLE

>>> template = Image("template.png")
>>> img = camera.getImage()
>>> fs = img.macthSIFTKeyPoints(template)

SEE ALSO

_getRawKeypoints() _getFLANNMatches() drawKeypointMatches() findKeypoints()

max(other)

SUMMARY

The maximum value of my image, and the other image, in each channel If other is a number, returns the maximum of that and the number

PARAMETERS

  • other - Image or a number.

RETURNS

A SimpelCV image.

maxValue(locations=False)

SUMMARY Returns the brightest/maximum pixel value in the grayscale image. This method can also return the locations of pixels with this value.

PARAMETERS

  • locations - If true return the location of pixels

    that have this value.

RETURNS

The maximum value and optionally the list of points as a list of (x,y) tuples.

EXAMPLE

>>> img = Image("lenna")
>>> max = img.maxValue()
>>> min, pts = img.minValue(locations=True)
>>> img2 = img.stretch(min,max)
meanColor()

SUMMARY

This method finds the average color of all the pixels in the image.

RETURNS

A tuple of the average image values. Tuples are in the channel order. For most images this means the results are (B,G,R).

EXAMPLE

>>> img = Image('lenna')
>>> colors = img.meanColor()
medianFilter(window='', grayscale=False)

SUMMARY

Smooths the image, with the median filter. Performs a median filtering operation to denoise/despeckle the image. The optional parameter is the window size. see : http://en.wikipedia.org/wiki/Median_filter

Parameters

  • window - should be in the form a tuple (win_x,win_y). Where win_x should be equal to win_y. By default it is set to 3x3, i.e window = (3x3).

Note

win_x and win_y should be greater than zero, a odd number and equal.

For OpenCV versions <= 2.3.0 this acts as Convience function derived from the smooth() method. Which internally calls cv.Smooth

For OpenCV versions >= 2.3.0 cv2.medianBlur function is called.

mergeChannels(r=None, g=None, b=None)

SUMMARY

Merge channels is the oposite of splitChannels. The image takes one image for each of the R,G,B channels and then recombines them into a single image. Optionally any of these channels can be None.

PARAMETERS

  • r - The r or last channel of the result SimpleCV Image.
  • g - The g or center channel of the result SimpleCV Image.
  • b - The b or first channel of the result SimpleCV Image.

RETURNS

A SimpleCV Image.

EXAMPLE

>>> img = Image("lenna")
>>> [r,g,b] = img.splitChannels()
>>> r = r.binarize()
>>> g = g.binarize()
>>> b = b.binarize()
>>> result = img.mergeChannels(r,g,b)
>>> result.show()

SEE ALSO splitChannels()

mergedLayers()

SUMMARY

Return all DrawingLayer objects as a single DrawingLayer.

RETURNS

Returns a drawing layer with all of the drawing layers of this image merged into one.

EXAMPLE

>>> img = Image("Lenna")
>>> myLayer1 = DrawingLayer((img.width,img.height))
>>> myLayer2 = DrawingLayer((img.width,img.height))
>>> img.insertDrawingLayer(myLayer1,1) # on top
>>> img.insertDrawingLayer(myLayer2,2) # on the bottom
>>> derp = img.mergedLayers()

SEE ALSO

DrawingLayer addDrawingLayer() dl() toPygameSurface() getDrawingLayer() removeDrawingLayer() layers() applyLayers() drawText() drawRectangle() drawCircle() blit()

min(other)

SUMMARY

The minimum value of my image, and the other image, in each channel If other is a number, returns the minimum of that and the number

Parameter

  • other - Image

Returns

IMAGE

minValue(locations=False)

SUMMARY Returns the darkest/minimum pixel value in the grayscale image. This method can also return the locations of pixels with this value.

PARAMETERS

  • locations - If true return the location of pixels

    that have this value.

RETURNS

The minimum value and optionally the list of points as a list of (x,y) tuples.

EXAMPLE

>>> img = Image("lenna")
>>> max = img.maxValue()
>>> min, pts = img.minValue(locations=True)
>>> img2 = img.stretch(min,max)
morphClose()

SUMMARY

morphologyClose applies a morphological close operation which is effectively a dilation operation followed by a morphological erosion. This operation helps to ‘bring together’ or ‘close’ binary regions which are close together.

  • See: Closing
  • See: Morphology from OpenCV
  • Example Use: Use when a part, which should be one blob is really two blobs.
  • Example Code: ./examples/MorphologyExample.py

RETURNS

A SimpleCV image.

EXAMPLE

>>> img = Image("lenna")
>>> derp = img.binarize()
>>> derp.morphClose.show()

SEE ALSO

erode() dilate() binarize() morphOpen() morphGradient() findBlobsFromMask()

morphGradient()

SUMMARY

The morphological gradient is the difference betwen the morphological dilation and the morphological gradient. This operation extracts the edges of a blobs in the image.

RETURNS

A SimpleCV image.

EXAMPLE

>>> img = Image("lenna")
>>> derp = img.binarize()
>>> derp.morphGradient.show()

SEE ALSO

erode() dilate() binarize() morphOpen() morphClose() findBlobsFromMask()

morphOpen()

SUMMARY

morphologyOpen applies a morphological open operation which is effectively an erosion operation followed by a morphological dilation. This operation helps to ‘break apart’ or ‘open’ binary regions which are close together.

RETURNS

A SimpleCV image.

EXAMPLE

>>> img = Image("lenna")
>>> derp = img.binarize()
>>> derp.morphOpen.show()

SEE ALSO

erode() dilate() binarize() morphClose() morphGradient() findBlobsFromMask()

motionBlur(intensity=15, angle=0)

SUMMARY

Performs the motion blur of an Image given the intensity and angle

see : https://en.wikipedia.org/wiki/Motion_blur

Parameters

  • intensity - The intensity of the motion blur effect. Governs the

    size of the kernel used in convolution

  • angle - Angle in degrees at which motion blur will occur. Positive

    is Clockwise and negative is Anti-Clockwise. 0 blurs from left to right

RETURNS

An image with the specified motion blur applied.

EXAMPLE >>> img = Image (‘lenna’) >>> blur = img.motionBlur(40,45) >>> blur.show()

palettize(bins=10, hue=False, centroids=None)

SUMMARY

This method analyzes an image and determines the most common colors using a k-means algorithm. The method then goes through and replaces each pixel with the centroid of the clutsters found by k-means. This reduces the number of colors in an image to the number of bins. This can be particularly handy for doing segementation based on color.

PARAMETERS

  • bins - an integer number of bins into which to divide the colors in the image.
  • hue - if hue is true we do only cluster on the image hue values.

RETURNS

An image matching the original where each color is replaced with its palette value.

EXAMPLE

>>> img2 = img1.palettize()
>>> img2.show()

NOTES

The hue calculations should be siginificantly faster than the generic RGB calculation as it works in a one dimensional space. Sometimes the underlying scipy method freaks out about k-means initialization with the following warning:

Warning

UserWarning: One of the clusters is empty. Re-run kmean with a different initialization. This shouldn’t be a real problem.

SEE ALSO

rePalette() drawPaletteColors() palettize() getPalette() binarizeFromPalette() findBlobsFromPalette()

pixelize(block_size=10, region=None, levels=None, doHue=False)

SUMMARY

Pixelation blur, like the kind used to hide naughty bits on your favorite tv show.

PARAMETERS

  • block_size - the blur block size in pixels, an integer is an square blur, a tuple is rectangular.
  • region - do the blur in a region in format (x_position,y_position,width,height)
  • levels - the number of levels per color channel. This makes the image look like an 8-bit video game.
  • doHue - If this value is true we calculate the peak hue for the area, not the average color for the area.

RETURNS

Returns the image with the pixelation blur applied.

EXAMPLE

>>> img = Image("lenna")
>>> result = img.pixelize( 16, (200,180,250,250), levels=4)
>>> img.show()
prewitt()

SUMMARY

Prewitt operator for edge detection

PARAMETERS

None

RETURNS

Image with prewitt opeartor applied on it

EXAMPLE

>>> img = Image("lenna")
>>> p = img.prewitt()
>>> p.show()

NOTES

Read more at: http://en.wikipedia.org/wiki/Prewitt_operator

rawDFTImage(grayscale=False)

SUMMARY

This method returns the RAW DFT transform of an image as a list of IPL Images. Each result image is a two channel 64f image where the first channel is the real component and the second channel is teh imaginary component. If the operation is performed on an RGB image and grayscale is False the result is a list of these images of the form [b,g,r].

PARAMETERS

  • grayscale - If grayscale is True we first covert the image to grayscale, otherwise we perform the operation on each channel.

RETURNS

A list of the DFT images (see above). Note that this is a shallow copy operation.

EXAMPLE

>>> img = Image('logo.png')
>>> myDFT = img.rawDFTImage()
>>> for c in myDFT:
>>>    #do some operation on the DFT

NOTES

http://en.wikipedia.org/wiki/Discrete_Fourier_transform http://math.stackexchange.com/questions/1002/fourier-transform-for-dummies

SEE ALSO

rawDFTImage() getDFTLogMagnitude() applyDFTFilter() highPassFilter() lowPassFilter() bandPassFilter() InverseDFT() applyButterworthFilter() InverseDFT() applyGaussianFilter() applyUnsharpMask()

rePalette(palette, hue=False)

SUMMARY

rePalette takes in the palette from another image and attempts to apply it to this image. This is helpful if you want to speed up the palette computation for a series of images (like those in a video stream.

PARAMETERS

  • palette - The pre-computed palette from another image.
  • hue - Boolean Hue - if hue is True we use a hue palette, otherwise we use a BGR palette.

RETURNS

A SimpleCV Image.

EXAMPLE

>>> img = Image("lenna")
>>> img2 = Image("logo")
>>> p = img.getPalette()
>>> result = img2.rePalette(p)
>>> result.show()

SEE ALSO

rePalette() drawPaletteColors() palettize() getPalette() binarizeFromPalette() findBlobsFromPalette()

readText()

SUMMARY

This function will return any text it can find using OCR on the image.

Please note that it does not handle rotation well, so if you need it in your application try to rotate and/or crop the area so that the text would be the same way a document is read

RETURNS

A String

EXAMPLE

>>> img = Imgae("somethingwithtext.png")
>>> text = img.readText()
>>> print text

NOTE

If you’re having run-time problems I feel bad for your son, I’ve got 99 problems but dependencies ain’t one:

http://code.google.com/p/tesseract-ocr/ http://code.google.com/p/python-tesseract/

recognizeFace(recognizer=None)

SUMMARY

Find faces in the image using FaceRecognizer and predict their class.

PARAMETERS

  • recognizer - Trained FaceRecognizer object

EXAMPLES

>>> cam = Camera()
>>> img = cam.getImage()
>>> recognizer = FaceRecognizer()
>>> recognizer.load("training.xml")
>>> print img.recognizeFace(recognizer)
regionSelect(x1, y1, x2, y2)

SUMMARY

Region select is similar to crop, but instead of taking a position and width and height values it simply takes two points on the image and returns the selected region. This is very helpful for creating interactive scripts that require the user to select a region.

PARAMETERS

  • x1 - Int - Point one x coordinate.
  • y1 - Int - Point one y coordinate.
  • x2 - Int - Point two x coordinate.
  • y2 - Int - Point two y coordinate.

RETURNS

A cropped SimpleCV Image.

EXAMPLE

>>> img = Image("lenna")
>>> subreg = img.regionSelect(10,10,100,100) # often this comes from a mouse click
>>> subreg.show()

SEE ALSO

crop()

removeDrawingLayer(index=-1)

SUMMARY

Remove a layer from the layer stack based on the layer’s index.

PARAMETERS

  • index - Int - the index of the layer to remove.

RETURNS

This method returns the removed drawing layer.

EXAMPLES

>>> img = Image("Lenna")
>>> img.removeDrawingLayer(1) # removes the layer with index = 1
>>> img.removeDrawingLayer() # if no index is specified it removes the top layer

SEE ALSO

DrawingLayer addDrawinglayer() dl() toPygameSurface() getDrawingLayer() removeDrawingLayer() clearLayers() layers() mergedLayers() applyLayers() drawText() drawRectangle() drawCircle() blit()

removeGrid()

SUMMARY

Remove Grid Layer from the Image.

PARAMETERS

None

RETURNS

Drawing Layer corresponding to the Grid Layer

EXAMPLE

>>>> img = Image(‘something.png’) >>>> img.grid([20,20],(255,0,0)) >>>> gridLayer = img.removeGrid()

replaceLineScan(linescan, x=None, y=None, pt1=None, pt2=None, channel=None)

SUMMARY

This function easily lets you replace the linescan in the image. Once you get the LineScan object, you might want to edit it. Perform some task, apply some filter etc and now you want to put it back where you took it from. By using this function, it is not necessary to specify where to put the data. It will automatically replace where you took the LineScan from.

PARAMETERS

  • linescan - LineScan object
  • x - put line scan at the column x.
  • y - put line scan at the row y.
  • pt1 - put line scan between two points on the line the line scan values always go in the +x direction
  • pt2 - Second parameter for a non-vertical or horizontal line scan.
  • channel - To select a channel. eg: selecting a channel RED,GREEN or BLUE. If set to -1 it operates with gray scale values

RETURNS

A SimpleCV.Image

EXAMPLE

>>> img = Image('lenna')
>>> a = img.getLineScan(x=10)
>>> for index in range(len(a)):
    ... a[index] = 0
>>> newimg = img.replaceLineScan(a)
>>> newimg.show()
# This will show you a black line in column 10.
resize(w=None, h=None)

SUMMARY

This method resizes an image based on a width, a height, or both. If either width or height is not provided the value is inferred by keeping the aspect ratio. If both values are provided then the image is resized accordingly.

PARAMETERS

  • width - The width of the output image in pixels.
  • height - The height of the output image in pixels.

RETURNS

Returns a resized image, if the size is invalid a warning is issued and None is returned.

EXAMPLE

>>> img = Image("lenna")
>>> img2 = img.resize(w=1024) # h is guessed from w
>>> img3 = img.resize(h=1024) # w is guessed from h
>>> img4 = img.resize(w=200,h=100)
rotate(angle, fixed=True, point=[-1, -1], scale=1.0)

SUMMARY*

This function rotates an image around a specific point by the given angle By default in “fixed” mode, the returned Image is the same dimensions as the original Image, and the contents will be scaled to fit. In “full” mode the contents retain the original size, and the Image object will scale by default, the point is the center of the image. you can also specify a scaling parameter

PARAMETERS

  • angle - angle in degrees positive is clockwise, negative is counter clockwise
  • fixed - if fixed is true,keep the original image dimensions, otherwise scale the image to fit the rotation
  • point - the point about which we want to rotate, if none is defined we use the center.
  • scale - and optional floating point scale parameter.

RETURNS

The rotated SimpleCV image.

EXAMPLE

>>> img = Image('logo')
>>> img2 = img.rotate( 73.00, point=(img.width/2,img.height/2))
>>> img3 = img.rotate( 73.00, fixed=False, point=(img.width/2,img.height/2))
>>> img4 = img2.sideBySide(img3)
>>> img4.show()

SEE ALSO

rotate90()

rotate180()

DESCRIPTION

Rotate the image 180 degrees to the left/right. This is the same as rotate 90.

RETURNS

A SimpleCV image.

EXAMPLE

>>>> img = Image(‘lenna’) >>>> img.rotate180().show()

rotate270()

DESCRIPTION

Rotate the image 270 degrees to the left, the same as 90 degrees to the right. This is the same as rotateRight()

RETURNS

A SimpleCV image.

EXAMPLE

>>>> img = Image(‘lenna’) >>>> img.rotate270().show()

rotate90()

DESCRIPTION

Rotate the image 90 degrees to the left, the same as 270 degrees to the right. This is the same as rotateRight()

RETURNS

A SimpleCV image.

EXAMPLE

>>>> img = Image(‘lenna’) >>>> img.rotate90().show()

rotateLeft()

DESCRIPTION

Rotate the image 90 degrees to the left. This is the same as rotate 90.

RETURNS

A SimpleCV image.

EXAMPLE

>>>> img = Image(‘lenna’) >>>> img.rotateLeft().show()

rotateRight()

DESCRIPTION

Rotate the image 90 degrees to the right. This is the same as rotate 270.

RETURNS

A SimpleCV image.

EXAMPLE

>>>> img = Image(‘lenna’) >>>> img.rotateRight().show()

save(filehandle_or_filename='', mode='', verbose=False, temp=False, path=None, filename=None, cleanTemp=False, **params)

SUMMARY

Save the image to the specified filename. If no filename is provided then then it will use the filename the Image was loaded from or the last place it was saved to. You can save to lots of places, not just files. For example you can save to the Display, a JpegStream, VideoStream, temporary file, or Ipython Notebook.

Save will implicitly render the image’s layers before saving, but the layers are not applied to the Image itself.

PARAMETERS

  • filehandle_or_filename - the filename to which to store the file. The method will infer the file type.
  • mode - This flag is used for saving using pul.
  • verbose - If this flag is true we return the path where we saved the file.
  • temp - If temp is True we save the image as a temporary file and return the path
  • path - path where temporary files needed to be stored
  • filename - name(Prefix) of the temporary file.
  • cleanTemp - This flag is made True if tempfiles are tobe deleted once the object is to be destroyed.
  • params - This object is used for overloading the PIL save methods. In particular this method is useful for setting the jpeg compression level. For JPG see this documentation: http://www.pythonware.com/library/pil/handbook/format-jpeg.htm

EXAMPLES

To save as a temporary file just use:

>>> img = Image('simplecv')
>>> img.save(temp=True)

It will return the path that it saved to.

Save also supports IPython Notebooks when passing it a Display object that has been instainted with the notebook flag.

To do this just use:

>>> disp = Display(displaytype='notebook')
>>> img.save(disp)

Note

You must have IPython notebooks installed for this to work path and filename are valid if and only if temp is set to True.

Attention

We need examples for all save methods as they are unintuitve.

scale(width, height=-1, interpolation=1)

SUMMARY

Scale the image to a new width and height.

If no height is provided, the width is considered a scaling value.

PARAMETERS

RETURNS

The resized image.

EXAMPLE

>>> img.scale(200, 100) #scales the image to 200px x 100px
>>> img.scale(2.0) #enlarges the image to 2x its current size

Warning

The two value scale command is deprecated. To set width and height use the resize function.

resize()

setLineScan(linescan, x=None, y=None, pt1=None, pt2=None, channel=-1)

SUMMARY

This function helps you put back the linescan in the image.

PARAMETERS

  • linescan - LineScan object
  • x - put line scan at the column x.
  • y - put line scan at the row y.
  • pt1 - put line scan between two points on the line the line scan values always go in the +x direction
  • pt2 - Second parameter for a non-vertical or horizontal line scan.
  • channel - To select a channel. eg: selecting a channel RED,GREEN or BLUE. If set to -1 it operates with gray scale values

RETURNS

A SimpleCV.Image

EXAMPLE

>>> img = Image('lenna')
>>> a = img.getLineScan(x=10)
>>> for index in range(len(a)):
    ... a[index] = 0
>>> newimg = img.putLineScan(a, x=50)
>>> newimg.show()
# This will show you a black line in column 50.
shear(cornerpoints)

SUMMARY

Given a set of new corner points in clockwise order, return a shear-ed image that transforms the image contents. The returned image is the same dimensions.

PARAMETERS

  • cornerpoints - a 2x4 tuple of points. The order is (top_left, top_right, bottom_left, bottom_right)

RETURNS

A simpleCV image.

EXAMPLE

>>> img = Image("lenna")
>>> points = ((50,0),(img.width+50,0),(img.width,img.height),(0,img.height))
>>> img.shear(points).show()

SEE ALSO

transformAffine() warp() rotate()

http://en.wikipedia.org/wiki/Transformation_matrix

show(type='window')

SUMMARY

This function automatically pops up a window and shows the current image.

PARAMETERS

  • type - this string can have one of two values, either ‘window’, or ‘browser’. Window opens a display window, while browser opens the default web browser to show an image.

RETURNS

This method returns the display object. In the case of the window this is a JpegStreamer object. In the case of a window a display object is returned.

EXAMPLE

>>> img = Image("lenna")
>>> img.show()
>>> img.show('browser')

SEE ALSO

JpegStreamer Display

sideBySide(image, side='right', scale=True)

SUMMARY

Combine two images as a side by side images. Great for before and after images.

PARAMETERS

  • side - what side of this image to place the other image on. choices are (‘left’/’right’/’top’/’bottom’).
  • scale - if true scale the smaller of the two sides to match the edge touching the other image. If false we center the smaller of the two images on the edge touching the larger image.

RETURNS

A new image that is a combination of the two images.

EXAMPLE

>>> img = Image("lenna")
>>> img2 = Image("orson_welles.jpg")
>>> img3 = img.sideBySide(img2)

TODO

Make this accept a list of images.

size()

SUMMARY

Returns a tuple that lists the width and height of the image.

RETURNS

The width and height as a tuple.

skeletonize(radius=5)

SUMMARY

Skeletonization is the process of taking in a set of blobs (here blobs are white on a black background) and finding a squigly line that would be the back bone of the blobs were they some sort of vertebrate animal. Another way of thinking about skeletonization is that it finds a series of lines that approximates a blob’s shape.

A good summary can be found here:

http://www.inf.u-szeged.hu/~palagyi/skel/skel.html

PARAMETERS

  • radius - an intenger that defines how roughly how wide a blob must be to be added to the skeleton, lower values give more skeleton lines, higher values give fewer skeleton lines.

EXAMPLE

>>> cam = Camera()
>>> while True:
>>>     img = cam.getImage()
>>>     b = img.binarize().invert()
>>>     s = img.skeletonize()
>>>     r = b-s
>>>     r.show()

NOTES

This code was a suggested improvement by Alex Wiltchko, check out his awesome blog here:

http://alexbw.posterous.com/

smartFindBlobs(mask=None, rect=None, thresh_level=2, appx_level=3)

SUMMARY

smartFindBlobs uses a method called grabCut, also called graph cut, to automagically determine the boundary of a blob in the image. The dumb find blobs just uses color threshold to find the boundary, smartFindBlobs looks at both color and edges to find a blob. To work smartFindBlobs needs either a rectangle that bounds the object you want to find, or a mask. If you use a rectangle make sure it holds the complete object. In the case of a mask, it need not be a normal binary mask, it can have the normal white foreground and black background, but also a light and dark gray values that correspond to areas that are more likely to be foreground and more likely to be background. These values can be found in the color class as Color.BACKGROUND, Color.FOREGROUND, Color.MAYBE_BACKGROUND, and Color.MAYBE_FOREGROUND.

PARAMETERS

  • mask - A grayscale mask the same size as the image using the 4 mask color values
  • rect - A rectangle tuple of the form (x_position,y_position,width,height)
  • thresh_level - This represents what grab cut values to use in the mask after the graph cut algorithm is run,
    • 1 - means use the foreground, maybe_foreground, and maybe_background values
    • 2 - means use the foreground and maybe_foreground values.
    • 3+ - means use just the foreground
  • appx_level - The blob approximation level - an integer for the maximum distance between the true edge and the approximation edge - lower numbers yield better approximation.

RETURNS

A featureset of blobs. If everything went smoothly only a couple of blobs should be present.

EXAMPLE

>>> img = Image("RatTop.png")
>>> mask = Image((img.width,img.height))
>>> mask.dl().circle((100,100),80,color=Color.MAYBE_BACKGROUND,filled=True
>>> mask.dl().circle((100,100),60,color=Color.MAYBE_FOREGROUND,filled=True)
>>> mask.dl().circle((100,100),40,color=Color.FOREGROUND,filled=True)
>>> mask = mask.applyLayers()
>>> blobs = img.smartFindBlobs(mask=mask)
>>> blobs.draw()
>>> blobs.show()

NOTES

http://en.wikipedia.org/wiki/Graph_cuts_in_computer_vision

SEE ALSO

smartThreshold()

smartThreshold(mask=None, rect=None)

SUMMARY

smartThreshold uses a method called grabCut, also called graph cut, to automagically generate a grayscale mask image. The dumb version of threshold just uses color, smartThreshold looks at both color and edges to find a blob. To work smartThreshold needs either a rectangle that bounds the object you want to find, or a mask. If you use a rectangle make sure it holds the complete object. In the case of a mask, it need not be a normal binary mask, it can have the normal white foreground and black background, but also a light and dark gray values that correspond to areas that are more likely to be foreground and more likely to be background. These values can be found in the color class as Color.BACKGROUND, Color.FOREGROUND, Color.MAYBE_BACKGROUND, and Color.MAYBE_FOREGROUND.

PARAMETERS

  • mask - A grayscale mask the same size as the image using the 4 mask color values
  • rect - A rectangle tuple of the form (x_position,y_position,width,height)

RETURNS

A grayscale image with the foreground / background values assigned to:

  • BACKGROUND = (0,0,0)
  • MAYBE_BACKGROUND = (64,64,64)
  • MAYBE_FOREGROUND = (192,192,192)
  • FOREGROUND = (255,255,255)

EXAMPLE

>>> img = Image("RatTop.png")
>>> mask = Image((img.width,img.height))
>>> mask.dl().circle((100,100),80,color=Color.MAYBE_BACKGROUND,filled=True)
>>> mask.dl().circle((100,100),60,color=Color.MAYBE_FOREGROUND,filled=True)
>>> mask.dl().circle((100,100),40,color=Color.FOREGROUND,filled=True)
>>> mask = mask.applyLayers()
>>> new_mask = img.smartThreshold(mask=mask)
>>> new_mask.show()

NOTES

http://en.wikipedia.org/wiki/Graph_cuts_in_computer_vision

SEE ALSO

smartFindBlobs()

smooth(algorithm_name='gaussian', aperture=(3, 3), sigma=0, spatial_sigma=0, grayscale=False, aperature=None)

SUMMARY

Smooth the image, by default with the Gaussian blur. If desired, additional algorithms and apertures can be specified. Optional parameters are passed directly to OpenCV’s cv.Smooth() function.

If grayscale is true the smoothing operation is only performed on a single channel otherwise the operation is performed on each channel of the image.

for OpenCV versions >= 2.3.0 it is advisible to take a look at

PARAMETERS

  • algorithm_name - valid options are ‘blur’ or gaussian, ‘bilateral’, and ‘median’.

  • aperture - A tuple for the aperture of the gaussian blur as an (x,y) tuple.
    • Note there was rampant spelling mistakes in both smooth & sobel, aperture is spelled as such, and not “aperature”. This code is backwards compatible.

Warning

These must be odd numbers.

  • sigma -
  • spatial_sigma -
  • grayscale - Return just the grayscale image.

RETURNS

The smoothed image.

EXAMPLE

>>> img = Image("Lenna")
>>> img2 = img.smooth()
>>> img3 = img.smooth('median')

SEE ALSO

bilateralFilter() medianFilter() blur()

sobel(xorder=1, yorder=1, doGray=True, aperture=5, aperature=None)

DESCRIPTION

Sobel operator for edge detection

PARAMETERS

  • xorder - int - Order of the derivative x.
  • yorder - int - Order of the derivative y.
  • doGray - Bool - grayscale or not.
  • aperture - int - Size of the extended Sobel kernel. It must be 1, 3, 5, or 7.

RETURNS

Image with sobel opeartor applied on it

EXAMPLE

>>> img = Image("lenna")
>>> s = img.sobel()
>>> s.show()
split(cols, rows)

SUMMARY

This method can be used to brak and image into a series of image chunks. Given number of cols and rows, splits the image into a cols x rows 2d array of cropped images

PARAMETERS

  • rows - an integer number of rows.
  • cols - an integer number of cols.

RETURNS

A list of SimpleCV images.

EXAMPLE

>>> img = Image("lenna")
>>> quadrant =img.split(2,2)
>>> for f in quadrant:
>>>    f.show()
>>>    time.sleep(1)

NOTES

TODO: This should return and ImageList

splitChannels(grayscale=True)

SUMMARY

Split the channels of an image into RGB (not the default BGR) single parameter is whether to return the channels as grey images (default) or to return them as tinted color image

PARAMETERS

  • grayscale - If this is true we return three grayscale images, one per channel. if it is False return tinted images.

RETURNS

A tuple of of 3 image objects.

EXAMPLE

>>> img = Image("lenna")
>>> data = img.splitChannels()
>>> for d in data:
>>>    d.show()
>>>    time.sleep(1)

SEE ALSO

mergeChannels()

stegaDecode()

SUMMARY

A simple steganography tool for hidding and finding messages in images.

RETURNS

Your message decoded in the image.

EXAMPLE

>>>> img = Image(‘lenna’) >>>> img2 = img.stegaEncode(“HELLO WORLD!”) >>>> img2.save(“TopSecretImg.png”) >>>> img3 = Image(“TopSecretImg.png”) >>>> img3.stegaDecode()

NOTES

More here: http://en.wikipedia.org/wiki/Steganography You will need to install stepic: http://domnit.org/stepic/doc/pydoc/stepic.html

You may need to monkey with jpeg compression as it seems to degrade the encoded message.

PNG sees to work quite well.

stegaEncode(message)

SUMMARY

A simple steganography tool for hidding messages in images. PARAMETERS

  • message -A message string that you would like to encode.

RETURNS

Your message encoded in the returning image.

EXAMPLE

>>>> img = Image(‘lenna’) >>>> img2 = img.stegaEncode(“HELLO WORLD!”) >>>> img2.save(“TopSecretImg.png”) >>>> img3 = Image(“TopSecretImg.png”) >>>> img3.stegaDecode()

NOTES

More here: http://en.wikipedia.org/wiki/Steganography You will need to install stepic: http://domnit.org/stepic/doc/pydoc/stepic.html

You may need to monkey with jpeg compression as it seems to degrade the encoded message.

PNG sees to work quite well.

stretch(thresh_low=0, thresh_high=255)

SUMMARY

The stretch filter works on a greyscale image, if the image is color, it returns a greyscale image. The filter works by taking in a lower and upper threshold. Anything below the lower threshold is pushed to black (0) and anything above the upper threshold is pushed to white (255)

PARAMETERS

  • thresh_low - The lower threshold for the stretch operation. This should be a value between 0 and 255.
  • thresh_high - The upper threshold for the stretch operation. This should be a value between 0 and 255.

RETURNS

A gray scale version of the image with the appropriate histogram stretching.

EXAMPLE

>>> img = Image("orson_welles.jpg")
>>> img2 = img.stretch(56.200)
>>> img2.show()

NOTES

TODO - make this work on RGB images with thresholds for each channel.

SEE ALSO

binarize() equalize()

threshold(value)

SUMMARY

We roll old school with this vanilla threshold function. It takes your image converts it to grayscale, and applies a threshold. Values above the threshold are white, values below the threshold are black (note this is in contrast to binarize... which is a stupid function that drives me up a wall). The resulting black and white image is returned.

PARAMETERS

  • value - the threshold, goes between 0 and 255.

RETURNS

A black and white SimpleCV image.

EXAMPLE

>>> img = Image("purplemonkeydishwasher.png")
>>> result = img.threshold(42)

NOTES

THRESHOLD RULES BINARIZE DROOLS!

SEE ALSO

binarize()

toBGR()

SUMMARY

This method attemps to convert the image to the BGR colorspace. If the color space is unknown we assume it is in the BGR format.

RETURNS

Returns the converted image if the conversion was successful, otherwise None is returned.

EXAMPLE

>>> img = Image("lenna")
>>> BGRImg = img.toBGR()

SEE ALSO

isBGR()

toGray()

SUMMARY

This method attemps to convert the image to the grayscale colorspace. If the color space is unknown we assume it is in the BGR format.

RETURNS

A grayscale SimpleCV image if successful. otherwise None is returned.

EXAMPLE

>>> img = Image("lenna")
>>> img.toGray().binarize().show()

SEE ALSO

isGray() binarize()

toHLS()

SUMMARY

This method attempts to convert the image to the HLS colorspace. If the color space is unknown we assume it is in the BGR format.

RETURNS

Returns the converted image if the conversion was successful, otherwise None is returned.

EXAMPLE

>>> img = Image("lenna")
>>> HLSImg = img.toHLS()

SEE ALSO

isHLS()

toHSV()

SUMMARY

This method attempts to convert the image to the HSV colorspace. If the color space is unknown we assume it is in the BGR format

RETURNS

Returns the converted image if the conversion was successful, otherwise None is returned.

EXAMPLE

>>> img = Image("lenna")
>>> HSVImg = img.toHSV()

SEE ALSO

isHSV()

toPygameSurface()

SUMMARY

Converts this image to a pygame surface. This is useful if you want to treat an image as a sprite to render onto an image. An example would be rendering blobs on to an image.

Warning

THIS IS EXPERIMENTAL. We are plannng to remove this functionality sometime in the near future.

RETURNS

The image as a pygame surface.

SEE ALSO

DrawingLayer insertDrawingLayer() addDrawingLayer() dl() toPygameSurface() getDrawingLayer() removeDrawingLayer() clearLayers() layers() mergedLayers() applyLayers() drawText() drawRectangle() drawCircle() blit()

toRGB()

SUMMARY

This method attemps to convert the image to the RGB colorspace. If the color space is unknown we assume it is in the BGR format

RETURNS

Returns the converted image if the conversion was successful, otherwise None is returned.

EXAMPLE

>>> img = Image("lenna")
>>> RGBImg = img.toRGB()

SEE ALSO

isRGB()

toString()

SUMMARY

Returns the image as a string, useful for moving data around.

RETURNS

The image, converted to rgb, then converted to a string.

toXYZ()

SUMMARY

This method attemps to convert the image to the XYZ colorspace. If the color space is unknown we assume it is in the BGR format

RETURNS

Returns the converted image if the conversion was successful, otherwise None is returned.

EXAMPLE

>>> img = Image("lenna")
>>> XYZImg = img.toXYZ()

SEE ALSO

isXYZ()

toYCrCb()

SUMMARY

This method attemps to convert the image to the YCrCb colorspace. If the color space is unknown we assume it is in the BGR format

RETURNS

Returns the converted image if the conversion was successful, otherwise None is returned.

EXAMPLE

>>> img = Image("lenna")
>>> RGBImg = img.toYCrCb()

SEE ALSO

isYCrCb()

track(method='CAMShift', ts=None, img=None, bb=None, **kwargs)

DESCRIPTION

Tracking the object surrounded by the bounding box in the given image or TrackSet.

PARAMETERS

  • method - str - The Tracking Algorithm to be applied
  • ts - TrackSet - SimpleCV.Features.TrackSet.
  • img - Image - Image to be tracked or list - List of Images to be tracked.
  • bb - tuple - Bounding Box tuple (x, y, w, h)

Optional Parameters

CAMShift

CAMShift Tracker is based on mean shift thresholding algorithm which is combined with an adaptive region-sizing step. Histogram is calcualted based on the mask provided. If mask is not provided, hsv transformed image of the provided image is thresholded using inRange function (band thresholding).

lower HSV and upper HSV values are used inRange function. If the user doesn’t provide any range values, default range values are used.

Histogram is back projected using previous images to get an appropriate image and it passed to camshift function to find the object in the image. Users can decide the number of images to be used in back projection by providing num_frames.

lower - Lower HSV value for inRange thresholding. tuple of (H, S, V). Default : (0, 60, 32) upper - Upper HSV value for inRange thresholding. tuple of (H, S, V). Default: (180, 255, 255) mask - Mask to calculate Histogram. It’s better if you don’t provide one. Default: calculated using above thresholding ranges. num_frames - number of frames to be backtracked. Default: 40

LK

LK Tracker is based on Optical Flow method. In brief, optical flow can be defined as the apparent motion of objects caused by the relative motion between an observer and the scene. (Wikipedia).

LK Tracker first finds some good feature points in the given bounding box in the image. These are the tracker points. In consecutive frames, optical flow of these feature points is calculated. Users can limit the number of feature points by provideing maxCorners and qualityLevel. number of features will always be less than maxCorners. These feature points are calculated using Harris Corner detector. It returns a matrix with each pixel having some quality value. Only good features are used based upon the qualityLevel provided. better features have better quality measure and hence are more suitable to track.

Users can set minimum distance between each features by providing minDistance.

LK tracker finds optical flow using a number of pyramids and users can set this number by providing maxLevel and users can set size of the search window for Optical Flow by setting winSize.

docs from http://docs.opencv.org/ maxCorners - Maximum number of corners to return in goodFeaturesToTrack. If there are more corners than are found, the strongest of them is returned. Default: 4000 qualityLevel - Parameter characterizing the minimal accepted quality of image corners. The parameter value is multiplied by the best corner quality measure, which is the minimal eigenvalue or the Harris function response. The corners with the quality measure less than the product are rejected. For example, if the best corner has the quality measure = 1500, and the qualityLevel=0.01 , then all the corners with the quality measure less than 15 are rejected. Default: 0.08 minDistance - Minimum possible Euclidean distance between the returned corners. Default: 2 blockSize - Size of an average block for computing a derivative covariation matrix over each pixel neighborhood. Default: 3 winSize - size of the search window at each pyramid level. Default: (10, 10) maxLevel - 0-based maximal pyramid level number; if set to 0, pyramids are not used (single level), Default: 10 if set to 1, two levels are used, and so on

SURF

SURF based tracker finds keypoints in the template and computes the descriptor. The template is chosen based on the bounding box provided with the first image. The image is cropped and stored as template. SURF keypoints are found and descriptor is computed for the template and stored.

SURF keypoints are found in the image and its descriptor is computed. Image keypoints and template keypoints are matched using K-nearest neighbor algorithm. Matched keypoints are filtered according to the knn distance of the points. Users can set this criteria by setting distance. Density Based Clustering algorithm (DBSCAN) is applied on the matched keypoints to filter out points that are in background. DBSCAN creates a cluster of object points anc background points. These background points are discarded. Users can set certain parameters for DBSCAN which are listed below.

K-means is applied on matched KeyPoints with k=1 to find the center of the cluster and then bounding box is predicted based upon the position of all the object KeyPoints.

eps_val - eps for DBSCAN. The maximum distance between two samples for them to be considered as in the same neighborhood. default: 0.69 min_samples - min number of samples in DBSCAN. The number of samples in a neighborhood for a point to be considered as a core point. default: 5 distance - thresholding KNN distance of each feature. if KNN distance > distance, point is discarded. default: 100

MFTrack

Median Flow tracker is similar to LK tracker (based on Optical Flow), but it’s more advanced, better and faster.

In MFTrack, tracking points are decided based upon the number of horizontal and vertical points and window size provided by the user. Unlike LK Tracker, good features are not found which saves a huge amount of time.

feature points are selected symmetrically in the bounding box. Total number of feature points to be tracked = numM * numN.

If the width and height of bounding box is 200 and 100 respectively, and numM = 10 and numN = 10, there will be 10 points in the bounding box equally placed(10 points in 200 pixels) in each row. and 10 equally placed points (10 points in 100 pixels) in each column. So total number of tracking points = 100.

numM > 0 numN > 0 (both may not be equal)

users can provide a margin around the bounding box that will be considered to place feature points and calculate optical flow. Optical flow is calculated from frame1 to frame2 and from frame2 to frame1. There might be some points which give inaccurate optical flow, to eliminate these points the above method is used. It is called forward-backward error tracking. Optical Flow seach window size can be set usung winsize_lk.

For each point, comparision is done based on the quadratic area around it. The length of the square window can be set using winsize.

numM - Number of points to be tracked in the bounding box
in height direction. default: 10
numN - Number of points to be tracked in the bounding box
in width direction. default: 10
margin - Margin around the bounding box.
default: 5
winsize_lk - Optical Flow search window size.
default: 4
winsize - Size of quadratic area around the point which is compared.
default: 10

Available Tracking Methods

  • CamShift
  • LK
  • SURF
  • MFTrack

RETURNS

SimpleCV.Features.TrackSet

Returns a TrackSet with all the necessary attributes.

HOW TO

>>> ts = img.track("camshift", img=img1, bb=bb)

Here TrackSet is returned. All the necessary attributes will be included in the trackset. After getting the trackset you need not provide the bounding box or image. You provide TrackSet as parameter to track(). Bounding box and image will be taken from the trackset. So. now

>>> ts = new_img.track("camshift",ts)

The new Tracking feature will be appended to the given trackset and that will be returned. So, to use it in loop:

img = cam.getImage()
bb = (img.width/4,img.height/4,img.width/4,img.height/4)
ts = img.track(img=img, bb=bb)
while (True):
    img = cam.getImage()
    ts = img.track("camshift", ts=ts)

ts = []
while (some_condition_here):
    img = cam.getImage()
    ts = img.track("camshift",ts,img0,bb)

now here in first loop iteration since ts is empty, img0 and bb will be considered. New tracking object will be created and added in ts (TrackSet) After first iteration, ts is not empty and hence the previous image frames and bounding box will be taken from ts and img0 and bb will be ignored.

# Instead of loop, give a list of images to be tracked.

ts = [] imgs = [img1, img2, img3, ..., imgN] ts = img0.track(“camshift”, ts, imgs, bb) ts.drawPath() ts[-1].image.show()

Using Optional Parameters:

for CAMShift

>>> ts = []
>>> ts = img.track("camshift", ts, img1, bb, lower=(40, 100, 100), upper=(100, 250, 250))

You can provide some/all/None of the optional parameters listed for CAMShift.

for LK

>>> ts = []
>>> ts = img.track("lk", ts, img1, bb, maxCorners=4000, qualityLevel=0.5, minDistance=3)

You can provide some/all/None of the optional parameters listed for LK.

for SURF

>>> ts = []
>>> ts = img.track("surf", ts, img1, bb, eps_val=0.7, min_samples=8, distance=200)

You can provide some/all/None of the optional parameters listed for SURF.

for MFTrack >>> ts = [] >>> ts = img.track(“mftrack”, ts, img1, bb, numM=12, numN=12, winsize=15)

You can provide some/all/None of the optional parameters listed for MFTrack.

Check out Tracking examples provided in the SimpleCV source code.

READ MORE:

CAMShift Tracker: Uses meanshift based CAMShift thresholding technique. Blobs and objects with single tone or tracked very efficiently. CAMshift should be preferred if you are trying to track faces. It is optimized to track faces.

LK (Lucas Kanade) Tracker: It is based on LK Optical Flow. It calculates Optical flow in frame1 to frame2 and also in frame2 to frame1 and using back track error, filters out false positives.

SURF based Tracker: Matches keypoints from the template image and the current frame. flann based matcher is used to match the keypoints. Density based clustering is used classify points as in-region (of bounding box) and out-region points. Using in-region points, new bounding box is predicted using k-means.

Median Flow Tracker:

Media Flow Tracker is the base tracker that is used in OpenTLD. It is based on Optical Flow. It calculates optical flow of the points in the bounding box from frame 1 to frame 2 and from frame 2 to frame 1 and using back track error, removes false positives. As the name suggests, it takes the median of the flow, and eliminates points.

transformAffine(rotMatrix)

SUMMARY

This helper function for shear performs an affine rotation using the supplied matrix. The matrix can be a either an openCV mat or an np.ndarray type. The matrix should be a 2x3

PARAMETERS

  • rotMatrix - A 2x3 numpy array or CvMat of the affine transform.

RETURNS

The rotated image. Note that the rotation is done in place, i.e. the image is not enlarged to fit the transofmation.

EXAMPLE

>>> img = Image("lenna")
>>> points = ((50,0),(img.width+50,0),(img.width,img.height),(0,img.height))
>>> src =  ((0, 0), (img.width-1, 0), (img.width-1, img.height-1))
>>> result = cv.createMat(2,3,cv.CV_32FC1)
>>> cv.GetAffineTransform(src,points,result)
>>> img.transformAffine(result).show()

SEE ALSO

shear() :py:meth`warp` transformPerspective() rotate()

http://en.wikipedia.org/wiki/Transformation_matrix

transformPerspective(rotMatrix)

SUMMARY

This helper function for warp performs an affine rotation using the supplied matrix. The matrix can be a either an openCV mat or an np.ndarray type. The matrix should be a 3x3
PARAMETERS
  • rotMatrix - Numpy Array or CvMat

RETURNS

The rotated image. Note that the rotation is done in place, i.e. the image is not enlarged to fit the transofmation.

EXAMPLE

>>> img = Image("lenna")
>>> points = ((50,0),(img.width+50,0),(img.width,img.height),(0,img.height))
>>> src = ((30, 30), (img.width-10, 70), (img.width-1-40, img.height-1+30),(20,img.height+10))
>>> result = cv.CreateMat(3,3,cv.CV_32FC1)
>>> cv.GetPerspectiveTransform(src,points,result)
>>> img.transformPerspective(result).show()

SEE ALSO

shear() warp() transformPerspective() rotate()

http://en.wikipedia.org/wiki/Transformation_matrix

transpose()

SUMMARY

Does a fast 90 degree rotation to the right with a flip.

Warning

Subsequent calls to this function WILL NOT keep rotating it to the right!!! This function just does a matrix transpose so following one transpose by another will just yield the original image.

RETURNS

The rotated SimpleCV Image.

EXAMPLE

>>> img = Image("logo")
>>> img2 = img.transpose()
>>> img2.show()

SEE ALSO

rotate()

tvDenoising(gray=False, weight=50, eps=0.0002, max_iter=200, resize=1)

SUMMARY

Performs Total Variation Denoising, this filter tries to minimize the total-variation of the image.

see : http://en.wikipedia.org/wiki/Total_variation_denoising

Parameters

  • gray - Boolean value which identifies the colorspace of

    the input image. If set to True, filter uses gray scale values, otherwise colorspace is used.

  • weight - Denoising weight, it controls the extent of denoising.

  • eps - Stopping criteria for the algorithm. If the relative difference

    of the cost function becomes less than this value, the algorithm stops.

  • max_iter - Determines the maximum number of iterations the algorithm

    goes through for optimizing.

  • resize - Parameter to scale up/down the image. If set to

    1 filter is applied on the original image. This parameter is mostly to speed up the filter.

NOTE

This function requires Scikit-image library to be installed! To install scikit-image library run:

sudo pip install -U scikit-image

Read More: http://scikit-image.org/

uncrop(ListofPts)

SUMMARY

This function allows us to translate a set of points from the crop window back to the coordinate of the source window.

PARAMETERS

  • ListofPts - set of points from cropped image.

RETURNS

Returns a list of coordinates in the source image.

EXAMPLE

>> img = Image(‘lenna’) >> croppedImg = img.crop(10,20,250,500) >> sourcePts = croppedImg.uncrop([(2,3),(56,23),(24,87)])

upload(dest, api_key=None, api_secret=None, verbose=True)

SUMMARY

Uploads image to imgur or flickr or dropbox. In verbose mode URL values are printed.

PARAMETERS

  • api_key - a string of the API key.
  • api_secret (required only for flickr and dropbox ) - a string of the API secret.
  • verbose - If verbose is true all values are printed to the screen

RETURNS

if uploading is successful

  • Imgur return the original image URL on success and None if it fails.
  • Flick returns True on success, else returns False.
  • dropbox returns True on success.

EXAMPLE

TO upload image to imgur:

>>> img = Image("lenna")
>>> result = img.upload( 'imgur',"MY_API_KEY1234567890" )
>>> print "Uploaded To: " + result[0]

To upload image to flickr:

>>> img.upload('flickr','api_key','api_secret')
>>> img.invert().upload('flickr') #Once the api keys and secret keys are cached.

To upload image to dropbox:

>>> img.upload('dropbox','api_key','api_secret')
>>> img.invert().upload('dropbox') #Once the api keys and secret keys are cached.

NOTES

Warning

This method requires two packages to be installed

  • PyCurl
  • flickr api.
  • dropbox
verticalHistogram(bins=10, threshold=128, normalize=False, forPlot=False)

DESCRIPTION

This method generates histogram of the number of grayscale pixels greater than the provided threshold. The method divides the image into a number evenly spaced vertical bins and then counts the number of pixels where the pixel is greater than the threshold. This method is helpful for doing basic morphological analysis.

PARAMETERS

  • bins - The number of bins to use.
  • threshold - The grayscale threshold. We count pixels greater than this value.
  • normalize - If normalize is true we normalize the bin countsto sum to one. Otherwise we return the number of pixels.
  • forPlot - If this is true we return the bin indicies, the bin counts, and the bin widths as a tuple. We can use these values in pyplot.bar to quickly plot the histogram.

RETURNS

The default settings return the raw bin counts moving from left to right on the image. If forPlot is true we return a tuple that contains a list of bin labels, the bin counts, and the bin widths. This tuple can be used to plot the histogram using matplotlib.pyplot.bar function.

EXAMPLE

>>> import matplotlib.pyplot as plt
>>> img = Image('lenna')
>>> plt.bar(*img.verticalHistogram(threshold=128,bins=10,normalize=False,forPlot=True),color='y')
>>> plt.show()

NOTES

See: http://docs.scipy.org/doc/numpy/reference/generated/numpy.histogram.html See: http://matplotlib.org/api/pyplot_api.html?highlight=hist#matplotlib.pyplot.hist

warp(cornerpoints)

SUMMARY

This method performs and arbitrary perspective transform. Given a new set of corner points in clockwise order frin top left, return an Image with the images contents warped to the new coordinates. The returned image will be the same size as the original image

PARAMETERS

  • cornerpoints - A list of four tuples corresponding to the destination corners in the order of (top_left,top_right,bottom_left,bottom_right)

RETURNS

A simpleCV Image with the warp applied. Note that this operation does not enlarge the image.

EXAMPLE

>>> img = Image("lenna")
>>> points = ((30, 30), (img.width-10, 70), (img.width-1-40, img.height-1+30),(20,img.height+10))
>>> img.warp(points).show()

SEE ALSO

shear() transformAffine() transformPerspective() rotate()

http://en.wikipedia.org/wiki/Transformation_matrix

watershed(mask=None, erode=2, dilate=2, useMyMask=False)

SUMMARY

Implements the Watershed algorithm on the input image.

Read more:

Watershed: “http://en.wikipedia.org/wiki/Watershed_(image_processing)”

PARAMETERS

  • mask - an optional binary mask. If none is provided we do a binarize and invert.
  • erode - the number of times to erode the mask to find the foreground.
  • dilate - the number of times to dilate the mask to find possible background.
  • useMyMask - if this is true we do not modify the mask.

RETURNS

The Watershed image

EXAMPLE

>>> img = Image("/sampleimages/wshed.jpg")
>>> img1 = img.watershed()
>>> img1.show()

# here is an example of how to create your own mask

>>> img = Image('lenna')
>>> myMask = Image((img.width,img.height))
>>> myMask = myMask.floodFill((0,0),color=Color.WATERSHED_BG)
>>> mask = img.threshold(128)
>>> myMask = (myMask-mask.dilate(2)+mask.erode(2))
>>> result = img.watershed(mask=myMask,useMyMask=True)

SEE ALSO Color.WATERSHED_FG - The watershed foreground color Color.WATERSHED_BG - The watershed background color Color.WATERSHED_UNSURE - The watershed not sure if fg or bg color.

TODO: Allow the user to pass in a function that defines the watershed mask.

whiteBalance(method='Simple')

SUMMARY

Attempts to perform automatic white balancing. Gray World see: http://scien.stanford.edu/pages/labsite/2000/psych221/projects/00/trek/GWimages.html Robust AWB: http://scien.stanford.edu/pages/labsite/2010/psych221/projects/2010/JasonSu/robustawb.html http://scien.stanford.edu/pages/labsite/2010/psych221/projects/2010/JasonSu/Papers/Robust%20Automatic%20White%20Balance%20Algorithm%20using%20Gray%20Color%20Points%20in%20Images.pdf Simple AWB: http://www.ipol.im/pub/algo/lmps_simplest_color_balance/ http://scien.stanford.edu/pages/labsite/2010/psych221/projects/2010/JasonSu/simplestcb.html

PARAMETERS

RETURNS

A SimpleCV Image.

EXAMPLE

>>> img = Image("lenna")
>>> img2 = img.whiteBalance()
width = 0
class SimpleCV.ImageClass.ImageSet(directory=None)

Bases: list

SUMMARY

This is an abstract class for keeping a list of images. It has a few advantages in that you can use it to auto load data sets from a directory or the net.

Keep in mind it inherits from a list too, so all the functionality a normal python list has this will too.

EXAMPLES

>>> imgs = ImageSet()
>>> imgs.download("ninjas")
>>> imgs.show(ninjas)

or you can load a directory path:

>>> imgs = ImageSet('/path/to/imgs/')
>>> imgs.show()

This will download and show a bunch of random ninjas. If you want to save all those images locally then just use:

>>> imgs.save()

You can also load up the sample images that come with simplecv as:

>>> imgs = ImageSet('samples')
>>> imgs.filelist
>>> logo = imgs.find('simplecv.png')

TO DO

Eventually this should allow us to pull image urls / paths from csv files. The method also allow us to associate an arbitraty bunch of data with each image, and on load/save pickle that data or write it to a CSV file.

average(mode='first', size=(None, None))

SUMMARY

Casts each in the image set into a 32F image, averages them together and returns the results. If the images are different sizes the method attempts to standarize them.

PARAMETERS

  • mode - * “first” - resize everything to the size of the first image. * “max” - resize everything to be the max width and max height of the set. * “min” - resize everything to be the min width and min height of the set. * “average” - resize everything to be the average width and height of the set * “fixed” - fixed, use the size tuple provided.
  • size - if the mode is set to fixed use this tuple as the size of the resulting image.

RETURNS

Returns a single image that is the average of all the values.

EXAMPLE

>>> imgs = ImageSet()
>>> imgs.load("images/faces")
>>> result = imgs.average(mode="first")
>>> result.show()

TODO * Allow the user to pass in an offset parameters that blit the images into the resutl.

dimensions()

SUMMARY

Return an np.array that are the width and height of every image in the image set.

PARAMETERS

–NONE–

RETURNS A 2xN numpy array where N is the number of images in the set. The first column is the width, and the second collumn is the height.

EXAMPLE >>> iset = ImageSet(”./b/”) >>> sz = iset.dimensions() >>> np.max(sz[:,0]) # returns the largest width in the set.

download(tag=None, number=10, size='thumb')

SUMMARY

This function downloads images from Google Image search based on the tag you provide. The number is the number of images you want to have in the list. Valid values for size are ‘thumb’, ‘small’, ‘medium’, ‘large’ or a tuple of exact dimensions i.e. (640,480). Note that ‘thumb’ is exceptionally faster than others.

Warning

This requires the python library Beautiful Soup to be installed http://www.crummy.com/software/BeautifulSoup/

PARAMETERS

  • tag - A string of tag values you would like to download.
  • number - An integer of the number of images to try and download.
  • size - the size of the images to download. Valid options a tuple of the exact size or a string of the following approximate sizes:
    • thumb ~ less than 128x128
    • small ~ approximately less than 640x480 but larger than 128x128
    • medium ~ approximately less than 1024x768 but larger than 640x480.
    • large ~ > 1024x768

RETURNS

Nothing - but caches local copy of images.

EXAMPLE

>>> imgs = ImageSet()
>>> imgs.download("ninjas")
>>> imgs.show(ninjas)
filelist = None
load(directory=None, extension=None, sort_by=None)

SUMMARY

This function loads up files automatically from the directory you pass it. If you give it an extension it will only load that extension otherwise it will try to load all know file types in that directory.

extension should be in the format: extension = ‘png’

PARAMETERS

  • directory - The path or directory from which to load images.

  • extension - The extension to use. If none is given png is the default.

  • sort_by - Sort the directory based on one of the following parameters passed as strings. * time - the modification time of the file. * name - the name of the file. * size - the size of the file.

    The default behavior is to leave the directory unsorted.

RETURNS

The number of images in the image set.

EXAMPLE

>>> imgs = ImageSet()
>>> imgs.load("images/faces")
>>> imgs.load("images/eyes", "png")
save(destination=None, dt=0.2, verbose=False, displaytype=None)

SUMMARY

This is a quick way to save all the images in a data set. Or to Display in webInterface.

If you didn’t specify a path one will randomly be generated. To see the location the files are being saved to then pass verbose = True.

PARAMETERS

  • destination - path to which images should be saved, or name of gif
  • file. If this ends in .gif, the pictures will be saved accordingly.
  • dt - time between frames, for creating gif files.
  • verbose - print the path of the saved files to the console.
  • displaytype - the method use for saving or displaying images.

valid values are:

  • ‘notebook’ - display to the ipython notebook.
  • None - save to a temporary file.

RETURNS

Nothing.

EXAMPLE

>>> imgs = ImageSet()
>>> imgs.download("ninjas")
>>> imgs.save(destination="ninjas_folder", verbose=True)
>>> imgs.save(destination="ninjas.gif", verbose=True)
show(showtime=0.25)

SUMMARY

This is a quick way to show all the items in a ImageSet. The time is in seconds. You can also provide a decimal value, so showtime can be 1.5, 0.02, etc. to show each image.

PARAMETERS

  • showtime - the time, in seconds, to show each image in the set.

RETURNS

Nothing.

EXAMPLE

>>> imgs = ImageSet()
>>> imgs.download("ninjas")
>>> imgs.show()
showPaths()

SUMMARY

This shows the file paths of all the images in the set.

If they haven’t been saved to disk then they will not have a filepath

RETURNS

Nothing.

EXAMPLE

>>> imgs = ImageSet()
>>> imgs.download("ninjas")
>>> imgs.save(verbose=True)
>>> imgs.showPaths()

TO DO

This should return paths as a list too.

standardize(width, height)

SUMMARY

Resize every image in the set to a standard size.

PARAMETERS

  • width - the width that we want for every image in the set.
  • height - the height that we want for every image in the set.

RETURNS

A new image set where every image in the set is scaled to the desired size.

EXAMPLE

>>>> iset = ImageSet(”./b/”) >>>> thumbnails = iset.standardize(64,64) >>>> for t in thumbnails: >>>> t.show()

upload(dest, api_key=None, api_secret=None, verbose=True)

SUMMARY

Uploads all the images to imgur or flickr or dropbox. In verbose mode URL values are printed.

PARAMETERS

  • api_key - a string of the API key.
  • api_secret - (required only for flickr and dropbox ) a string of the API secret.
  • verbose - If verbose is true all values are printed to the screen

RETURNS

if uploading is successful

  • Imgur return the original image URL on success and None if it fails.
  • Flick returns True on success, else returns False.
  • dropbox returns True on success.

EXAMPLE

TO upload image to imgur:

>>> imgset = ImageSet("/home/user/Desktop")
>>> result = imgset.upload( 'imgur',"MY_API_KEY1234567890" )
>>> print "Uploaded To: " + result[0]

To upload image to flickr:

>>> imgset.upload('flickr','api_key','api_secret')
>>> imgset.upload('flickr') #Once the api keys and secret keys are cached.

To upload image to dropbox:

>>> imgset.upload('dropbox','api_key','api_secret')
>>> imgset.upload('dropbox') #Once the api keys and secret keys are cached.

NOTES

Warning

This method requires two packages to be installed -PyCurl -flickr api. -dropbox

Warning

You must supply your own API key.

Find more about API keys:

Stream Module

class SimpleCV.Stream.JpegStreamHandler(request, client_address, server)

Bases: SimpleHTTPServer.SimpleHTTPRequestHandler

The JpegStreamHandler handles requests to the threaded HTTP server. Once initialized, any request to this port will receive a multipart/replace jpeg.

do_GET()
class SimpleCV.Stream.JpegStreamer(hostandport=8080, st=0.1)

The JpegStreamer class allows the user to stream a jpeg encoded file to a HTTP port. Any updates to the jpg file will automatically be pushed to the browser via multipart/replace content type.

To initialize: js = JpegStreamer()

to update: img.save(js)

to open a browser and display: import webbrowser webbrowser.open(js.url)

Note 3 optional parameters on the constructor: - port (default 8080) which sets the TCP port you need to connect to - sleep time (default 0.1) how often to update. Above 1 second seems to cause dropped connections in Google chrome

Once initialized, the buffer and sleeptime can be modified and will function properly – port will not.

counter = 0
framebuffer = ''
host = ''
port = ''
refreshtime = 0
server = ''
sleeptime = ''
streamUrl()

Returns the URL of the MJPEG stream. If host and port are not set in the constructor, defaults to “http://localhost:8080/stream/

url()

Returns the JpegStreams Webbrowser-appropriate URL, if not provided in the constructor, it defaults to “http://localhost:8080

class SimpleCV.Stream.JpegTCPServer(server_address, RequestHandlerClass, bind_and_activate=True)

Bases: SocketServer.ThreadingMixIn, SocketServer.TCPServer

allow_reuse_address = True
class SimpleCV.Stream.VideoStream(filename, fps=25, framefill=True)

The VideoStream lets you save video files in a number of different formats.

You can initialize it by specifying the file you want to output:

vs = VideoStream("hello.avi")

You can also specify a framerate, and if you want to “fill” in missed frames. So if you want to record a realtime video you may want to do this:

vs = VideoStream("myvideo.avi", 25, True) #note these are default values

Where if you want to do a stop-motion animation, you would want to turn fill off:

vs_animation = VideoStream("cartoon.avi", 15, False)

If you select a fill, the VideoStream will do its best to stay close to “real time” by duplicating frames or dropping frames when the clock doesn’t sync up with the file writes.

You can save a frame to the video by using the Image.save() function:

my_camera.getImage().save(vs)
filename = ''
fourcc = ''
fps = 25
framecount = 0
framefill = True
initializeWriter(size)
starttime = 0.0
videotime = 0.0
writeFrame(img)

This writes a frame to the display object this is automatically called by image.save() but you can use this function to save just the bitmap as well so image markup is not implicit,typically you use image.save() but this allows for more finer control

writer = ''

base Module

class SimpleCV.base.InitOptionsHandler

Bases: object

summary

this handler is supposed to store global variables. for now, its only value defines if simplecv is being run on an ipython notebook.

enable_notebook()
set_headless()
SimpleCV.base.LazyProperty
SimpleCV.base.download_and_extract(URL)

This function takes in a URL for a zip file, extracts it and returns the temporary path it was extracted to

SimpleCV.base.exception_handler(excType, excValue, traceback)
SimpleCV.base.find(f, seq)

Search for item in a list

Returns: Boolean

SimpleCV.base.get_logging_level()

This function prints the current logging level of the main logger.

SimpleCV.base.init_logging(log_level)
SimpleCV.base.int_to_bin(i)

Integer to two bytes

SimpleCV.base.ipython_exception_handler(shell, excType, excValue, traceback, tb_offset=0)
SimpleCV.base.is_number(n)

Determines if it is a number or not

Returns: Type

SimpleCV.base.is_tuple(n)

Determines if it is a tuple or not

Returns: Boolean

SimpleCV.base.npArray2cvMat(inputMat, dataType=5)

This function is a utility for converting numpy arrays to the cv.cvMat format.

Returns: cvMatrix

SimpleCV.base.read_logging_level(log_level)
SimpleCV.base.reverse_tuple(n)

Reverses a tuple

Returns: Tuple

SimpleCV.base.set_logging(log_level, myfilename=None)

This function sets the threshold for the logging system and, if desired, directs the messages to a logfile. Level options:

‘DEBUG’ or 1 ‘INFO’ or 2 ‘WARNING’ or 3 ‘ERROR’ or 4 ‘CRITICAL’ or 5

If the user is on the interactive shell and wants to log to file, a custom excepthook is set. By default, if logging to file is not enabled, the way errors are displayed on the interactive shell is not changed.

SimpleCV.base.system()

SUMMARY

Output of this function includes various informations related to system and library.

Main purpose: - While submiting a bug, report the output of this function - Checking the current version and later upgrading the library based on the output

RETURNS

None

EXAMPLE

>>> import SimpleCV
>>> SimpleCV.system()
SimpleCV.base.test()

This function is meant to run builtin unittests