# 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 access to two types of routines:
     (1) Data structure for storing bb image annotations.
     (2) Routines for evaluating the Pascal criteria for object detection.

     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 (in addition routines for loading PASCAL
     format data are provided, see bbLoad()).

     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 and filter.
       [objs,bbs] = bbGt( 'bbLoad', fName, [pLoad] )
     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, pDraw )

    %% (2) Routines for evaluating the Pascal criteria for object detection.
     Get all corresponding files in given directories.
       [fs,fs0] = bbGt('getFiles', dirs, [f0], [f1] )
     Copy corresponding files into given directories.
       fs = bbGt( 'copyFiles', fs, dirs )
     Load all ground truth and detection bbs in given directories.
       [gt0,dt0] = bbGt( 'loadAll', gtDir, [dtDir], [pLoad] )
     Evaluates detections 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 )
     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, imFs, 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 )

     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>getFiles, bbGt>copyFiles,
     bbGt>loadAll, bbGt>evalRes, bbGt>showRes,  bbGt>compRoc, bbGt>cropRes,
     bbGt>compOas, bbGt>compOa

     Piotr's Image&Video Toolbox      Version 3.20
     Copyright 2013 Piotr Dollar.  [pdollar-at-caltech.edu]
     Please email me if you find bugs, or have suggestions or questions!
     Licensed under the Simplified BSD License [see external/bsd.txt]