Classes
class	CorpusCallbackI

class	TrainerCallbackReceiverI

class	DetectorCallbackReceiverI

Functions
def	getFSPath

def	getCvacPath

def	isLikelyVideo

def	isLikelyDir

def	getLabelable

def	getLabelableList

def	getCorpusServer

def	getDefaultCorpusServer

def	openCorpus

def	closeCorpus

def	createLocalMirror

def	getDataSet

def	isInBounds

def	isProperRunSet

def	printCategoryInfo

def	printSubstrateInfo

def	printRunSetInfo

def	getPurpose

def	getPurposedLabelableSeq

def	addPurposedLabelablesToRunSet

def	addToClassmap

def	_determineDefaultPurpose

def	getCategories

def	addToRunSet

def	createRunSet

def	getFileServer

def	getDefaultFileServer

def	putFile

def	getFile

def	collectSubstrates

def	_collectSubstratesFromResults

def	putAllFiles

def	getAllFiles

def	deleteAllFiles

def	getProxyString

def	getTrainerProperties

def	getTrainer

def	getVerbosityNumber

def	train

def	getDetectorProperties

def	getDetector

def	discardSuboptimal

def	getBestDetectorData

def	makeROCdata

def	isROCdata

def	getSensitivityOptions

def	detect

def	getPurposeName

def	getLabelText

def	printResults

def	initGraphics

def	showImage

def	showROCPlot

def	drawResults

def	drawLabelables

def	showImagesWithLabels

def	getHighestConfidenceLabel

def	sortIntoFolders

def	testResultSyntax

Variables
	args = sys.argv

tuple	modulepath = os.path.dirname(__file__)

tuple	config_client_path = os.path.abspath(modulepath)

tuple	nextdir = os.path.dirname(config_client_path)

tuple	ic = Ice.initialize(args)

	defaultCS = None

tuple	CVAC_DataDir = ic.getProperties()

tuple	CVAC_ClientVerbosity = os.getenv("CVAC_CLIENT_VERBOSITY", "info")

Detailed Description

Easy Computer Vision

easy.py is a high-level interface to the underlying metadata
description syntax and to the multi-language service-oriented
architecture.  Its goal is to hide the lower-leve complexities
and to provide, uhm, easy access functions to its functionality.

Function Documentation

def easy.easy._collectSubstratesFromResults ( results )

private

Collect all image substrates of found labels;
if the foundLabel does not have a path, use the path from
the original

def easy.easy._determineDefaultPurpose	(	label,
		purpose,
		classmap
	)

private

If a purpose is given, return that.  If not, return the purpose in the
classmap mapping from label to Purpose.  If not found, return UNPURPOSED.

def easy.easy.addPurposedLabelablesToRunSet	(	runset,
		purpose,
		labelables
	)

Append labelables to a sequence with the same purpose.
If the runset does not have one, add a new sequence.

def easy.easy.addToClassmap	(	classmap,
		key,
		purpose
	)

def easy.easy.addToRunSet	(	runset,
		samples,
		purpose = `None`,
		classmap = `None`
	)

Add samples to a given RunSet.
Take a look at the documentation for createRunSet for details.

def easy.easy.closeCorpus	(	corpus,
		corpusServer = `None`
	)

Close a previously opened Corpus, presumable to re-open
it with an updated properties file or new files

def easy.easy.collectSubstrates ( runset )

obtain a set (a list without duplicates) of all
substrates that occur in this runset or result set

def easy.easy.createLocalMirror	(	corpusServer,
		corpus
	)

Call the corpusServer to create the local mirror for the
specified corpus.  Provide a simple callback for tracking.

def easy.easy.createRunSet	(	samples,
		purpose = `None`,
		classmap = `None`
	)

Add all samples from the argument to a new RunSet.
Determine whether this is a two-class (positive and negative)
or a multiclass dataset and create the RunSet appropriately.
Input argument can also be a string to a single file.
Note that the positive and negative classes might not be
determined correctly automatically.  Specifiy a single Purpose
if all samples will have the same purpose.
Return the mapping from Purpose (class ID) to label name.

def easy.easy.deleteAllFiles	(	fileserver,
		uploadedFiles
	)

Delete all files that were previously uploaded to the fileserver.
For reporting purposes, return what has and has not been uploaded.

def easy.easy.detect	(	detector,
		detectorData,
		runset,
		detectorProperties = `None`,
		callbackRecv = `None`
	)

Synchronously run detection with the specified detector,
trained model, and optional callback receiver.
The detectorData has to be a filename of a pre-trained model, or
 empty if the detector is pre-configured with a model, or if it does
 not require a model.  Naturally, the model has to be
 compatible with the detector.
The runset can be either a cvac.RunSet object or anything that
createRunSet can turn into a RunSet.
If a callback receiver is specified, this function returns nothing,
otherwise, the obtained results are returned.

def easy.easy.discardSuboptimal	(	perfdata,
		saveRelativeDir = `None`
	)

This function returns
1) all ROC operating points [x-axis: false alarm, y-axis:recall] 
2) index of optimal ROC points among all ROC points.
Input variables are 
1) perfdata = performance data from jousting 
2) saveRelativeDir = directory for saving a log file (CAUTION: it's just for DEBUGGING)

def easy.easy.drawLabelables	(	lablist,
		maxsize = `None`
	)

def easy.easy.drawResults ( results )

def easy.easy.getAllFiles	(	fileserver,
		runset
	)

Make sure all files in the RunSet are available on the local site;
if they are not then they will be downloaded via the remote fileserver
to the local site.
For reporting purposes, return what has and has not been uploaded.

def easy.easy.getBestDetectorData	(	listRocData,
		dFAR,
		dRec
	)

This function returns the best detector data among detectors from a ROC file
according to a criteria.
Users can select only one criteria at a time; false alarm rate or recall rate
When users set both criterias, it will return the best f-scored detector data. 
But, it may cause unexpected results.

def easy.easy.getCategories ( lablist )

def easy.easy.getCorpusServer ( configstr )

Connect to a Corpus server based on the given configuration string

def easy.easy.getCvacPath ( fsPath )

Turn a file system path into a CVAC FilePath

def easy.easy.getDataSet	(	corpus,
		corpusServer = `None`,
		createMirror = `False`
	)

Obtain the set of labels from the given corpus and return it as
a dictionary of label categories.  Also return a flat list of all labels.
The default local corpusServer is used if not explicitly specified.
If the corpus argument is not given as an actual cvac.Corpus object
but the argument is a string instead, an attempt is made to
open (but not create) a Corpus object from the corpusServer.
Note that this will fail if the corpus needs a local mirror but has not
been downloaded yet, unless createMirror=True.

def easy.easy.getDefaultCorpusServer ( )

Returns the CorpusServer that is expected to run locally at port 10011

def easy.easy.getDefaultFileServer ( detector )

Assume that a FileServer is running on the host of the detector
at the default port (10110).  Obtain a connection to that.

def easy.easy.getDetector ( configString )

Connect to a detector service

def easy.easy.getDetectorProperties ( detector )

Get the detector properties for this detector

def easy.easy.getFile	(	fileserver,
		filepath
	)

def easy.easy.getFileServer ( configString )

Obtain a reference to a remote FileServer.
Generally, every host of CVAC services also has one FileServer.

def easy.easy.getFSPath	(	cvacPath,
		abspath = `False`
	)

Turn a CVAC path into a file system path

def easy.easy.getHighestConfidenceLabel ( lablist )

Return the label in the list that has the highest confidence.
If multiple labels have the same high confidence, the first of these
is returned.

def easy.easy.getLabelable	(	filepath,
		labelText = `None`
	)

Create a Labelable wrapper around the file, assigning
a textual label if specified.

def easy.easy.getLabelableList	(	dirpath,
		recursive = `True`,
		video = `True`,
		image = `True`
	)

Return a list of Labelables contained within the directory (optionally recursively)

def easy.easy.getLabelText	(	label,
		classmap = `None`,
		guess = `False`
	)

Return a label text for the label: either
"unlabeled" or the name of the label or whatever
Purpose this label maps to.

def easy.easy.getProxyString ( configString )

If we have a proxy string already then just return it.  If we have
a detector name look it up in the config.client file and return the
proxy string.  If we don't have either then return empty string

def easy.easy.getPurpose ( purpose )

Try to convert the input in to cvac.Purpose

def easy.easy.getPurposedLabelableSeq	(	runset,
		purpose
	)

Return the PurposedLabelableSeq in the runset that has
the specified purpose, or None.

def easy.easy.getPurposeName ( purpose )

Returns a string to identify the purpose or an
int to identify a multiclass class ID.

def easy.easy.getSensitivityOptions ( detectorData )

Return any False Alarm, and Recall rate options available
in the model file.  This will return a list of
<false alarm, recall> pairs that
have been trained into the model or None if they are not any.
detectorData is the model file that that might contain the
different model files and sensitivity options.

def easy.easy.getTrainer ( configString )

Connect to a trainer service

def easy.easy.getTrainerProperties ( trainer )

Get the trainer properties for this trainer

def easy.easy.getVerbosityNumber ( verbosityString )

Convert error, info, warning etc into 1, 2, 3 etc.

def easy.easy.initGraphics ( title = "results" )

def easy.easy.isInBounds ( labelable )

Return True if the LabeledLocation is within image bounds.

def easy.easy.isLikelyDir ( path )

Return true if path is likely a directory.
Note that the path could be on a remote server, therefore
we cannot check for existence and type of path (dir, file)
but instead have to guess from the file extension, if any

def easy.easy.isLikelyVideo ( cvacPath )

def easy.easy.isProperRunSet	(	runset,
		deleteInvalid = `False`
	)

Return True if the RunSet has proper syntax, False otherwise.
If deleteInvalid==True, labeled artifacts with bounding boxes out
of image bounds will be removed from the RunSet.

def easy.easy.isROCdata ( rocZip )

This function checks whether the input zip file is a ROC zip file or 
not (a regular detector file). Decision is based on existence 
of the file "roc.properties".
Return 1) is it a ROC zip file or not
Return 2) model files and their false alarm rate and recall rate 
(if it is a ROC zip file). 
Return 3) a temp folder including model files (if it is a ROC zip file).

def easy.easy.makeROCdata ( rocData_optimal )

This function makes a single ZIP file incluing mulitple detector data 
and their performance values (false alarm and recall).
Performance values are written in the file "roc.properties"
Input format: a list of [detectordata, false alarm, recall]

def easy.easy.openCorpus	(	corpusPath,
		corpusServer = `None`
	)

Open a Corpus specified by a properties file,
   or create a new Corpus from all files in a given directory;
   if no corpusServer is specified, a default local server is
   expected at port 10011

def easy.easy.printCategoryInfo ( categories )

Categories are a dictionary, key being the label and the
value being all samples of that label.

def easy.easy.printResults	(	results,
		foundMap = `None`,
		origMap = `None`,
		inverseMap = `False`
	)

Print detection results as specified in a ResultSet.
If classmaps are specified, the labels are mapped
(replaced by) purposes: the foundMap maps found labels and
the origMap maps the original labels.  The maps are Python
dictionaries, mapping either a label to a Purpose or a label
to a string.

If inverseMap=True: Since detectors do not produce Purposes,
but the foundMap maps labels to Purposes, it is assumed that
the user wishes to replace a label that hints at the Purpose
with the label that maps to that same Purpose.  For example,
a result label of '12' is assumed to be a class ID.  The
classmap might map 'face' to a Purpose(MULTICLASS, 12).
Hence, we would replace '12' with 'face'.

def easy.easy.printRunSetInfo	(	runset,
		printLabels = `False`,
		printArtifacts = `True`
	)

You can pass in an actual cvac.RunSet or a dictionary with
the runset and a classmap, as returned by createRunSet.

def easy.easy.printSubstrateInfo	(	labelList,
		indent = `""`,
		printLabels = `False`
	)

def easy.easy.putAllFiles	(	fileserver,
		runset
	)

Make sure all files in the RunSet are available on the remote site;
it is the client\'s responsibility to upload them if not.
For reporting purposes, return what has and has not been uploaded.

def easy.easy.putFile	(	fileserver,
		filepath,
		testExistence = `True`
	)

Copy the file referenced by filepath to the specified fileserver.
By default, test first if the file exists on the fileserver, and only
putFile if it does not exist.

def easy.easy.showImage ( img )

def easy.easy.showImagesWithLabels	(	substrates,
		maxsize = `None`
	)

Takes a dictionary of type dict[file_system_path] = [Labelable] as
input and renders every image with labels overlaid.  The size
parameter can be used to display all images at the same size.

def easy.easy.showROCPlot ( ptList )

Plot image is 300x200 with 10 pixel space around the plot so the
plot area is 280x180. So each 1/10th is 18 pixels in height and 28 pixels in width.
Plot 0,0 is pixel 10, 190

def easy.easy.sortIntoFolders	(	results,
		outfolder,
		multi = `"highest"`,
		symlink = `False`
	)

Sort the substrates from the original labels into subfolders of
"outfolder" corresponding to the found labels;
if multiple labels were found per original, consider only
the label with the highest confidence unless otherwise
specified.  Create symlinks if desired and if possible (on Unix),
copy files by default.  CVAC.DataDir must be absolute for symlinks to work.
Note: this method is intended for images, not videos.

def easy.easy.testResultSyntax	(	results,
		runset = `None`
	)

More a unit testing routine than for user consumption, this function
tests whether the result data structure returned from a detector is
valid.  It checks the data structure composition as well as some
required contents and reports errors accordingly.  A boolean return
value signals success.
If a runset is given, the results\' original labels are compared
against the labels provided in the runset.

def easy.easy.train	(	trainer,
		runset,
		callbackRecv = `None`,
		trainerProperties = `None`
	)

A callback receiver can optionally be specified

Variable Documentation

easy.easy.args = sys.argv

easy.easy.config_client_path = os.path.abspath(modulepath)

tuple easy.easy.CVAC_ClientVerbosity = os.getenv("CVAC_CLIENT_VERBOSITY", "info")

string easy.easy.CVAC_DataDir = ic.getProperties()

easy.easy.defaultCS = None

tuple easy.easy.ic = Ice.initialize(args)

tuple easy.easy.modulepath = os.path.dirname(__file__)

tuple easy.easy.nextdir = os.path.dirname(config_client_path)

Classes

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation