Single Page User Guide

Table of Contents

• 1. Overview
• 2. Install and Run
  • 2.1 Mac OS
  • 2.2 Linux
  • 2.3 Windows
  • 2.4 Supplementary Directory
• 3. Main Window
  • 3.1 Main Window Fields
  • 3.2 Top Menu Bar
• 4. Loading Data
  • 4.1 Open a TID Directory
  • 4.2 Move Between TIDs
  • 4.3 Open Archives
  • 4.4 TID Explorer
  • 4.5 Archive Downloader
  • 4.6 Load a Telemetry Database
  • 4.7 Export Housekeeping Data
• 5. Opening Viewers
  • 5.1 Open Viewer Files
  • 5.2 Viewer Finder
  • 5.3 Make HK Viewer
  • 5.4 Quick Graph
  • 5.5 Set Viewer Refresh Rate
  • 5.6 Clear Viewer Data
• 6. Built-In Viewer Reference
  • 6.1 Science and Radiance Viewers
  • 6.2 Counts and Statistics Viewers
  • 6.3 DDC Viewers
  • 6.4 SSM Viewers
  • 6.5 GSE Viewers
  • 6.6 Packet, Cache, Marker, and Test Viewers
• 7. Common Viewer Controls
• 8. Earth Image Workflow
• 9. Radiance vs. Time Workflow
• 10. Spectral Radiance Workflow
• 11. DDC Raw Workflow
• 12. Saving and Restoring Windows
• 13. Setup Menu
• 14. OCI Settings
• 15. Limits Monitor
• 16. Preferences
• 17. Help
• 18. Troubleshooting
  • 18.1 No Data Appears in a Viewer
  • 18.2 Opening a Telemetry File Fails
  • 18.3 Archive Download Fails
  • 18.4 The UI Is Slow
• 19. Documentation Maintenance Notes

1. Overview

OCI Data Viewer is an application for viewing telemetry data.

It provides the following features:

• View data in real-time. Supports TCP or reading from a file.
• Load archives to post-process data. Supports CCSDS or 699 packets. Additional formats can be supported upon request.
• Generic displays (viewers) of telemetry data:
  • Tabular view
    • Time series plots
    • Packet statistics
    • Event log
    • Data rate
    • Raw packets as hex
• Custom viewers to meet a mission's needs
• Generic and mission specific settings
• Display science data and housekeeping telemetry data together
• Save and load viewer configurations
• Multiple models per mission to support per model configuration
• Supports interpretation of the ITOS and ASIST mnemonic definition formats

The Data Viewer can be run on Windows, Mac OS and Linux.

2. Install and Run

2.1 Mac OS

Mac OS versions are distributed as an Apple Disk Image (dmg). The dmg contains a single .app which can be placed anywhere on your machine and then run. The recommended location is in your Applications directory. The .app contains all required dependencies.

2.2 Linux

The Linux version is distributed as an AppImage which are similar to the Mac OS .apps. All dependencies are contained within the AppImage which makes it easy to distribute and run. The user or sys admin does not need to manage dependencies. The AppImage can also be run from any directory by double clicking it or running it from the terminal:

cd <dir containing appimage>
./<appimage_name>

If you are not able to run it, you may need to make it executable:

cd <dir containing appimage>
chmod +x <appimage_name>

2.3 Windows

The Windows version is distributed as a zip file that contains the executable and all dependencies. The zip file can be extracted to any location. After extraction, the .exe can be run by double clicking on it.

2.4 Supplementary Directory

We use a separate repository for each mission to store released versions of the Data Viewer, config files, and other miscellaneous applications and files. The repository is used for more than just the Data Viewer. For example, on OCI we have an ocigse Git repository that's maintained on the gs490v-gitlab GitLab. We use the version control to provide updates to the workstations and end users.

The instructions to setup the gse repository is mission specific, but can generally be boiled down to:

1. Acquire permissions to access the repository. Usually a NAMS request.
2. Checkout the repository
3. Perform initial one-time setup

If a machine does not have direct access to the repository, the supplementary directory may instead be distributed as a zip file.

The instructions to setup the ocigse directory are maintained in the README.md of the repository: https://gs490v-gitlab.ndc.nasa.gov/497_OCI/OCI_XINA

3. Main Window

The main window displays info about the loaded data. Closing this window will close the application.

3.1 Main Window Fields

Field	Description
Archive	Active telemetry archive file name. Blank when receiving network data.
Full path	Full path to the active telemetry file.
Model	Model associated with the data, or Unknown if unresolved.
meta	Metadata file path. It can identify the file, model, config, and DB patches.
Relative t0	Time origin, in seconds, used for relative telemetry times.
File Size	Current active telemetry file size, formatted as bytes, KB, MB, or GB.
Pkt Count	Number of packets currently loaded in the telemetry cache.
Created	Generated timestamp for the telemetry data, or Unknown if unavailable.
tmdb(s)	Loaded telemetry databases and patches used to decode, scale, and name fields.
archive load	Time required to parse and load the archive, in milliseconds.
db load	Time required to load database files and patches, in milliseconds.
viewers load	Time required to reload open viewers after data and caches are ready.

3.2 Top Menu Bar

The top menu bar provides access to data-loading commands, viewer windows, application setup, and help resources.

• File
  • Opens telemetry data and data-management tools.
  • Use this menu to open a TID directory, open one or more archives, move to the next or previous TID, show the TID Explorer, show the Archive Downloader, load a telemetry database, or export housekeeping data.
• Data Viewers
  • Opens and manages viewer windows.
  • Use this menu to open viewer definition files, search with Viewer Finder, create an HK viewer, build a Quick Graph, set the viewer refresh rate, clear all viewer data, or open built-in OCI viewer windows.
• Setup
  • Controls saved layouts, chart behavior, live-data tools, playback tools, and OCI processing settings.
  • Use this menu to save or restore window configurations, enable or disable chart animations, choose plot series colors, open the FEDS Client or FEDS Control windows, open Local Playback, or edit OCI Settings.
• Limits
  • Opens the Limits Monitor when limit monitoring is enabled in settings.
  • This menu is hidden when the limit monitor is disabled.
• Options
  • Opens the application Preferences dialog for the active ground software configuration group.
  • Use this menu to review or edit environment-level paths and settings.
• Help
  • Shows application information and support resources.
  • Use this menu to open the About dialog, view What's New release notes, or find the configured issue-reporting contact.

4. Loading Data

4.1 Open a TID Directory

Use File > Open TID... or Ctrl+O.

Select a TID directory. The selected directory will be searched for a telemetry file.

4.2 Move Between TIDs

Use:

• File > Open next TID... or Ctrl+Right
• File > Open prev TID... or Ctrl+Left

These actions look for adjacent TID directories beside the current TID directory. They only work after a TID has already been opened and when neighboring directories follow the expected naming convention.

4.3 Open Archives

Use File > Open Archives....

Select one or more archive files to load.

4.4 TID Explorer

Use File > TID Explorer or Ctrl+E.

The TID Explorer opens a browser rooted at the configured data root. Click a test directory or archive in the explorer to open it.

The data root comes from the active ground software configuration group. For OCI, this is the data_root setting in the active Config699 group. Open Options > Preferences to review or change the configured data root. The same data root is also used as the default starting location for File > Open TID... and as the default save location for archive downloads.

When a telemetry metadata file identifies a different model or configuration group, OCI Data Viewer can switch to that group while opening the data. In that case, future data-root lookups use the newly active group.

4.5 Archive Downloader

Use File > Archive Downloader or Ctrl+D.

The downloader can find and download daily archives. Select:

• Date
• Save to
• Model

Then click Find Archives. Matching archives appear in a table with start and end times. Click Download on the desired row to download that archive. The downloader checks available disk space before starting and shows progress in the table.

The downloader supports these model choices:

• PACE-OCI (Science + HK)
• PACE-spacecraft (HK)

4.6 Load a Telemetry Database

Use File > Load database....

Select a telemetry database file. The loaded database patch list and load time are shown on the main splash page. If loading fails, the splash page records the failure message.

4.7 Export Housekeeping Data

Use File > Export HK Data....

This opens the HK export dialog for the currently loaded telemetry file. Open telemetry data before using this workflow.

5. Opening Viewers

The Data Viewers menu manages all viewer windows.

5.1 Open Viewer Files

Use Data Viewers > Open....

Select one or more viewer definition files from the configured viewers directory. Supported file types are:

• .hk
• .sc
• .rt
• .grf

5.2 Viewer Finder

Use Data Viewers > Viewer Finder or Ctrl+N.

Viewer Finder searches the configured viewer directory and opens the selected viewer.

5.3 Make HK Viewer

Use Data Viewers > Make HK Viewer or Ctrl+M.

This opens the HK viewer builder for creating or editing housekeeping viewer definitions.

5.4 Quick Graph

Use Data Viewers > Quick graph... or Ctrl+G.

Select one or more housekeeping items and a time mode. OCI Data Viewer creates a temporary graph viewer with the selected traces.

5.5 Set Viewer Refresh Rate

Use Data Viewers > Set Viewer Refresh Rate.

Available refresh rates:

• Disabled
• 1 Hz
• 2 Hz
• 10 Hz
• Custom...

Disabling refresh stops live updates. A higher refresh rate updates viewers more often but can increase CPU and UI load.

5.6 Clear Viewer Data

Use Data Viewers > Clear all data.

This clears cached telemetry, science cache data, marker cache data, and viewer data, then resumes updates if viewer refreshing is enabled.

6. Built-In Viewer Reference

The built-in viewers are listed directly in the Data Viewers menu. Use this section as the guide's viewer index.

6.1 Science and Radiance Viewers

Viewer	Use
Earth Image	Build scan-line image products and export current or RGB images.
Image	View OCI image-style science data.
Radiance vs. Time	Plot radiance over time by CCD, wavelength, HAM side, and scan line.
Radiance vs. Time Summed	Plot summed radiance over time.
Sci Pixel 3D	Inspect science pixel data in a 3D visualization.
Spectral Radiance	View spectral radiance with optional FPA and SDA model overlays.
Spectral Radiance Stats	View statistical spectral radiance summaries.
Spectral Waterfall	View spectral data as a waterfall plot.

6.2 Counts and Statistics Viewers

Viewer	Use
Counts Per Pixel vs. Time	Plot count data per pixel over time.
Counts Per Tap (and SSM CH)	Plot counts per tap and SSM channel data.
Stats Per Pixel vs. Time	Plot selected pixel statistics over time.
Stats Per Tap vs. Time	Plot selected tap statistics over time.

6.3 DDC Viewers

Viewer	Use
DDC Func Verification	Verify DDC functional behavior.
DDC Raw	Inspect DDC reset, video, CDS, ADC, tap, and CDS SD charts.
DDC Scope Mode	Inspect DDC scope-mode captures.
DDC Sci Packet	Inspect DDC science packets.

6.4 SSM Viewers

Viewer	Use
SSM Ch Stats Table	View SSM channel statistics in table form.
SSM Ch Stats vs. Time	Plot SSM channel statistics over time.
SSM Func Verification	Verify SSM functional behavior.
SSM Line Check	Check SSM line consistency.
SSM Sci Packet	Inspect SSM science packets.
SSM Trend	Trend SSM data over time.

6.5 GSE Viewers

Viewer	Use
GSE FW Det vs. Time	Plot GSE filter wheel detector data over time.
GSE Radiance vs. Time	Plot GSE radiance data over time.
GSE Spectral Radiance	View GSE spectral radiance data.
GSE Spectral Waterfall	View GSE spectral data as a waterfall plot.

6.6 Packet, Cache, Marker, and Test Viewers

Viewer	Use
DAUC Dwell vs Time	View DAUC dwell values over time.
Markers	View OCI markers and marker-derived context.
PRBS 9	Inspect PRBS9 verification statistics.
Sci Cache	Inspect the science cache state.

7. Common Viewer Controls

Viewer controls vary by data type, but many viewers use common patterns:

• Reload updates the viewer using the current settings.
• Go Live moves the chart to new data.
• Pause stops live chart following.
• Control Table opens a selector for choosing scan-line related settings from control-table data.
• y auto or Y Axis Auto Scale lets the chart scale the Y axis from displayed data.
• Time Window controls how much recent data is shown on time plots.
• Line Avg and Scan Avg control spatial or scan averaging where supported.
• Max Points Per Series limits the amount of plotted data for performance.

8. Earth Image Workflow

1. Open telemetry data with File > Open TID... or File > Open Archives....
2. Open Data Viewers > Earth Image.
3. Choose dark subtraction, HAM side, line start, and line end.
4. Select wavelengths to sum.
5. Set the scan window.
6. Click Reload.
7. Adjust the color scale manually or enable Auto.
8. Use Export Current Image to save the current image.
9. Use Export RGB Images to export red, green, and blue image outputs.

9. Radiance vs. Time Workflow

1. Open telemetry data.
2. Open Data Viewers > Radiance vs. Time.
3. Set CCD ID, wavelength, dark mode, HAM side, scan line, line average, and scan average.
4. Click Add to create a series.
5. Repeat for additional series.
6. Use Reload All Changed Series after modifying existing series settings.
7. Use Copy To All Series when selected settings should be copied from one series to every series.
8. Adjust Time Window, y auto, normalized, and Max Points Per Series as needed.

10. Spectral Radiance Workflow

1. Open telemetry data.
2. Open Data Viewers > Spectral Radiance.
3. Choose dark mode, HAM side, scan line, line average, and scan average.
4. Click Control Table if you want to select a scan line from control-table data.
5. Click Reload.
6. Adjust Y-axis mode and auto-scaling.
7. Enable FPA Model or SDA Model overlays when requirements/model comparison is needed.

11. DDC Raw Workflow

1. Open telemetry data.
2. Open Data Viewers > DDC Raw.
3. Select the CCD/DDC ID.
4. Select export format and whether to fix CDS order.
5. Choose which charts are visible.
6. Adjust line window, Y-axis auto scale, synchronized axes, region display, and chart height.
7. Use Export ADC Charts or Export CDS SD Charts when a chart export is needed.

12. Saving and Restoring Windows

Use the Setup menu to preserve a working layout:

• Setup > Save Windows or Ctrl+S
• Setup > Restore Windows or Ctrl+R

When closing the application, OCI Data Viewer may prompt you to save the current window configuration before quitting.

13. Setup Menu

The Setup menu contains application-level tools and display settings:

• Save Windows
• Restore Windows
• Chart animations
• Select Series Colors
• FEDS Client
• FEDS Control
• Local Playback
• OCI Settings

Use Chart animations to enable or disable chart animation globally. Disable animations if chart motion makes analysis harder or if the UI is under load.

Use Select Series Colors to customize the color sequence used for plotted series.

14. OCI Settings

Use Setup > OCI Settings.

These settings affect science processing and can force all viewers to reload. Review changes before saving.

Settings include:

• Grande correction enablement and correction/uncertainty files.
• Dark collect shifting.
• Handling of scans with missing lines.
• Ancillary data handling.
• Whether scans with no lines are added.
• DDC science packet CRC checking.
• MCE HK scan buffer size.
• SWIR science product offsets file.
• SWIR high-speed ADC channel offsets file.
• SWIR single-image ADC channel offsets file.
• SWIR channel mapping file.
• Expected SSM shorted-input counts and standard deviation ranges.
• Dropping invalid SSM data or SSM reset data.
• SSM line-delay handling.
• CCD start-delay handling.
• Number of dark collect scan lines to skip.
• ADC latency mapping.
• HK stale timeout.

15. Limits Monitor

If the limits monitor is enabled in settings, the Limits menu appears. Use Limits > Limits Monitor or Ctrl+L to bring the monitor to the front.

16. Preferences

Use Options > Preferences.

Preferences open the ground software configuration dialog for the active configuration group. Use this to review environment-level settings such as configured data, database, and viewer directories.

17. Help

The Help menu contains:

• About
• What's New...
• Report an issue...

Use What's New... to read the built-in release notes. Use Report an issue... to find the configured developer contact for bugs and suggestions.

18. Troubleshooting

18.1 No Data Appears in a Viewer

Check:

• A TID or archive is open.
• The loaded telemetry database matches the telemetry data.
• Required decoder and transfer-function plugins loaded successfully.
• The viewer scan/time/window settings include the data of interest.
• Viewer refresh is enabled, or click Reload in the viewer.

18.2 Opening a Telemetry File Fails

Check:

• The selected directory contains a supported telemetry file.
• The telemetry database can decode the packets in the file.
• Required metadata is present.
• The file is readable by the current user.

18.3 Archive Download Fails

Check:

• The selected date and model have available archive entries.
• The destination directory exists or can be created.
• At least 10 GB of disk space remains after the estimated download.
• Network access to the archive source is available.

18.4 The UI Is Slow

Try:

• Lowering Data Viewers > Set Viewer Refresh Rate.
• Disabling Setup > Chart animations.
• Reducing Max Points Per Series in time-based viewers.
• Closing viewers that are not needed.
• Clearing old viewer data with Data Viewers > Clear all data.

19. Documentation Maintenance Notes

When adding or changing a viewer:

1. Update the Built-In Viewer Reference table.
2. Add or revise a workflow section if the viewer has unique user actions.
3. Update menu descriptions if the menu text or shortcut changes.
4. Add screenshots after UI text stabilizes.
5. Update the table of contents and section numbers when sections are added, removed, renamed, or moved.