HSLViewer

Table of contents

• Overview
• Before You Start
• Getting Ready
• Launching the Viewer
• Interface Tour
• Loading and Managing Logs
• Understanding Categories and Blocks
• Controlling Visibility
• Navigating Large Logs
• Working with Pipetting Data
• Reading Metrics and Status Messages
• Keyboard and Mouse Shortcuts
• Example Workflow
• Customization Guide
• Packaging a Standalone Build
• Troubleshooting and Tips
• Project Layout
• Next Steps

Overview

HSLViewer is a desktop application for inspecting Hamilton STAR and STARlet trace logs (.trc, .log, .txt). It classifies each line into high level categories, builds collapsible blocks with inline summaries, and highlights pipetting activity so that you can review runs, diagnose failures, and spot anomalies quickly.

Core capabilities include:

• Automatic detection and color-coding of critical events, user traces, pipetting steps, CO-RE gripper activity, heater/shaker operations, and system chatter.
• Collapsible blocks with inline summaries so you can skim runs without losing context.
• Time-aware selection readouts that show elapsed time with and without error intervals.
• A pipetting analyzer that aligns channel data, highlights labware, and exposes a detailed aspirate/dispense table for any selection.
• Search, go-to-line/time, and a jump palette that let you move through large logs without manual scrolling.
• A ttk-based dark theme tuned for long sessions and consistent across Windows, macOS, and Linux.

Before You Start

Make sure the following prerequisites are in place before launching the viewer.

1. Operating system: Windows 10/11, macOS 12 or newer, or a modern Linux distribution with Tk support. The UI is built on tkinter and tested on 1920x1080 or higher displays.
2. Python: install Python 3.10 or newer from https://www.python.org. During installation on Windows, enable "Add Python to PATH".
3. Tk availability: verify tkinter is present by running python -m tkinter in a terminal. A small window should appear; close it once confirmed. If the command fails, install the tkinter package for your platform (for example sudo apt install python3-tk on Debian/Ubuntu or brew install python-tk on macOS with Homebrew).
4. Log files: ensure you can read the .trc, .log, or .txt files you intend to inspect. Large logs (hundreds of thousands of lines) are supported but benefit from SSD storage.
5. Optional but recommended: a mouse or trackpad for working with the gutter and legend buttons.

Getting Ready

The repository already contains everything required to run the viewer. Use the following steps to prepare the workspace.

1. Download or clone the project.
   • Clone: git clone https://github.com/your-org/HSLViewer.git
   • Download: use GitHub's "Download ZIP", then extract the archive.
2. Open a terminal or PowerShell window and change into the project directory, for example cd HSLViewer.
3. (Optional but encouraged) create a virtual environment so that any future dependencies stay isolated:

   python -m venv .venv
   

   Activate it with:
   • PowerShell: .venv\Scripts\Activate.ps1
   • Command Prompt: .venv\Scripts\activate.bat
   • macOS/Linux: source .venv/bin/activate
4. Upgrade pip inside the environment so builds stay reproducible:

   python -m pip install --upgrade pip
   

5. Install runtime dependencies. The viewer only relies on the Python standard library and tkinter, so there is nothing extra to install. If you plan to package a standalone executable later, install PyInstaller now with pip install pyinstaller.
6. Verify the environment by launching an interactive session with python. Import tkinter (import tkinter) to confirm the module resolves, then exit.

Launching the Viewer

You can run HSLViewer either by double-clicking the launcher script on Windows or from any terminal session.

Option 1: Windows launcher

1. Locate hamilton_log_highlighter.py in the project root.
2. Double-click the file. The script relaunches itself using pythonw.exe so that no console window stays open.
3. If Windows asks how to open .py files, choose "Python" from the list. After the first run the association is remembered.
4. The main window appears sized to 1280x800 by default. Resize it as needed; the current geometry is remembered per log file.

Option 2: Command line (all platforms)

1. Open a terminal with the project directory as the working folder.
2. To start without an initial log, run:

   python hamilton_log_highlighter.py
   

3. To load a log immediately, provide the path as the first argument:

   python hamilton_log_highlighter.py path\to\run.trc
   

   Paths containing spaces must be quoted.
4. Optional flags:
   • --no-relaunch disables the pythonw auto-relaunch (useful on Linux or macOS).
   • --diagnostics keeps console logging visible for debugging crashes.
5. Keep the terminal open while you work if you want to see diagnostic prints (for example when enabling pipette sync tracing).

Opening the bundled sample

If you want a practice file, open examples/HamiltonStar_Vibrant_TBDS_NZPS_12col_8Plates_Ver1.1.0_5c483a5222e0406faa37d634b4187b92_Trace.trc. It highlights all major features.

Interface Tour

The window is divided into five regions. Understanding them up front makes navigation easier.

Command bar (top)

• Primary actions: Open, Reload, Find, Go To, Jump.
• Toggle buttons on the right mirror view options: Compact, Hover, Summaries, Stripes. Each button reflects the current state.
• The More... drop-down exposes secondary commands such as Zoom In/Out, Reset Zoom, Focus-only Summary Colors, Clear Focus, Collapse All, and Expand All.

Main text pane (center-left)

• A fixed-width gutter on the left shows line numbers and displays a + or - button for the block under the mouse.
• The central Text widget renders the log with syntax colors, inline block summaries, selection highlights, and pipetting overlays.
• Vertical and horizontal scrollbars sit on the right and bottom of the pane. Scrolling schedules a throttled gutter redraw so the UI stays fluid on large files.
• The log is read-only to prevent accidental edits. Select text with the mouse or keyboard; copy works via Ctrl+C or Cmd+C.

Legend pane (right)

• Lists every category rule with a color swatch.
• Clicking a category name sets the focus filter, dimming every other category. Right-click the same label to clear focus.
• Each category row has quick action buttons:
  • Collapse this category folds all blocks of that type.
  • Expand this category restores them.
  • Hide this category elides all lines of that type.
  • Show this category makes a hidden category visible again.

Bottom toolbar

• Provides one-click toggles for Collapse All, Expand All, Compact Lines, Color Summaries, Hover Highlight, and Collapsed Stripes.
• These buttons stay visible even when dialogs are open, so you can recover from an aggressive collapse quickly.

Status bar and metrics strip (bottom)

• A metrics label on the right reports total run time and total time excluding critical error intervals whenever the log contains timestamps.
• The status bar beneath it reports contextual hints (for example "Loaded: ...", search results, selection spans, pipetting summaries).
• Messages remain until the next action, so you can glance away without missing the result.

Loading and Managing Logs

1. Click Open on the command bar or press Ctrl+O. Choose a .trc, .log, or .txt file. The viewer reads the file with error replacement so malformed bytes do not abort the load.
2. The window title updates to include the filename, and a status message reports the number of lines loaded.
3. Click Reload or press Ctrl+R to re-read the same file after external edits. The viewer reclassifies and rebuilds blocks each time.
4. The application writes a small JSON state file alongside the log (for example Run.trc.state.json). It remembers zoom level, compact mode, focus category, which categories are hidden, and the window geometry. Delete this file to reset preferences for that log.
5. The last used settings persist per log. When you open a different log the viewer applies the defaults until you adjust them.
6. If the file cannot be read, a dialog explains the error and the status bar reports it. Consult hamilton_log_highlighter.error.log in the project root for stack traces when troubleshooting.

Understanding Categories and Blocks

HSLViewer groups consecutive lines that share a category into a block. Blocks are the unit you collapse, jump to, and summarize.

Classification rules live in hslviewer/rules.py and are applied top-to-bottom. The defaults are:

Category	Color (hex)	Trigger pattern	Typical meaning
Critical	#ff6b6b	Any line containing "Abort", "ERROR", or "Warning" (case-insensitive)	Failures, warnings, aborted steps. These blocks are highlighted in bold and feed timing metrics.
USER Trace	#7ee787	Lines starting with "USER : Trace"	Operator annotations or scripted trace markers. Summaries are suppressed to keep the raw note.
Pipetting	#58a6ff	"Aspirate", "Dispense", "Tip Pick Up", or "Tip Eject"	Liquid handling steps; the pipetting analyzer hooks into these blocks.
CO-RE Gripper	#ffb86c	"CO-RE Grip" phrases	Plate movements handled by the gripper. Summaries list distinct grip events and barcodes.
Heater/Shaker (HSL)	#c678dd	"HSLHamHeaterShakerLib"	Heater or shaker operations with timestamps and USB node information.
System/Other	#8b949e	Fallback for anything else, including firmware chatter and initialization messages	Baseline system events. These often get collapsed when focusing on a particular task.

Block summaries are generated per category:

• Pipetting blocks describe labware usage, well ranges, volume counts, and tip pick-up totals.
• CO-RE gripper blocks list unique moves and barcodes.
• Heater/Shaker blocks summarize operations, USB nodes, and time spans.
• Critical blocks display the generic "Critical event(s)" label so you catch them even when collapsed.

The first line of each block always remains visible. When you collapse a block the summary is inserted inline above that first line, indented so the original content stays aligned.

Controlling Visibility

The viewer offers several mechanisms to control how much of the log you see at once.

• Focus filter: left-click a category name in the legend to emphasize it. All other categories are dimmed. Right-click any legend name or use More... ? Clear Focus to restore the full palette.
• Hide/Show: use the legend buttons to hide a category completely. Hidden categories stay collapsed until you click "Show this category".
• Collapse/Expand: collapse or expand a category from the legend, the bottom toolbar, or the More... menu.
• Collapsed stripes: when enabled (default), a narrow stripe in the gutter shows the color of collapsed sections so you can spot them while scrolling. Toggle with the Stripes button on the command bar or toolbar.
• Compact lines: reduces vertical spacing to fit more content on screen. Toggle using the Compact button on the command bar or bottom toolbar.
• Color summaries: toggles whether inline summaries inherit their category color. Turn it off when you want neutral summaries while still highlighting full blocks.
• Hover highlight: temporarily highlights the line under the mouse and draws the +/- button in the gutter. Disable it from the command bar if you prefer static line numbers.
• Focus-only summary colors: found under More..., this option limits colored inline summaries to the focused category while dimming others.

All visibility settings are persisted in the .state.json file created next to the log.

Navigating Large Logs

Use the following tools to move around quickly.

Basic scrolling and selection

• Scroll with the mouse wheel or trackpad. Holding Shift scrolls horizontally on most platforms.
• Home/End jump to the start or end of the file. Page Up/Page Down move a screen at a time.
• Drag the vertical scrollbar thumb to fast-scroll; collapsed ranges still show their color stripe so you do not miss them.
• Select text with the mouse or by holding Shift and using the arrow keys. The status bar updates with timing information automatically.

Zooming

• Press Ctrl+= (or Ctrl++), Ctrl+-, and Ctrl+0 to zoom in, zoom out, and reset.
• The current font size is saved per log. The gutter font follows the body font so the layout stays tidy.

Collapsing from the gutter

• Hover a line number to reveal a small button. A + indicates a collapsed block, - indicates an expanded block.
• Click the button to flip the block state.
• Collapsing a block reveals its inline summary if one exists; expanding removes the summary and restores the full text.

Search panel

1. Press Ctrl+F or click Find on the command bar.
2. Enter a query. Toggle Match case, Regex, Whole word, and Search summaries as needed.
3. Use Find Next (F3) and Find Prev (Shift+F3) to cycle through results. The current match is highlighted in a darker shade, while other hits stay marked.
4. Find All highlights every match without moving the caret.
5. Mark All adds entire-line marks so you can scan for them. Use Clear Marks to remove the markings.
6. Results honor the current focus and hidden categories to avoid revealing elided blocks unexpectedly.

Go To line or time

1. Press Ctrl+G or choose Go To from the command bar.
2. Specify either an absolute line number or a timestamp.
   • Line numbers are clamped to the file range.
   • Timestamps accept HH:MM:SS(.ms) or YYYY-MM-DD HH:MM:SS(.ms).
3. The viewer builds a per-line time index on load. When you go to a time it selects the best matching line, even within collapsed blocks (they are auto-expanded temporarily).

Jump to block palette

1. Press Ctrl+P or click Jump in the command bar.
2. Start typing to filter by category, summary text, or trace content. The filter is order-sensitive: type pipette a1 to match blocks containing both terms in order.
3. Hit Enter or double-click to jump to the block. The block expands if it was collapsed.

Selecting with the keyboard

• Ctrl+A selects the entire document.
• Hold Shift with arrow keys or Page Up/Page Down to grow the selection.
• The status bar reports selection length, time span, and pipetting summary if applicable.

Marked lines

• After using Mark All, the viewer keeps a set of marked line numbers. They render with a subtle background tint.
• You can mark different queries sequentially; the set is combined until you choose Clear Marks.

Working with Pipetting Data

Pipetting steps receive special handling so you can audit labware movements without parsing raw text.

• Automatic alignment: when a pipetting block loads, the viewer scans channel rows and pads labware, position, and volume columns so they line up. This keeps multi-channel runs readable even with varying field lengths.
• Inline highlighting: while blocks are visible, channel labware names use the pipette_lab_fg color, aspirate positions use pipette_src_fg, dispense positions use pipette_dst_fg, and volumes use pipette_volume_fg. These subtle blues draw attention without overwhelming the primary category color.
• Selection summaries: select one or more lines that include aspirate or dispense completions. The status bar shows a condensed summary such as Pipetting: aspiratex3 from LabA, LabB inc OK (ch1-8); dispensex3 to LabC.
• Detailed panel: press Ctrl+Shift+L to open a dedicated window for the current selection.
  1. Select the block or lines you care about.
  2. Press Ctrl+Shift+L. If no pipetting steps are present the status bar reports "Selection has no pipetting steps" and no window opens.
  3. When a panel appears it lists the selection range and the same condensed summary at the top.
  4. Aspirate and dispense tables render side by side when both exist. Columns cover step number, log line, channel, labware, position, and volume.
  5. Scroll either table; the other stays in sync. Selecting a row in one table selects the matching row in the other thanks to guarded selection synchronization.
  6. Use the mouse wheel inside a table to scroll both simultaneously. Press Esc to close the panel; focus returns to the log automatically.
• Channel increment checks: the summary flags whether wells advance monotonically per channel. inc OK (ch1-8) indicates continuous progress; inc mixed (ok ch1-4; stalled ch5-8) warns about channels that repeat positions.
• Tip counts: summaries include tips xN whenever a tip pick-up event reports the number of channels involved.

If your selection does not include the complete lines for aspirate or dispense events, the analyzer returns "Selection has no pipetting steps"; expand the selection to include them.

Reading Metrics and Status Messages

The viewer surfaces multiple layers of feedback. Keep an eye on them to understand what the tool is doing.

• Metrics label: appears on the bottom toolbar's right side when the log contains timestamps. It shows Total duration (first timestamp to last) and w/o errors, which subtracts the span of blocks flagged as Critical. This helps answer "How much productive time did we get?" at a glance.
• Status messages: the status bar below the toolbar reports the latest action, including load success, search hits, go-to results, selection spans, and pipetting summaries. Messages persist until another action writes a new one.
• Selection span readout: when you highlight text, the status message shows the elapsed time covered by the selection, the same span with critical blocks removed, start and end timestamps when available, and the number of lines selected.
• Pipetting summary snippet: selection summaries described in the previous section append to the same status line. This keeps timing and pipetting context together.
• Hover hints: hovering the gutter reveals the plus/minus button; hovering legend controls changes their background to confirm they are interactive.

Keyboard and Mouse Shortcuts

Action	Shortcut or interaction
Open file dialog	Ctrl+O
Reload current file	Ctrl+R
Zoom in / out / reset	Ctrl+= (or Ctrl++), Ctrl+-, Ctrl+0
Find panel	Ctrl+F
Find next / previous	F3, Shift+F3
Mark all matches	Find panel ? Mark All
Go To line/time	Ctrl+G
Jump to block palette	Ctrl+P
Toggle pipette selection panel	Ctrl+Shift+L
Toggle compact lines	Command bar ? Compact button
Toggle hover highlight	Command bar ? Hover button
Toggle colored summaries	Command bar ? Summaries button
Toggle collapsed stripes	Command bar ? Stripes button
Collapse/expand all blocks	Bottom toolbar buttons or Command bar More... menu
Focus on category	Left-click the category name in the legend
Clear focus	Right-click any category name or More... ? Clear Focus
Hide/Show category	Legend ? "Hide this category" / "Show this category"
Collapse/Expand category	Legend ? "Collapse this category" / "Expand this category"
Collapse/Expand single block	Hover gutter line number and click the +/- button
Copy selection	Ctrl+C (Cmd+C on macOS)
Close pipette panel	Esc

Example Workflow

Follow this guided tour with the bundled sample log to get comfortable with the tooling.

1. Launch the viewer and open the sample file under examples/.
2. Observe the legend. Click Pipetting to focus on pipette activity. All other categories dim.
3. Click Collapse All on the bottom toolbar. Inline summaries appear so you can skim the run.
4. Use the scroll wheel to skim. When a summary looks interesting, hover its first line and click the + button to expand just that block.
5. Press Ctrl+P and type critical to jump to the first critical block. Expand it to see the raw error messages.
6. With the critical block visible, drag to select the affected lines. Read the status bar: you will see the total time span, time excluding other critical blocks, and any pipetting summary if applicable.
7. Move to a pipetting block using the jump palette or the legend controls. Select the entire block and press Ctrl+Shift+L to open the pipette panel. Scroll the aspirate and dispense tables to confirm they stay aligned.
8. Close the panel (Esc), then press Ctrl+F and search for Barcode. Use Mark All to highlight every occurrence, then scroll through the log to see where they cluster.
9. Clear marks, right-click the legend to clear focus, and toggle Compact to see the full log with tighter spacing.
10. When you are done, press Ctrl+R to prove the log reloads cleanly without losing your current zoom and visibility settings.

Customization Guide

You can tailor the viewer to your environment or data conventions.

Adjust category rules

• Edit hslviewer/rules.py.
• Each CategoryRule takes name, pattern, fg color, and optional font_kind ("bold" or "italic").
• Patterns are Python regular expressions compiled with re.IGNORECASE | re.MULTILINE.
• Add new rules above System/Other so they take precedence. For example:

  CategoryRule("Maintenance", r"\bService\b", fg="#ffa657", font_kind="italic")

• Restart the viewer or press Ctrl+R on an open log to apply changes.

Change the dark theme

• Tweak colors in hslviewer/theme.py. Tokens are grouped logically (backgrounds, foregrounds, pipette accents, treeview colors).
• Keep contrast at comfortable levels for readability. The apply_base_style function configures ttk styles globally, so changes propagate automatically.

Modify summaries

• Summaries live in hslviewer/blocks.py.
• Functions like _summ_pipetting and _summ_core can be adjusted to pull out different fields or wording.
• Run python scripts/dev_smoke.py for a quick sanity check after editing; it prints category assignments and summaries for a small sample.

Extend pipetting analysis

• hslviewer/pipetting.py holds the data structures and parsing helpers.
• Add new attributes to PipettingChannel or PipettingEvent if you need more context in the table.
• The UI layer calls _apply_pipette_highlights and _format_sequence_summary; update those if you add new information.

Reset saved state

• Remove the .state.json files next to your logs to reset zoom, focus, and visibility preferences.
• Delete hamilton_log_highlighter.error.log if you want to clear old diagnostic messages.

All source files are typed and organized so that tests can be added later. Follow the standards in AGENTS.md if you plan on contributing code changes.

Packaging a Standalone Build

Produce a self-contained executable when you need to distribute the viewer to teammates who do not have Python installed.

1. Activate your virtual environment (optional but recommended).
2. Install PyInstaller if you have not already: pip install pyinstaller.
3. Run the packaging helper:

   python scripts/package_exe.py --mode onefile --name HSLViewer
   

   • --mode onefile bundles everything into a single executable. Use --mode onedir for a folder distribution.
   • --name controls the executable name.
   • --dist-dir and --build-dir let you override the default dist/ and build/ directories if needed.
4. Add --clean if you want the script to remove previous build artifacts before running.
5. On Windows the resulting executable appears under dist/HSLViewer.exe. On macOS or Linux the filename has no extension; run chmod +x dist/HSLViewer once to mark it executable.
6. Launch the packaged build to confirm it starts and can open logs. The same configuration files and error log are created next to the executable on first run.

Troubleshooting and Tips

• ModuleNotFoundError: No module named '_tkinter': install tkinter for your platform (see the prerequisites) and rerun the script.
• App does not start or immediately closes: check hamilton_log_highlighter.error.log for stack traces. The launcher writes detailed diagnostics there and shows a dialog with the path.
• Log loads but nothing is colored: confirm the file uses newline characters the viewer can parse. Mixed line endings are handled, but extremely large single-line entries can exceed tkinter's rendering limits; split such lines or inspect them in a text editor.
• Performance feels sluggish on huge logs: collapse categories you do not need, disable hover highlight, and keep Compact on. The viewer batches gutter redraws but still incurs work for millions of visible lines.
• Wrong category classification: update the regex in hslviewer/rules.py or add a more specific rule above the generic ones. Reload the log after editing.
• Pipette panel shows blank tables: ensure your selection includes the lines where the instrument reports complete; for each step. Without those markers the analyzer cannot extract channels.
• Need to reset preferences: delete the *.state.json file next to the log and restart the viewer.
• Want console output: launch the app from a terminal with python hamilton_log_highlighter.py --diagnostics so print statements (for example the pipette sync trace) appear in the console.

Project Layout

• hamilton_log_highlighter.py - entry script that bootstraps the tkinter app.
• hslviewer/ - main package.
  • app.py - HighlighterApp class, UI wiring, state handling.
  • blocks.py - classification helpers and block summarizers.
  • rules.py - category definitions.
  • search.py - find panel controller.
  • pipetting.py - selection analyzer and data structures.
  • panels.py - Go To dialog, jump palette, and outline hooks.
  • theme.py - ttk theme tokens and style setup.
  • ui/commandbar.py - command bar widget.
  • state.py - load/save of per-log preferences.
• examples/ - sample trace log for practice.
• scripts/ - helper scripts (package_exe.py, dev_smoke.py).
• todo/ - engineering plans, roadmaps, and progress notes.
• AGENTS.md - engineering approach and collaboration standards.

Next Steps

• Review the documents under todo/ for performance, UI modernization, and rollout plans before making major changes.
• Capture any future feature ideas or bug reports in todo/progress_log.md to keep the history aligned with the guidelines in AGENTS.md.
• If you add new panels or instrumentation, remember the core principles: keep domain logic separate from UI glue, avoid blocking the Tk main loop, and favor small, well-typed functions.

With this guide you should be able to run HSLViewer, explore Hamilton logs confidently, and extend the tooling as your workflows evolve.