Repository navigation
User Guide
This comprehensive guide covers all features and functionality of UltraLog v3.0.
- Interface Overview
- Loading Files
- Channel Selection
- Chart Interaction
- Comparing Two Logs
- Timeline and Playback
- Tools Panel
- Settings Panel
- Computed Channels
- Exporting
- About Window
- Accessibility Features
- Keyboard Shortcuts
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]
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.
- 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
- Main data visualization area
- Displays selected channels as time-series graphs
- Shows cursor with current time position
- Legend with channel info and values
- Playback buttons (Play, Pause, Stop)
- Speed selector
- Timeline scrubber
- Time display and manual input
| Extension | Format | ECU System |
|---|---|---|
.csv |
CSV text files | Haltech, ECUMaster, RomRaider, MegaSquirt, Woolich Racing Tuned |
.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) |
Method 1: Activity Bar
- Click the Files icon (📁) in the activity bar
- Click the "Select a file" button
- Navigate to your log file
- Click Open
Method 2: Drag and Drop
- Drag one or more files from your file manager
- Drop them anywhere on the UltraLog window
- Files load automatically
- 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
After loading, the Files panel shows:
- File name
- ECU type (Haltech, ECUMaster, Speeduino, AiM, Link, Emerald, MegaSquirt, Woolich, etc.)
- Channel count
- Duration
- Delete button to remove the file
Click the Channels icon (📋) in the activity bar to open the Channels panel.
The Channels panel contains:
- Search box - Filter channels by name
- Available channels list - All channels from the loaded file
- Selected channel cards - Currently displayed channels with color indicators
- Use the search box to filter channels (e.g., type "rpm" or "afr")
- Click a channel name to add it to the chart
- The channel appears as a card in the "Selected Channels" section
- Click the channel card or name again to remove it
Limit: Maximum of 10 channels can be displayed simultaneously.
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
Channels are assigned colors from the Night Drive data palette. With Color blind mode on, they are assigned from an 8-color Okabe-Ito palette that stays distinguishable for the common types of color vision deficiency (see Color Blind Mode).
When you select more channels than the palette has colors, later series repeat the colors dashed, then dotted, so every line stays distinct. Data colors follow Color blind mode only. The Ultra intensity setting never changes them.
While you compare two logs, the dash shows the log instead: log A is solid and log B is dashed in the same color (see Comparing Two Logs).
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
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
| 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 |
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
Overlay a second log on the current tab, for example the same pull before and after a tune change, or one pull on two fuel maps. The tab's own file is log A; the second file is log B.
- Load both logs and open the tab of the first one
- In the Channels panel, choose the second log under Compare, or use File → Compare with…
- Open file… loads a log that is not open yet and makes it log B of the tab you asked from
Choose None to stop comparing. Log B's channels leave the tab.
- When you pick a channel, its match from log B is added too, paired by name. With field normalization on, names are matched after normalization, so
Engine Speedpairs withRPM - A pair has one color: log A is solid and log B is dashed
- A pair shares one scale, so the higher peak looks higher. Without this, every channel fills its own 0-1 range and two different pulls would look the same
- The Log A | Log B switch shows log B's channel list, to add a channel that only log B has
- A card marked not in B has no match in log B. Computed channels are not paired
- On a card, × removes that channel and the trash button removes the whole pair
- A pair counts as one channel against the 10-channel limit
Both logs start at 0 s. To line up two events:
- Log B offset - seconds added to log B's times. Drag or type a value, or use −1, −0.1, +0.1 and +1 s. Reset sets it back to 0
- Align at cursor - put the cursor on an event in log A (for example the throttle tip-in), click Align at cursor, then click the same event in log B on the chart. Log B moves so that point sits under the cursor. Esc cancels
The timeline covers both logs, including any part of log B before log A starts.
- The legend, the direct labels and the channel cards tag every series A or B; hover the tag on a card to see the file name
- Legend values come from each log at the cursor, and stay blank where a log has no data
- Min/Max jumps on a log B card land on the right point of the shared timeline
- The GPS track map stays on log A, and its "Color by" lists log A's channels only
The exported sheet draws log B dashed, tags the legend A · and B ·, and adds a line with both file names and log B's offset.
Located at the bottom of the window:
[▶] [⏸] [⏹] [1.0x ▼] ═══════○═══════════ 00:15.234 / 02:30.000
| Button | Action |
|---|---|
| ▶ Play | Start/resume playback |
| ⏸ Pause | Pause at current position |
| ⏹ Stop | Stop and reset to beginning |
Keyboard shortcut: Press Space to Play/Pause
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)
- Click anywhere on the timeline to jump to that time
- Drag the handle to scrub through the data
Shows current time / total duration in seconds
Click on the time display to type a specific time in seconds.
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
Click the Tools icon (🔧) in the activity bar to open the Tools panel.
The tool switcher at the top of the main window has five tools:
-
Log Viewer (
Ctrl/Cmd + 1) -
Scatter Plots (
Ctrl/Cmd + 2) -
Histogram (
Ctrl/Cmd + 3) -
Lambda Delay (
Ctrl/Cmd + 4) — see Tuning Table Generators -
Accel Enrichment (
Ctrl/Cmd + 5) — see Tuning Table Generators
The Tools panel also opens the Analysis window, lists the table generators with their current status, and has an Export... button that opens the Export dialog (see Exporting).
The scatter plot visualizes the relationship between two channels.
How to use:
- Open Tools panel → Select "Scatter Plot"
- Select X-axis channel from the dropdown
- Select Y-axis channel from the dropdown
- 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
The histogram creates 2D heatmap visualizations for analyzing channel distributions.
How to use:
- Open Tools panel → Select "Histogram"
- Select X-axis channel from the dropdown
- Select Y-axis channel from the dropdown
- Optionally select Z-axis channel for color coding
- Choose grid size: 10x10, 16x16, 20x20, or 25x25
- 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:
- Cells use the theme's sequential color map (cividis-style, low to high), not a blue-to-red heat gradient
- Empty cells are hatched, so "no samples" never reads as a low value
- 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
Lambda Delay and Accel Enrichment mine your logs for events and build tuning tables binned by RPM × load or RPM × throttle rate, with per-cell sample counts and confidence, an event inspector, and CSV, clipboard, PNG and PDF export. Setup lives in the Tool Properties panel; the table fills the center panel. They are covered on their own page: Tuning Table Generators.
The Analysis panel provides built-in signal processing and statistical analysis.
How to use:
- Open Tools panel → Select "Analysis"
- Choose a category: Filters, Statistics, AFR, or Derived
- Select an analysis tool from that category
- Configure parameters (varies by tool)
- Click "Run Analysis"
- Optionally save results as computed channels
Categories:
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
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
Specialized AFR analysis tools:
- AFR Target Comparison - Compare actual AFR to target AFR
- AFR Deviation - Calculate deviation from stoichiometric
- Lambda Analysis - Lambda-specific calculations
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)
Click the Settings icon (⚙️) in the activity bar to open the Settings panel.
The Settings panel consolidates all application settings in one place:
- Units - Unit preferences for measurements
- Display - Visual settings and accessibility
- Language - Interface language selection
- Computed Channels - Manage computed channel library
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.
Visual settings and accessibility options.
Slider: 0-100
- Controls how much neon the interface wears: glow, gradients, and at high values a grid floor under the chart
- Named stops: Stealth (0, default), Night Drive (35), Neon (70) and Ultra (100)
- Also in the theme menu at the end of the menu bar, which shows the current level
- Never changes your data colors or text contrast
- Locked while High contrast is on
Toggle: On/Off
- Color blind safe data colors (Okabe-Ito, 8 colors)
- The cividis sequential map and a blue/orange diverging map for heatmaps
- Dashed and labelled lines
- Stronger text contrast and a white cursor
- See Accessibility Features for details
Toggle: On/Off
- Black grounds, white text and outlined controls
- Neon effects are off
- Locks the Ultra intensity slider
Options: S (Small), M (Medium), L (Large), XL (Extra Large)
- Scales all UI text for improved readability
- Default: M (Medium)
- Useful for high-DPI displays or accessibility needs
Your unit, display, theme (Ultra intensity, Color blind mode, High contrast), font size, normalization and export choices are saved automatically and restored the next time you start UltraLog.
Toggle: On/Off
- When enabled, chart automatically scrolls to keep cursor centered
- Useful for scrubbing through long logs
- Default: Off
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
Button: Open Normalization Editor
Create custom field name mappings:
- Click "Open Normalization Editor"
- Enter source name (ECU-specific)
- Enter target name (standardized)
- Click Add
- Mappings apply immediately
Note: Custom mappings are saved with your settings and restored the next time you start UltraLog.
Configure the interface language for UltraLog.
Dropdown: Select Language
UltraLog supports 15 languages:
| Language | Native Name |
|---|---|
| English | English |
| Spanish | Español |
| German | Deutsch |
| French | Français |
| Italian | Italiano |
| Portuguese (Brazil) | Português (Brasil) |
| Portuguese (Portugal) | Português (Portugal) |
| Chinese (Simplified) | 简体中文 |
| Japanese | 日本語 |
| Hindi | हिन्दी |
| Arabic | العربية |
| Bengali | বাংলা |
| Russian | Русский |
| Urdu | اردو |
| Indonesian | Bahasa Indonesia |
Features:
- UI text and menus update immediately when language is changed
- Language preference persists across application restarts
- All core UI elements are translated
- Default: English
Note: Channel names and data from log files remain in their original language - only the UltraLog interface is translated.
Button: Open Computed Channels Manager
Manage your library of computed channel templates. See Computed Channels section below for full details.
Computed channels (also called virtual or math channels) allow you to create custom data channels from mathematical formulas.
Settings panel → Computed Channels → "Open Computed Channels Manager"
- Click "+ New Channel" in the Computed Channels window
- 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
- Click "Save"
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
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
- Create and save a formula in the library
- Click "Apply to File" next to the formula
- The computed channel appears in your channel list (Channels panel)
- Select it like any other channel to visualize
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
- Linux:
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
UltraLog validates formulas before saving:
- Checks for syntax errors
- Verifies all referenced channels exist
- Tests evaluation with sample data
- Shows helpful error messages
Open the Export dialog from any of these:
- File menu → Export...
- The Export... button in the Tools panel
-
Ctrl/Cmd + E(this no longer saves a PNG at once)
In the dialog:
- Under Format, choose PDF or PNG
- Choose a theme:
- Paper - Light. The default; prints cleanly.
- Graphite - Dark, ink-saving grey.
- Click Export PDF or Export PNG, then choose a save location and filename
UltraLog remembers your choices. The theme is remembered separately for each format.
Exports always use the color blind safe palette, so anyone you share them with can read them. They ignore the Ultra intensity, Color blind mode and High contrast settings.
Every export is the same sheet:
- The UltraLog lockup
- A title (the file name or the tool name)
- The time range, with the record and channel counts
- The chart or table
- A legend or color scale
- A footer with ultralog.co, the version and the export date
| Format | Size | Notes |
|---|---|---|
| PNG | 1920×1080 | Fixed size, whatever the window size |
| A4 landscape | Vector, with real, selectable text |
PDF fonts are embedded, so symbols such as − λ ° and non-Latin channel names print correctly.
| Tool | Export contents |
|---|---|
| Log Viewer | The visible time range of the chart |
| Scatter Plots | Both density plots, side by side |
| Histogram | The grid as the tool shows it: custom ranges, sample filters and minimum-hits blanking are applied |
| Lambda Delay / Accel Enrichment | The table with values, count badges and edge labels (see Tuning-Table-Generators) |
Copy image in the Export dialog copies just the chart or table to the clipboard, without the header or footer. Paste it into a document or message.
Help → About UltraLog shows:
- The version
- The license (AGPL-3.0)
- Links: Website (ultralog.co), Documentation, Source code, Report Issue and Support Development
- A Check for Updates button
Location: Settings panel → Display → Color blind mode
Designed for deuteranopia, protanopia and tritanopia. It changes:
- Data colors - An 8-color Okabe-Ito palette
- Heatmaps - The cividis sequential map, and a blue/orange diverging map for signed values
- Lines - Dashed and labelled, so series differ by more than color
- Text and cursor - Stronger text contrast and a white cursor
Series beyond the 8 palette colors repeat the colors dashed, then dotted. Status messages always show an icon plus words, never color alone.
Location: Settings panel → Display → High contrast
Black grounds, white text and outlined controls. The neon effects are off and the Ultra intensity slider is locked.
Location: Settings panel → Display → Ultra intensity
Sets how much neon the interface wears, from Stealth (0) to Ultra (100). It never changes data colors or text contrast, so it is safe to turn up or down for taste.
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 is saved with your other settings.
UltraLog uses the Outfit typeface for:
- Clear readability
- Consistent appearance across platforms
- Good distinction between similar characters
Non-intrusive notifications appear for:
- File load success/failure
- Export completion
- Errors and warnings
| Shortcut | Action |
|---|---|
Ctrl/Cmd + O |
Open file |
Ctrl/Cmd + W |
Close current tab |
Ctrl/Cmd + E |
Open the Export dialog |
Ctrl/Cmd + 1 … 5
|
Switch tool (Log Viewer, Scatter Plots, Histogram, Lambda Delay, Accel Enrichment) |
| Shortcut | Action |
|---|---|
Space |
Play/Pause toggle |
Escape |
Stop playback |
- 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
- Start wide - Load the full log and play through at 1x
- Identify areas of interest - Note any anomalies or events
- Zoom in - Use scroll to zoom on specific areas
- Compare channels - Add related channels to identify correlations
- Use tools - Scatter plot and histogram for deeper analysis
- Document - Export charts for records or sharing
- 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
- Supported-ECU-Formats - Detailed ECU format information
- Unit-Conversion - Complete unit reference
- Troubleshooting - Common issues and solutions
- FAQ - Frequently asked questions
Links