Skip to content

User Guide

Jump to bottom
Cole Gentry edited this page Jan 1, 2026 · 4 revisions

User Guide

This comprehensive guide covers all features and functionality of UltraLog v2.0.

Table of Contents

Interface Overview

Main Window Layout

UltraLog v2.0 features a redesigned VS Code-style interface with an activity bar on the far left side:

┌─────────────────────────────────────────────────────────────────┐
│  [Tab 1] [Tab 2] [Tab 3]                            [Tab Bar]   │
├─┬────────┬──────────────────────────────────┬───────────────────┤
│A│        │                                  │                   │
│C│ PANEL  │                                  │                   │
│T│        │                                  │                   │
│I│ FILES  │          CHART AREA              │                   │
│V│   OR   │                                  │                   │
│I│CHANNELS│                                  │                   │
│T│   OR   │                                  │                   │
│Y│ TOOLS  │                                  │                   │
│ │   OR   │                                  │                   │
│B│SETTINGS│                                  │                   │
│A│        │                                  │                   │
│R│        │                                  │                   │
├─┴────────┴──────────────────────────────────┴───────────────────┤
│  [▶] [⏸] [⏹]  [1.0x ▼]  ═══════○═══════════  00:15.234 / 02:30  │
└─────────────────────────────────────────────────────────────────┘
                          [Timeline Controls]

Activity Bar (Left Edge)

The activity bar contains four icons that switch between different panels:

Icon Panel Purpose
📁 Folder Files File list, drop zone, loaded files management
📋 List Channels Channel selection, search, selected channel cards
🔧 Wrench Tools Scatter plot, histogram, and analysis tools
⚙️ Gear Settings All application settings

Click an icon to open that panel. Click it again to close the panel.

Tab Bar (Top)

  • Switch between multiple open log files
  • Each tab shows the filename
  • Close tabs with the × button
  • Each tab maintains its own channel selections and view state

Chart Area (Center)

  • Main data visualization area
  • Displays selected channels as time-series graphs
  • Shows cursor with current time position
  • Legend with channel info and values

Timeline Controls (Bottom)

  • Playback buttons (Play, Pause, Stop)
  • Speed selector
  • Timeline scrubber
  • Time display and manual input

Loading Files

Supported File Types

Extension Format ECU System
.csv CSV text files Haltech, ECUMaster, RomRaider
.log Standard log files Various
.txt Text-based log files Various
.mlg MegaLogViewer binary Speeduino/rusEFI
.xrk, .drk AiM binary format AiM data loggers
.llg Link log format Link ECU
.lg1, .lg2 Emerald binary format Emerald ECU (both files required)

Loading Methods

Method 1: Activity Bar

  1. Click the Files icon (📁) in the activity bar
  2. Click the "Select a file" button
  3. Navigate to your log file
  4. Click Open

Method 2: Drag and Drop

  1. Drag one or more files from your file manager
  2. Drop them anywhere on the UltraLog window
  3. Files load automatically

Multi-File Support

  • Each file opens in its own tab
  • Click tabs to switch between files
  • Close tabs with the × button
  • Duplicate files are automatically detected and rejected

File Information

After loading, the Files panel shows:

  • File name
  • ECU type (Haltech, ECUMaster, Speeduino, AiM, Link, Emerald, etc.)
  • Channel count
  • Duration
  • Delete button to remove the file

Channel Selection

Accessing the Channels Panel

Click the Channels icon (📋) in the activity bar to open the Channels panel.

Panel Layout

The Channels panel contains:

  1. Search box - Filter channels by name
  2. Available channels list - All channels from the loaded file
  3. Selected channel cards - Currently displayed channels with color indicators

Selecting Channels

  1. Use the search box to filter channels (e.g., type "rpm" or "afr")
  2. Click a channel name to add it to the chart
  3. The channel appears as a card in the "Selected Channels" section
  4. Click the channel card or name again to remove it

Limit: Maximum of 10 channels can be displayed simultaneously.

Channel Cards

Each selected channel shows:

  • Color indicator - Matches the line on the chart
  • Channel name - May be normalized if Field Normalization is enabled
  • Current value - Value at cursor position with units
  • Remove button (×) - Deselect the channel

Channel Colors

Channels are assigned colors from a palette:

  • Standard: Blue, Orange, Green, Red, Purple, Brown, Pink, Gray, Yellow, Cyan
  • Colorblind Mode: Black, Orange, Sky Blue, Bluish Green, Yellow, Blue, Vermillion, Reddish Purple

Chart Interaction

The Chart Display

The main chart shows:

  • Y-axis: Normalized values (0-1 scale)
  • X-axis: Time in seconds
  • Lines: One colored line per selected channel
  • Cursor: Vertical line showing current position
  • Legend: Channel info with min/max/current values

Normalized Display

All channels are displayed normalized to a 0-1 range:

  • Why? Allows comparing channels with vastly different scales
  • Example: RPM (0-8000) and Lambda (0.7-1.3) can be compared visually
  • Original values are shown in the legend with proper units

Mouse Controls

Action Result
Click Move cursor to clicked position
Scroll Zoom in/out on time axis
Drag Pan the view left/right
Double-click Reset zoom to fit all data

Legend Information

For each selected channel, the legend displays:

■ Channel Name    Min: 0.00    Max: 100.00    Current: 45.67 units
  • Color indicator - Matches the line on the chart
  • Channel name - May be normalized if Field Normalization is enabled
  • Min/Max - Peak values across the entire log
  • Current - Value at cursor position with unit symbol

Timeline and Playback

Timeline Controls

Located at the bottom of the window:

[▶] [⏸] [⏹]  [1.0x ▼]  ═══════○═══════════  00:15.234 / 02:30.000

Playback Buttons

Button Action
▶ Play Start/resume playback
⏸ Pause Pause at current position
⏹ Stop Stop and reset to beginning

Keyboard shortcut: Press Space to Play/Pause

Playback Speed

Available speeds:

  • 0.25x (quarter speed)
  • 0.5x (half speed)
  • 1.0x (real-time)
  • 2.0x (double speed)
  • 4.0x (4x speed)
  • 8.0x (8x speed)

Timeline Scrubber

  • Click anywhere on the timeline to jump to that time
  • Drag the handle to scrub through the data

Time Display

Shows current time / total duration in seconds

Manual Time Input

Click on the time display to type a specific time in seconds.

Cursor Tracking Mode

When enabled (Settings → Display → Cursor Tracking):

  • The chart automatically scrolls to keep the cursor centered
  • Useful when scrubbing through long logs
  • The view window adjusts dynamically

Tools Panel

Accessing Tools

Click the Tools icon (🔧) in the activity bar to open the Tools panel.

Available Tools

The Tools panel provides access to three major analysis tools:

  1. Scatter Plot
  2. Histogram
  3. Analysis

Use the selector at the top of the Tools panel to switch between tools.

Scatter Plot Tool

The scatter plot visualizes the relationship between two channels.

How to use:

  1. Open Tools panel → Select "Scatter Plot"
  2. Select X-axis channel from the dropdown
  3. Select Y-axis channel from the dropdown
  4. Data points are plotted showing the correlation

Features:

  • Real-time updates as you scrub through data
  • Zoom and pan controls
  • Cursor tracking shows current position
  • Points colored to match timeline

Use cases:

  • AFR vs MAP - See how AFR changes with manifold pressure
  • Ignition vs RPM - Visualize timing curve
  • TPS vs Load - Check throttle-to-load relationship
  • Coolant Temp vs AFR - Check cold-start enrichment

Interpreting Results:

  • Linear pattern - Direct correlation between channels
  • Scattered points - No strong relationship
  • Clusters - Distinct operating conditions
  • Outliers - Potential tuning issues or sensor problems

Histogram Tool

The histogram creates 2D heatmap visualizations for analyzing channel distributions.

How to use:

  1. Open Tools panel → Select "Histogram"
  2. Select X-axis channel from the dropdown
  3. Select Y-axis channel from the dropdown
  4. Optionally select Z-axis channel for color coding
  5. Choose grid size: 10x10, 16x16, 20x20, or 25x25
  6. Toggle between "Hit Count" and "Average Z-Value" modes

Modes:

  • Hit Count - Shows how many data samples fall into each grid cell (heat intensity)
  • Average Z-Value - Colors cells by the average value of the Z-axis channel

Features:

  • Heat gradient from blue (low) to red (high)
  • Cell statistics on hover/click
  • Cursor position tracking during playback
  • Analyze data distributions and correlations

Use cases:

  • RPM vs TPS heatmap - Visualize where you spend time driving
  • Boost vs RPM colored by AFR - See AFR distribution across the boost/RPM map
  • MAP vs Timing - Identify timing patterns across load ranges

Analysis Tools

The Analysis panel provides built-in signal processing and statistical analysis.

How to use:

  1. Open Tools panel → Select "Analysis"
  2. Choose a category: Filters, Statistics, AFR, or Derived
  3. Select an analysis tool from that category
  4. Configure parameters (varies by tool)
  5. Click "Run Analysis"
  6. Optionally save results as computed channels

Categories:

Filters

Signal processing tools to smooth or process data:

  • Moving Average - Smooth noisy signals
  • Kalman Filter - Advanced signal filtering
  • Low-pass Filter - Remove high-frequency noise
  • High-pass Filter - Remove low-frequency trends

Statistics

Calculate statistical measures:

  • Min/Max - Find minimum and maximum values
  • Percentiles - Calculate 25th, 50th, 75th, 95th, 99th percentiles
  • Standard Deviation - Measure data variability
  • Variance - Statistical variance
  • Mean/Average - Average value over range

AFR (Air-Fuel Ratio)

Specialized AFR analysis tools:

  • AFR Target Comparison - Compare actual AFR to target AFR
  • AFR Deviation - Calculate deviation from stoichiometric
  • Lambda Analysis - Lambda-specific calculations

Derived

Calculate new channels from existing data:

  • Rate of Change - Calculate derivatives
  • Integration - Integrate values over time
  • Acceleration - Calculate acceleration from speed
  • Power Calculation - Estimate power from torque and RPM

Saving Results:

After running an analysis, you can:

  • Preview results in the analysis panel
  • Save as computed channel to add to your channel list
  • Export data (coming soon)

Settings Panel

Accessing Settings

Click the Settings icon (⚙️) in the activity bar to open the Settings panel.

Settings Categories

The Settings panel consolidates all application settings in one place:

  1. Units - Unit preferences for measurements
  2. Display - Visual settings and accessibility
  3. Computed Channels - Manage computed channel library

Units Settings

Configure display units for 8 measurement categories. Changes apply immediately to all displayed values.

Category Options Default
Temperature Kelvin, Celsius, Fahrenheit Celsius
Pressure kPa, PSI, Bar kPa
Speed km/h, mph km/h
Distance km, miles km
Fuel Economy L/100km, MPG L/100km
Volume Liters, Gallons Liters
Flow Rate L/min, GPM L/min
Acceleration m/s², g m/s²

Note: Unit conversion is display-only. Your original data is never modified.

Display Settings

Visual settings and accessibility options.

Colorblind Mode

Toggle: On/Off

  • Uses Wong's optimized 8-color palette
  • Designed for deuteranopia, protanopia, and tritanopia
  • Colors: Black, Orange, Sky Blue, Bluish Green, Yellow, Blue, Vermillion, Reddish Purple

Font Size

Options: S (Small), M (Medium), L (Large), XL (Extra Large)

  • Scales all UI text for improved readability
  • Default: M (Medium)
  • Settings persist across sessions
  • Useful for high-DPI displays or accessibility needs

Cursor Tracking

Toggle: On/Off

  • When enabled, chart automatically scrolls to keep cursor centered
  • Useful for scrubbing through long logs
  • Default: Off

Field Normalization

Toggle: On/Off

  • Maps ECU-specific channel names to standardized names
  • Example: "Act_AFR", "AFR1", "Aft" all become "AFR"
  • Helps compare data across different ECU systems
  • Default: Off

Normalization Editor

Button: Open Normalization Editor

Create custom field name mappings:

  1. Click "Open Normalization Editor"
  2. Enter source name (ECU-specific)
  3. Enter target name (standardized)
  4. Click Add
  5. Mappings apply immediately

Note: Custom mappings are stored in memory and reset when the application closes. Persistent custom mappings are planned for a future release.

Computed Channels Settings

Button: Open Computed Channels Manager

Manage your library of computed channel templates. See Computed Channels section below for full details.

Computed Channels

Computed channels (also called virtual or math channels) allow you to create custom data channels from mathematical formulas.

Opening the Manager

Settings panel → Computed Channels → "Open Computed Channels Manager"

Creating a Formula

  1. Click "+ New Channel" in the Computed Channels window
  2. Fill in the form:
    • Name: Display name (e.g., "Boost Delta")
    • Formula: Mathematical expression (e.g., MAP - "Barometric Pressure")
    • Unit: Display unit (e.g., "kPa", "%", "deg")
    • Description: Optional notes
  3. Click "Save"

Formula Syntax

Operators:

  • Arithmetic: +, -, *, /, ^ (power)
  • Parentheses: (, ) for grouping

Functions:

  • Trigonometry: sin, cos, tan, asin, acos, atan, atan2
  • Hyperbolic: sinh, cosh, tanh, asinh, acosh, atanh
  • Math: sqrt, abs, exp, ln, log, log2, log10
  • Rounding: floor, ceil, round, trunc
  • Comparison: max, min

Constants:

  • pi - Pi (3.14159...)
  • e - Euler's number (2.71828...)
  • tau - Tau (2π)
  • phi - Golden ratio (1.61803...)

Channel References:

Simple names:

RPM
TPS
MAP

Names with spaces (use quotes):

"Manifold Pressure"
"Coolant Temp"
"Engine Speed"

Time-Shifting:

Reference past or future values:

Index-based (by sample count):

RPM[-1]           Previous sample
RPM[-2]           Two samples ago
RPM[+1]           Next sample

Time-based (in seconds):

Boost@-0.5s       Value 0.5 seconds ago
AFR@-0.1s         Value 100ms ago
TPS@+0.2s         Value 0.2 seconds in the future

Example Formulas

Simple Arithmetic:

RPM * 0.5
Half the RPM value

TPS / 100
Convert TPS from percent to decimal

Channel Combination:

"Manifold Pressure" - "Barometric Pressure"
Calculate gauge pressure

max(AFR1, AFR2)
Maximum of two AFR sensors

(AFR1 + AFR2) / 2
Average AFR from two sensors

Rate of Change:

RPM - RPM[-1]
RPM change per sample

(Boost - Boost[-10]) / 0.1
Boost rate of change (assuming 10Hz logging)

Time-Shifted Calculations:

(Boost@-0.5s - Boost) / 0.5
Boost rate over last 0.5 seconds

RPM - "Engine Speed"[-5]
RPM difference from 5 samples ago

Complex Math:

sqrt(TPS * MAP / 100)
Complex calculation

abs("Coolant Temp" - 90)
Temperature deviation from 90°C

Using Computed Channels

  1. Create and save a formula in the library
  2. Click "Apply to File" next to the formula
  3. The computed channel appears in your channel list (Channels panel)
  4. Select it like any other channel to visualize

Library Management

Persistence:

  • Templates are saved automatically to disk
  • Persist across application restarts
  • Stored in JSON format:
    • Linux: ~/.config/ultralog/computed_channels.json
    • macOS: ~/Library/Application Support/UltraLog/computed_channels.json
    • Windows: %APPDATA%\UltraLog\computed_channels.json

Editing:

  • Click "Edit" on any template to modify
  • Changes are saved immediately

Deleting:

  • Click "Delete" on any template to remove
  • Deletion is permanent but can be recreated

Reusability:

  • One template can be applied to multiple log files
  • Formulas automatically adapt to available channels in each file
  • If a referenced channel doesn't exist, you'll see an error

Validation

UltraLog validates formulas before saving:

  • Checks for syntax errors
  • Verifies all referenced channels exist
  • Tests evaluation with sample data
  • Shows helpful error messages

Exporting

PNG Export

Save the current chart view as a PNG image:

  1. File menu → Export → PNG (or Ctrl/Cmd + E)
  2. Choose save location
  3. Enter filename
  4. Click Save

The exported image includes:

  • Current chart view (with zoom/pan state)
  • Legend with channel information
  • Time axis labels

PDF Export

Generate a PDF document of your chart:

  1. File menu → Export → PDF
  2. Choose save location
  3. Enter filename
  4. Click Save

Accessibility Features

Colorblind Mode

Location: Settings panel → Display → Colorblind Mode

Uses Wong's optimized palette designed for:

  • Deuteranopia (red-green colorblindness)
  • Protanopia (red colorblindness)
  • Tritanopia (blue-yellow colorblindness)

Colorblind Palette Colors:

  1. Black
  2. Orange
  3. Sky Blue
  4. Bluish Green
  5. Yellow
  6. Blue
  7. Vermillion
  8. Reddish Purple

Font Scaling

Location: Settings panel → Display → Font Size

Four sizes available:

  • S (Small) - Compact UI for small screens
  • M (Medium) - Default size, good for most displays
  • L (Large) - Larger text for readability
  • XL (Extra Large) - Maximum size for accessibility or high-DPI displays

Font size setting persists across sessions.

Custom Font

UltraLog uses the Outfit typeface for:

  • Clear readability
  • Consistent appearance across platforms
  • Good distinction between similar characters

Toast Notifications

Non-intrusive notifications appear for:

  • File load success/failure
  • Export completion
  • Errors and warnings

Keyboard Shortcuts

Global Shortcuts

Shortcut Action
Ctrl/Cmd + O Open file
Ctrl/Cmd + W Close current tab
Ctrl/Cmd + E Export PNG

Playback Shortcuts

Shortcut Action
Space Play/Pause toggle
Escape Stop playback

Tips and Best Practices

Performance

  • UltraLog handles large files well, but loading may take a few seconds for 50MB+ files
  • Use release builds for best performance
  • Close unused tabs to free memory

Analysis Workflow

  1. Start wide - Load the full log and play through at 1x
  2. Identify areas of interest - Note any anomalies or events
  3. Zoom in - Use scroll to zoom on specific areas
  4. Compare channels - Add related channels to identify correlations
  5. Use tools - Scatter plot and histogram for deeper analysis
  6. Document - Export charts for records or sharing

Channel Selection

  • Start with essential channels: RPM, AFR, MAP, TPS
  • Add diagnostic channels as needed
  • Remove channels you're not currently analyzing
  • Use search to quickly find specific channels

Next Steps

UltraLog Wiki

Home

Getting Started

User Documentation

Support

Development

Legal

Links

Clone this wiki locally