# maskGaussians

## PURPOSE

Divides a volume into softly overlapping gaussian windows.

## SYNOPSIS

function [masks,keepLocs] = maskGaussians( siz, M, width, offset, show )

## DESCRIPTION

     Divides a volume into softly overlapping gaussian windows.

     Return M^nd masks each of size siz.  Each mask represents a symmetric
     gaussian window, the locations are evenly spaced throughout the array of
     size siz.  For example, if M=2, then along each dimension d the location
     of each mask is either 1/4 or 3/4 of siz(d) and likewise if M=3 that mask
     is at 1/6,3/6, or 5/6 of siz(d). For higher M the locations are:
     1/2M,3/2M,...,M-1/2M. See examples below to visualize the masks.

     The std of each gaussian is set to be equal to the spacing between two
     adjacent masks multiplied by width.  Reducing the widths of the gaussians
     causes there to be less overlap between masks, but if the width is
     reduced too far certain pixels in between masks receive very little
     weight.  A desired property of the masks is that their coverage (the
     total weight placed on the pixel by all the masks) is approximately
     constant.  Typically, we settle for having the coverage be monotonically
     decreasing as we move away from the center.  (In reality the coverage
     oscilates as we move past peaks, it's just that the oscillations tend to
     be small).  The default value of the width is .6, which minimizes overlap
     while still providing good overall coverage. Values lower tend to produce
     noticeable oscillations in coverage.  offset in (-.5,1) controls the
     spacing of the locations.  Essentially, a positive offset moves the
     locations away from the center of the array and a negative offset moves
     the windows away from the center.  Using a positive offset gives better
     coverage to areas near the borders.

     USAGE
      [masks,keepLocs] = maskGaussians( siz, M, [width], [offset], [show] )

     INPUTS
      siz         - dimensions of each mask
      M           - # mask locations along each dim [either scalar or vector]
      width       - [.6] widths of the gaussians
      offset      - [.1] spacing of mask centers; in (-.5,1)
      [show]      - [0] figure to use for display (no display if==0) (nd<=3)

     OUTPUTS
      masks       - [see above] array of size [siz x M^nd]
      keepLocs    - logical array of all locs where masks is nonzero

     EXAMPLE
      masks = maskGaussians( 100, 10, .6, -.1, 1 );  %1D
      masks = maskGaussians( [35 35], 3, .6, .1, 1 );  %2D
      masks = maskGaussians( [35 35 35], [2 2 4], .6, .1, 1 ); %3D

     See also HISTCIMLOC, MASKCIRCLE

     Piotr's Image&Video Toolbox      Version 2.0
     Copyright 2008 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:

- filterGauss n-dimensional Gaussian filter.
- im Function for displaying grayscale images.
- montage2 Used to display collections of images and videos.
- c clc - clear command window.
- checkNumArgs Helper utility for checking numeric vector arguments.
- ind2sub2 Improved version of ind2sub.
- simpleCache A simple cache that can be used to store results of computations.

This function is called by:

- histcImLoc Creates a series of locally position dependent histograms.