| measureCheckerboardSize {StereoMorph} | R Documentation |
Estimates checkerboard square size
Description
This function estimates the square size of a checkerboard, optionally scaling this to real-world units (e.g. millimeters).
Usage
measureCheckerboardSize(corner.file, nx, ruler.file=NULL, ruler.pt.size=NULL)
## S3 method for class 'measureCheckerboardSize'
summary(object, ...)
Arguments
corner.file |
a file path to text file containing a matrix of internal corners from a checkerboard pattern (a point grid) or the matrix itself. The text file must not have row names or a header. |
nx |
the number of internal corners in the first dimension along which the checkerboard points are ordered. |
ruler.file |
a file path to a text file containing a matrix of evenly spaced points digitized along a ruler (or comparable standard) or the matrix itself. The text file must have row names but no header or column names. |
ruler.pt.size |
the size of the spacing between points in the |
object |
a list of class |
... |
further arguments passed to other methods. |
Details
corner.file can be a file path to a text file containing a matrix of internal corners from a checkerboard pattern (ie points in a regular grid pattern) or the matrix itself. These can be automatically detected from a JPEG image using the function findCheckerboardCorners. The function first fits a camera perspective model to the corner points to robustly compare the opposing side lengths of the grid (see resampleGridImagePoints). These are returned as side.lengths and are displayed when calling the summary method. Opposing sides that differ greatly in length indicate that the grid was not completely flat relative to the image plane when it was photographed.
measureCheckerboardSize() then estimates the checkerboard or grid square size by fitting a simple grid model to the points (see gridPointsFit). The best fitting parameters are used to estimate the square size. Model fitting is more robust to noise in the grid point coordinates than taking the mean inter-point distance, for instance. The model goodness of fit can be assessed by the returned elements dist.corner.fit.mean and dist.corner.fit.sd.
ruler.file can be a file path to a text file containing a matrix of points at equal intervals along a ruler or the matrix itself. These ruler points can be digitized from an image using the function digitizeImage. If ruler.file is NULL, then only the checkerboard square size (in the input units) is returned. All other return values are NULL. If ruler.file is non-NULL, the distance between consecutive ruler points (the ruler point interval) is estimated by fitting a model of points at a regular interval along a line (see gridPointsFit). The goodness of fit for the ruler point model can be assessed by the returned elements dist.ruler.fit.mean and dist.ruler.fit.sd. The estimated ruler point interval is used to scale the checkerboard square size to the units of ruler.pt.size.
ruler.pt.size can be numeric or alphanumeric (including the units). For example, '1', '1 mm' and '1.0 mm' are all possible inputs to ruler.pt.size. The units are automatically extracted and only used in the summary function to help interpret the function results. measureCheckerboardSize() also returns the estimated real-world size of a pixel. This represents the resolution of the camera at the surface of the checkerboard pattern.
Value
a list of class "measureCheckerboardSize" with the following elements:
side.lengths |
the lengths of the four sides of the grid estimated by camera perspective model fitting. |
dist.corner.fit.mean |
the mean difference between the corner points |
dist.corner.fit.sd |
the standard deviation in the difference between the corner points |
square.size.px |
the best-fit estimate of the checkerboard square size in pixels. |
square.size.rwu |
the best-fit estimate of the checkerboard square size in real-world units. |
dist.ruler.fit.mean |
the mean difference between the |
dist.ruler.fit.sd |
the standard deviation in the difference between the |
ruler.size.px |
the best-fit estimate of the distance between consecutive points on the ruler (in pixels) in the plane of the imaged grid. |
rwu.per.px |
the real-world size of a pixel in the image (the length of one side of the pixel) in the plane of the imaged grid. |
unit |
if |
Author(s)
Aaron Olsen
See Also
drawCheckerboard, resampleGridImagePoints, gridPointsFit, digitizeImage
Examples
## GET THE FILE DIRECTORY FOR EXTRA R PACKAGE FILES
fdir <- paste0(path.package("StereoMorph"), "/extdata/")
## SET FILE PATH TO CHECKERBOARD POINTS FILE
corner_file <- paste0(fdir, "checker_21_14_200(9).txt")
## NUMBER OF INTERNAL CORNERS IN THE HORIZONTAL DIMENSION
nx <- 21
## NUMBER OF INTERNAL CORNERS IN THE VERTICAL DIMENSION
ny <- 14
## SET FILE PATH TO RULER POINTS FILE
ruler_file <- paste0(fdir, "ruler_21_14_200(9).txt")
## ESTIMATE SQUARE SIZE
square_size <- measureCheckerboardSize(corner.file=corner_file, nx=nx)
## PRINT SUMMARY
summary(square_size)
## ESTIMATE SQUARE SIZE AND SCALE WITH RULER POINTS
square_size_scale <- measureCheckerboardSize(corner.file=corner_file, nx=nx,
ruler.file=ruler_file, ruler.pt.size='1 mm')
## PRINT SUMMARY
summary(square_size_scale)
## Not run:
## INPUT MATRICES DIRECTLY
## READ POINTS INTO MATRICES
corner_pts <- as.matrix(read.table(corner_file))
ruler_pts <- as.matrix(read.table(ruler_file, row.names=1))
## ESTIMATE SQUARE SIZE AND SCALE WITH RULER POINTS
square_size_scale <- measureCheckerboardSize(corner.file=corner_pts, nx=nx,
ruler.file=ruler_pts, ruler.pt.size='1 mm')
## End(Not run)