# offGridPoints

Create a non-binary source mask from Cartesian points.

## Syntax

    mask = offGridPoints(kgrid, points, scale)
    mask = offGridPoints(kgrid, points, scale, ...)

## Description

`offGridPoints` creates a non-binary source mask for defining source or sensor points not aligned with the Cartesian grid points defined by `kgrid`. For each point given in the input points, a band-limited interpolant (BLI) is computed corresponding to a point source at that location. The point sources are then summed to give the source mask.

The input scale can be used to scale the overall mask (e.g., to account for the relative density of the off-grid points compared to the density of `kgrid` grid points). If given as a vector the same length as points, it can also be used to scale the magnitude of the individual BLIs. If undefined, no scaling is used.

By default, the spatial extent of the BLI at each point is truncated at 10% of its maximum value. This tolerance can be controlled by using the optional input `'BLITolerance'`. If set to 0, the BLI is evaluated at all points on the grid. For low BLI tolerance values, it may be more efficient to set the value to 0, and then truncate the resulting mask.

The BLI is computed using a sinc function by default, but this is an approximation to the true BLI for a point source. The exact BLI can be used by setting the optional input `'BLIType'` to `'exact'` (this will also force `'BLITolerance'` to be zero).

## Inputs

`kgrid` | Object of the `kWaveGrid` class defining the Cartesian and k-space grid fields.
`points` | List of Cartesian points defined by a matrix with dimensions `num_dims` by `num_points`.
`scale` | Scaling factor accounting for density of source points relative to the density of kgrid nodes.

## Optional Inputs

Optional 'string', value pairs that may be used to modify the default computational settings.

Input | Valid Settings | Default | Description
--- | --- | --- | ---
`'BLITolerance'` | (numeric scalar) | `0.1` | Scalar value controlling where the spatial extent of the BLI at each point is truncated as a portion of the maximum value.
`'BLIType'` | `'sinc'` `'exact'` | `'sinc'` | String controlling the BLI expression that is used for each point source. `'BLITolerance'` is ignored if `'exact'` is specified.
`'MaskOnly'` | (Boolean) | `false` | Boolean controlling whether a logical mask is returned instead of the non-binary source mask, where the mask contains the extent of the off-grid source.
`'SinglePrecision'` | (Boolean) | `false` | Boolean controlling whether the mask is returned in single precision. If `'BLITolerance'` is greater than 0, then calculations are also performed in single precision to improve performance.
`'WaitBar'` | (Boolean) | `false` | Boolean controlling whether a waitbar is displayed.

## Outputs

`mask` | Non-binary source mask

## See Also

`kWaveArray`