Region of Interest¶

Example¶

[5]:

# import
import imhr
# parameters
path = imhr.__path__[0]
image_path = '%s/dist/roi/raw/2/'%(path)
output_path = '%s/dist/roi/output/'%(path)
metadata_source = '%s/dist/roi/raw/2/metadata.xlsx'%(path)
position = 'topcenter'
# initiate
roi = imhr.eyetracking.ROI(isMultiprocessing=False, isDebug=True,
    # roi detection method and contour shape
    detection='manual', shape='straight',
    # path to read and export data
    image_path=image_path, output_path=output_path, metadata_source=metadata_source,
    # stimuli size and screen size
    screensize=[1920,1080], recenter=[(1920*.50),(1080*.50)], scale=.75,
    # applying new id, renaming variables and output
    newcolumn={'position': position}, uuid=['image','roi','position'], append_output_name=position,
    # image backend
    image_backend='PIL')
# run
df, error = roi.process()

not multiprocessing
starting()
finished()

Required Parameters¶

Here are all of the required parameters that are part of this module:

>>> imagename = "BM001"; roiname = 1; feature = "lefteye"

Optional Parameters¶

Here are optional parameters, not required to run the code, but allow output tweaking:

Additional core parameters

These properties control additional core parameters for the API:

Data processing parameters

These properties control data is processed which include the type of haarcascade used, delimiters for metadata:

>>>  [{'custom_cascade': {
...   'file': 'haarcascade_eye.xml',
...   'type': 'profileface',
...   'path': './haarcascade_eye.xml',
...   'minN': 5,
...   'minS':(100,100),
...   'sF': 1.01 }
...  }]

>>> roi = imhr.eyetracking.ROI(detection='manual.....)
>>> roi.default_classifiers['eye']['minNeighbors'] = 10

Image export parameters

Here are properties specific to how images are exported after processing. The code can either use matplotlib or PIL as a backend engine:

Manual coding¶

Using multilayered images (psd, dcm)

The recommended method of manually identifying each region of interest is by using a image media file that is able to store multiple layers of content. The two filetypes supported here are Adobe Photoshop Document (psd) and Digital Imaging and Communications in Medicine (dcm) filetypes. Each ROI can be stored as a seperate layer, which can then processed for exporting.

Figure: Example psd in Adobe Photoshop.

Figure: Example DICOM in Adobe Photoshop.

Haar Cascades¶

Another method for creating ROI’s is by using automated feature extraction using haar cascades feature classifiers. This is done by using machine-training to identify unique features (eyes, smile) from an image.

Figure: Example face, eye, and smile identfication using haar cascades.

Bounds¶

Bounds can be created for each region of interest with different levels of granularity. The list below provides an example of each, in order of granularity.

Figure: Original images before contour extraction.

Polygon

Figure: Contour Approximation (polygon) that will most closely match the orginal shape of the ROI.

Hull

Figure: Generated Convex Hull (hull), which is similar to but not as complex as a Contour Approximation and will include bulges for areas that are convex.

Circle

Figure: Circle creates a mininum enclosing circle, with the center equal to that of the ROI.

Rectangle (rotated)

Figure: Bounding Rectangle (rotated), with the position matching that of the general shape of the ROI.

Rectangle (straight)

Figure: Bounding Rectangle (straight) parallel to the shape of the background ima

Data¶

Two types of data are exported, contour shape and boundaries. Boundaries are saved in SR Research DataViewer (ias), and Microsoft Office Open XML Workbook (xlsx) formats, while contour shapes are saved in Hierarchical Data Format (HDF5; h5). Exported data can read either by SR Research DataViewer (ias) or any other data processing tool (xlsx, h5).

Both xlsx and HDF5 provide all metadata associated with each image, while ias files matches the format required by DataViewer. Of the three filetypes, HDF5 files are the most detailed providing both metadata for each ROI as well as exact pixel coordinates associated with each ROI.

For more information, click bounds.ias, bounds.xlsx, contours.h5 to see an example of each filetype.

Figure: Sample bounds output saved to xlsx.

[3]:

df

[3]: