NPY Preview

NumPy .npy binary tensors. Header is always parsed; tensor data is only fetched when it fits the preview cap.

Extensions: npy

NPY format brief

A .npy file has four sections in order:

┌─────────────────────────┐
│ magic   "\x93NUMPY"     │  6 bytes
├─────────────────────────┤
│ version (major, minor)  │  2 bytes (uint8 each)
├─────────────────────────┤
│ header_len              │  2 bytes (v1) or 4 bytes (v2/v3)
├─────────────────────────┤
│ header dict (ASCII)     │  e.g. "{'descr': '<f4', 'fortran_order': False, 'shape': (1024, 7), }"
├─────────────────────────┤
│ raw data                │  np.prod(shape) * itemsize bytes
└─────────────────────────┘

The header is a literal Python dict repr (NumPy's choice). The previewer parses it with a small ASCII reader — no eval.

Two-stage Range fetch

stage 1: GET .npy  Range: bytes=0-4095
  └─ parse magic + version + header → { dtype, shape, fortran_order }
 
stage 2 (only if shape product ≤ npyPreviewElements):
  GET .npy  Range: bytes=<headerEnd>-<headerEnd + dataBytes - 1>
  └─ decode into typed array

If the tensor's element count exceeds limits.npyPreviewElements (default 1024), stage 2 is skipped. The previewer shows shape, dtype, and a "preview disabled" notice with a download button. A 10 GB tensor file consumes ~4 KB of network on preview.

<FilePreview url={url} limits={{ npyPreviewElements: 4096 }} />

Supported dtypes

Unsupported

• Big-endian (>f4, etc.) — fails with a clear error message; download button still works.
• Complex (<c8, <c16) — not decoded.
• Structured / record dtypes ({'names': [...], 'formats': [...]}) — not decoded.
• Unicode strings (<U...) — not decoded.

In each unsupported case, the header is still shown so the user sees shape and dtype, plus a download link.

Display

Once decoded, the tensor is rendered as a flat list (1D) or grid (2D), with shape and dtype in the header bar:

shape: (1024, 7)   dtype: float32   elements: 7168   size: 28.0 KB

Higher-dimensional tensors (3D+) are rendered as the first 2D slice with a "showing slice [0, :, :]" note. Use the download button for full inspection in NumPy.

Live demo

Two tiles: a small (7,) joint pose (under the 1024-element cap, decoded with stats and value list) and a medium (1024, 6) IMU buffer (6144 elements > cap → metadata only).

import { FilePreview } from '@vuer-ai/vuer-m3u/preview'

export function MyComponent() {
  return (
    <FilePreview url="/vuer-m3u-demo/preview/npy/joints_small.npy" />
  )
}

Cross-links

• Size Strategy — bounded fetches
• API — npyPreviewElements