Ported/edited ISIS Session Logs Docs (#67) (89b68adc) · Commits · aflab / astrogeology / Asc Public Docs

docs/concepts/isis-fundamentals/session-logs.md

0 → 100644

+105 −0

Original line number	Original line	Diff line number	Diff line
			# Session Logs

			Session logs are a way for users to keep track of work they have done. They record the execution of an ISIS program or sequence of ISIS programs. Info written to the log includes:

			- Program run, with:
			- Version, Date/time run, Computer name, Username, Description
			- Groups for:
			- User input parameters, Results, Accounting, and Errors (if any occur)

			## Format

			Session logs are output in the Parameter Value Language (PVL) format; below are two examples.

			??? abstract "Session Log File recording a High Pass Filter"
			```ini
			Object = Highpass
			IsisVersion = 3.0
			ProgramVersionDate = 2003-05-16
			ExecutionDateTime = 2003-06-25T12:18:45
			ComputerName = char
			UserName = janderso
			ProgramDescription = "Apply a high pass filter to a cube"

			Group = UserParameters
			From = input.cub
			To = output.cub
			Samples = 5
			Lines = 5
			Low = "Use all pixels"
			High = "Use all pixels"
			Minimum = 0
			Propagate = True
			EndGroup

			Group = Results
			PixelsChanged = 1024000
			PercentChanged = 100.0
			EndGroup

			Group = Accounting
			ConnectTime = 0:00:05.2
			CpuTime = 0:00:04.1
			DirectIO = 0
			PageFaults = 2673
			ProcessSwaps = 0
			EndGroup
			EndObject
			```

			??? failure "Session Log File with Error"

			Notice `Group = Error` and the associated error information.
			```ini
			Object = Highpass
			IsisVersion = 3.0
			ProgramVersionDate = 2003-05-16
			ExecutionDateTime = 2003-06-25T12:18:45
			ComputerName = char
			UserName = janderso
			ProgramDescription = "Apply a high pass filter to a cube"

			Group = UserParameters
			From = moon.cub
			To = output.cub
			Samples = 5
			Lines = 5
			Low = "Use all pixels"
			High = "Use all pixels"
			Minimum = 0
			Propagate = True
			EndGroup

			Group = Error
			Program = Highpass
			Class = "I/O ERROR"
			Code = -3
			Message = "Unable to open cube [moon.cub]"
			Source = IsisCube.cpp
			Line = 203
			EndGroup
			EndObject
			```

			## Output

			Output of session logs can be set with [ISIS user preferences](../../concepts/isis-fundamentals/preference-dictionary.md).
			File and Terminal/STDOUT output can both be set On or Off independently.
			If `FileOutput` is `On`, then the `FileName` and `FileAccess` parameters will apply.

			```ini
			# Isis Preferences File
			Group = SessionLog
			TerminalOutput = On \| Off
			FileOutput = On \| Off
			FileName = print.prt
			FileAccess = Append \| Overwrite
			EndGroup
			```

			!!! tip "Terminal Output and Redirection"

			If `TerminalOutput` is `On`, info will be logged to STDOUT (the terminal),
			and standard Unix constructs may be used to redirect the output. For example,

			stats from=moon.cub > stats.log
			No newline at end of file

docs/concepts/isis-fundamentals/spice-format.md

+2 −2

Original line number	Original line	Diff line number	Diff line
	@@ -69,7 +69,7 @@ The InstrumentPointing Table contains information needed to rotate from the J200

	### The InstrumentPointing Table Label		### The InstrumentPointing Table Label

	The InstrumentPointing Table's label contains all of the information described in [ISIS Table Labels](#ISIS-Table-Labels) along some additional keywords. The `TimeDependentFrames` and `ConstantFrames` keywords contain the NAIF codes of the reference frames that are rotated through. These keywords should be read right to left, so the start frame is last in the value array and the final frame is first in the value array. The `ConstantRotation` keyword contains a 3x3 rotation matrix that rotates from the last time dependent frame to the final frame, that is the frames in the `ConstantFrames` keyword. The rotations through the frames in the `TimeDependentFrames` are stored in the binary portion of the InstrumentPointing Table. The `CkTableStartTime` and `CkTableEndTime` keywords contain the valid time range for the rotation information in the InstrumentPointing Table. The `CkTableOriginalSize` keyword describes how many records were in the InstrumentPointing Table prior to any reduction steps. The `FrameTypeCode` keyword describes what type of NAIF SPICE C Kernel the rotation information came from. The `Kernels` keyword contains the SPICE Kernels the rotation information came from.		The InstrumentPointing Table's label contains all of the information described in [ISIS Table Labels](#isis-table-labels) along some additional keywords. The `TimeDependentFrames` and `ConstantFrames` keywords contain the NAIF codes of the reference frames that are rotated through. These keywords should be read right to left, so the start frame is last in the value array and the final frame is first in the value array. The `ConstantRotation` keyword contains a 3x3 rotation matrix that rotates from the last time dependent frame to the final frame, that is the frames in the `ConstantFrames` keyword. The rotations through the frames in the `TimeDependentFrames` are stored in the binary portion of the InstrumentPointing Table. The `CkTableStartTime` and `CkTableEndTime` keywords contain the valid time range for the rotation information in the InstrumentPointing Table. The `CkTableOriginalSize` keyword describes how many records were in the InstrumentPointing Table prior to any reduction steps. The `FrameTypeCode` keyword describes what type of NAIF SPICE C Kernel the rotation information came from. The `Kernels` keyword contains the SPICE Kernels the rotation information came from.

	### The InstrumentPointing Table Binary Data		### The InstrumentPointing Table Binary Data

	@@ -92,7 +92,7 @@ The InstrumentPosition Table contains the position and velocity of the sensor re

	### The InstrumentPosition Table Label		### The InstrumentPosition Table Label

	The InstrumentPosition Table's label contains all of the information described in [ISIS Table Labels](#ISIS-Table-Labels) along some additional keywords.The `SpkTableStartTime` and `SpkTableEndTime` keywords contain the valid time range for the information. The `SpkTableOriginalSize` keyword contains the original number of entries in the InstrumentPosition Table prior to any reduction techniques. The `CacheType` keyword describes what type of information is stored in the binary portion of the Table. The `Kernels` keyword contains the SPICE Kernels the information came from. The possible values of `CacheType` are `Linear`, `HermiteSpline`, and `PolyFunction`.		The InstrumentPosition Table's label contains all of the information described in [ISIS Table Labels](#isis-table-labels) along some additional keywords.The `SpkTableStartTime` and `SpkTableEndTime` keywords contain the valid time range for the information. The `SpkTableOriginalSize` keyword contains the original number of entries in the InstrumentPosition Table prior to any reduction techniques. The `CacheType` keyword describes what type of information is stored in the binary portion of the Table. The `Kernels` keyword contains the SPICE Kernels the information came from. The possible values of `CacheType` are `Linear`, `HermiteSpline`, and `PolyFunction`.


	### The InstrumentPosition Table Binary Data		### The InstrumentPosition Table Binary Data

docs/how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md

+2 −1

Original line number	Original line	Diff line number	Diff line
	@@ -60,6 +60,7 @@ void IsisMain() {
	}		}
	```		```

			<a name="if-your-application-uses-applicationlog"></a>
	??? Warning "If your application uses `Application::Log()`"		??? Warning "If your application uses `Application::Log()`"
	Due to how the Application singleton works, calling `Application::Log()` outside an ISIS application currently causes a segmentation fault. To avoid this, modify the new `appname` function to return a Pvl that contains all the PvlGroups that need to be logged instead of calling `Application::Log()`. Then, change your `main.cpp` to		Due to how the Application singleton works, calling `Application::Log()` outside an ISIS application currently causes a segmentation fault. To avoid this, modify the new `appname` function to return a Pvl that contains all the PvlGroups that need to be logged instead of calling `Application::Log()`. Then, change your `main.cpp` to

	@@ -105,7 +106,7 @@ Once the `appname` function is defined, the `appname(UserInterface &ui)` functio

	Most ISIS3 applications were designed to read their inputs from files and then output their results to the command line and/or files. Unfortunately, gtest is very poorly setup to test against files and the command line. To work around this, it is necessary to remove as much file and command line output from the new `appname` functions as possible. Here are some examples of how outputs can be separated from the application logic:		Most ISIS3 applications were designed to read their inputs from files and then output their results to the command line and/or files. Unfortunately, gtest is very poorly setup to test against files and the command line. To work around this, it is necessary to remove as much file and command line output from the new `appname` functions as possible. Here are some examples of how outputs can be separated from the application logic:

	1. Anything that would be logged to the terminal should be simply returned via the log pointer. This way, it can be programmatically validated in gtest. This in fact already needs to be done because of [issues](#if-your-application-uses-applicationlog) with `Application::Log()`.		1. Anything that would be logged to the terminal should be simply returned via the log pointer. This way, it can be programmatically validated in gtest. This already needs to be done because of [issues](#if-your-application-uses-applicationlog) with `Application::Log()`.
	1. No input filenames should be passed as arguments. All files required by the program should be opened and converted into in-memory objects and then passed to the function. This will help eliminate the need for test data files in many applications. Make sure that for cubes, the appropriate CubeAttributeInput and CubeAttributeOutput values are set!		1. No input filenames should be passed as arguments. All files required by the program should be opened and converted into in-memory objects and then passed to the function. This will help eliminate the need for test data files in many applications. Make sure that for cubes, the appropriate CubeAttributeInput and CubeAttributeOutput values are set!

	### Process, helper functions, and global variables		### Process, helper functions, and global variables

docs/index.md

+4 −4

Original line number	Original line	Diff line number	Diff line
	@@ -16,22 +16,22 @@ These docs use a simple system of defining software documentation in four catego
	{		{
	"title": "Getting Started",		"title": "Getting Started",
	"content": "Step-by-step tutorials for beginners to get started with different aspects of the Astro software portfolio; this is the best place to learn new things as a beginner to some of our software or those unfamiliar with particular parts of the code.",		"content": "Step-by-step tutorials for beginners to get started with different aspects of the Astro software portfolio; this is the best place to learn new things as a beginner to some of our software or those unfamiliar with particular parts of the code.",
	"url" : getting-started/index.html		"url" : getting-started/index.md
	},		},
	{		{
	"title": "How-To Guides",		"title": "How-To Guides",
	"content": "Examples on how-to complete common software tasks; for intermediate to advanced users who want examples on how to accomplish a particular task.",		"content": "Examples on how-to complete common software tasks; for intermediate to advanced users who want examples on how to accomplish a particular task.",
	"url" : how-to-guides/index.html		"url" : how-to-guides/index.md
	},		},
	{		{
	"title": "Concepts",		"title": "Concepts",
	"content": "Write-ups that define and explain concepts that apply to our software; this is for anyone who wants a better understanding of particular higher-level concepts.",		"content": "Write-ups that define and explain concepts that apply to our software; this is for anyone who wants a better understanding of particular higher-level concepts.",
	"url" : concepts/index.html		"url" : concepts/index.md
	},		},
	{		{
	"title": "Software Manuals",		"title": "Software Manuals",
	"content": "Links to in-depth software manuals; contains in-depth references to a particular software project's apps and APIs.",		"content": "Links to in-depth software manuals; contains in-depth references to a particular software project's apps and APIs.",
	"url" : manuals/index.html		"url" : manuals/index.md
	},		},
	]		]

mkdocs.yml

+2 −0

Original line number	Original line	Diff line number	Diff line
	@@ -74,6 +74,7 @@ nav:
	- ISIS Development on the Mac M1 ARM System: how-to-guides/isis-developer-guides/developing-mac-m1-arm-systems.md		- ISIS Development on the Mac M1 ARM System: how-to-guides/isis-developer-guides/developing-mac-m1-arm-systems.md
	- ALE Developer Guides:		- ALE Developer Guides:
	- Creating Ale Drivers: how-to-guides/ale-developer-guides/creating-ale-drivers.md		- Creating Ale Drivers: how-to-guides/ale-developer-guides/creating-ale-drivers.md

	- Concepts:		- Concepts:
	- Home: concepts/index.md		- Home: concepts/index.md
	- Glossary: concepts/glossary.md		- Glossary: concepts/glossary.md
	@@ -92,6 +93,7 @@ nav:
	- Command Line Usage: concepts/isis-fundamentals/command-line-usage.md		- Command Line Usage: concepts/isis-fundamentals/command-line-usage.md
	- Preference Dictionary: concepts/isis-fundamentals/preference-dictionary.md		- Preference Dictionary: concepts/isis-fundamentals/preference-dictionary.md
	- Error Dictionary: concepts/isis-fundamentals/error-dictionary.md		- Error Dictionary: concepts/isis-fundamentals/error-dictionary.md
			- Session Logs: concepts/isis-fundamentals/session-logs.md

	- SPICE:		- SPICE:
	- SPICE Overview: concepts/spice/spice-overview.md		- SPICE Overview: concepts/spice/spice-overview.md