X [Not up to date] Standard ISD Keywords

Note: this wiki page is no longer up-to-date. For a link to the up-to-date specification, see the README.md.

We will be designing our own standards for Image Support Data (ISD) keywords to be used by our Community Sensor Models (CSM's) simplify creating the proper ISD for each CSM.

Why We Need an ISD Keyword Standard

• Any Sensor Exploitation Tool (SET) must be able to use any CSM.
• To initialize a CSM, you must have a model state string or ISD object.
• The CSM Plugin will expect certain parameter (keyword) names in order to create a valid sensor model.
• The CSM Plugin must know what values each parameter (keyword) contains.
• Anyone can use our CSM's with their own SET's if they provide or create an appropriate ISD for a particular CSM.
• Establishing a standardized set of ISD keywords will make it easier for anyone consuming our CSM's to create proper ISD's.

Proposed Keywords

The table below proposes a standard list of expected ISD keywords to be used by CSM plugins.

This is a preliminary proposal, please review and comment.

Note that "adapted from param" references MdisSensorModel member names.

Keyword	Units	Description	Notes	associated Framing Camera keyword	associated Linescan keyword
BORESIGHT	vector	Boresight x,y,z vector	boresight	?
DETECTOR_CENTER	pixels	Center of the detector	adapted from ccd_center	ccd_center	DETECTOR_SAMPLE_ORIGIN/DETECTOR_LINE_ORIGIN
EPHEMERIS_TIME	?	Ephemeris time of image		see NAIF	ephemeris_time
FOCAL_LENGTH	mm	Camera focal length	focal_length	FOCAL
FOCAL_LENGTH_EPSILON	mm	Degree of uncertainty related to focal length	focal_length_epsilon	?
IFOV	degrees	Instantaneous field of view		ifov	?
IMAGE_LINES	pixels	Number of lines in image	adapted from nlines	nlines	TOTAL_LINES
IMAGE_SAMPLES	pixels	Number of samples in image	adapted from nsamples	nsamples	TOTAL_SAMPLES
ITRANS_LINE	matrix	Transformation matrix from pixels (line) to image plane (y mm)	itrans_line	ITRANSL
ITRANS_SAMPLE	matrix	Transformation matrix from pixels (sample) to image plane (x mm)	itrans_sample	ITRANSS
INSTRUMENT_ID	string	Name of the instrument/sensor	instrument_id	SENSOR_ID
**OPTICAL_DISTORTION_X	matrix	Undistorted to distorted image plane	adapted from odt_x	odt_x	OPTICAL_DIST_COEFF
**OPTICAL_DISTORTION_Y	matrix	Undistorted to distorted image plane	adapted from odt_y	odt_y	OPTICAL_DIST_COEFF
SPACECRAFT_NAME	string	Name of the spacecraft		spacecraft_name	?
STARTING_DETECTOR_SAMPLE	pixels	Sample on detector where data starts	starting_detector_sample	DETECTOR_SAMPLE_ORIGIN
STARTING_DETECTOR_LINE	pixels	Line on detector where data starts		starting_detector_line	DETECTOR_LINE_ORIGIN
TARGET_NAME	string	Name of target body		target_name	?
TRANS_X	matrix	Transformation x coefficients from image plane (mm) to pixel coordinates	transx	?
TRANS_Y	matrix	Transformation y coefficients from image plane (mm) to pixel coordinates	transy	?
SENSOR_LOCATION_X	meters	X location of sensor in body-fixed frame	adapted from x_sensor_origin	x_sensor_location	EPHEM_PTS (?)
SENSOR_LOCATION_Y	meters	Y location of sensor in body-fixed frame	adapted from y_sensor_origin	EPHEM_PTS (?)
SENSOR_LOCATION_Z	meters	Z location of sensor in body-fixed frame	adapted from z_sensor_origin	EPHEM_PTS (?)
**SENSOR_OMEGA	radians	Omega rotation	Where is origin of rotation? Sensor? Spacecraft?	omega	QUATERNIONS
**SENSOR_PHI	radians	Phi rotation	phi	QUATERNIONS
**SENSOR_KAPPA	radians	Kappa rotation	kappa	QUATERNIONS

Needs to be added/fixed:

• INT_TIME (the line rate of the detector map)

• DETECTOR_SAMPLE_SUMMING (or some other way to convey summing)

• ABERR (flag to indicate if we should apply the light time correction or not)

• CENTER_EPHEMERIS_TIME vs. STARTING_EPHEMERIS_TIME (clarify in above table which EPHEMERIS_TIME is)

• STARTING_SAMPLE (Same as above?)

• DETECTOR_LINE_OFFSET

• EPHEM_RATES (or some other way of representing v_x, v_y, v_z)

• Change keywords marked ** above to something nested like: optical_distortion: list of coeffs; some kind of key into LUT and orientation: { type: quaternion or euler_angle value: array of values as appropriate }

• Some way to deal with filters.

• LINE_SUMMING and SAMPLE_SUMMING

• Also, these:

Camera keyword	from	Description / Consequences
NUMBER_OF_EPHEM	linescanner	used as input to lagrangeinterp and on line 127 to set an index. Can we just calculate this?
NUMBER_OF_QUATERNIONS	linescanner	can we just calculate this? Also used as input to lagrangeinterp & to determine "quaternion order"
DT_EPHEM	linescanner	The difference in time between each ephemeris point in time. Used as input to
lagrangeinterp, can we just calculate this?
T0_EPHEM	linescanner	First ephemeris time - center ephemeris time. Used as input to lagrangeinterp and one other place. Can we just calculate this?
DT_QUAT	linescanner	Time spacing of quaternions. Used as input to lagrangeinterp. Can we just calculate this?
T0_QUAT	linescanner	Used in the same way as above.
REFERENCE_HEIGHT	linescanner	reference height is used inside the CSM for determining the intersection of the look vector with the ellipsoid in body fixed coords

Proposed Existing Keywords To Eliminate (rather than consolidate)

Camera keyword	from	Description / Consequences
IKCODE	linescanner	Will need to remove the code to select a distortion equation based on IK code from linescanner. I think this could be handled elsewhere / differently / better than case statements in the code.
ATMREF	linescanner	defined in the ISD, but not used in the plugin or sensor model, so no consequences.

Not sure what to do with these yet

Camera keyword	from	Description / Consequences
SENSOR_TYPE	Name of the sensor (ie. USGSAstroLineScanner)
ISIS_Z_DIRECTION	linescanner	The Z-Direction of the focal plane
PLATFORM	linescanner	flag to indicate if there's a platform or not, we can probably omit this
MOUNTING_ANGLES	linescanner	Rotation angle (sensor <-> spacecraft)
TRI_PARAMETERS	linescanner	array of 18 values, 14 are 0, 15 is the focal length -- does this have to do with the trifocal tensor? (Yes probably and the array is hardcoded for linescanner. Why?
IMAGE_ID	linescanner	?
PLATFORM_ID	linescanner	Not used - eliminate this
TRAJ_ID	linescanner	Not used - eliminate
COLL_ID	linescanner	?

Keywords MdisPlugin Currently Expects in ISD

The table below describes the current keywords that are expected in an ISD that will be used by the MdisPlugin to create an appropriate MdisSensorModel.

Keyword	Units	Description	Required?
boresight	vector	Boresight x,y,z vector	Yes
ccd_center	pixels	Center of the detector	Yes
ephemeris_time	?	Ephemeris time of image	Yes
focal_length	mm	Camera focal length	Yes
focal_length_epsilon	mm	Degree of uncertainty related to focal length	No
ifov	degrees	Instantaneous field of view	?
nlines	pixels	Number of lines in image	Yes
nsamples	pixels	Number of samples in image	Yes
itrans_line	matrix	Transformation matrix from pixels (line) to image plane (y mm)	Yes
itrans_sample	matrix	Transformation matrix from pixels (sample) to image plane (x mm)	Yes
instrument_id	string	Name of the instrument/sensor	Yes
odt_x	matrix	Undistorted to distorted image plane (i.e. distortion model)	No
odt_y	matrix	Undistorted to distorted image plane (i.e. distortion model)	No
original_half_lines	pixels	???	No
original_half_samples	pixels	???	No
pixel_pitch	mm	Size of a pixel (mm/pixel)	No
semi_major_axis	meters	Target ellipsoid's major axis	Yes
semi_minor_axis	meters	Target ellipsoid's minor axis	No
spacecraft_name	string	Name of the spacecraft	Yes
starting_detector_sample	pixels	Sample on detector where data starts	No
starting_detector_line	pixels	Line on detector where data starts	No
target_name	string	Name of target body	No
transx	matrix	Transformation x coefficients from image plane (mm) to pixel coordinates	Yes
transy	matrix	Transformation y coefficients from image plane (mm) to pixel coordinates	Yes
x_sensor_origin	meters	X location of sensor in body-fixed frame	Yes
y_sensor_origin	meters	Y location of sensor in body-fixed frame	Yes
z_sensor_origin	meters	Z location of sensor in body-fixed frame	Yes
omega	radians	Omega rotation angle (pitch) from sensor to body-fixed frame	Yes
phi	radians	Phi rotation angle (roll) from sensor to body-fixed frame	Yes
kappa	radians	Kappa rotation angle (yaw) from sensor to body-fixed frame	Yes

Framing Camera ISD Keywords and attempted match to Linescan

Framing Camera keyword	Corresponding Line Scanner keyword
boresight	?
ccd_center	?
ephemeris_time	REF_DATE_TIME
focal_length	FOCAL
focal_length_epsilon	?
ifov	?
instrument_id	SENSOR_ID
itrans_sample	ITRANSS
itrans_line	ITRANSL
kappa	(uses quaternions)
min_elevation	MIN_VALID_HT
max_elevation	MAX_VALID_HT
model_name	?
nlines	TOTAL_LINES
nsamples	TOTAL_SAMPLES
odt_x	OPTICAL_DIST_COEF
odt_y	OPTICAL_DIST_COEF
omega	(uses quaternions)
original_half_lines	?
original_half_samples	?
phi	(uses quaternions)
pixel_pitch	?
semi_major_axis	SEMI_MAJOR_AXIS
semi_minor_axis	ECCENTRICITY (achieves the same thing)
spacecraft_name	?
starting_detector_line	DETECTOR_LINE_ORIGIN
starting_detector_sample	DETECTOR_SAMPLE_ORIGIN
target_name	?
transx	?
transy	?
x_sensor_origin	?
y_sensor_origin	?
z_sensor_origin	?
x_sensor_velocity	?
y_sensor_velocity	?
z_sensor_velocity	?
x_sun_position	?
y_sun_position	?
z_sun_position	?

Linescan ISD keywords that didn't match framing camera keywords

Camera keyword	Description
SENSOR_TYPE	?
PLATFORM	flag to indicate if there's a platform or not
ABERR	flag to indicate if we should apply the light time correction or not
ATMREF	defined in the ISD, but not used in the plugin or sensor model
INT_TIME	the line rate from the detector map
STARTING_EPHEMERIS_TIME
CENTER_EPHEMERIS_TIME
DETECTOR_SAMPLE_SUMMING
IKCODE	why do we need this?
ISIS_Z_DIRECTION	why do we need this
STARTING_SAMPLE
DETECTOR_LINE_OFFSET
MOUNTING_ANGLES	Rotation angle (sensor <-> spacecraft)
DT_EPHEM	The difference in time between each ephemeris point in time.
T0_EPHEM	First ephemeris time - center ephemeris time (why does this need to be its own keyword?
DT_QUAT
T0_QUAT
NUMBER_OF_EPHEM	why do we need this?
NUMBER_OF_QUATERNIONS	why do we need this?
EPHEM_PTS	(x,y,z) of sensor
EPHEM_RATES	Ephemeris position in meters / second - (v_x, v_y, v_z) of sensor
QUATERNIONS	this model applies the rotation using the quaternions
TRI_PARAMETERS	array of 18 values, 14 are 0, 15 is the focal length -- does this have to do with the trifocal tensor?
REFERENCE_HEIGHT	?
IMAGE_ID	?
PLATFORM_ID	?
TRAJ_ID	?
COLL_ID	?

Line scan state keywords

   STA_SENSOR_MODEL_NAME
   STA_IMAGE_IDENTIFIER
   STA_SENSOR_TYPE
   STA_TOTAL_LINES
   STA_TOTAL_SAMPLES
   STA_OFFSET_LINES
   STA_OFFSET_SAMPLES
   STA_PLATFORM_FLAG
   STA_ABERR_FLAG
   STA_ATMREF_FLAG
   STA_INT_TIME
   STA_STARTING_EPHEMERIS_TIME
   STA_CENTER_EPHEMERIS_TIME
   STA_DETECTOR_SAMPLE_SUMMING
   STA_STARTING_SAMPLE
   STA_IK_CODE
   STA_FOCAL
   STA_ISIS_Z_DIRECTION
   STA_OPTICAL_DIST_COEF
   STA_I_TRANS_S
   STA_I_TRANS_L
   STA_DETECTOR_SAMPLE_ORIGIN
   STA_DETECTOR_LINE_ORIGIN
   STA_DETECTOR_LINE_OFFSET
   STA_MOUNTING_MATRIX
   STA_SEMI_MAJOR_AXIS
   STA_SEMI_MINOR_AXIS
   STA_REFERENCE_DATE_AND_TIME
   STA_PLATFORM_IDENTIFIER
   STA_SENSOR_IDENTIFIER
   STA_TRAJECTORY_IDENTIFIER
   STA_COLLECTION_IDENTIFIER
   STA_REF_ELEVATION
   STA_MIN_ELEVATION
   STA_MAX_ELEVATION
   STA_DT_EPHEM
   STA_T0_EPHEM
   STA_DT_QUAT
   STA_T0_QUAT
   STA_NUM_EPHEM
   STA_NUM_QUATERNIONS
   STA_EPHEM_PTS
   STA_EPHEM_RATES
   STA_QUATERNIONS
   STA_PARAMETER_VALS
   STA_PARAMETER_TYPE
   STA_REFERENCE_POINT_XYZ
   STA_GSD
   STA_FLYING_HEIGHT
   STA_HALF_SWATH
   STA_HALF_TIME
   STA_COVARIANCE
   STA_IMAGE_FLIP_FLAG

Questions

• When should we separate vector component into individual keywords (e.g. SENSOR_OMEGA, SENSOR_PHI, SENSOR_KAPPA) vs. using keywords that store multiple values (e.g. OMEGA_PHI_KAPPA)?

Example Standards

• Prefacing keywords with "STA_" if they are state strings.
• Prefacing parameters with "ISD_" if they are an part of an ISD object.
• All caps snake case.
• Be as verbose as possible; more descriptive.
• Examples:
  • Name of the Sensor Model
    • ISD_SENSOR_MODEL_NAME
  • Number of Lines in the image
    • ISD_NUMBER_OF_LINES
  • Number of Samples in the image
    • ISD_NUMBER_OF_SAMPLES
  • Number of Bands in the image
    • ISD_NUMBER_OF_BANDS
  • Type of Sensor
    • ISD_SENSOR_TYPE

Example Keywords From Existing CSM's (Old?)

Below are examples of keywords used in 4 different files: the Pinhole Sensor Model and its plugin, and the Line Scanner Sensor Model and its plugin.

The number of parameters used vary and the actual names of the parameters are often different for the same information. For example: ISD_NUMBER_OF_LINES -> TOTAL_LINES. Same data, different keyword. Furthermore, there is no standard described in the Community Sensor Model (CSM) Technical Requirements Document.

PinholePluginCSM302.cpp & PinholeSensorModelCSM302.cpp

This is a version 3 sensor. Example of keywords from ISD object.

• ISD_SENSOR_MODEL_NAME
• ISD_LINE_PRINCIPAL_POINT_PIXELS
• ISD_SAMPLE_PRINCIPAL_POINT_PIXELS
• ISD_FOCAL_LENGTH_PIXELS
• ISD_NUMBER_OF_LINES
• ISD_NUMBER_OF_SAMPLES
• ISD_SEMI_MAJOR_AXIS_METERS
• ISD_SEMI_MINOR_AXIS_METERS
• ISD_MIN_ELEVATION_METERS
• ISD_MAX_ELEVATION_METERS
• ISD_X_SENSOR_CURR_METERS
• ISD_Y_SENSOR_CURR_METERS
• ISD_Z_SENSOR_CURR_METERS
• ISD_OMEGA_CURR_RADIANS
• ISD_PHI_CURR_RADIANS
• ISD_KAPPA_CURR_RADIANS
• ISD_CURRENT_PARAMETER_COVARIANCE

UsgsAstroLineScannerPlugin.cpp & UsgsAstroLineScannerSensorModel.cpp

This is a version 2 sensor. Example of keywords from a model state string.

• STA_SENSOR_MODEL_NAME
• STA_IMAGE_IDENTIFIER
• STA_SENSOR_TYPE
• STA_TOTAL_LINES
• STA_TOTAL_SAMPLES
• STA_FULL_LINES
• STA_FULL_SAMPLES
• STA_OFFSET_LINES
• STA_OFFSET_SAMPLES
• STA_PLATFORM_FLAG
• STA_ABERR_FLAG
• STA_ATMREF_FLAG
• STA_INT_TIME
• STA_STARTING_EPHEMERIS_TIME
• STA_CENTER_EPHEMERIS_TIME
• STA_DETECTOR_SAMPLE_SUMMING
• STA_STARTING_SAMPLE
• STA_IK_CODE
• STA_FOCAL
• STA_ISIS_Z_DIRECTION
• STA_OPTICAL_DIST_COEF
• STA_I_TRANS_S
• STA_I_TRANS_L
• STA_DETECTOR_SAMPLE_ORIGIN
• STA_DETECTOR_LINE_ORIGIN
• STA_DETECTOR_LINE_OFFSET
• STA_MOUNTING_MATRIX
• STA_SEMI_MAJOR_AXIS
• STA_SEMI_MINOR_AXIS
• STA_ECC_SQUARE
• STA_REFERENCE_DATE_AND_TIME
• STA_PLATFORM_IDENTIFIER
• STA_SENSOR_IDENTIFIER
• STA_TRAJECTORY_IDENTIFIER
• STA_MIN_ELEVATION
• STA_MAX_ELEVATION
• STA_DT_EPHEM
• STA_T0_EPHEM
• STA_DT_QUAT
• STA_T0_QUAT
• STA_NUM_EPHEM
• STA_NUM_QUATERNIONS
• STA_EPHEM_PTS
• STA_EPHEM_RATES
• STA_QUATERNIONS
• STA_ORIGINAL_PARAMETER
• STA_CURRENT_PARAMETER
• STA_PARAMETER_TYPE
• STA_REFERENCE_POINT_XYZ
• STA_GSD
• STA_FLYING_HEIGHT
• STA_HALF_SWATH
• STA_HALF_TIME
• STA_ORIGINAL_COVARIANCE
• STA_CURRENT_COVARIANCE