rePhotograph: rePhotograph

In MatthewGilbertUCD/rePhoto: Functions for Finding Geographic Location of Historical Photograph

Description

rePhotograph is the core function used to evaluate a large geographical grid (a data frame) of possible locations for a historical photograph. The input is a data frame supplying the geographical coordinates of three or four points of reference and the distances between the points of reference in a photograph. The output is the data frame with associated values that help determine the likelihood of the photographic location. Note that the function evaluates a large grid using vectorisation, never-the-less it can take time to complete the calculations ~1 to 10s with the defaults on a off the shelf laptop.

Usage

rePhotograph(data1,scaleToSearch=2,PtDensity=1000,CameraLens=90,UseOrder=TRUE,grid=c(0,0,0,0),...)

Arguments

data1	a data frame containing 3 or 4 rows, with columns X, Lat and Long corresponding to the X distance between points of reference in the original photograph and the latitude and longitude.
scaleToSearch	default 2; a value setting the scale of the region (i.e. grid size) to evaluate. The value applied as a multiple of the maximum range of points in data1 e.g. if the maximum range of latitudes or longitudes is 0.5 degrees, then a grid is evaluated scaleToSearch times the range, or 1 degree.
PtDensity	default 1000; a value setting the size of the grid searched i.e. a value of 1000 evaluates a 1000 by 1000 grid of latitudes and longitudes. Note that at values > 1000 the function will take a long time to evaluate. The minimum spatial resolution is thus the maximum range of latitudes or longitudes times the scaleToSearch divided by the PtDensity. For the default values and a 0.5 degree range: 0.5 degree*2/1000 = 3.6 seconds of latitude or longitude.
CameraLens	default 90; a value setting the approximate field of view angle for the camera lens used for the original photograph. This value is used to exclude grid locations that are too near to the points of reference to be possible for that camera angle.
UseOrder	default TRUE; sets whether the function excludes grid locations based upon the order of the points of reference being wrong. e.g. given an order of points of reference in the photograph, then on the reverse side of points of reference the order of points are reversed.
grid	default c(0,0,0,0); sets the boundaries of the grid of latitude and longitudes that are evaluated. This is useful to specify rectangular grids rather than the default square grid. Not used unless grid is specified as non 0 values e.g. grid=c(1,2,3,4) where 1 and 2 are the latitudes and 3 and 4 are the longitudes of the grid to be evaluated. Note this setting overrides scaleToSearch.

Details

The rePhotograph function is applied to data for either three or four points of reference (POR). If the latter, the calculations are run twice for groups of three points and the output combined via geometric mean.

The rePhotograph function sets up the analysis and calls the AngleCalcs() function to do most of the calculations.

The function could be extended to more than four points of reference, but this was not implemented in favor of the following approach. For example with six POR, use three POR to estimate a KML output showing a likely search area, then estimate an independent search area using the remaining three POR. Compare the two independently predicted search areas. In this manner incorrect POR will have less impact than with a composite analysis.

Note that expected inputs are: latitudes + for northern and - for southern hemisphere locations, longitudes + for east and - for locations west. The X column in data1 is unitless as the ratios of lengths are used e.g. on a photograph the horizontal distances between points of reference can be measured by ruler (e.g. mm) to simply the X pixel values.

Value

rePhotograph returns a large data frame (default 1000x1000 rows) of latitude and longitudes and values that relate to the likelihood of these locations being the original photograph location. The data frame contains these columns:

Lat latitudes evaluated

Long longitudes evaluated

diff1 a value relating to the likelihood that a location specified by Lat and Long is the location of the camera in the original photograph. This is based upon the first three POR. Values of 1 are default indicators of exclusion from consideration.

diff2 the same as diff1 but based upon the first, second and fourth POR.

diffcomb the geometric mean of diff1 and diff2, or just diff1 if three POR were input.

include logical values (1 or 0) determining if the location was excluded based upon the camera angles and order of POR (if TRUE). A value of 0 indicates exclusion, 1 indicates inclusion.

Note that the logic applying 'include' is applied to diff1 and diff2. Thus, to override this logic and see actual diff values, set UseOrder = FALSE and CameraLens=360

Examples

See rePhotograph vignette

MatthewGilbertUCD/rePhoto documentation built on Jan. 7, 2022, 10:55 a.m.