Intellectual property rights
Copyright (C) 2017-2020 Michel M. Verstraete.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following three conditions:
1. The above copyright notice and this permission notice shall be included in their entirety in all copies or substantial portions of the Software.
2.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
See: https://opensource.org/licenses/MIT.
3. The current version of this Software is freely available from
Feedback
Please send comments and suggestions to the author at
<EMAIL_ADDRESS>Purpose: This function converts a valid MISR Block number into a properly formatted STRING
, with or without the B
header.
Algorithm: This function converts the input positional parameter misr_block
, provided as an INT
value, into a zero-padded STRING
formatted as Bzzz
(by default), or as zzz
if the optional input keyword parameter NOHEADER
is set.
Syntax: rc = block2str(misr_block, misr_block_str, $
NOHEADER = noheader, DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_block {INT} [I]:
The selected MISR Block number.
misr_block_str {STRING} [O]:
A STRING
representation of the MISR Block with or without the B
header, depending on the input keyword parameter NOHEADER
.
Keyword parameters [Input/Output]:
NOHEADER = noheader{INT} [I] (Default value: 0):
Flag to avoid (1
) or add (0
) the header B
to the ouput positional parameter misr_block_str
.
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call. The output positional parameter misr_block_str
contains the string version of the Block, with or without the B
header.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameter misr_block_str
is set to a null STRING
.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_block
is invalid.
Dependencies:
chk_misr_block.pro
strstr.pro
Remarks:
Note 1: A STRING
value containing only digits for the input positional argument misr_block
is tolerated and results in correct output positional argument misr_block_str
if the input keyword parameter DEBUG
is NOT set, but an error message is issued if this keyword is set, because this situation likely corresponds to an unintentional incorrect user call (see the last example below).
Examples:
IDL> misr_block = 90
IDL> rc = block2str(misr_block, misr_block_str, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ', rc, ', excpt_cond = >' + excpt_cond + '<'
rc = 0, excpt_cond = ><
IDL> PRINT, 'misr_block_str = >' + misr_block_str +'<'
misr_block_str = >B090<
IDL> misr_block = 89
IDL> rc = block2str(misr_block, misr_block_str, $
/NOHEADER, /DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ', rc, ', excpt_cond = >' + excpt_cond + '<'
rc = 0, excpt_cond = ><
IDL> PRINT, 'misr_block_str = >' + misr_block_str +'<'
misr_block_str = >089<
IDL> misr_block = '88'
IDL> rc = block2str(misr_block, misr_block_str)
IDL> PRINT, 'rc = ' + strstr(rc)
rc = 0
IDL> PRINT, 'misr_block_str = >' + misr_block_str + '<'
misr_block_str = >B088<
IDL> misr_block = '87'
IDL> rc = block2str(misr_block, misr_block_str, $
/NOHEADER, /DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ', rc, ' excpt_cond = >' + excpt_cond + '<'
rc = 110 excpt_cond = >Error 110 in BLOCK2STR:
Error 110 in CHK_MISR_BLOCK: Input positional parameter
misr_block must be of numeric type.<
IDL> PRINT, 'misr_block_str = >' + misr_block_str +'<'
misr_block_str = ><
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–05–14: Version 1.2 — Minor update.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function checks the validity of the input positional parameter misr_band
.
Algorithm: This function indicates whether the value of the input positional parameter misr_band
is one of [’Blue’, ’Green’, ’Red’, ’NIR’]
.
Syntax: rc = chk_misr_band(misr_band, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_band {STRING} [I/O]:
The selected MISR spectral Band name.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. Upon exiting this function, the I/O
positional parameter misr_band
is a valid properly capitalized Band name.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The input positional parameter misr_band
is invalid.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_band
is not of type STRING
.
Error 120: Input positional parameter misr_band
is not a scalar.
Error 200: An exception condition occurred in set_cap.pro
.
Error 210: Input positional parameter misr_band
is invalid: must be one of
[’Blue’, ’Green’, ’Red’, ’NIR’]
.
Dependencies:
is_scalar.pro
is_string.pro
set_cap.pro
set_misr_specs.pro
strstr.pro
Remarks:
Note 1: Since the purpose of this function is to check the validity of the input positional parameter misr_band
, all tests are performed irrespective of the setting of the input keyword parameter DEBUG
. The keywords DEBUG
and EXCPT_COND
are included for consistency, and to allow reporting of the exception condition if one is encountered.
Note 2: The input positional parameter misr_band
is properly capitalized on output.
Examples:
IDL> misr_band = 'nir'
IDL> rc = chk_misr_band(misr_band, /DEBUG, $
EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + ', $
excpt_cond = >' + excpt_cond + '<'
rc = 0, excpt_cond = ><
IDL> PRINT, 'misr_band = ', misr_band
misr_band = NIR
IDL> misr_band = 'violet'
IDL> rc = chk_misr_band(misr_band, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + $
', excpt_cond = >' + excpt_cond + '<'
rc = 210, excpt_cond = >Error 210 in CHK_MISR_BAND:
Invalid misr_band name: must be one of ['Blue', 'Green',
'Red', 'NIR'].<
IDL> PRINT, 'misr_band = ', misr_band
misr_band = Violet
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–02–06: Version 2.01 — Minor coding update.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function checks the validity of the input positional parameter misr_block
.
Algorithm: This function indicates whether the value of the input positional parameter misr_block
is within [1, 180]
.
Syntax: rc = chk_misr_block(misr_block, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_block {INT} [I/O]:
The selected MISR Block number.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. Upon exiting this function, the I/O
positional parameter misr_block
is a valid Block number.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The input positional parameter misr_block
is invalid.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_block
is not of type numeric.
Error 120: Input positional parameter misr_block
is not a scalar.
Error 200: Input positional parameter misr_block
is invalid: must be within [1, 180].
Dependencies:
is_numeric.pro
is_scalar.pro
strstr.pro
Remarks:
Note 1: Since the purpose of this function is to check the validity of the input positional parameter misr_block
, all tests are performed irrespective of the setting of the input keyword parameter DEBUG
. The keywords DEBUG
and EXCPT_COND
are included for consistency, and to allow reporting of the exception condition if one is encountered.
Note 2: The input positional parameter misr_block
is recast as type INT
on output.
Examples:
IDL> rc = chk_misr_block(110, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + ', $
excpt_cond = >' + excpt_cond + '<'
rc = 0, excpt_cond = ><
IDL> rc = chk_misr_block(0, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + $
', excpt_cond = >' + excpt_cond + '<'
rc = 200, excpt_cond = >Error 200 in CHK_MISR_BLOCK:
Invalid misr_block number: must be within [1, 180].<
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function checks the validity of the input positional parameter
misr_camera
.
Algorithm: This function indicates whether the value of the input positional parameter misr_camera
is one of [’DF’, ’CF’, ’BF’, ’AF’, ’AN’, ’AA’, ’BA’, ’CA’, ’DA’]
.
Syntax: rc = chk_misr_camera(misr_camera, $
DEBUG = debug, EXCPT_COND = excp_cond)
Positional parameters [Input/Output]:
misr_camera {STRING} [I/O]:
The selected MISR Camera name.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. Upon exiting this function, the I/O
positional parameter misr_camera
is a valid properly capitalized Camera name.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The input positional parameter misr_camera
is invalid.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_camera
is not of type STRING
.
Error 120: Input positional parameter misr_camera
is not a scalar.
Error 200: Input positional parameter misr_camera
is invalid: must be one of [’DF’, ’CF’, ’BF’, ’AF’, ’AN’, ’AA’, ’BA’, ’CA’, ’DA’]
.
Dependencies:
is_scalar.pro
is_string.pro
set_misr_specs.pro
strstr.pro
Remarks:
Note 1: Since the purpose of this function is to check the validity of the input positional parameter misr_camera
, all tests are performed irrespective of the setting of the input keyword parameter DEBUG
. The keywords DEBUG
and EXCPT_COND
are included for consistency, and to allow reporting of the exception condition if one is encountered.
Note 2: The input positional parameter misr_camera
is properly capitalized on output.
Examples:
IDL> misr_camera = 'aa'
IDL> rc = chk_misr_camera(misr_camera, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + $
', excpt_cond = >' + excpt_cond + '<'
rc = 0, excpt_cond = ><
IDL> PRINT, 'misr_camera = ' + misr_camera
misr_camera = AA
IDL> misr_camera = 'xy'
IDL> rc = chk_misr_camera(misr_camera)
IDL> PRINT, 'rc = ' + strstr(rc)
rc = 200
IDL> PRINT, 'misr_camera = ' + misr_camera
misr_camera = XY
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–02–24: Version 2.01 — Minor coding and documentation update.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function checks the validity of the input positional parameter misr_mode
.
Algorithm: This function indicates whether the value of the input positional parameter misr_mode
is one of [’GM’, ’LM’]
.
Syntax: rc = chk_misr_mode, misr_mode, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_mode {STRING} [I/O]:
The selected MISR Mode name.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. Upon exiting this function, the I/O
positional parameter misr_mode
is a valid 2-character upper case Mode name.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The input positional parameter misr_mode
is invalid.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_mode
is not of type STRING
.
Error 120: Input positional parameter misr_mode
is not a scalar.
Error 200: Input positional parameter misr_mode
is invalid.
Dependencies:
is_scalar.pro
is_string.pro
set_misr_specs.pro
strstr.pro
Remarks:
Note 1: Since the purpose of this function is to check the validity of the input positional parameter misr_mode
, all tests are performed irrespective of the setting of the input keyword parameter DEBUG
. The keywords DEBUG
and EXCPT_COND
are included for consistency, and to allow reporting of the exception condition if one is encountered.
Note 2: The input positional parameter misr_mode
is properly capitalized on output.
Examples:
IDL> misr_mode = ' gm '
IDL> rc = chk_misr_mode(misr_mode, /DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + ', excpt_cond = >' + excpt_cond + '<'
rc = 0 and excpt_cond = ><
IDL> PRINT, 'misr_mode = >' + misr_mode + '<'
misr_mode = >GM<
References: None.
Versioning:
2018–05–01: Version 0.9 — Initial release.
2018–05–10: Version 1.0 — Initial public release.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–02–24: Version 2.01 — Documentation update.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function checks the validity of the input positional parameter misr_orbit
.
Algorithm: This function indicates whether the value of the input positional parameter misr_orbit
is within [995L, 200000L]
.
Syntax: rc = chk_misr_orbit(misr_orbit, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_orbit {LONG} [I/O]:
The selected MISR Orbit number.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. Upon exiting this function, the I/O
positional parameter misr_orbit
is a valid Orbit number.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The input positional parameter misr_orbit
is invalid.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_orbit
is not of type numeric.
Error 120: Input positional parameter misr_orbit
is not a scalar.
Error 200: Input positional parameter misr_orbit
is invalid: must be within [995L, 200000L]
.
Dependencies:
is_scalar.pro
is_numeric.pro
strstr.pro
Remarks:
Note 1: Since the purpose of this function is to check the validity of the input positional parameter misr_orbit
, all tests are performed irrespective of the setting of the input keyword parameter DEBUG
. The keywords DEBUG
and EXCPT_COND
are included for consistency, and to allow reporting of the exception condition if one is encountered.
Note 2: The input positional parameter misr_orbit
is recast as type LONG
on output.
Examples:
IDL> rc = chk_misr_orbit(68050L, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + $
', excpt_cond = >' + excpt_cond + '<'
rc = 0, excpt_cond = ><
IDL> rc = chk_misr_orbit(100L, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + $
', excpt_cond = >' + excpt_cond + '<'
rc = 200, excpt_cond = >Error 200 in CHK_MISR_ORBIT:
Invalid misr_orbit number: must be within [995L, 112000L].<
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function checks the validity of the input positional parameter misr_path
.
Algorithm: This function indicates whether the value of the input positional parameter misr_path
is within [1, 233]
.
Syntax: rc = chk_misr_path(misr_path, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_path {INT} [I/O]:
The selected MISR Path number.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. Upon exiting this function, the I/O
positional parameter misr_path
is a valid Path number.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The input positional parameter misr_path
is invalid.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_path
is not of type numeric.
Error 120: Input positional parameter misr_path
is not a scalar.
Error 200: Input positional parameter misr_path
is invalid: must be within [1, 233]
.
Dependencies:
is_scalar.pro
is_numeric.pro
strstr.pro
Remarks:
Note 1: Since the purpose of this function is to check the validity of the input positional parameter misr_path
, all tests are performed irrespective of the setting of the input keyword parameter DEBUG
. The keywords DEBUG
and EXCPT_COND
are included for consistency, and to allow reporting of the exception condition if one is encountered.
Note 2: The input positional parameter misr_path
is recast as type INT
on output.
Examples:
IDL> rc = chk_misr_path(168, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + $
', excpt_cond = >' + excpt_cond + '<'
rc = 0, excpt_cond = ><
IDL> rc = chk_misr_path(368, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + $
', excpt_cond = >' + excpt_cond + '<'
rc = 200, excpt_cond = >Error 200 in CHK_MISR_PATH:
Invalid misr_path number: must be within [1, 233].<
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function checks the validity of the input positional parameter misr_resol
.
Algorithm: This function indicates whether the value of the input positional parameter misr_resol
is either 275
or 1100
.
Syntax: rc = chk_misr_resol(misr_resol, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_resol {INT} [I]:
The selected MISR spatial resolution.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. The input positional parameter misr_resol
is valid.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The input positional parameter misr_resol
is invalid.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_resol
is not of type numeric.
Error 120: Input positional parameter misr_resol
is not a scalar.
Error 200: Input positional parameter misr_resol
is invalid: must be either 275
or 1100
.
Dependencies:
is_numeric.pro
is_scalar.pro
strstr.pro
Remarks:
Note 1: Since the purpose of this function is to check the validity of the input positional parameter misr_resol
, all tests are performed irrespective of the setting of the input keyword parameter DEBUG
. The keywords DEBUG
and EXCPT_COND
are included for consistency, and to allow reporting of the exception condition if one is encountered.
Note 2: The input positional parameter misr_resol
is recast as type INT
on output.
Examples:
IDL> rc = chk_misr_resol(275, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + ', $
excpt_cond = >' + excpt_cond + '<'
rc = 0, excpt_cond = ><
IDL> rc = chk_misr_resol(0, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + $
', excpt_cond = >' + excpt_cond + '<'
rc = 200, excpt_cond = >Error 200 in CHK_MISR_resol:
Invalid misr_resol number: must be either 275 or 1100.<
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–02–28: Version 2.01 — Documentation update.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function returns a structure containing the MISR Orbits belonging to the MISR Paths in the range misr_path_1
to misr_path_2
and between the dates date_1
and date_2
.
Algorithm: This function relies on the MISR Toolkit functions
MTK_PATH_TIMERANGE_TO_ORBITLIST
to deliver the required information.
Syntax: rc = find_orbits_paths_dates (misr_path_1, misr_path_2, $
date_1, date_2, misr_orbits, DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_path_1 {INT} [I] (Default value: None):
The first MISR Path to be considered.
misr_path_2 {INT} [I] (Default value: None):
The last MISR Path to be considered.
date_1 {STRING} [I/O] (Default value: None):
The first date to be considered, formatted as YYYY-MM-DD
, where YYYY
, MM
and DD
are the year, month and day numbers. Upon successful return, this date is formatted as YYYY-MM-DDT00:00:00Z
.
date_2 {STRING} [I/O] (Default value: None):
The last date to be considered, formatted as YYYY-MM-DD
, where YYYY
, MM
and DD
are the year, month and day numbers. Upon successful return, this date is formatted as YYYY-MM-DDT23:59:59Z
.
misr_orbits {STRUCTURE} [O]:
A structure containing the MISR Orbits belonging to each Path within the range [misr_path_1, misr_path_2]
and acquired in the time period [date_1, date_2]
.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call. The output positional parameter misr_orbits
is a stucture containing a list of the MISR Orbits belonging to the Paths in the range misr_path_1
to misr_path_2
and between the dates date_1
and date_2
.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameter misr_orbits
is a stucture that may be empty, incomplete or useless.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Positional parameter misr_path_1
is invalid.
Error 120: Positional parameter misr_path_2
is invalid.
Error 130: Positional parameter date_1
is invalid.
Error 140: Positional parameter date_2
is invalid.
Error 600: An exception condition occurred in the MISR Toolkit routine
MTK_PATH_TIMERANGE_TO_ORBITLIST
.
Dependencies:
chk_ymddate.pro
chk_misr_path.pro
strstr.pro
Remarks:
Note 1: This function returns information on the Orbits that are theoretically available within the specified Paths and between the given dates. Data for those Orbits may not be available at all if there was a technical problem on the platform, or may not be available locally if they have not been explicitly downloaded from the NASA Langley DAAC. Similarly, this function does not report on the eventual availability of partially available Orbits or of subsetted data files.
Note 2: The input argument misr_path_1
is deemed smaller than misr_path_2
; however, if this is not the case, the values of the two Paths are interchanged.
Note 3: Similarly, the input arguments date_1
and date_2
are expected to be given in chronological order; however, if this is not the case, the values of the two dates are interchanged.
Note 4: The positional parameters date_1
and date_2
are both expected to be provided as STRING
s formatted as YYYY-MM-DD
on input, and are reformatted as YYYY-MM-DDT00:00:00Z
and YYYY-MM-DDT23:59:59Z
on output, respectively, as required by the MISR Toolkit.
Note 5: If the value of the input positional parameter date_1
precedes the start of MISR’s operational phase, it is reset to that date.
Examples:
IDL> misr_path_1 = 168
IDL> misr_path_2 = 169
IDL> date_1 = '2010-01-01'
IDL> date_2 = '2010-01-31'
IDL> rc = find_orbits_paths_dates(misr_path_1, misr_path_2, $
date_1, date_2, misr_orbits, /DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ', rc, ' and excpt_cond = >' + excpt_cond + '<'
rc = 0 and excpt_cond = ><
IDL> HELP, misr_orbits
** Structure <30305c78>, 8 tags, length=56, data length=48, refs=1:
TITLE STRING 'MISR_Orbits'
N_MISR_PATHS LONG 2
MISR_PATH_0 INT 168
MISR_PATH_0_NORBITS
LONG 2
MISR_PATH_0_ORBITS
LONG Array[2]
MISR_PATH_1 INT 169
MISR_PATH_1_NORBITS
LONG 2
MISR_PATH_1_ORBITS
LONG Array[2]
IDL> PRINT, misr_orbits
{ MISR_Orbits 2 168 2 53604 53837
169 2 53473 53706}
IDL> PRINT, misr_orbits
{ MISR_Orbits 2 168 53604 53837 169 53473 53706}
References: None.
Versioning:
2017–09–07: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2018–08–21: Version 1.6 — Documentation update.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–04–04: Version 2.01 — Code update: Use the new function chk_ymddate.pro
instead of the old function chk_date_ymd.pro
.
2019–04–04: Version 2.02 — Update the output structure to report on the number of Orbits found in each Path, and to include the list of Orbits as an array rather than individual items.
2019–05–04: Version 2.03 — Update the code to report the specific error message of MTK routines.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
2020–03–23: Version 2.1.1 — Update the code to reset date_1
to the date of the start of MISR operations if it preceded it, and update the documentation.
Purpose: This function extracts metadata on the contents of a MISR or MISR-HR file, based on its specification filespec.
Algorithm: This function first determines the category of the input positional parameters filespec
, and then extracts the relevant metadata items for that file. Output positional parameters that are not relevant or not found in the file name are returned as empty strings.
Syntax: rc = fn2mpocbv(filespec, misr_cat_id, misr_mode_id, $
misr_path_id, misr_orbit_id, misr_camera_id, $
misr_block_id, misr_product_id, misr_version_id, $
misrhr_product_id, misrhr_version_id, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
filespec {STRING} [I]:
An arbitrary character string, typically the filename of a MISR data file or MISR-HR product file.
misr_cat_id {STRING} [O]:
The category of the file: {MISR | MISR-HR | Other}.
misr_mode_id {STRING} [O]:
The Mode identifer: {GM | LM}.
misr_path_id {INTEGER} [O]:
The MISR Path identifer.
misr_orbit_id {LONG} [O]:
The MISR Orbit identifer.
misr_camera_id {STRING} [O]:
The MISR Camera identifer.
misr_block_id {STRING} [O]:
The MISR Block identifer.
misr_product_id {STRING} [O]:
The MISR Product: {BR | L1B2 | RCCM | GMP | L2AERO | L2LAND}.
misr_version_id STRING [O]:
The MISR Version identifer.
misrhr_product_id {STRING} [O]:
The MISR-HR Product: {L1B3 | BRF | RPV | TIP}.
misrhr_version_id STRING [O]:
The MISR-HR Version identifer.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call. The output positional parameters contain the desired information.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameters may be invalid.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter filespec
is not of type STRING
.
Dependencies:
is_string.pro
strstr.pro
Remarks:
Note 1: It is highly recommended to call this function with specific output positional parameter names such as misr_mode_id
, misr_path_id
, etc. (rather than misr_mode
, misr_path
, etc.), to avoid interfering with values possibly already set in the calling routine.
Note 2: If the input positional parameter filespec
contains multiple instances of recognizable string patterns (which should not occur for proper file names), the first one encountered, when scanning filespec
from left to right, sets the definitive value of the output parameter.
Note 3: This function does not check the existence or the readability of the presumed input positional parameter filespec
, so that file does not need to be accessible or even match an actual file: See the last example below.
Note 4: Output positional parameters that are irrelevant for the specified filespec
are assigned an empty string. For instance, the MISR Mode is undefined for MISR-HR product files, and, conversely, the misrhr_version_id
is undefined for MISR data files.
Examples:
IDL> filespec = 'MISR_AM1_GRP_TERRAIN_GM_P168_O005839_DA_F03_0024.hdf'
IDL> rc = fn2mpocbv(filespec, misr_cat_id, misr_mode_id, misr_path_id, $
IDL> misr_orbit_id, misr_camera_id, misr_block_id, misr_product_id, $
IDL> misr_version_id, misrhr_product_id, misrhr_version_id, $
IDL> DEBUG = debug, EXCPT_COND = excpt_cond)
IDL> PRINT, 'misr_cat_id = ' + misr_cat_id
misr_cat_id = MISR
IDL> PRINT, 'misr_mode_id = >' + misr_mode_id + '<'
misr_mode_id = >GM<
IDL> PRINT, 'misr_path_id = >' + misr_path_id + '<'
misr_path_id = >P168<
IDL> PRINT, 'misr_orbit_id = >' + misr_orbit_id + '<'
misr_orbit_id = >O005839<
IDL> PRINT, 'misr_camera_id = >' + misr_camera_id + '<'
misr_camera_id = >DA<
IDL> PRINT, 'misr_block_id = >' + misr_block_id + '<'
misr_block_id = ><
IDL> PRINT, 'misr_product_id = >' + misr_product_id + '<'
misr_product_id = >L1B2<
IDL> PRINT, 'misr_version_id = >' + misr_version_id + '<'
misr_version_id = >F03_0024<
IDL> PRINT, 'misrhr_product_id = >' + misrhr_product_id + '<'
misrhr_product_id = ><
IDL> PRINT, 'misrhr_version_id = >' + misrhr_version_id + '<'
misrhr_version_id = ><
IDL> filespec = 'MISR_HR_TIP_20180310_P168_O096942_B112_V2.00-0_GRN.hdf'
IDL> rc = fn2mpocbv(filespec, misr_cat_id, misr_mode_id, misr_path_id, $
IDL> misr_orbit_id, misr_camera_id, misr_block_id, misr_product_id, $
IDL> misr_version_id, misrhr_product_id, misrhr_version_id, $
IDL> DEBUG = debug, EXCPT_COND = excpt_cond)
IDL> PRINT, 'misr_cat_id = ' + misr_cat_id
misr_cat_id = MISR-HR
IDL> PRINT, 'misr_mode_id = >' + misr_mode_id + '<'
misr_mode_id = ><
IDL> PRINT, 'misr_path_id = >' + misr_path_id + '<'
misr_path_id = >P168<
IDL> PRINT, 'misr_orbit_id = >' + misr_orbit_id + '<'
misr_orbit_id = >O096942<
IDL> PRINT, 'misr_camera_id = >' + misr_camera_id + '<'
misr_camera_id = ><
IDL> PRINT, 'misr_block_id = >' + misr_block_id + '<'
misr_block_id = >B112<
IDL> PRINT, 'misr_product_id = >' + misr_product_id + '<'
misr_product_id = ><
IDL> PRINT, 'misr_version_id = >' + misr_version_id + '<'
misr_version_id = ><
IDL> PRINT, 'misrhr_product_id = >' + misrhr_product_id + '<'
misrhr_product_id = >TIP<
IDL> PRINT, 'misrhr_version_id = >' + misrhr_version_id + '<'
misrhr_version_id = >V2.00-0<
References: None.
Versioning:
2017–09–03: Version 0.9 — Initial release under the name fn2pocv_l1b2_gm.pro
.
2018–01–30: Version 1.0 — Initial public release.
2018–05–07: Version 1.1 — Add the misr_mode
output positional parameter, merge this function with its twin fn2pocv_l1b2_lm.pro
and change the name to
fn2mpocv_l1b2.pro
.
2018–05–18: Version 1.5 — Implement new coding standards.
2018–07–13: Version 1.6 — Modify the code to ensure that the output variable misr_camera
is a scalar string and update the documentation.
2019–02–26: Version 1.7 — Generalize the applicability of this function by extracting the MISR Mode, Path, Orbit, Camera, Block and Version identifiers on the basis of string patterns rather than relying on MISR Toolkit, change its name from fn2mpocv_l1b2.pro
tofn2mpocbv.pro
and move this function to the MISR_Tools repository.
2019–03–01: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
2019–11–06: Version 2.1.1 — Major rewrite of the function to add the output positional parameters misr_cat_id
, misr_product_id
and misrhr_product_id
, recognize more MISR and MISR-HR products, and update the documentation.
Purpose: This function downsizes the high spatial resolution (2048 × 512) input positional parameter inarray
by a factor 4 in each dimension, to the reduced spatial resolution (512 × 128) output array, and returns the latter to the calling routine. The algorithm used depends on the value of input positional parameter innature
.
Algorithm: If the input positional parameter inarray
contains radiance or reflectance data at the full (native) spatial resolution of the MISR instrument, this function simulates the averaging taking place on-board the Terra platform for the 24 non-red data channels of the Global Mode off-nadir cameras. This function can also be used to downsize other arrays, such as RDQI or land cover masks. The downscaling algorithm analyzes successive, non-overlapping subwindows of 4 × 4 pixels in the input array. If this subwindow is identified as
subarray = inarray[ii:ii + 3, jj:jj + 3]
where ii
and jj
are the indices in the input high spatial resolution array, then the corresponding value in the output low spatial resolution array is set as follows, depending on the value of the input positional parameter innature
:
If innature = ’RDQI’
and the input array inarray
is of type BYTE
, the algorithm assumes that it contains RDQI data, where values range within [0B, 3B]
. The RDQI values of the low resolution output array are set to the largest RDQI value found among the 16 samples of each subwindow:
outarray[i, j] = MAX(subarray)
.
If innature = ’Mask’
and the input array inarray
is of type BYTE
, the algorithm assumes that it contains a land, water and cloud mask, where values range within [1B, 254B]
, and where usable values are within [1B, 3B]
. The mask values of the low resolution output array are set to the most frequent usable value found among the 16 samples of each subwindow, unless there are more obscured or edge values than usable values. If two mask categories contain the same largest number of values, the one with the greatest value prevails.
If innature = ’Radrd’
and the input array inarray
is of type UINT
, the algorithm assumes that it contains L1B2 scaled Radiance data, with the RDQI attached, where values range within [0U, 65535U]
, and where usable values are within ]0U, 65507U]
. The scaled Radiance values of the low resolution output array are set to the mean value of the usable (non-zero) scaled Radiances (without the RDQI attached) found among the 16 samples of each subwindow:
outarray[i, j] = MEAN(subarray[good])
, where subarray[good]
stands for the usable values in the subwindow, with the maximum RDQI value attached. If all values of the subwindow are unusable, the low resolution output array value is set to the largest UINT
found within that subwindow.
If innature = ’Rad’
and the input array inarray
is of type FLOAT
, the algorithm assumes that it contains unscaled Radiance data, which can only take on usable values within the range ]0.0, 800.0]
[Wm − 2sr − 1μm − 1]. The unscaled Radiance values of the low resolution output array are set to the mean value of the usable (non-zero) unscaled Radiances found among the 16 samples of each subwindow:
outarray[i, j] = MEAN(subarray[good])
, where subarray[good]
stands for the usable values in the subwindow. If all values of the subwindow are unusable, the low resolution output array value is set to 0.0
.
If innature = ’Brf’
and the input array inarray
is of type FLOAT
, the algorithm assumes that it contains L1B2 Bidirectional reflectance factor (Brf) data, which can only take on usable values within the range ]0.0, 2.0]
. The Brf values of the low resolution output array are set to the mean value of the usable (non-zero) Brfs found among the 16 samples of each subwindow:
outarray[i, j] = MEAN(subarray[good])
, where subarray[good]
stands for the usable values in the subwindow. If all values of the subwindow are unusable, the low resolution output array value is set to 0.0
.
Syntax: outarray = hr2lr(inarray, innature = innature, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
inarray {UINT or FLOAT} [I]:
An array of 2048 × 512 elements, presumably containing data from a MISR L1B2 high spatial resolution field.
innature {STRING} [I] (Default value: None):
Indicator of the nature and expected value range of the input array inarray
:
If innature = ’RDQI’
, usable values of the input array inarray
are expected to range between 0B
and 3B
; the corresponding values of outarray depends on the largest value found in each subwindow.
If innature = ’Mask’
, usable values of the input array inarray
are expected to range between 1B
and 3B
; the corresponding values of outarray depends on the most frequent value found in each subwindow.
If innature = ’Radrd’
, usable values of the input array inarray
are expected to range between 0U
and 65506U
; the corresponding values of outarray depends on the average usable value (after removing the RDQI) found in each subwindow, with the maximum RDQI value mong the usable values.
If innature = ’Rad’
, usable values of the input array inarray
are expected to range between 0.0
and 800.0
; the corresponding values of outarray depends on the average usable value found in each subwindow.
If innature = ’Brf’
, usable values of the input array inarray
are expected to range between 0.0
and 2.0
; the corresponding values of outarray depends on the average usable value found in each subwindow.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: A numeric array, dimensioned 512 × 128, if the processing was successful, or an INT
(error code) otherwise.
Outcome:
If no exception condition has been detected, this function returns a numeric array of the same type as inarray
and dimensioned 512 × 128 elements, where the value of each element is defined as described above. The output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Positional parameter inarray
is not an array of type BYTE
, UINT
, or FLOAT
.
Error 120: Argument innature
is not a scalar of type STRING
.
Error 130: Argument innature
is not recognized: must be RDQI
, Mask
, Rad
, Brf
or Radrd
.
Error 140: Arguments inarray
and innature
are incompatible.
Error 200: Positional parameter inarray
is not properly dimensioned: must be 2048 × 512.
Dependencies:
is_array.pro
is_byte.pro
is_float.pro
is_scalar.pro
is_string.pro
is_uint.pro
strstr.pro
Remarks:
Note 1: This function is specifically designed to handle MISR
L1B2
scaled and unscaled Radiance, as well as Brf data arrays, as well as RDQI and land cover masks.
Note 2: Since this function averages up to 16 original values to estimate 1 low resolution value, it reduces the information content of the original file. Contrast this with the function lr2hr.pro
, which appears to implement the reverse transformation, but only duplicates values. Hence lr2hr(hr2lr(hr_array))
is generally not equivalent to hr_array
.
Examples:
IDL> inarray = FLTARR(2048, 512)
IDL> outarray = hr2lr(inarray, /DEBUG, EXCPT_COND = excpt_cond)
IDL> HELP, outarray
OUTARRAY FLOAT = Array[512, 128]
References: None.
Versioning:
2012–11–22: Version 0.5 — Initial release by Linda Hunt (as downsize_fullres
).
2017–07–17: Version 0.9 — Changed the function name to hr2lr
, removed arguments factor
(fixed, in this context) and maxgood
(not used), added code to handle cases when WHERE
returns -1
), added tests and in-line documentation.
2018–01–30: Version 1.0 — Initial public release.
2018–05–13: Version 1.1 — In-line documentation update.
2018–05–18: Version 1.5 — Implement new coding standards.
2018–12–20: Version 1.6 — Correct a bug in the computation of indices that resulted in incorrect values in the last column and last line of the lower resolution array, add code to adjust processing as a function of the input array data type, and update the documentation.
2019–01–24: Version 1.7 — Update the code to also handle input arrays of type BYTE
.
2019–03–01: Version 2.00 — Update the code to also handle input arrays of type UINT
; systematic update of all routines to implement stricter coding standards and improve documentation.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the use of verbose
and the assignment of numeric return codes), and switch to 3-parts version identifiers.
2019–08–20: Version 2.1.1 — Update the code to handle land, water and cloud BYTE
masks differently from RDQI.
2019–09–27: Version 2.1.2 — Add the input positional parameter innature
and update the code to explicitly process input arrays containing RDQI, Mask, Radrd, Rad or Brf data with specific dedicated algorithms. The code segment dedicated to scaled radiances without the RDQI attached is deleted because it is never used.
Purpose: This function checks that the specified MISR Orbit does belong to the specified Path.
Algorithm: This function relies of the MISR Toolkit to determine the correct Path associated with the given Orbit, and returns 1
if the input positional parameters are consistent, or 0
otherwise.
Syntax: res = is_frompath(misr_path, misr_orbit, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_path {INTEGER} [I]:
The selected MISR Path number.
misr_orbit {LONG} [I]:
The selected MISR Orbit number.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 1
if the input positional parameter misr_orbit
does belong to the specified misr_path
, and 0
otherwise, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call.
If an exception condition has been detected, this function returns -1
, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: The input positional parameter misr_path
is invalid.
Error 120: The input positional parameter misr_orbit
is invalid.
Error 600: An exception condition occurred in the MISR Toolkit routine
MTK_ORBIT_TO_PATH
.
Dependencies:
MISR Toolkit
chk_misr_orbit.pro
chk_misr_path.pro
strstr.pro
Remarks: None.
Examples:
IDL> misr_path = 168
IDL> misr_orbit = 68050L
IDL> debug = 1
IDL> res = is_frompath(misr_path, misr_orbit, $
DEBUG = debug, EXCPT_COND = excpt_cond)
IDL> PRINT, 'res = ', res
res = 1
IDL> misr_orbit = 68051L
IDL> res = is_frompath(misr_path, misr_orbit, $
DEBUG = debug, EXCPT_COND = excpt_cond)
IDL> PRINT, 'res = ', res
res = 0
References: None.
Versioning:
2019–03–17: Version 1.0 — Initial release.
2019–03–20: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–05–04: Version 2.01 — Update the code to report the specific error message of MTK routines.
2019–06–11: Version 2.02 — Update the code to return an error code -1
if an exception condition is encountered in the MISR Toolkit function MTK_ORBIT_TO_PATH
.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function identifies the Block, Line and Sample coordinates of the MISR pixel closest to the specified latitude and longitude, and updates the latitude and longitude to reflect the geographical coordinates of the center of that closest pixel.
Algorithm: This function converts the geographical coordinates (latitude and longitude, in decimal degrees) of a specified location, within a given MISR Path into the Block, Line and Sample coordinates of the center of the closest pixel within that Path, and then computes and returns the latitude and longitude, in decimal degrees, of that center pixel.
Syntax: rc = latlonp2bls(misr_path, misr_resol, latitude, longitude, $
misr_block, misr_line, misr_sample, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_path {INT} [I]:
The selected MISR Path number.
misr_resol {INT} [I]:
The selected MISR spatial resolution (either 275 or 1100 m).
latitude {DOUBLE} [I/O]:
The latitude of a location of interest on input, the latitude of the center of the nearest pixel on output.
longitude {DOUBLE} [I/O]:
The longitude of a location of interest on input, the longitude of the center of the nearest pixel on output.
misr_block {INT} [O]:
The MISR Block number containing that location.
misr_line {INT} [O]:
The line number of the closest pixel to the specified location with the indicated Block.
misr_sample {INT} [O]:
The sample number of the closest pixel to the specified location with the indicated Block.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. The output positional parameters latitude
, longitude
, misr_block
, misr_line
, misr_sample
contain the results generated by this function.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameters may be undefined, incomplete or incorrect.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: The input positional parameter misr_path
is invalid.
Error 120: The input positional parameter misr_resol
is invalid.
Error 130: The input positional parameter latitude
is not a scalar number or lies outside of the range [ − 90.0, + 90.0].
Error 140: The input positional parameter longitude
is not a scalar number or lies outside of the range [ − 180.0, + 180.0].
Error 600: An exception condition occurred in the MISR Toolkit routine
MTK_LATLON_TO_BLS
.
Error 610: An exception condition occurred in the MISR Toolkit routine
MTK_BLS_TO_LATLON
.
Dependencies:
MISR Toolkit
chk_misr_path.pro
chk_misr_resol.pro
is_numeric.pro
is_scalar.pro
strstr.pro
Remarks:
Note 1: The positional parameters latitude
and longitude
are modified on output to reflect the geographical coordinates of the center of the pixel closest to the location specified in input.
Note 2: The finest spatial sampling distance of the MISR instrument is 275 m. Along a meridian, this corresponds to just under 9 arc seconds or 0.0024 arc degree, so geographical coordinates should be specified with at least 5 significant digits to uniquely designate a particular pixel. See the examples below.
Examples:
IDL> misr_path = 169
IDL> misr_resol = 275
IDL> latitude = -27.360
IDL> longitude = 30.130
IDL> rc = latlonp2bls(misr_path, misr_resol, $
latitude, longitude, misr_block, misr_line, misr_sample)
IDL> PRINT, misr_block, misr_line, misr_sample
112 399 1135
IDL> latitude = -27.361
IDL> rc = latlonp2bls(misr_path, misr_resol, $
latitude, longitude, misr_block, misr_line, misr_sample)
IDL> PRINT, misr_block, misr_line, misr_sample
112 399 1135
IDL> latitude = -27.362
IDL> rc = latlonp2bls(misr_path, misr_resol, $
latitude, longitude, misr_block, misr_line, misr_sample)
IDL> PRINT, misr_block, misr_line, misr_sample
112 400 1135
References: None.
Versioning:
2019–06–09: Version 1.0 — Initial public release.
2019–06–10: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function upsizes the low spatial resolution (512 × 128) input array inarray
by a factor 4 in each dimension, to a high spatial resolution (2048 × 512) output array of the same type, and returns the latter to the calling routine.
Algorithm: This function duplicates 16 times the value of each pixel in the low-resolution data set to generate a pseudo high-resolution output array outarray
of the same type as inarray
.
Syntax: outarray = lr2hr(inarray, DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
inarray {Numeric} [I]:
An array of 512 × 128 elements, presumably retrieved from one of the low spatial resolution grids of an L1B2 GRP ToA GM radiance file.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: A numeric array, dimensioned 2048 × 512, of the same type as inarray
, if no exception condition has been detected, or an INT
otherwise.
Outcome:
If no exception condition has been detected, this function returns a numeric array of the same type as inarray
and dimensioned 2048 × 512 elements, where each element of inarray
is duplicated 16 (4 × 4) times in outarray
. The output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call.
If an exception condition has been detected, this function returns an INTEGER
array dimensioned 2048 × 512 elements, where each element is set to -1
, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Positional parameter inarray
is not of a numeric type.
Error 120: Positional parameter inarray
is not properly dimensioned: must be [512 x 128].
Dependencies:
is_numeric.pro
strstr.pro
Remarks:
Note 1: This function is specifically designed to handle MISR
L1B2
files, but is otherwise generic and could be used in other contexts.
Note 2: Since this function duplicates 1 original value to estimate 16 high resolution values, it does not change the information content of the original file. Contrast this with the function hr2lr.pro
, which appears to implement the reverse transformation, but implements loses some information in the process. Hence,
hr2lr(lr2hr(lr_array))
is not equivalent to lr_array
.
Note 3: The MISR-HR processing system does NOT rely on this function to generate the L1B3 product. Instead, this function is used exclusively to facilitate comparisons with high spatial resolution data fileds, or to generate maps of Global Mode MISR data of the same size and visual appearance as those created from Local Mode data or MISR-HR products.
Examples:
IDL> inarray = FLTARR(512, 128)
IDL> outarray = lr2hr(inarray, /DEBUG, EXCPT_COND = excpt_cond)
IDL> HELP, outarray
OUTARRAY FLOAT = Array[2048, 512]
References: None.
Versioning:
2012–11–22: Version 0.5 — Initial release by Linda Hunt (as upsize_array
).
2017–07–17: Version 0.9 — Changed the function name to lr2hr
, removed arguments factor
(fixed, in this context) and maxgood
(not used), added tests and in-line documentation.
2018–01–30: Version 1.0 — Initial public release.
2018–05–13: Version 1.1 — In-line documentation update.
2018–05–18: Version 1.5 — Implement new coding standards.
2019–03–01: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the use of verbose
and the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function computes the latitude and longitude of the center of the MISR or MISR-HR pixel closest to the latitude and longitude of a site of interest, within the specified misr_path
.
Algorithm: This function (1) relies on the MISR Toolkit functions to convert the latitude and longitude of a site of interest, provided as the input positional parameters lat_sit
and lon_sit
(in decimal degrees) into fractional line and sample coordinates of a MISR pixel (resolution of 1100) or of a MISR-HR pixel (resolution of 275), (2) rounds these off, and (3) relies again on the MISR Toolkit functions to compute the latitude and longitude of the center of that pixel. It also reports the distance (on a horizontal plane) between the site of interest and the center of this closest pixel, using the haversine formula and a mean Earth radius of 6,371 km.
Syntax: rc = nearest_pixel(misr_path, lat_sit, lon_sit, $
resolution, misr_block, misr_line, misr_sample, $
lat_pix, lon_pix, distance, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_path {INTEGER} [I]:
The selected MISR Path number.
lat_sit {DOUBLE} [I]:
The latitude of the site of interest, in decimal degrees.
lon_sit {DOUBLE} [I]:
The longitude of the site of interest, in decimal degrees.
resolution {INT} [I]:
The spatial resolution of the remote sensing data product: either 1100 (for the Global Mode non-red spectral channels of the off-nadir MISR cameras) or 275 (for the Global Mode red spectral channels of the off-nadir MISR cameras, or the 4 spectral bands of the nadir camera, or for any data channel in Local Mode, or for any MISR-HR data product).
misr_block {INTEGER} [O]:
The MISR Block number in which the site of interest resides.
misr_line {INTEGER} [O]:
The line number of the pixel in the Block.
misr_sample {INTEGER} [O]:
The sample number of the pixel in the line
.
lat_pix {DOUBLE} [O]:
The latitude of the center of the pixel closest to the site of interest, in decimal degrees, within the range [-90.0, 90.0]
.
lon_pix {DOUBLE} [O]:
The longitude of the center of the pixel closest to the site of interest, in decimal degrees, within the range [-180.0, 180.0]
.
distance {DOUBLE} [O]:
The distance between the site of interest and the center of the closest pixel.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. The coordinates of the center of the closest pixel, as well as the distance between that location and the site of interest are provided in output positional parameters.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The coordinates of the center of the closest pixel, as well as the distance between that location and the site of interest may be undefined, incomplete or incorrect.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: The input positional parameter misr_path
is invalid.
Error 120: The input positional parameter lat_sit
is is not of type FLOAT
or DOUBLE
.
Error 122: The input positional parameter lat_sit
is invalid.
Error 130: The input positional parameter lon_sit
is is not of type FLOAT
or DOUBLE
.
Error 132: The input positional parameter lon_sit
is invalid.
Error 140: The input positional parameter resolution
is is not of type INT
.
Error 142: The input positional parameter resolution
is is invalid.
Error 200: An exception condition occurred in function haversine.pro
.
Error 600: An exception condition occurred in the MISR Toolkit routine
MTK_LATLON_TO_BLS
.
Error 610: An exception condition occurred in the MISR Toolkit routine
MTK_BLS_TO_LATLON
.
Dependencies:
MISR Toolkit
chk_misr_path.pro
haversine.pro
is_double.pro
is_float.pro
is_integer.pro
is_numeric.pro
strstr.pro
Remarks: None.
Examples:
IDL> misr_path = 168
IDL> lat_sit = -27.34439555
IDL> lon_sit = 30.13553714
IDL> lat_sit = -27.34439555D
IDL> lon_sit = 30.13553714D
IDL> resolution = 275
IDL> rc = nearest_pixel(misr_path, lat_sit, lon_sit, resolution, $
misr_block, lat_pix, lon_pix, distance)
IDL> PRINT, 'distance = ' + strstr(distance)
distance = 132.22869
References: None.
Versioning:
2019–04–06: Version 1.0 — Initial release.
2019–04–06: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–04–12: Version 2.01 — Add the misr_line
and misr_sample
output positional parameters.
2019–05–04: Version 2.02 — Update the code to report the specific error message of MTK routines.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function returns the date of acquisition of the specified MISR Orbit, either as a STRING
or as a LONG
Julian day number.
Algorithm: This function relies on MISR Toolkit routine MTK_ORBIT_TO_TIMERANGE
to determine the date on which the specified MISR Orbit was acquired.
Syntax: res = orbit2date(misr_orbit, DATAPOOL = datapool, $
JULIAN = julian, DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_orbit {LONG} [I]:
The selected MISR Orbit number.
Keyword parameters [Input/Output]:
DATAPOOL = datapool {STRING} [I] (Default value: 0):
Flag to request (1
) or decline (0
) returning the output as a STRING
formatted as yyy.mm.dd
instead of the default STRING
formatted as yyyy-mm-dd
.
JULIAN = julian {INT} [I] (Default value: 0):
Flag to request (1
) or decline (0
) returning the output as a LONG
number representing the Julian day number instead of the default STRING
formatted as yyyy-mm-dd
.
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: STRING
OR LONG
.
Outcome:
If no exception condition has been detected and the optional keyword parameter JULIAN
is not invoked, this function returns a STRING
containing the date when the selected MISR Orbit was acquired, formatted as YYYY-MM-DD
. If the optional keyword parameter JULIAN
is invoked, this function returns the Julian day number corresponding to the date of acquisition of that Orbit as a LONG
integer. In both cases, the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call.
If an exception condition has been detected, this function returns a null STRING
, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Positional parameter misr_orbit
is not a scalar.
Error 120: Positional parameter misr_orbit
is invalid.
Error 600: An exception condition was encountered in Mtk routine
MTK_ORBIT_TO_TIMERANGE
.
Dependencies:
MISR Toolkit
chk_misr_orbit.pro
is_scalar.pro
strcat.pro
strstr.pro
Remarks:
Note 1: Argument misr_orbit
cannot be smaller than 995L
(the first Orbit for which MISR acquired data, on February 24, 2000) or larger than 200,000L
(to be acquired on July 25, 2037).
Note 2: This function is unusual in that the value returned may be a STRING
or a LONG
integer number, depending on the setting of the optional input keyword parameter JULIAN
.
Note 3: If the optional input keyword parameters DATAPOOL
and JULIAN
are both set, the former overrides the latter.
Examples:
IDL> res = orbit2date(68050)
IDL> PRINT, res
2012-10-03
IDL> res = orbit2date(68050, /JULIAN)
IDL> PRINT, res
2456204
IDL> res = orbit2date(200000, /DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'res = >' + res + '<, excpt_cond = >' + excpt_cond + '<'
res = ><, excpt_cond = >Error 120 in ORBIT2DATE:
Error 300 in CHK_MISR_ORBIT:
Invalid misr_orbit number: must be within [995L, 112000L].<
References:
Web site: https://www-misr.jpl.nasa.gov/
, select Gallery
and search for First Light
, accessed on 5 Nov 2017.
MISR Toolkit documentation.
Versioning:
2009–11–11: Version 0.5 — Initial release by Linda Hunt (as orbit_to_date
).
2017–07–05: Version 0.9 — Changed function name to orbit2date
, updated the in-line documentation and added argument checking logic.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2018–09–21: Version 1.6 — Add the optional input keyword parameter JULIAN
to return the date as a REAL
Julian day number instead of a STRING
formatted as YYYY-MM-DD
.
2018–12-12: Version 1.7 — Add the optional input keyword parameter DATAPOOL
to return the date as a STRING
formatted as YYYY.MM.DD
instead of YYYY-MM-DD
.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–05–04: Version 2.01 — Update the code to report the specific error message of MTK routines.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function converts a valid MISR Orbit number into a properly formatted STRING
, with or without the O
header.
Algorithm: This function converts the input positional parameter misr_orbit
, provided as an LONG
value, into a zero-padded STRING
formatted as Oyyyyyy
(by default), or as yyyyyy
if the optional input keyword parameter NOHEADER
is set.
Syntax: rc = orbit2str(misr_orbit, misr_orbit_str, $
NOHEADER = noheader, DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_orbit {LONG} [I]:
The selected MISR Orbit number.
misr_orbit_str {STRING} [O]:
A STRING
representation of the MISR Orbit with or without the O
header, depending on the input keyword parameter NOHEADER
.
Keyword parameters [Input/Output]:
NOHEADER = noheader{INT} [I] (Default value: 0):
Flag to avoid (1
) or add (0
) the header O
to the ouput positional parameter misr_orbit_str
.
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call. The output positional parameter misr_orbit_str
contains the string version of the Orbit, with or without the O
header.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameter misr_orbit_str
is set to a null STRING
.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_orbit
is invalid.
Dependencies:
chk_misr_orbit.pro
strstr.pro
Remarks:
Note 1: A STRING
value for the input positional argument misr_orbit
is tolerated and results in correct output positional argument misr_orbit_str
if the input keyword parameter DEBUG
is NOT set, but an error message is issued if this keyword is set, because this situation likely corresponds to an unintentional incorrect user call (see the last example below).
Examples:
IDL> misr_orbit = 68050
IDL> rc = orbit2str(misr_orbit, misr_orbit_s, misr_orbit_str, $
DEBUG = debug, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ', rc, ' and excpt_cond = >' + excpt_cond + '<'
rc = 0 and excpt_cond = ><
IDL> PRINT, 'misr_orbit_s = >' + misr_orbit_s + '<'
misr_orbit_s = >068050<
IDL> PRINT, 'misr_orbit_str = >' + misr_orbit_str + '<'
misr_orbit_str = >O068050<
IDL> misr_orbit = '65487'
IDL> rc = orbit2str(misr_orbit, misr_orbit_s, misr_orbit_str)
IDL> PRINT, 'rc = ' + strstr(rc)
rc = 0
IDL> PRINT, 'misr_orbit_s = >' + misr_orbit_s + '<'
misr_orbit_s = >065487<
IDL> PRINT, 'misr_orbit_str = >' + misr_orbit_str + '<'
misr_orbit_str = >B065487<
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function converts a valid MISR Path number into a properly formatted STRING
, with or without the P
header.
Algorithm: This function converts the input positional parameter misr_path
, provided as an INT
value, into a zero-padded STRING
formatted as Pxxx
(by default), or as xxx
if the optional input keyword parameter NOHEADER
is set.
Syntax: rc = path2str(misr_path, misr_path_str, $
NOHEADER = noheader, DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_path {INT} [I]:
The selected MISR Path number.
misr_path_str {STRING} [O]:
A STRING
representation of the MISR Path with or without the P
header, depending on the input keyword parameter NOHEADER
.
Keyword parameters [Input/Output]:
NOHEADER = noheader{INT} [I] (Default value: 0):
Flag to avoid (1
) or add (0
) the header P
to the ouput positional parameter misr_path_str
.
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call. The output positional parameter misr_path_str
contains the string version of the Path, with or without the P
header.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameter misr_path_str
is set to a null STRING
.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_path
is invalid.
Dependencies:
chk_misr_path.pro
strstr.pro
Remarks:
Note 1: A STRING
value for the input positional argument misr_path
is tolerated and results in correct output positional argument misr_path_str
if the input keyword parameter DEBUG
is NOT set, but an error message is issued if this keyword is set, because this situation likely corresponds to an unintentional incorrect user call (see the last example below).
Examples:
IDL> misr_path = 4
IDL> rc = path2str(misr_path, misr_path_str, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ', rc, ' and excpt_cond = >' + excpt_cond + '<'
rc = 0 and excpt_cond = ><
IDL> PRINT, 'misr_path_str = >' + misr_path_str +'<'
misr_path_str = >P004<
IDL> misr_path = '123'
IDL> rc = path2str(misr_path, misr_path_s, misr_path_str)
IDL> PRINT, 'rc = ' + strstr(rc)
rc = 0
IDL> PRINT, 'misr_path_s = >' + misr_path_s + '<'
misr_path_s = >123<
IDL> PRINT, 'misr_path_str = >' + misr_path_str + '<'
misr_path_str = >P123<
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function computes the geographical coordinates (latitude and longitude) of each of the 4 corners of an individual MISR or MISR-HR pixel.
Algorithm: This function relies on the MISR Toolkit to compute these coordinates.
Syntax: rc = pixel_corners(misr_path, misr_resol, $
misr_block, misr_line, misr_sample, corners, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_path {INT} [I]:
The selected MISR Path number.
misr_resol {INT} [I]:
The selected MISR or MISR-HR spatial resolution: either 275 or 1100 m.
misr_block {INT} [I]:
The selected MISR Block number.
misr_line {INT} [I]:
The selected MISR line number within the Block.
misr_sample {INT} [I]:
The selected MISR sample number within the line.
corners {STRUCTURE} [O]:
The structure containing the latitude and longitude coordinates of the 4 corners of the specified pixel.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. The output structure corners
contains the desured results.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output structure corners
may be undefined, incomplete or incorrect.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: The input positional parameter misr_path
is invalid.
Error 120: The input positional parameter misr_resol
must be either 275 or 1100.
Error 130: The input positional parameter misr_block
is invalid.
Error 150: The input positional parameter misr_sample
is invalid.
Error 600: An exception condition occurred in the MISR Toolkit routine
MTK_BLS_TO_LATLON
while computing the coordinates of the nort-west corner.
Error 610: An exception condition occurred in the MISR Toolkit routine
MTK_BLS_TO_LATLON
while computing the coordinates of the nort-east corner.
Error 620: An exception condition occurred in the MISR Toolkit routine
MTK_BLS_TO_LATLON
while computing the coordinates of the south-west corner.
Error 630: An exception condition occurred in the MISR Toolkit routine
MTK_BLS_TO_LATLON
while computing the coordinates of the south-east corner.
Dependencies:
MISR Toolkit
chk_misr_block.pro
chk_misr_path.pro
chk_misr_resol.pro
strstr.pro
Remarks: None.
Examples:
IDL> misr_path = 168
IDL> misr_resol = 1100
IDL> misr_block = 112
IDL> misr_line = 100
IDL> misr_sample = 240
IDL> debug = 1
IDL> rc = pixel_corners(misr_path, misr_resol, misr_block, $
misr_line, misr_sample, corners, $
DEBUG = debug, EXCPT_COND = excpt_cond)
IDL> PRINT, 'The NW corner is at lat = ', corners.nwc_lat, $
' and lon = ', corners.nwc_lon
The NW corner is at lat = -27.317877 and lon = 31.189198
IDL> PRINT, 'The SE corner is at lat = ', corners.sec_lat, $
' and lon = ', corners.sec_lon
The SE corner is at lat = -27.328760 and lon = 31.199127
References: None.
Versioning:
2019–04–07: Version 1.0 — Initial release.
2019–04–08: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–05–04: Version 2.01 — Update the code to report the specific error message of MTK routines.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function reports on the range of MISR Blocks containing actual data (instead of fill data) in a L1B2 Global or Local Mode file.
Algorithm: This function retrieves the first and last MISR Blocks containing useful data from the input positional parameter Global or Local Mode file l1b2_fspec
, and sets the values of the output positional parameters start_block
and end_block
accordingly.
Syntax: rc = range_misr_blocks(l1b2_fspec, start_block, end_block, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
l1b2_fspec {STRING} [I]:
The specification (path and name) of the L1B2 Global or Local Mode file to inspect.
start_block {INT} [O]:
The nothernmost Block number containing actual data.
end_block {INT} [O]:
The southernmost Block number containing actual data.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call. The output positional parameters start_block
and
end_block
contain the values of the starting and ending Block numbers, respectively.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameters start_block
and end_block
are set to 0
.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter l1b2_fspec
is not found or not readable.
Error 600: An exception condition occurred in the MISR Toolkit routine
MTK_FILEATTR_GET
while recovering start_block
.
Error 610: An exception condition occurred in the MISR Toolkit routine
MTK_FILEATTR_GET
while recovering end_block
.
Dependencies:
MISR Toolkit
strstr.pro
Remarks: None.
Examples:
IDL> l1b2_fspec = '/Volumes/MISR_Data3/P168/L1_GM/' + $
'MISR_AM1_GRP_TERRAIN_GM_P168_O068050_CF_F03_0024.hdf'
IDL> rc = range_misr_blocks(l1b2_fspec, start_block, end_block, $
DEBUG = debug, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ' + strstr(rc) + ', excpt_cond = >' + excpt_cond + '<'
rc = 0, excpt_cond = ><
IDL> PRINT, 'start_block = ' + strstr(start_block)
start_block = 19
IDL> PRINT, 'end_block = ' + strstr(end_block)
end_block = 162
References: None.
Versioning:
2017–12–13: Version 0.9 — Initial release.
2017–12–20: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–05–04: Version 2.01 — Update the code to report the specific error message of MTK routines.
2019–05–17: Version 2.02 — Code simplification (FILE_TEST
).
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function returns a structure containing standard metadata on the MISR instrument, such as the number, names and angles of the 9 cameras; the number, names and positions of the 4 spectral bands; the size of GM data buffers (512 samples by 128 lines, except 2048 samples by 512 lines for all 4 data channels of the nadir pointing camera or the red spectral band on the other 8 off-nadir cameras); and the standard sequence of 36 data channels (from camera DF to camera DA, and from the Blue band to the NIR band within each camera).
Algorithm: This function requires no input; it returns a structure containing metadata on the MISR instrument, as described below.
Syntax: misr_specs = set_misr_specs()
Positional parameters [Input/Output]: None.
Keyword parameters [Input/Output]: None.
Returned value type: STRUCTURE
.
Outcome: This function accepts no positional or keyword parameters and returns a structure containing the following elements:
Title = ’MISR Instrument Metadata’
.
NModes = 2
.
ModeNames = [’GM’, ’LM’]
.
NCameras = 9
.
CameraNames = [’DF’, ’CF’, ’BF’, ’AF’, ’AN’, ’AA’, ’BA’, ’CA’, ’DA’]
.
CameraIDs = [1, 2, 3, 4, 5, 6, 7, 8, 9]
.
CameraAngles = [70.3, 60.2, 45.7, 26.2, 0.1, 26.2, 45.7, 60.2, 70.6]
.
NBands = 4
.
BandNames = [’Blue’, ’Green’, ’Red’, ’NIR’]
.
BandIDs = [0, 1, 2, 3]
.
BandPositions = [446.4, 557.5, 671.7, 866.4]
.
NChannels = 36
.
ChannelOrder = [0, 1, 2, ..., 33, 34, 35]
.
ChannelNames = [’DF_Blue’, ’DF_Green’, ’DF_Red’, ..., $
’DA_Green’, ’DA_Red’, ’DA_NIR’]
.
GMChannelLines = 128 or 512
.
GMChannelSamples = 512 or 2048
.
GMChannelResolution = 1100 or 275
.
LMChannelResolution = 275
.
NL1B2Grids = 6
.
L1B2GridNames = [’BlueBand’, ’GreenBand’, ’RedBand’, $
’NIRBand’, ’BRF Conversion Factors’, ’GeometricParameters’]
Exception conditions: None.
Dependencies: None.
Remarks:
Note 1: In the MISR-HR context, numeric indices referring to Camera, Band and Data Channel arrays are all 0
-based, although Cameras are sometimes numbered from 1
to 9
in the standard MISR context.

MISR Toolkit documentation.
Versioning:
2017–07–08: Version 0.8 — Initial release.
2017–09–03: Version 0.9 — Add CameraIDs
to the output structure.
2017–11–30: Version 1.0 — Initial public release.
2018–05–01: Version 1.1 — Add MISR Mode information.
2018–05–29: Version 1.2 — Add MISR BandIDs information.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–02–24: Version 2.01 — Add the ChannelOrder
array to the output structure misr_specs
, and update the documentation.
2019–02–25: Version 2.02 — Reset the MISR camera indices to range from 0 to 8 instead of 1 to 9.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
2019–09–15: Version 2.1.1 — Change the definition of the output structure element ChannelOrder
from a 1-D array of 36 elements to a 2-D array dimensioned [9, 4]; add the GMChannelLines
and GMChannelSamples
items to the output structure misr_specs
.
2020–04–04: Version 2.1.2 — Add the fields GMChannelResolution
and LMChannelResolution
, both INT
arrays dimensioned [9, 4], to the output structure misr_specs
.
Purpose: This function sets
the STRING
array root_dirs
to contain the default root directories of the 4 main sets of files used by the MISR-HR processing system on the current computer, namely
0: the MISR AGP files,
1: the MISR input data files,
2: the MISR-HR output products, and
3: the outcomes of the MISR-HR post-processing routines.
These array elements may contain wildcard characters to point to one or more disks or directories.
the STRING
array versions
to contain the default version indicators of the various MISR data and MISR-HR product files, namely
0: the version identifier of MISR AGP files,
1: the version identifier of MISR Browse files,
2: the version identifier of MISR L1B2 GRP Terrain projected GM files,
3: the version identifier of MISR L1B2 GRP Terrain projected LM files,
4: the version identifier of MISR Geometric Parameters Product files,
5: the version identifier of MISR L1B2 GRP RCCM files,
6: the version identifier of MISR L2 Aerosol files,
7: the version identifier of MISR L2 Land files,
8: the version identifier of all MISR-HR product files.
Algorithm: This function requires no input; it relies on the function get_host_info.pro
to identify the underlying operating system and retrieve the computer name, and then sets the default paths to the various MISR data and MISR-HR product files. It also sets the default versions of the various MISR data and MISR-HR product files.
Syntax: rc = set_roots_vers(root_dirs, versions, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
root_dirs {STRING array} [O]:
The array containing the default directory addresses of the folders containing MISR data and MISR-HR product files.
versions {STRING array} [O]:
The array containing the default version identifiers of the MISR data and MISR-HR product files.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided in the call. The output positional parameter(s) root_dirs
and versions
are defined an initialized.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameter(s) root_dirs
and versions
may be inexistent, incomplete or incorrect.
Exception conditions:
Error 99: The operating system or the computer is unrecognized, the default values of directory addresses and version numbers are not set.
Error 100: One or more positional parameter(s) are missing.
Dependencies:
get_host_info.pro
strstr.pro
Remarks:
Note 1: If this function does not recognize the operating system or the computer, it returns an error code 99
and an error message. Processing can proceed, provided the directory addresses of all required input and output folders are explicitly specified through input keyword parameters.
Note 2: In other routines of this library, whenever input and output folders are explicitly specified through input keyword parameters, they override the default values set by this function.
Note 3: This function currently recognizes the computers named MicMac
, MicMac2
, pc18
, and 5CG7213978
; other computers can be added by inserting more options in the OS-specific CASE
statements.
Note 4: This setup assumes that the subdirectory structures below those root directories conform to a preset standard; it allows other programs and functions in this system to read from and write to default folders in those predefined locations, without having to specify their locations explicitly.
Note 5: Whenever routines from the MISR Toolkit are used, (1) they require directory addresses to be absolute addresses, i.e., from the computer root directory: Do not use the Linux shortcut ~ to designate the home directory as part of those addresses, and (2) those addresses cannot contain wildcard characters such as ?
or *
.
Note 6: It is the user’s responsibility to correctly set the directory addresses for his or her computer in this function, as the latter does not verify that those folders are readable or writable, since they can be overridden.
Examples:
IDL> = set_roots_dirs(root_dirs, versions, DEBUG = debug, $
EXCPT_COND = excpt_cond)
IDL> FOR i = 0, 3 DO PRINT, 'root_dirs[' + strstr(i) + $
'] = ' + root_dirs[i]
root_dirs[0] = /Users/michel/MISR_HR/Input/AGP/
root_dirs[1] = /Volumes/MISR_Data*/
root_dirs[2] = /Volumes/MISR-HR/
root_dirs[3] = /Users/michel/MISR_HR/Outcomes/
References: None.
Versioning:
2017–07–09: Version 0.9 — Initial release as set_misr_roots.pro
.
2017–11–30: Version 1.0 — Initial public release.
2018–03–25: Version 1.1 — Add computer MicMac2.
2018–04–08: Version 1.2 — Add an array element to point to AGP files, update addresses for pc18 to allow for multiple input and output disks, and rename the function to set_root_dirs.pro
.
2018–05–12: Version 1.3 — Update the documentation to note that the MISR Toolkit requires absolute directory adresses.
2018–06–01: Version 1.5 — Implement new coding standards.
2018–07–02: Version 1.6 — Revamp the logic to correctly detect and initialize computers running under the Microsoft Windows operating system.
2018–07–05: Version 1.7 — Update this routine to rely on the function
get_host_info.pro
.
2018–11–26: Version 1.8 — Remove code to stop processing if the computer is unrecognized.
2019–01–07: Version 1.9 — Upgrade the function to set default version identifiers as well as default paths, now provided as output positional parameters, change the directory address root_dirs[0]
, and rename it set_roots_vers.pro
.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–04–11: Version 2.01 — Add pointers to computer rhapsody
.
2019–05–08: Version 2.02 — Update the defaults version number of MISR-HR products to V2.00-0
.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
2020–01–05: Version 2.1.1 — Update the code to exit gracefully if the operating system and computer names were properly identified but the corresponding values of root_dirs
were not set.
Purpose: This function converts a valid STRING
representation of a MISR Block, with or without the B
header, into its INT
equivalent; it performs the converse operation of function block2str
.
Algorithm: This function checks the validity of the input positional parameter
misr_block_str
, provided as a STRING
value, removes the B
header if it is present, and converts the remaining string to an INT
integer.
Syntax: rc = str2block(misr_block_str, misr_block, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_block_str {STRING} [I]:
The selected STRING
representation of the MISR Block, with or without the B
header.
misr_block {INT} [O]:
The required MISR Block number.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call. The output positional parameter misr_block
contains the Block number.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameter misr_block
is set to 0
.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_block_str
is not of type STRING
.
Error 200: The numerical value of input positional parameter misr_block_str
is invalid.
Dependencies:
chk_misr_block.pro
first_char.pro
is_string.pro
strstr.pro
Remarks:
Note 1: The input positional parameter misr_block_str
is expected to be a STRING
formatted as Bzzz
or bzzz
or zzz
, where zzz
is the numeric value of the MISR Block.
Note 2: The presence of blank spaces before or after the character B
, or after the number zzz
, is tolerated. See the example below.
Examples:
IDL> misr_block_str = ' b 111 '
IDL> rc = str2block(misr_block_str, misr_block, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ', rc, ' and excpt_cond = >' + excpt_cond + '<'
rc = 0 and excpt_cond = ><
IDL> PRINT, 'misr_block = ', misr_block
misr_block = 111
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–02–25: Version 2.01 — Bug fix: Preserve input argument.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function converts a valid STRING
representation of a MISR Orbit, with or without the O
header, into its LONG
equivalent; it performs the converse operation of function orbit2str
.
Algorithm: This function checks the validity of the input positional parameter
misr_orbit_str
, provided as an STRING
value, removes the B
header if it is present, and converts remaining string to a LONG
integer.
Syntax: rc = str2orbit(misr_orbit_str, misr_orbit, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_orbit_str {STRING} [I]:
The selected STRING
representation of the MISR Orbit, with or without the O
header.
misr_orbit {LONG} [O]:
The required MISR Orbit number.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call. The output positional parameter misr_orbit
contains the Orbit number.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameter misr_orbit
is set to 0
.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_orbit_str
is not of type STRING
.
Error 200: The numerical value of input positional parameter misr_orbit_str
is invalid.
Dependencies:
chk_misr_orbit.pro
first_char.pro
is_string.pro
strstr.pro
Remarks:
Note 1: The input positional parameter misr_orbit_str
is expected to be a STRING
formatted as Oyyyyyy
or oyyyyyy
or yyyyyy
, where yyyyyy
is the numeric value of the MISR Orbit.
Note 2: The presence of blank spaces before or after the character O
, or after the number yyyyyy
, is tolerated. See the example below.
Examples:
IDL> misr_orbit_str = ' o 68050 '
IDL> rc = str2orbit(misr_orbit_str, misr_orbit, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ', rc, ' and excpt_cond = >' + excpt_cond + '<'
rc = 0 and excpt_cond = ><
IDL> PRINT, 'misr_orbit = ', misr_orbit
misr_orbit = 68050
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–04–24: Version 1.2 — Improve debugging diagnostic.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–02–25: Version 2.01 — Bug fix: Preserve input argument.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.
Purpose: This function converts a valid STRING
representation of a MISR Path, with or without the P
header, into its INT
equivalent; it performs the converse operation of function path2str
.
Algorithm: This function checks the validity of the input positional parameter
misr_path_str
, provided as an STRING
value, removes the P
header if it is present, and converts remaining string to an INT
integer.
Syntax: rc = str2path(misr_path_str, misr_path, $
DEBUG = debug, EXCPT_COND = excpt_cond)
Positional parameters [Input/Output]:
misr_path_str {STRING} [I]:
The selected STRING
representation of the MISR Path, with or without the P
header.
misr_path {INT} [O]:
The required MISR Path number.
Keyword parameters [Input/Output]:
DEBUG = debug {INT} [I] (Default value: 0):
Flag to activate (1
) or skip (0
) debugging tests.
EXCPT_COND = excpt_cond {STRING} [O] (Default value: ”):
Description of the exception condition if one has been encountered, or a null string otherwise.
Returned value type: INT
.
Outcome:
If no exception condition has been detected, this function returns 0
, and the output keyword parameter excpt_cond
is set to a null string, if the optional input keyword parameter DEBUG
was set and if the optional output keyword parameter EXCPT_COND
was provided in the call. The output positional parameter misr_path
contains the Path number.
If an exception condition has been detected, this function returns a non-zero error code, and the output keyword parameter excpt_cond
contains a message about the exception condition encountered, if the optional input keyword parameter DEBUG
is set and if the optional output keyword parameter EXCPT_COND
is provided. The output positional parameter misr_path
is set to 0
.
Exception conditions:
Error 100: One or more positional parameter(s) are missing.
Error 110: Input positional parameter misr_path_str
is not of type STRING
.
Error 200: The numerical value of input positional parameter misr_path_str
is invalid.
Dependencies:
chk_misr_path.pro
first_char.pro
is_string.pro
strstr.pro
Remarks:
Note 1: The input positional parameter misr_path_str
is expected to be a STRING
formatted as Pxxx
or pxxx
or xxx
, where xxx
is the numeric value of the MISR Path.
Note 2: The presence of blank spaces before or after the character P
, or after the number xxx
, is tolerated. See the example below.
Examples:
IDL> misr_path_str = 'p 170 '
IDL> rc = str2path(misr_path_str, misr_path, $
/DEBUG, EXCPT_COND = excpt_cond)
IDL> PRINT, 'rc = ', rc, ' and excpt_cond = >' + excpt_cond + '<'
rc = 0 and excpt_cond = ><
IDL> PRINT, 'misr_path = ', misr_path
misr_path = 170
References: None.
Versioning:
2017–11–15: Version 0.9 — Initial release.
2017–11–30: Version 1.0 — Initial public release.
2018–01–16: Version 1.1 — Implement optional debugging.
2018–06–01: Version 1.5 — Implement new coding standards.
2019–01–28: Version 2.00 — Systematic update of all routines to implement stricter coding standards and improve documentation.
2019–02–25: Version 2.01 — Bug fix: Preserve input argument.
2019–08–20: Version 2.1.0 — Adopt revised coding and documentation standards (in particular regarding the assignment of numeric return codes), and switch to 3-parts version identifiers.