# bbApply

## PURPOSE

Functions for manipulating bounding boxes (bb).

## SYNOPSIS

function varargout = bbApply( action, varargin )

## DESCRIPTION

     Functions for manipulating bounding boxes (bb).

     A bounding box (bb) is also known as a position vector or a rectangle
     object. It is a four element vector with the fields: [x y w h]. A set of
     n bbs can be stores as an [nx4] array, most funcitons below can handle
     either a single or multiple bbs. In addtion, typically [nxm] inputs with
     m>4 are ok (with the additional columns ignored/copied to the output).

     bbApply contains a number of utility functions for working with bbs. The
     format for accessing the various utility functions is:
      outputs = bbApply( 'action', inputs );
     The list of functions and help for each is given below. Also, help on
     individual subfunctions can be accessed by: "help bbApply>action".

     Compute area of bbs.
       bb = bbApply( 'area', bb )
     Shift center of bbs.
       bb = bbApply( 'shift', bb, xdel, ydel )
     Get center of bbs.
       cen = bbApply( 'getCenter', bb )
     Get bb at intersection of bb1 and bb2 (may be empty).
       bb = bbApply( 'intersect', bb1, bb2 )
     Get bb that is union of bb1 and bb2 (smallest bb containing both).
       bb = bbApply( 'union', bb1, bb2 )
     Resize the bbs (without moving their centers).
       bbr = bbApply( 'resize', bb, hr, wr, [ar] )
     Fix bb aspect ratios (without moving the bb centers).
       bbr = bbApply( 'squarify', bb, flag, [ar] )
     Draw single or multiple bbs to image (calls rectangle()).
       hs = bbApply( 'draw', bb, [col], [lw], [ls], [prop], [ids] )
     Embed single or multiple bbs directly into image.
      I = bbApply( 'embed', I, bb, [varargin] )
     Crop image regions from I encompassed by bbs.
       [patches, bbs] = bbApply('crop',I,bb,[padEl],[dims])
     Convert bb relative to absolute coordinates and vice-versa.
       bb = bbApply( 'convert', bb, bbRef, isAbs )
     Uniformly generate n (integer) bbs constrained between [1,w]x[1,h].
       bb = bbApply('random',w,h,bbw,bbh,n)
     Convert weighted mask to bbs.
       bbs = bbApply('frMask',M,bbw,bbh,[thr])
     Create weighted mask encoding bb centers (or extent).
       M = bbApply('toMask',bbs,w,h,[fill])

     USAGE
      varargout = bbApply( action, varargin );

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

     OUTPUTS
      varargout  - depends on action, see above

     EXAMPLE

     See also bbApply>area bbApply>shift bbApply>getCenter bbApply>intersect
     bbApply>union bbApply>resize bbApply>squarify bbApply>draw bbApply>crop
     bbApply>convert bbApply>random bbApply>frMask bbApply>toMask

     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:

- imResample Fast bilinear image downsampling/upsampling.
- arrayCrop Used to crop a rectangular region from an n dimensional array.
- c clc - clear command window.
- char2img Convert ascii text to a binary image using pre-computed templates.
- getPrmDflt Helper to set default values (if not already set) of parameter struct.
- ind2sub2 Improved version of ind2sub.
- randint2 Faster but restricted version of randint.

This function is called by:

- bbGt Bounding box (bb) annotations struct, evaluation and sampling routines.
- bbNms Bounding box (bb) non-maximal suppression (nms).