StereoMorph (version 1.6.7)

measureCheckerboardSize: 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 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 ruler.file matrix in real world units. This can be numeric or alphanumeric including the unit (see "Details").

object

a list of class "measureCheckerboardSize".

...

further arguments passed to other methods.

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 corner.file and those generated assuming the best-fit simple grid model.

dist.corner.fit.sd

the standard deviation in the difference between the corner points corner.file and those generated assuming the best-fit model.

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. NULL if ruler.file is NULL.

dist.ruler.fit.mean

the mean difference between the ruler.file matrix and those generated assuming the best-fit model. NULL if ruler.file is NULL.

dist.ruler.fit.sd

the standard deviation in the difference between the ruler.file matrix and those generated assuming the best-fit model. NULL if ruler.file is NULL.

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. NULL if ruler.file is NULL.

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. NULL if ruler.file is NULL.

unit

if ruler.pt.size includes a unit, the unit. NULL if ruler.file is NULL.

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.

See Also

drawCheckerboard, resampleGridImagePoints, gridPointsFit, digitizeImage

Examples

# NOT RUN {
## 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')
# }