Introduction

h5v is a terminal HDF5 viewer and editor.

It provides:

• tree navigation for groups, datasets, links, and projected compound fields
• preview, matrix, heatmap, image, and schema views
• attribute inspection and editing
• command and startup-script automation
• multichart comparison

Start with Installation and Quick start.

Installation

Recommended: shell installer

Linux and macOS can install the latest release directly from GitHub:

curl -fsSL https://raw.githubusercontent.com/DanielHauge/h5v/main/install.sh | sh

The shell installer also works in Git Bash, MSYS2, and Cygwin on Windows. It prefers conventional install locations: /usr/local/bin when writable, ~/.local/bin on Unix-like systems without a writable system prefix, and %LOCALAPPDATA%\Programs\h5v\bin on Windows shells.

Options:

install.sh --version VERSION --install-dir PATH --repo OWNER/REPO --dry-run

Other install paths

PowerShell

irm https://raw.githubusercontent.com/DanielHauge/h5v/main/install.ps1 | iex

Homebrew

brew tap DanielHauge/h5v https://github.com/DanielHauge/h5v.git
brew install h5v

Scoop

scoop bucket add h5v https://github.com/DanielHauge/h5v
scoop install h5v/h5v

Prebuilt binaries with cargo-binstall

cargo binstall h5v

Build from source

cargo install h5v

On Linux, source builds may require native packages such as cmake, pkg-config, libfontconfig, freetype, and expat development headers.

Terminal graphics

h5v works in plain terminals, but image and chart previews look best with a real graphics protocol such as Kitty.

Links:

• Kitty graphics protocol: https://sw.kovidgoyal.net/kitty/graphics-protocol/
• ratatui-image: https://github.com/ratatui/ratatui-image
• terminal support gallery: https://benjajaja.github.io/ratatui-image-screenshots/

If graphics probing causes trouble:

h5v --no-terminal-graphics path/to/file.h5

That disables graphics probing and uses the safer text-only path.

Compatibility mode

If your terminal also struggles with icons or line drawing:

h5v --compatibility path/to/file.h5

This switches to simpler symbols and disables terminal graphics probing.

You can also enable it with H5V_COMPATIBILITY_MODE or h5v.compatibility = true.

H5V_COMPATIBILITY_MODE=true h5v path/to/file.h5
H5V_COMPATIBILITY_MODE=off h5v path/to/file.h5

Precedence:

1. --compatibility
2. h5v.compatibility
3. H5V_COMPATIBILITY_MODE
4. default false

For config details, see Configuration and theming. For display problems, see Troubleshooting and limits.

To make the environment variable permanent:

# ~/.bashrc or ~/.zshrc
export H5V_COMPATIBILITY_MODE=true

# ~/.config/fish/config.fish
set -gx H5V_COMPATIBILITY_MODE true

Invalid values are rejected.

Write mode

h5v opens files read-only unless you pass -w:

h5v -w path/to/file.h5

Without -w, edit actions report that the file must be reopened in write mode.

Quick start

Open a file:

h5v path/to/file.h5
h5v -w path/to/file.h5

Press ? to open the in-app help.

Try the bundled example

h5v examples/h5v-example.h5 --script examples/h5v-example.h5v

Regenerate the example file if needed:

python scripts/generate_example_h5.py

Default workflow

1. Move around the tree on the left.
2. Inspect the selected node in the content pane.
3. Inspect or edit metadata in the attributes pane.

Useful keys:

• ? opens the in-app help
• Tab switches between preview and matrix when both exist
• : opens the command minibuffer
• m adds the current preview to multichart, including group previews driven by H5V_PREVIEW_EXPR
• M opens or closes multichart mode

Help

The help view has five tabs:

• Keymap
• Commands
• Multichart
• Heatmap
• Customization

Use Tab / Shift+Tab or h / l to switch tabs.

In Keymap, Commands, and Customization, use j / k, arrow keys, Home, End, g, and G to move through the left-hand list.

Example paths:

First commands

:goto /signals/sine_wave
:goto /group_preview
:mode matrix
:help mchart

Script a startup

Inline commands:

h5v examples/h5v-example.h5 \
  -c "goto /signals/sine_wave" \
  -c "mchart add" \
  -c "goto /signals/cosine_wave" \
  -c "mchart add" \
  -c "mchart show"

Script file:

h5v examples/h5v-example.h5 --script examples/h5v-example.h5v

Dry-run:

h5v --script-test --script examples/h5v-example.h5v

See Controls reference, Commands, Configuration, and Startup scripting.

Navigation and layout

Pane model

h5v has three panes:

• the tree pane for HDF5 structure and selection
• the content pane for preview, matrix, schema, image, and multichart views
• the attributes pane for metadata inspection and editing

Wide terminals use a side-by-side layout. Narrow terminals stack the panes. Search takes over the working area.

Moving focus

• Shift + arrow keys to move between panes directly
• Ctrl+W, then h/j/k/l for vim-style pane navigation

The sidebar can be toggled with s or Ctrl+W o.

Tree navigation

• j / k or arrow keys move the selection
• h and l collapse or expand nodes
• Enter or Space toggles the current node
• g / G jump to the top or bottom
• u / Ctrl+U and Ctrl+D move by larger chunks

When the current selection is previewable, m adds it to the multichart workspace.

Mouse support:

• a click selects the row under the cursor
• clicking the already selected group or compound container toggles it
• repeated clicks on Load more keep expanding long child lists

Content modes

The content pane changes with the selected node:

• numeric datasets prefer chart-style preview
• matrixable datasets can switch to matrix mode
• numeric datasets with at least two non-singleton dimensions can switch to heatmap mode
• scalar and string data render as text
• HDF5 image datasets render inline as images
• compound container nodes show a recursive schema view
• file nodes show filesystem metadata
• groups stay previewable even when they only show an empty-state card

Use Tab to switch modes when more than one is available.

Search and help

• / enters search mode
• : opens the command minibuffer
• ? opens the built-in help
• . repeats the last successful command

The help view has tabs for Keymap, Commands, Multichart, Heatmap, and Customization. Tabs with a left-hand list use the normal list navigation keys.

See Controls reference and Commands.

Controls reference

These are the shipped defaults. h5v.keymaps can override them for non-text-entry contexts.

Global and pane controls

Help

Tree navigation

Preview and matrix selectors

Content and attributes

Edits use your configured editor through $EDITOR and fall back to vi.

Heatmap

Mouse

Command minibuffer

Multichart mode

HDF5 feature support

h5v can browse groups, datasets, links, broken links, and synthetic nodes created for projected compound fields.

Matrixable and previewable data types

Matrix mode is only available when a dataset is matrixable and its shape has at least one dimension larger than 1. Single-value datasets stay in scalar preview mode.

Strings and highlighting

String datasets can carry a HIGHLIGHT attribute with an extension hint such as json, py, or yml. If it is absent, h5v falls back to the dataset name extension.

Enum styling overrides

Enum datasets can override the default symbol and color cycle with:

• SYMBOLS: a 1D string attribute, aligned with ascending numeric enum value order
• COLORS: a 1D string attribute, aligned with ascending numeric enum value order

Color values accept named colors and #RRGGBB. See Configuration reference.

Group preview expressions

Groups can opt into preview rendering with a variable-length string attribute named H5V_PREVIEW_EXPR. The value uses the same expression syntax as multichart.

Image metadata handling

Datasets that follow the HDF5 image convention are rendered inline as images. See Images and Image conventions.

Properties vs attributes

type, size, shape, chunk, link, and path are properties shown in the Properties section. They are not HDF5 attributes.

Those built-in properties include:

• type
• size
• shape
• chunk
• link
• path

Preview types

Numeric chart preview

h5v renders numeric datasets as a line plot over a selected one-dimensional slice.

• active x-axis dimension
• fixed indices for the other dimensions
• visible slice when the data is segmented

Use x / X, [ / ], and the index controls to move through higher-dimensional data.

Large previews are segmented at 250000 elements. PageUp / PageDown move between segments.

If a slice contains only invalid numeric values such as NaN or infinity, h5v reports that bounds cannot be computed.

Scalar and string preview

Scalar datasets render as text. This covers:

• floating-point scalars
• signed and unsigned integer scalars
• fixed and variable strings

Scalar enums use the enum renderer, including optional SYMBOLS and COLORS overrides.

String datasets can carry syntax-highlighting hints. Resolution order:

• HIGHLIGHT attribute on the dataset
• dataset name extension such as .py or .yml

File preview

Selecting the root file node shows filesystem metadata such as path, size, timestamps, permissions, and open mode.

Schema preview for compounds

Selecting the root of a compound dataset shows a recursive schema preview.

Projected compound leaves follow their field type:

• /compound/nested_records/gain previews like a numeric field
• /compound/nested_records/window is matrixable and editable as one value per line
• projected enum leaves can inherit custom symbol/color styling from dataset metadata
• projected multi-value string arrays stay matrix-only instead of attempting chart preview

Group preview

If a group has a variable-length string attribute named H5V_PREVIEW_EXPR, h5v evaluates it with the same syntax as multichart and renders the result in the preview pane.

The bundled example includes /group_preview:

(!/group_preview/time, (!/group_preview/value - #/group_preview/offset) * #/group_preview:scale)

Press m on that group to add the same expression to multichart.

Image preview

Datasets recognized as HDF5 images render inline in the content pane. See Images for behavior and Image conventions for the required metadata.

Matrix views

When matrix mode is available

Matrix mode appears when the current dataset or projected compound field is matrixable and has more than one effective element. Use Tab to move between preview and matrix mode when both are available.

Dimension selection

For datasets with more than two dimensions, h5v exposes selectors for:

• the row axis
• the column axis
• the currently selected extra dimension
• the active index value for fixed dimensions

Dimensions with size 1 are forced to index 0. The row and column axes must stay distinct, and the selected-dimension controls let you walk a higher-dimensional array one slice at a time.

Rendering behavior

Numeric values

Numeric datasets render as dense tables with one line per row. Column widths are sized for readable values and a minimum width of 24 characters.

Enums

Enums render with symbol and color mapping so repeated categories are easier to scan visually.

Strings

String matrices render inline with widths adjusted to the visible content.

Compound fields

Compound container roots are documented through the schema preview. Individual projected leaf fields, however, can still render in matrix mode once you drill down to a matrixable field.

Practical workflow

Use matrix mode when:

• the shape is dense enough that spatial layout matters more than trend shape
• you need to compare neighboring values directly
• a chart preview hides too much structure in a higher-dimensional slice

Switch back to preview mode when trend shape matters more than cell-by-cell inspection.

Heatmap

Heatmap is the image-style view for numeric datasets with at least two non-singleton dimensions.

It is available only when:

• compatibility mode is off
• terminal image rendering is available

What it shows

• a rendered 2D slice
• slice/page context
• settings
• viewport stats
• optional selection stats
• legend and histogram

Settings

The settings panel controls:

• colormap
• range mode
• invert x
• invert y
• invert colors
• normalization

Built-in range modes include Auto, MIN/MAX, Clip 1-99%, Sigma +-2sigma, and Winsor 2-98%.

Use Up / Down to move between settings and Left / Right to change the selected value. Click a settings row to focus it directly.

Selection and viewport

• no explicit selection means the active region is the current viewport
• one left click selects one terminal-cell region
• a second left click expands that to a rectangle
• another left click after a rectangle clears the explicit selection

The region panel shows both:

• viewport x/y/w/h, mean, std
• selection x/y/w/h, mean, std

Zoom and pan

• z zoom in
• Z zoom out
• 0 reset viewport
• v clear explicit selection
• H / J / K / L pan the zoomed viewport
• PageUp / PageDown move through segmented heatmap pages

Mouse

• left click selects a region
• wheel zoom is anchored to the hovered cell
• right click on an explicit selection zooms into that selection
• right-click drag pans the viewport

Commands and scripts

Heatmap uses the existing movement commands:

• up / down
• left / right
• page-up / page-down

Dedicated heatmap range commands:

• heatmap range list
• heatmap range use "Clip 1-99%"
• heatmap range add 5% 80% "5-80%"
• heatmap range add 2.5 5.5 "2.5..5.5"

Zoom, reset, clear selection, and viewport pan are key-driven. In scripts, use press:

• press z
• press Z
• press 0
• press v
• press H

Copy

y copies the active heatmap summary:

• selection summary when a region is selected
• viewport summary otherwise

Configuration

Heatmap configuration:

• include heatmap in h5v.content_mode_order
• style shared panel/title colors through h5v.colors
• style shared symbols through h5v.symbols
• set h5v.heatmap.default_range
• set h5v.heatmap.default_colormap
• set h5v.heatmap.default_normalization
• set h5v.heatmap.default_invert_x
• set h5v.heatmap.default_invert_y
• set h5v.heatmap.default_invert_c
• add h5v.heatmap.range_modes

Images

h5v renders datasets inline as images when they match the HDF5 image convention.

For the full subclass and shape rules, see Image conventions.

Terminal support

Image previews work best in terminals with a full graphics protocol. Kitty is the strongest target.

• Kitty graphics protocol: https://sw.kovidgoyal.net/kitty/graphics-protocol/
• ratatui-image backend support: https://github.com/ratatui/ratatui-image
• ratatui-image terminal screenshot matrix: https://benjajaja.github.io/ratatui-image-screenshots/

Raw JPEG and PNG payloads

h5v supports raw encoded image payloads stored as:

• u8 byte streams
• variable-length arrays of u8

Multi-frame image datasets

Image navigation works for multi-frame data as well:

• grayscale and truecolor image stacks can use the leading dimension as a frame axis
• raw JPEG and PNG payloads can be stored as variable-length byte arrays
• frame movement is clamped to the available range

Viewport behavior

For very wide or tall datasets, h5v switches to a windowed viewport. The HUD shows:

• the currently visible row or column range
• total coverage percentage
• how many rows or columns are visible
• how far each arrow-key press pans the viewport

Try /images/truecolor_rgb and /images/wide_grayscale in the bundled example file.

Related chapters

• Image conventions
• Preview types
• Troubleshooting and limits

Image conventions

Required attributes

h5v follows the standard HDF5 image convention. A dataset must have:

1. CLASS = "IMAGE"
2. IMAGE_SUBCLASS = ...

Supported IMAGE_SUBCLASS values are:

• IMAGE_GRAYSCALE
• IMAGE_TRUECOLOR
• IMAGE_BITMAP
• IMAGE_INDEXED
• IMAGE_JPEG
• IMAGE_PNG

Interlace mode

Truecolor and indexed images also need:

• INTERLACE_MODE = "INTERLACE_PIXEL" or
• INTERLACE_MODE = "INTERLACE_PLANE"

If that attribute is missing for formats that require it, h5v will not treat the dataset as an inline image.

Shape expectations

The exact dataset interpretation depends on the subclass plus the interlace mode.

Pannable wide or tall images

When an image would be clipped heavily by the current terminal aspect ratio, h5v switches from a simple fit-to-area preview to a windowed image view. The image chrome then shows which row or column range is currently visible, and the hidden portion can be explored like a pannable image slice.

In practice this works especially well for unusually wide or tall datasets. The bundled example path /images/wide_grayscale is intended to demonstrate that behavior.

Compound datasets

Synthetic child nodes

The bundled example file includes /compound/records and /compound/nested_records so you can test both simple and nested compound browsing immediately.

Compound datasets are not treated as opaque blobs. h5v creates synthetic tree nodes for their fields so you can navigate the compound structure directly from the main tree.

Root-level schema preview

When the focused node is the root of a compound dataset, the preview pane shows a recursive schema view rather than an empty content area. The schema includes:

• field names
• field types
• byte offsets
• nested compounds and compound arrays

Recursion handling

Schema rendering has a hard recursion limit of 32 nested levels and explicitly omits recursive loops once they are detected. That keeps pathological or self-referential layouts from hanging the preview.

Projected field workflows

Once you drill down to a concrete leaf field, that projected field behaves like an ordinary dataset slice:

• numeric fields can preview as charts
• matrixable fields can render in matrix mode
• scalar string fields render as text
• multi-value string arrays stay matrix-only

The bundled example is a good regression harness here:

• /compound/records/label shows projected string handling
• /compound/nested_records/window shows a projected fixed array that can be edited from matrix mode

Projected enum leaves use the same enum renderer as normal enum datasets. They can inherit dataset-wide SYMBOLS and COLORS overrides, and they also check field-scoped variants first by prefixing the projected field path in uppercase with underscores. For example, a projected field like status/evaluation looks for STATUS_EVALUATION_SYMBOLS and STATUS_EVALUATION_COLORS before falling back to plain SYMBOLS and COLORS.

This makes compound-heavy files much easier to inspect without exporting fields into standalone datasets first.

Commands

Press : to open the command minibuffer.

Minibuffer behavior:

• Tab cycles matching completions
• Shift+Tab and arrow keys move through suggestions
• Ctrl+P / Ctrl+N browse command history
• help or help <command> shows command help
• . repeats the last successful command

Press ? for the full in-app help. Use help <command> in the minibuffer for command-specific help.

Common commands

Navigation:

goto /signals/sine_wave
seek 5
down 3
left 2
page-down

View control:

focus tree
focus attributes
focus content
mode preview
mode matrix
mode heatmap
toggle-tree
reload
configure
configure reset

Heatmap view control:

up
down
left
right
page-up
page-down

Heatmap key-only actions:

press z
press Z
press 0
press v
press H

Heatmap range presets:

heatmap range list
heatmap range use "Clip 1-99%"
heatmap range add 5% 80% "5-80%"
heatmap range add 2.5 5.5 "2.5..5.5"

Selection:

x next
row prev
col next
dim next
index next 10

Attributes:

attr create title string "release candidate"
attr delete title

Multichart:

mchart open
mchart add !/signals/sine_wave
mchart fit all
mchart visible
mchart select next
mchart prompt
mchart expr "($1[0..512], !/signals/cosine_wave[..512])"
mchart zoom x in 25
mchart pan right 10

For the full command list, aliases, and mchart action table, see Command reference.

Aliases and numeric shorthand

Numeric shorthand still works:

:5
:+3
:-2

Mappings:

• :5 -> seek 5
• :+3 -> down 3
• :-2 -> up 2

Quoting

Quoted strings work in commands and scripts. Use them for:

• attribute values with spaces
• command scripts containing expression tuples
• press ... commands that need modifier sequences

press goes through the normal keymap:

press ctrl+w o
press M j enter

If you override keys in h5v.keymaps, press uses the effective keymaps after config load.

Try commands against the bundled example:

h5v examples/h5v-example.h5

See Configuration and theming and Startup scripting.

Command reference

Key columns below show the shipped defaults. h5v.keymaps can override them for non-text-entry contexts.

Top-level commands

Numeric shorthand

Focus targets

View modes

Heatmap view command mapping

Heatmap uses the existing movement commands:

Heatmap commands

Heatmap key-only actions

These actions are available from the keymap and can be scripted with press ...:

Selection directions

Attribute actions

Multichart actions

Press examples

press ctrl+w o
press M j enter

press uses the effective keymaps after config load, including custom keymap overrides.

Startup scripting

Sources

1. --script <PATH>
2. --script -
3. piped stdin
4. repeated --command / -c

Order: scripts first, then stdin, then inline commands.

Startup scripts use the same command parser as the minibuffer. That includes:

• navigation commands
• view and focus commands
• attribute commands
• heatmap range commands
• multichart commands
• press <keys> sequences

Heatmap can be scripted with generic movement commands, heatmap range ... commands, and press for zoom, reset, clear selection, and viewport pan.

press uses the effective keymaps after config load, so startup scripts follow any configured key remaps.

Validation mode

Use --script-test or -ct to validate a script without launching the UI:

h5v file.h5 --script-test --script setup.h5v

Bundled example script

h5v examples/h5v-example.h5 --script examples/h5v-example.h5v

Regenerate the example file if needed:

python scripts/generate_example_h5.py

Script format

• newline-separated commands
• semicolon-separated commands
• blank lines
• comment lines beginning with #

Examples:

h5v file.h5 -c "focus content" -c "mode matrix"
h5v file.h5 --script setup.h5v
printf 'toggle-tree; mode preview\nreload\n' | h5v file.h5

Example setup.h5v:

# open with a clean content layout
toggle-tree
focus content
mode preview
mchart add !/group/dataset[..,0]

Example heatmap script fragment:

focus content
mode heatmap
heatmap range add 5% 80% "5-80%"
page-down
press z
press L
press v

Bundled examples/h5v-example.h5v:

goto /signals/sine_wave
focus content
mchart add
goto /signals/cosine_wave
mchart add
mchart open
mchart select prev
mchart visible
mchart select next
mchart prompt
mchart expr "$1 - $2"
mchart zoom in 20

See Command reference for the full command surface.

Configuration

h5v loads init.lua at startup.

If the file is invalid, h5v keeps running, shows a warning toast, and marks the header with a config warning badge until the configuration loads cleanly again.

Config file location

init.lua lives under your platform config directory:

• Linux: ~/.config/h5v/init.lua
• macOS: ~/Library/Application Support/h5v/init.lua
• Windows: %AppData%\h5v\init.lua

If it does not exist, h5v creates it.

LuaLS sidecar files are generated next to it under .h5v-luals/. h5v.lua is refreshed automatically. .luarc.json is refreshed only while h5v manages it.

Commands

Start here

Most configs only need these fields:

• h5v.theme
• h5v.symbol_theme
• h5v.content_mode_order
• h5v.compatibility
• h5v.heatmap.*
• h5v.keymaps
• h5v.colors
• h5v.symbols

For all keys, scopes, themes, and accepted color names, see Configuration reference.

Keymaps

Keymaps live in h5v.keymaps.

Scopes:

• global
• normal
• window
• tree
• content
• heatmap
• attributes
• mchart

Precedence:

1. heatmap
2. content / tree / attributes / mchart / window
3. normal
4. global

Each scope supports:

• clear_defaults = true to remove shipped bindings for that scope
• unbind = { "key", ... } to remove selected shipped bindings
• bind = { { key = "...", action = "..." }, { key = "...", command = "..." } }
• bind(mode, key, action[, description])
• bind_command(mode, key, command[, description])
• bind_commands(mode, key, commands[, description])
• bind_script(mode, key, script[, description])
• bind_lua(mode, key, callback[, description])
• unbind(mode, key)

Use h5v.modes.* and h5v.actions.* constants in Lua. Examples: h5v.modes.Global, h5v.modes.Heatmap, h5v.actions.ShowHelp, h5v.actions.HeatmapZoomIn.

Example:

bind(h5v.modes.Global, "ctrl+h", h5v.actions.ShowHelp, "Show help")
unbind(h5v.modes.Heatmap, "v")
bind_command(h5v.modes.Heatmap, "ctrl+alt+r", "heatmap range use \"Clip 1-99%\"")
bind_commands(h5v.modes.Global, "ctrl+k", { "down 2", "up 1" })
bind_script(h5v.modes.Global, "ctrl+s", "down 2\nup 1")
bind_lua(h5v.modes.Global, "ctrl+l", function(ctx)
  ctx.command("help reload")
end)
bind(h5v.modes.Heatmap, "ctrl+z", h5v.actions.HeatmapZoomIn)

Heatmap defaults

Heatmap settings live under h5v.heatmap:

• default_range
• default_colormap
• default_normalization
• default_invert_x
• default_invert_y
• default_invert_c
• range_modes

Example

h5v.theme = "light"
h5v.content_mode_order = { "matrix", "preview" }
h5v.symbol_theme = "compatibility"
h5v.compatibility = true

h5v.heatmap.default_colormap = "inferno"
h5v.heatmap.default_normalization = "log"
h5v.heatmap.default_invert_c = true

bind(h5v.modes.Global, "ctrl+h", h5v.actions.ShowHelp)

h5v.colors.accent.selection_bg = "#e1c878"
h5v.colors.tree.group = "#d26c00"
h5v.colors.surface.panel_border = "#1e3755"

h5v.symbols.tree.dataset_link_icon = "D@"
h5v.symbols.tree.load_more_label = "v Load more"
h5v.symbols.title.matrix_tab = "Matrix"
h5v.symbols.chart.visibility_visible = "*"

The built-in light theme is a good starting point for a bright palette plus a few targeted overrides:

Use h5v.themes.<name> and h5v.symbol_themes.<name> as built-in catalogs when you want to copy values from a shipped theme.

Configuration reference

Core config fields

Built-in themes

Built-in symbol themes

Content modes

heatmap in h5v.content_mode_order only affects preferred tab order. Heatmap appears only when compatibility mode is off and terminal image rendering is available.

Color categories

Symbol categories

Accepted color values

Hex values: #RRGGBB

Color override keys

Symbol override keys

Example

h5v.theme = "dark"
h5v.symbol_theme = "rich"

h5v.colors.accent.selection_bg = "lightblue"
h5v.colors.chart.series_1 = "#ff8800"
h5v.symbols.title.preview = "Plot"
h5v.symbols.tree.dataset_icon = "D"

Heatmap config

Example:

h5v.content_mode_order = { "heatmap", "preview", "matrix" }
h5v.heatmap.default_range = "MIN/MAX"
h5v.heatmap.default_colormap = "inferno"
h5v.heatmap.default_normalization = "log"
h5v.heatmap.default_invert_y = true
h5v.heatmap.default_invert_c = true
h5v.heatmap.range_modes = {
  { label = "5-80%", min = "5%", max = "80%" },
}

Multichart config

Example:

h5v.multichart = {
  overview_max_samples = 2048,
  detail_enabled = true,
  detail_samples_per_column = 6,
  detail_min_samples = 1024,
  detail_max_samples = 32768,
  detail_padding_ratio = 0.1,
  derived_detail_enabled = true,
}

Keymap config

Scopes:

Each scope table accepts:

Each bind entry accepts:

An entry must set exactly one of action, command, commands, script, or lua.

Helper functions:

Common mode constants: h5v.modes.Global, h5v.modes.Normal, h5v.modes.Window, h5v.modes.Tree, h5v.modes.Content, h5v.modes.Heatmap, h5v.modes.Attributes, h5v.modes.Multichart.

Example:

bind(h5v.modes.Global, "ctrl+h", h5v.actions.ShowHelp)
unbind(h5v.modes.Heatmap, "v")
bind(h5v.modes.Heatmap, "ctrl+z", h5v.actions.HeatmapZoomIn)
bind_command(h5v.modes.Heatmap, "ctrl+alt+r", "heatmap range use \"Clip 1-99%\"")
bind_commands(h5v.modes.Global, "ctrl+k", { "down 2", "up 1" })
bind_lua(h5v.modes.Global, "ctrl+l", function(ctx) ctx.command("help reload") end)

Multichart

Multichart is the comparison workspace for previewable series.

Sources:

• the currently selected previewable tree selection
• an explicit dataset reference
• an expression-defined series

Basic workflow

1. Add a series with m or mchart add ....
2. Press M or run mchart open to enter the workspace.
3. Press Enter to open a new expression, or e to edit the selected series.
4. Build derived series with expressions such as $1 - $2, ($1, !/time[..]), or $1[0..256].
5. Use zoom and pan to inspect the area of interest.

Groups with H5V_PREVIEW_EXPR also work here. Pressing m on /group_preview adds the group preview expression as a chart item.

Expression editor

• Enter opens a new expression without changing the chart viewport
• e edits the selected series in place
• Enter submits the current expression
• Tab completes the selected suggestion
• Up and Down move through suggestions while editing
• Esc closes the editor

The editor validates expressions live and suggests chart item ids, dataset paths, and attribute references.

Raw dataset references such as !/big_dataset[..] are queued and loaded in the background when submitted. Zoomed dataset-backed views can request a denser viewport sample in the background while the coarse overview stays visible. Derived series can also refine to viewport detail when their referenced chart-item inputs share the same loaded detail window.

Config

Use h5v.multichart = { ... } in Lua to tune large-series behavior.

• overview_max_samples limits the initial background overview sample
• detail_enabled turns viewport-driven detail refinement on or off
• detail_samples_per_column scales viewport detail against chart width
• detail_min_samples and detail_max_samples clamp viewport detail size
• detail_padding_ratio loads extra x-range around the visible viewport
• derived_detail_enabled lets derived series refine when inputs share the same detail window

Visibility and organization

• move through chart items with j / k
• hide or show an item with Space or v
• remove the selected item with d, Backspace, or Delete when nothing depends on it
• clear the whole workspace with C
• open multichart help with ?

Zoom and pan

• +, =, or Shift+Up to zoom in
• - or Shift+Down to zoom out
• h / Shift+Left to pan left
• l / Shift+Right to pan right
• f to fit all visible series
• F to fit the selected series
• c to reset zoom

Mouse interaction follows the same anchored viewport model as heatmap:

• wheel zoom over the plot anchors to the hovered point
• plain wheel zoom changes both x and y
• Ctrl + wheel zoom changes x only
• Shift + wheel zoom changes y only
• right-click drag snapshots on press and pans on release

The same actions are available from the command line, including mchart fit ... and axis-specific zoom like mchart zoom x in 20.

Expression workflows

See Multichart expressions for syntax and Command reference for the full mchart command surface.

Multichart expressions

Supported references

Multichart expressions can refer to existing chart items, datasets, and attributes directly, but the reference type is always explicit.

Y-series and x/y-series

An expression can produce:

• a normal y-series
• a tuple-based x/y series

Examples:

$1 * #$1:SCALE
!/signals/sine_wave + #/group_preview/offset
$1[0..512] - $2[128..640]
($1 * #/group_preview:scale, !/group_preview/time)

The tuple form is the most important one for custom x/y plots because it gives you explicit control over both axes.

The same syntax is also used by group preview expressions. In the bundled example, /group_preview defines:

(!/group_preview/time, (!/group_preview/value - #/group_preview/offset) * #/group_preview:scale)

Here is an example of a parametric x/y series using sine and cosine signals to form a circle:

(!/signals/sine_wave, !/signals/cosine_wave)

Interactive prompt

Open the expression prompt with:

• Enter or e in multichart mode, or
• mchart prompt

The editor stays below the chart, so opening it does not change the plot viewport.

Enter starts a new expression. e loads the selected series expression so you can update it in place.

• Enter submits
• Tab applies the selected suggestion
• Up and Down move through suggestions
• Esc closes the editor

Invalid expressions are reported inline. Suggestions include chart item ids, dataset paths, and attribute names when they can be resolved from the current file.

Practical tips

• add a raw dataset first so you have stable $1, $2, and $3 references to build from
• use $id[start..end] when you want to align or compare only part of an existing chart item
• use :ATTR only when you want an explicit attribute lookup on an object or dataset-backed chart item
• prefer explicit dataset slicing when the same dataset can be interpreted several ways

Troubleshooting and limits

"Cannot edit in read-only mode"

h5v only writes when the file is opened with -w:

h5v -w file.h5

If you forget -w, edit actions report that the file must be reopened in write mode.

An image dataset does not render as an image

Check the image metadata:

• CLASS must be IMAGE
• IMAGE_SUBCLASS must be a supported image subclass
• truecolor and indexed images also need INTERLACE_MODE

See Image conventions.

The UI is blank or badly garbled

Try:

h5v --no-terminal-graphics file.h5

If the terminal also struggles with richer symbols or line drawing:

h5v --compatibility file.h5

Compatibility mode switches to simpler symbols and text/braille fallbacks. Multichart also falls back to a terminal-native braille plot.

See Installation for persistent compatibility settings.

A compound dataset does not show in matrix mode

That is expected for the compound container itself. The root node shows a schema preview. Drill down to a projected leaf field for preview or matrix rendering.

Large fixed strings look truncated

Fixed strings are read with a 32768 byte cap.

Very large previews are chunked

Chart previews are segmented with a maximum segment size of 250000 elements. Use PageUp and PageDown to move through the data.

A numeric preview fails to render bounds

If the current slice contains only invalid numeric values such as NaN or infinity, h5v cannot compute chart bounds.

Very wide or tall images

If an image is much wider or taller than the content pane, h5v may switch to a pannable windowed view instead of shrinking it aggressively.

Use /images/wide_grayscale from the bundled example file to test this path.