# bbGt

## PURPOSE

Bounding box (bb) annotations struct, evaluation and sampling routines.

## SYNOPSIS

function varargout = bbGt( action, varargin )

## DESCRIPTION

     Bounding box (bb) annotations struct, evaluation and sampling routines.

     bbGt gives acces to three types of routines:
     (1) Data structure for storing bb image annotations.
     (2) Routines for evaluating the Pascal criteria for object detection.
     (3) Routines for sampling training examples from a labeled image.

     The bb annotation stores bb for objects of interest with additional
     information per object, such as occlusion information. The underlying
     data structure is simply a Matlab stuct array, one struct per object.
     This annotation format is an alternative to the annotation format used
     for the PASCAL object challenges.

     Each object struct has the following fields:
      lbl  - a string label describing object type (eg: 'pedestrian')
      bb   - [l t w h]: bb indicating predicted object extent
      occ  - 0/1 value indicating if bb is occluded
      bbv  - [l t w h]: bb indicating visible region (may be [0 0 0 0])
      ign  - 0/1 value indicating bb was marked as ignore
      ang  - [0-360] orientation of bb in degrees

     Note: although orientation (angle) is stored for each bb, for now it is
     not being used during evaluation or sampling.

     bbGt contains a number of utility functions, accessed using:
      outputs = bbGt( 'action', inputs );
     The list of functions and help for each is given below. Also, help on
     individual subfunctions can be accessed by: "help bbGt>action".

    %% (1) Data structure for storing bb image annotations.
     Create annotation of n empty objects.
       objs = bbGt( 'create', [n] );
     Save bb annotation to text file.
       objs = bbGt( 'bbSave', objs, fName )
     Load bb annotation from text file.
       objs = bbGt( 'bbLoad', fName )
     Get object property 'name' (in a standard array).
       vals = bbGt( 'get', objs, name )
     Set object property 'name' (with a standard array).
       objs = bbGt( 'set', objs, name, vals )
     Draw an ellipse for each labeled object.
       hs = draw( objs, varargin )

    %% (2) Routines for evaluating the Pascal criteria for object detection.
     Returns filtered ground truth bbs for purpose of evaluation.
       gtBbs = bbGt( 'toGt', objs, prm )
     Evaluates detections in a single frame against ground truth data.
      [gt, dt] = bbGt( 'evalRes', gt0, dt0, [thr], [mul] )
     Display evaluation results for given image.
      [hs,hImg] = bbGt( 'showRes' I, gt, dt, varargin )
     Run evaluation evalRes for each ground truth/detection result in dirs.
      [gt,dt,files] = bbGt( 'evalResDir', gtDir, dtDir, [varargin] )
     Compute ROC or PR based on outputs of evalRes on multiple images.
      [xs,ys,ref] = bbGt( 'compRoc', gt, dt, roc, ref )
     Extract true or false positives or negatives for visualization.
      [Is,scores,imgIds] = bbGt( 'cropRes', gt, dt, files, varargin )
     Computes (modified) overlap area between pairs of bbs.
       oa = bbGt( 'compOas', dt, gt, [ig] )
     Optimized version of compOas for a single pair of bbs.
       oa = bbGt( 'compOa', dt, gt, ig )

    %% (3) Routines for sampling training examples from a labeled image.
     Sample pos or neg examples for training from an annotated image.
       [bbs, IS] = bbGt( 'sampleData', I, prm )

     USAGE
      varargout = bbGt( action, varargin );

     INPUTS
      action     - string specifying action
      varargin   - depends on action, see above

     OUTPUTS
      varargout  - depends on action, see above

     EXAMPLE

     See also bbApply, bbLabeler, bbGt>create, bbGt>bbSave, bbGt>bbLoad,
     bbGt>get, bbGt>set, bbGt>draw, bbGt>toGt, bbGt>evalRes, bbGt>showRes,
     bbGt>evalResDir, bbGt>compRoc, bbGt>cropRes, bbGt>compOas, bbGt>compOa,
     bbGt>sampleData

     Piotr's Image&Video Toolbox      Version 2.50
     Copyright 2010 Piotr Dollar.  [pdollar-at-caltech.edu]
     Please email me if you find bugs, or have suggestions or questions!
     Licensed under the Lesser GPL [see external/lgpl.txt]

## CROSS-REFERENCE INFORMATION

This function calls:

- bbApply Functions for manipulating bounding boxes (bb).
- bbGt Bounding box (bb) annotations struct, evaluation and sampling routines.
- bbNms Bounding box (bb) non-maximal suppression (nms).
- im Function for displaying grayscale images.
- montage2 Used to display collections of images and videos.
- c clc - clear command window.
- cell2array Flattens a cell array of regular arrays into a regular array.
- getPrmDflt Helper to set default values (if not already set) of parameter struct.
- plotEllipse Adds an ellipse to the current plot.
- ticStatus Used to display the progress of a long process.
- tocStatus Used to display the progress of a long process.

This function is called by:

- bbGt Bounding box (bb) annotations struct, evaluation and sampling routines.
- bbLabeler Bounding box or ellipse labeler for static images.