Skip to content

feat: Binary file hex preview in FileViewer#345

Merged
allison-truhlar merged 10 commits intoJaneliaSciComp:mainfrom
mkitti:mkitti-binary-file-display
Apr 9, 2026
Merged

feat: Binary file hex preview in FileViewer#345
allison-truhlar merged 10 commits intoJaneliaSciComp:mainfrom
mkitti:mkitti-binary-file-display

Conversation

@mkitti
Copy link
Copy Markdown
Contributor

@mkitti mkitti commented Apr 7, 2026

Summary

  • Adds a hex dump preview for binary files in the FileViewer component, showing the first 512 bytes via an HTTP Range request
  • Introduces HexDump.tsx — a new component rendering bytes in classic hexdump format (offset | hex | ASCII, 16 bytes/row)
  • Adds useFileBinaryPreviewQuery hook that fetches binary preview bytes using the existing /api/content/ endpoint's Range support
  • Updates FileViewer to detect binary files via the existing HEAD request (X-Is-Binary header) and render the hex preview instead of attempting text display
  • Simplifies the showJsonToggle condition (no longer needs metadataQuery.isSuccess guard)

Example output for a ZIP file:

Showing first 512 of 1,048,576 bytes

0000:  50 4B 03 04 14 00 00 00  08 00 6E 6F 55 58 00 00  PK........noUX..
0010:  00 00 00 00 00 00 00 00  00 00 09 00 1C 00 68 65  ..............he
0020:  6C 6C 6F 2E 74 78 74 55  54 09 00 03 8C 27 4E 7B  llo.txtUT.....'N{
0030:  8C 27 4E 7B 75 78 0B 00  01 04 E8 03 00 00 04 E8  .'N{ux..........

Test plan

  • Open a text file — syntax highlighting renders as before
  • Open a binary file (e.g. .h5, .zip, .png) — hex dump preview renders with offset, hex, and ASCII columns
  • Verify truncation message appears when file is larger than 512 bytes
  • Run pixi run test-frontend — all unit tests pass
  • Run pixi run node-check — no TypeScript errors
  • Run pixi run node-eslint-check — no ESLint errors

🤖 Generated with Claude Code

mkitti and others added 6 commits February 26, 2026 17:51
Previously, clicking a binary file showed nothing until a slow HEAD
request completed (which does synchronous file I/O server-side, painful
on NFS). Functional links were also absent for binary files.

Changes:
- isKnownBinaryExtension(): instant binary detection by file extension,
  bypasses the HEAD request entirely for common binary types (zip, h5,
  png, pdf, etc.)
- useFileBinaryPreviewQuery(): fetches first 512 bytes via HTTP Range
  header immediately, independent of binary detection, so the hex view
  appears as soon as the tiny read completes
- HexDump.tsx: classic hexdump renderer (offset | hex | ASCII, 16 B/row)
  with a "Showing first N of M bytes" label for truncated files
- FileViewer: always shows a download link in the header immediately,
  regardless of file type or loading state; uses two-stage binary
  detection (extension first, HEAD fallback for unknown types)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
The .nii.gz special case in isKnownBinaryExtension is redundant because
.gz is already in KNOWN_BINARY_EXTENSIONS, so split('.').pop() catches it.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
KNOWN_BINARY_EXTENSIONS and isKnownBinaryExtension are removed. Binary
detection now always uses the HEAD request (X-Is-Binary header), which
simplifies the logic at the cost of one extra server round-trip per file.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This is a standalone cosmetic feature unrelated to binary file display.
Removes HiOutlineDownload icon, getFileURL wiring, and the wrapper div
that was added to accommodate both the JSON toggle and download button.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Reformats six files to pass the pre-push ESLint/Prettier hook. No logic
changes — only line-wrapping adjustments flagged by prettier/prettier.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@mkitti
Copy link
Copy Markdown
Contributor Author

mkitti commented Apr 7, 2026

In #308, we removed binary previews completely. This adds a 512-byte preview as a hex display.

Flat binary files are common among many Janelia labs due to their simplicity when acquiring data from custom instrumentation. When I asking around if anyone uses NWB files, which are a form of HDF5 files, I got several responses like the following.

  1. "We're not using NWB either, just flat binaries in my lab."
  2. "We don’t use NWB nor do we have any clear plans to do so. Like [group leader 1, above] we prefer flat binaries or other simple formats."

The hex display adds some intelligible information about a binary file displayed as hex and is reminiscent of the output of hexdump command line utility. Often this can be used to identify a file since the first few bytes can be used to match a file signature. Additionally, some readable ASCII strings may be present in the few files providing some additional identifying information.

@mkitti mkitti changed the title Binary file hex preview in FileViewer feat: Binary file hex preview in FileViewer Apr 8, 2026
@allison-truhlar allison-truhlar merged commit 580c73d into JaneliaSciComp:main Apr 9, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants