3. Script Descriptions: G2_pixelInstruments

• G2_pixelInstruments

  • Description:

  This function generates pixel instruments for a given set of images and corresponding extrinsics/intrinsics. It works very similar to G1_imageProducts however instead of rectifying a uniform grid for rectified images, we rectify a set of points for bathymetric inversion, surface current, or run-up calculations. Rectifications can be made in both world and a local rotated coordinate system. However, for ease and accuracy, if planned to use in bathymetric inversion, surface current, or run-up applications, it should occur in local coordinates.

  Note: Function can either have a temporally constant elevation grid with spatially varying Z or a spatially constant elevation grid with a temporally varying elevation value. The code needs to be modified to have both. If zFixedCam is non-empty, this will take precident and make a spatially constant but temporally varying Z grid to rectifiy to.

  This function is to be run sixth or fifth in the progression for fixed and UAS collections.

  The user input of the code is prescribed for UASDemoData. However, one can uncomment lines in Section 5 for the FixedMultiCamDemoData.

  • Input:

  Input is entered by user into the script in Sections 1-5.

  Section 1: Saving Information

  Variable	Description
  oname	Output string for the basename for the georectified images to be saved as.
  odir	Output filepath where the SCP mat file will be saved.
  outputFlag	Flag if you would like individual frames rectified and saved in the odir. 1= yes, output individual frames. 0= no, only output image products.

  Section 2: Collection Information

Variable	Description
imageDirectory	The directory where the collection images are stored. Note, for UAS or collects with variable extrinsics solved in F, The images should be ordered in the same order listed in imageNames F_variableExtrinsicSolutions. For variable IOEO, the code will attempt to rectify all images in in the folder, if the number of images do not match it will crash. If the order does not match, they will be rectified incorrectly. For fixed IOEO, the code will rectify all images in the folder regardless with the same IOEO. Note for multi-camera collections, each camera will require a separate imagedirectory with the order of the images the same across all folders. It is up to the user to name files correctly so that images at the same index are simultaneous.
ioeopath	Filepath of the saved CIRN IOEO calibration results produced by C_singleExtrinsicSolution or F_variableExtrinsicSolutions . If not produced by C or F, minimum variables are listed below.
intrinsics	A [1x11] vector describing the focal lengths and distortion of the camera/lens combination. Distortion coefficients are defined by [3] and defined in Section 6.
extrinsics	A [Tx6] vector describing the camera pose and position in WORLD coordinates (whatever coordinate system GCPs were entered in). T is the number of frames extrinsics are solved for and number of images in imageDirectory. Extrinsic values are defined in Section 6 along with coordinate systems. The extrinsics should correspond to the images as ordered by matlab as was solved for in F.
t	A Tx1 vector of timing of each frame in datenum format produced by F_variableExtrinsicsSolutions. This is not necessarily required. User can specify it manually in Section 4. If t is not specified or loaded in the ioeopath mat file, vector is just numbers 1,2,3, etc. T should be the number of images in imageDirectory

Section 3: Manual Entry of Time and Elevation

Variable	Description
t	A Tx1 vector of timing of each frame in datenum format. If t is not specified or loaded in the ioeopath mat file (as if produced from F), vector is just numbers 1,2,3, etc. T should be the number of images in imageDirectory.
zFixedCam	A Tx1 vector of elevations in world coordinates and units. f a Fixed station, most likely images will span times where Z is no longer constant. We have to account for this in our Z grid. To do this, enter a z vector below that is the same length as t. For each frame, the entire z grid will be assigned to this value. If UAS or not desired, leave empty. It is assumed elevation is constant during a short collect.

Section 4: Instrument Information

Variable	Description
gridpath	Filepath of the saved rectification grid created in D_gridGenExampleRect. Minimum required variables are listed below. Local values only required if localFlag==1. Grid world coordinates need to be same coordinates as those in the extrinsics in ieopath. Note, resolution of the grid is irrelevant for instruments you desire. THe grid is used for defining alocal coordinate system, and pulling z elevation values. Thus, if you have a spatially variable Z grid, you may want grid dx,dy resolutions to be similar to your instruments.
X	NxM grids in World coordinates where N is the number of rows (direction of varying Y) and M is the number of columns (direction of varying X). Grid needs to be in meshgrid format and be in same World coordinates as extrinsics in ioeopath
Y
Z
localOrigin	Origin of new local coordinate system in world coordinates. should be in the same coordinate system of GCPs (worldCoord).
localAngle	relative angle between the new (local) X axis and old (World) X axis, positive counter-clockwise from the old (world) X. Units are degrees.
localX	NxM grids in rotated Local coordinates (according to localAngle and localOrigin) where N is the number of rows (direction of varying Y) and M is the number of columns (direction of varying X).
localY
localZ
worldCoord	String of description of the World coordinate system for IOEO specified ioeopath.
pixInst	Stucture where each entry is a type of pixel instruments. Values with coordinate systems and units should match those specified in Section 2 and 4. If localFlag==1, the specified parameters should be in local coordinates. Field Entries are entered below depending on what is entered for the field ‘type.’
type	Descriptor of instrument type. Can either be ‘grid’,’xtransect’, or ’ytransect.’ For each type, input is defined below
Grid- Good for bathymetric inversion algorithms and reduced resolution geo-rectified images
type	String of ‘Grid’
dx	Single Value of uniform grid resolution in world/local units
dy
xlim	[1 x 2] vector of minimum grid extents in world/local units
ylim
z	Elevation of instrument. Leave empty if you would like it interpolated from input Z grid or zFixedCam. If entered here it is assumed constant across domain and in time.
yTransect- Good for alongshore current estimations or variations in time.
type	String of ‘yTransect’
x	Single value X coordinate of transect, for points along transect this value is constant.
ylim	[1 x 2] vector of alongshore transect extents in world/local units
dy	Single Value of uniform transect resolution in world/local units
z	Elevation of instrument. Leave empty if you would like it interpolated from input Z grid or zFixedCam. If entered here it is assumed constant across transect and in time.
xTransect- Good for observing run-up and other cross shore variations in time.
type	String of ‘xTransect’
y	Single value Y coordinate of transect, for points along transect this value is constant.
xlim	[1 x 2] vector of cross-shore transect extents in world/local units
dz	Single Value of uniform transect resolution in world/local units
z	Elevation of instrument. Leave empty if you would like it interpolated from input Z grid or zFixedCam. If entered here it is assumed constant across transect and in time.

Section 5: Mulit-Camera Demo

Uncomment this section for the multi-camera demo. Impath and ioeopath should be entered as cells, with each entry representing a different camera. It is up to the user that entries between the two variables correspond. Extrinsics between all cameras should be in the same World Coordinate System. Note that no new grid or instrument file is specified, the cameras and images are all rectified to the same grid, instrument points, and time varying elevation. Also it is important to note for ImageDirectory, each camera should have its own directory for images. The number of images in each directory should be the same (T) as well as ordered by MATLAB so images in the same order are simultaneous across cameras (i.e. the third image in c1 is taken at t=1s, the third image in c2 is taken at t=1s, etc).

• Output:

A .mat file saved as oname_pixInst.mat in odir. Will contain following variables; variables left blank are defined in the user input.

Variable	Description
rectMeta	Structure with metadata about the grid data, images, and coordinate systems the pixInstruments were derived from. Fields are listed below.
ioeopath
imageDirectory
gridPath
imageNames	Filenames of all images rectified.
t
worldCoord
localFlag	All only if localFlag==1
localAngle
localOrigin
t
pixInst	Stucture where each entry is a type of pixel instruments. Each ‘type’ will have the same fields but different vector/matrix sizes as indicated in each column. N is number of points in Y Direction, M is number of points in X direction (Number of points as specified by limits and resolution). Spatial values will have coordinate system and units as specified in gridPath and localFlag.
field	grid	yTransect	xTransect
type	String of instrument description
	'grid'	'yTransect'	'xTransect'
dx	X resolution
	[1x1]	[]	[1x1]
dy	Y resolution
	[1x1]	[1x1]	[]
xlim	X limits
	[1x2]	[]	[1x2]
ylim	Y limits
	[1x2]	[1x2]	[]
z	Input Elevation of Instrument
y	Input Y coordinate of Instrument
	[]	[1x1]	[]
x	Input X coordinate of Instrument
	[]	[]	[1x1]
X	Instrument X Coordinates
	[NxM]	[Nx1]	[Mx1]
Y	Instrument Y Coordinates
	[NxM]	[Nx1]	[Mx1]
Z	Instrument Z Coordinates
	[NxM]	[Nx1]	[Mx1]
lrgb	Uint8 of RGB pixel intensity values for each point in instrument for each frame (T dimension)
	[NxMx3xT]	[NxTx3]	[MxTx3]
lgray	Uint8 of grayscale pixel intensity values for each point in instrument for each frame (T dimension)
	[NxMxT]	[NxT]	[MxT]

A figure for each camera with pixel instruments reprojected onto the first oblique image used (Figure 11).

Figure 11: Example figure output for G2_pixelInstruments with instrument locations projected onto the first oblique image for uasDemoData.

Figures plotting each pixel instrument Irgb value. Note, for grid instruments only the first snapshot in time is plotted (Figure 12).

Figure 12: Example Figure output for G2_pixelInstruments for (left to right): Grid, yTransect, and xTransect for uasDemoData.

• Required Core Sub-Functions:

  • imageRectification
  • cameraSeamBlend
  • xyz2DistUV
  • distortUV
  • intrinsicsExtrinsics2P
  • localTransformExtrinsics
  • localTransformPoints
  • plotRectification
  • stackPlotter
  • pixInstPrepXY