# pointsAtEvenSpacing: Generates evenly spaced points from point matrix In StereoMorph: Stereo Camera Calibration and Reconstruction

 pointsAtEvenSpacing R Documentation

## Generates evenly spaced points from point matrix

### Description

This function takes a matrix of points, calculates the cumulative distance from start to end and then uses the cumulative distance and intermediate points to generate evenly spaced points between the start and end points. Linear interpolation is used between neighboring points, so the returned points will either coincide with the input points or fall on straight lines between consecutive points.

### Usage

```pointsAtEvenSpacing(x, n)
```

### Arguments

 `x` a matrix or landmark list of points of any number of dimensions. If input is a list, only the first element is used. `n` the number of points to generate, including the start and end points.

### Details

The function first removes all `NA` values. Then, the cumulative distance is calculated from the first to last point. The last value is taken as the total length of the line or curve, defined by matrix `x`. This total length is divided by `n-1` to find a uniform segment length that will separate `n` evenly spaced points, including the first and last non-`NA` values in `x`.

The function iterates through `x`, finding the point that is at a distance equal to or just less than the segment length from the previous point. If the selected point is at a distance less than the segment length from the previous point, a point is chosen on the line between this point and the next to complete the full segment length. In this way, returned points will either coincide with the input points or fall on straight lines between consecutive points.

In the simplest implementation, `pointsAtEvenSpacing()` can be used for linear interpolation (see first example below). Define the start and end points in `x` as a two-row matrix and then select the number of points to include on the line.

If `x` represents densely sampled points on a curve (see the second example below) and if the curve can be approximated by straight lines between consecutive points, then `pointsAtEvenSpacing()` will provide comparable results to other methods, such as function fitting. This is especially useful for curves not easily fit by a mathematical function.

### Value

a matrix of `n` points. The start and end points correspond to the first and last non-NA values in `x`.

### Author(s)

Aaron Olsen

`imagePlaneGridTransform`, `resampleGridImagePoints`, `imagePlaneGridTransformError`

### Examples

```## LINEAR INTERPOLATION ##
## CREATE A MATRIX OF TWO POINTS
two_points <- matrix(c(0, 10, 0, 10), nrow=2, ncol=2)

## GENERATE 20 POINTS ALONG THE LINE
pts_aes <- pointsAtEvenSpacing(x=two_points, n=20)

## PLOT THE LINE
plot(two_points, type='l')

## AND THE POINTS ALONG THE LINE
points(pts_aes, col='red')

## POINTS ALONG A CURVE ##
## GET FILE DIRECTORY FOR PACKAGE FILES
fdir <- paste0(path.package("StereoMorph"), "/extdata/")

## GET 3D LANDMARK AND CURVE POINT FILE AND READ INTO A MATRIX

## PLOT THE LANDMARKS AND CURVE POINTS
pts <- na.omit(lm.matrix)
r <- abs(apply(pts, 2, 'max') - apply(pts, 2, 'min'))

## Not run:
## PLOT USING THE RGL PACKAGE
plot3d(pts, aspect=c(r/r, r/r, 1), size=0.5)

## End(Not run)

## CONVERT LANDMARKS TO LIST FORMAT TO EASILY ACCESS CURVE POINTS
lm.list <- landmarkMatrixToList(lm.matrix)

## CREATE 10 EVENLY SPACED POINTS ALONG ONE CURVE
lm.list\$pterygoid_crest_R <- pointsAtEvenSpacing(x=lm.list\$pterygoid_crest_R, n=10)

## CREATE 15 ALONG ANOTHER
lm.list\$tomium_R <- pointsAtEvenSpacing(x=lm.list\$tomium_R, n=15)

## CONVERT BACK TO MATRIX
lm.matrix <- landmarkListToMatrix(lm.list)

## Not run:
## PLOT NEW EVENLY SPACED POINTS WITH PREVIOUS POINTS