NetCDF Viewer & HDF5 Viewer (NC Viewer, H5 Viewer)

NetCDF Viewer & HDF5 Viewer (NC Viewer, H5 Viewer), a VS Code extension by Zovo

A NetCDF viewer and HDF5 viewer for climate and lab scientists who keep data in .nc or .h5 files. It shows the variables, their CF metadata, the values and a map inside VS Code. No Python, no NCL, nothing to set up.

Free, MIT license. Needs VS Code 1.90.0 or newer. Extension ID zovo.hdf5-netcdf-explorer, version 0.4.0.

New in 0.4.0: coastlines on latitude-longitude maps, a Play button that steps through time, NetCDF CDF-5 (64-bit data) files, and full plots of grids over 1 million cells, such as a 0.25 degree global field (721 x 1440).

A real VS Code window running version 0.4.0 on sst.day.mean.2023.nc from NOAA PSL (OISST v2 high resolution, daily, 2023). The map is sampled to every 3rd latitude and longitude, so it keeps its 2:1 shape, and drew in about 0.1 s. A click on the map plotted that point over 365 days.

Play (▶ next to the time slider) on the same 450 MB file, recorded frame by frame in VS Code.

• Maps with coastlines. When a heatmap's rows and columns are latitude and longitude, it draws the Natural Earth coastlines and puts north at the top. Grids from 0 to 360 and from -180 to 180 both work, and so do regional grids.
• Play through time. The ▶ button next to a slider steps through time, or any other dimension, at the speed you pick. The colour range stays fixed while it plays, so you can compare the frames.
• Made for NetCDF and climate data. Dimension names, coordinates, scale_factor, add_offset, _FillValue and CF time units are applied for you, so you see 263.75 K on 2024-12-04 06:00, not 1500 at index 13. The noleap, 360_day and all_leap calendars work too.
• Big files stay fast. The file is read slice by slice in a background thread. In our test a 37 GB array opens, shows a page and draws a sampled heatmap in about one second, and a slow read is stopped after 20 s instead of freezing the editor.
• Plots you can use in a report. Choose from 8 colour maps (viridis, cividis, magma, inferno, plasma, turbo, gray and a diverging blue-red map), reverse them, set the range (2-98 percentile, min to max, symmetric around 0, from the valid_range or actual_range attribute, or your own numbers) and turn on a log scale. "Save PNG" writes the plot with its title, units, the slider positions and the colour bar.
• Click a point, get its time series. On a variable with 3 or more dimensions, a click on the heatmap plots that grid point along time (or another dimension you pick), with dates on the x axis, like ncview does. Save it as PNG or copy it as CSV.
• Remote SSH, WSL and dev containers: VS Code runs this extension on the machine that has the file, so a 40 GB file stays where it is and only the slice on screen is sent to your window.
• One viewer for HDF5, NetCDF-4 and NetCDF-3 (classic, 64-bit offset and CDF-5), including HDF5 files with other names such as Julia .jld2, MATLAB 7.3 .mat and .loom. Groups, attributes, compound tables, strings, chunking and compression filters are all shown. Nothing leaves your machine.

Quick start

1. Install the extension.
2. Click a .nc or .h5 file in the Explorer. Pick a variable on the left.

Recorded in the same window. The white arrow is drawn in to show where each click lands.

Questions people ask

What you can do

• Browse the group tree with a filter box. Coordinates, plain datasets, external links and NetCDF dimensions have their own icons.
• Read the file overview (format, dimensions, global attributes and a table of all variables with units and long names), much like ncdump -h.
• See type, shape with dimension names, chunk shape, compression (shuffle, deflate level, LZF, szip and others by name), size in memory and the full attribute list. Internal HDF5 and NetCDF attributes are hidden behind a checkbox.
• Pick any two dimensions as rows and columns. Sliders fix the others and show the decoded coordinate value next to the index.
• Page through values 100 rows by 30 columns at a time, with coordinate values as row and column headers.
• Plot 1D data as a line and 2D slices as a heatmap with a colour bar and hover readout. Arrays larger than 512 x 512 are sampled with a stride.
• Read HDF5 files compressed with LZF, Blosc, bitshuffle, Zstd, LZ4, bzip2 or ZFP, as h5py, hdf5plugin and detector software write them, with no Python.
• See 8-bit RGB and RGBA images (height x width x 3 or 4, or HDF5 CLASS=IMAGE) as colour pictures, with the channel values under the mouse.
• Turn the coastlines on or off on latitude-longitude maps. They are drawn in the saved PNG too.
• Press ▶ next to any slider to play through that dimension. Pick the speed (0.5×, 1×, 2× or as fast as the file reads). Escape, a slider move or another variable stops it.
• Pick a colour map, reverse it, choose the colour range and a log scale. The colour map default is the setting hdf5NetcdfExplorer.colormap.
• Click a heatmap cell to plot the values at that point along time or another dimension. Escape closes the series.
• Save a heatmap, line plot or series as PNG with "Save PNG". The picture has a title with the variable, units and the slider positions, axis labels and the colour bar.
• See min, max, mean, std and the number of fill, NaN and Inf values for the slice on screen.
• Copy the path, or copy xarray or h5py code that loads the same slice.
• Export the slice on screen to CSV or JSON with "Export slice…". You get every row and column of the two chosen dimensions, with the coordinate values as headers. The sliders fix the other dimensions, and the JSON file records which index and value each of them had. Text from the file that starts with =, +, - or @ gets a leading ' in the CSV, so a spreadsheet does not run it as a formula.
• Turn CF decoding off to see the raw stored numbers.
• The view reloads when the file changes on disk, which helps while a model run is writing output. A script that deletes the file and writes it again also triggers a reload.

Supported files

The format is detected from the first bytes of the file, not from the extension, so a 512-byte user block (JLD2 and MATLAB 7.3 files have one) is fine. HDF4, NASA CDF and older MATLAB v5 .mat files get a clear message instead of an error. So does an HDF5 or NetCDF-4 file that was cut off during a copy or download: the message says how many bytes are missing.

Settings

Privacy and safety

The extension makes no network calls and has no telemetry. It never runs code from a file. Values go to the view as plain JSON and are drawn as text or canvas pixels, under a strict Content Security Policy with no remote scripts.

Known limits

• Files must be on a disk that the extension can read: your computer, or the remote machine in a Remote SSH, WSL or dev container window. Virtual file systems, such as GitHub repositories opened in vscode.dev, are not supported.
• Other HDF5 filters (SZ, JPEG and rarer plugins) are named in the dataset details, and reading such a dataset shows a message instead of values.
• Zarr is not supported yet.
• MATLAB .mat files saved in the v5 format are not HDF5. Save them again with save(filename, '-v7.3').
• Export writes at most hdf5NetcdfExplorer.maxReadValues values (1,000,000 by default) per file.
• The colour maps other than viridis are blended from 2 to 15 anchor colours, so they are close to the matplotlib maps but not identical.
• Coastlines are drawn on regular or near-regular latitude-longitude grids (1D coordinates). Curvilinear grids with 2D latitude and longitude arrays (many ocean models) and projected grids in metres get no coastlines yet.
• The colour range and saved heatmap PNG use the cells on screen, which are sampled to at most 512 x 512 for big arrays. Saved pictures are dark text on white, whatever the editor theme.
• A point series needs a numeric variable with 3 or more dimensions. Above 100,000 points it takes every Nth value and says so.
• The standard calendar uses the proleptic Gregorian calendar for dates before 1582.

Credits

Coastlines: Natural Earth 1:110m, public domain. Compression filters: h5wasm-plugins (the HDF Group plugins built to WebAssembly). HDF5 reading uses h5wasm by the National Institute of Standards and Technology, which bundles the HDF5 library by The HDF Group. NetCDF-3 headers are parsed with netcdfjs (MIT). See THIRD-PARTY-NOTICES.txt.

License

MIT

Guides

• A free NetCDF viewer that runs in VS Code
• Open an HDF5 (.h5) file in VS Code