Scientific Data Viewer - VSCode Extension

An extension to explore the metadata of scientific data files within your IDE, including NetCDF, Zarr, HDF5, GRIB, GeoTIFF and JPEG-2000.

🚀 Features

• Multi-format Support:

• Python Integration: Automatic Python environment detection and management
• File Tree Integration: Right-click on supported files in the explorer to open them
• Custom Editors: Direct file opening with dedicated editors
• Interactive Data Explorer: Browse file structure, dimensions, variables, and attributes
• Collapsible Nested Attributes (on by default): Tree view for Zarr and other formats with nested JSON attributes (see [Issue #120](https://github.com/etienneschalk/scientific-data-viewer/issues/120)); opt out via Nested Attributes View setting to use a flat list
• Browse Variable Information: View variable dimension names, data types, shapes, and memory usage
• Basic Data Visualization: Create plots and visualizations directly in VSCode (experimental, best effort)
• Enhanced GeoTIFF Support: Multi-band GeoTIFF files automatically convert bands to separate variables for improved readability and plotting
• HTML Report Export: Export complete data viewer content as self-contained HTML reports for sharing and documentation
• Command Palette Integration: Multiple commands for data viewer operations
• Status Bar Integration: Shows current Python interpreter status
• Human-readable File Sizes: Display file and variable sizes in appropriate units (B, kB, MB, GB, TB)
• Easy Settings Access: Ctrl+Shift+P ➜ Scientific Data Viewer: Show Settings
• Error Handling: Robust error handling with user-friendly messages
• Experimental Features: Configurable experimental features with clear warnings

📸 Screenshot Gallery

Data Visualization and Plotting

Light theme: GeoTIFF data visualization with plotting capabilities

Dark theme: GeoTIFF data visualization with plotting capabilities

Light theme: GeoTIFF plot in opened/expanded state

Data Structure Exploration

Light theme: NetCDF file with xarray HTML and text representation

Light theme: Zarr dataset tree view with variable focus

📦 Installation

1. Install from VSCode Marketplace:

   • Open VSCode
   • Go to Extensions view (Ctrl+Shift+X)
   • Search for "Scientific Data Viewer"
   • Click Install

2. Install required Python dependencies: (prompted by extension)

   pip install xarray matplotlib
   

3. Install optional Python dependencies: (prompted by extension)

   pip install netCDF4 h5py rioxarray cfgrib zarr cdflib
   

4. Open a supported file 🎉

⚙️ Prerequisites

Before using this extension, you need either Python 3.13 or uv installed on your system.

With Python 3.13:

The extension will prompt you to install the following packages if they are not available:

1. Required Python packages:
   • xarray
   • matplotlib
2. Optional Python packages:
   • netCDF4
   • h5py
   • rioxarray
   • cfgrib
   • zarr
   • cdflib (for NASA CDF files)

Note: Former Python versions may work, but it is not guaranteed nor supported.

With uv:

With uv, the extension will create and manage its own python environment, including Python version 3.13. The environment will be stored in the extension dedicated storage, provided by VSCode or Cursor.

🎯 Usage

🐍 Configuring Python Environment

The extension supports multiple ways to configure your Python environment:

1. Python Extension Integration (Default behaviour):

   • This mode delegates most of the work to the Python extension. Its installation is a requirement.
     • For VSCode users: 🔗 Python extension (VSCode Marketplace)
     • For Cursor users: 🔗 Python extension (Open VSX Registry)
   • Press Ctrl+Shift+P (open command palette)
   • Type "Python: Select Interpreter"
   • Choose your preferred Python environment
   • The extension will automatically detect it and use it

2. Extension Virtual Environment (Semi-Standalone):

   • Opt-in setting:
     • Press Ctrl+Shift+P (open command palette)
     • Type "Scientific Data Viewer: Show Settings"
     • Check "Scientific Data Viewer > Python > Use Extension Own Environment"
   • uv Required:
     • Consult the documentation: uv installation
     • If uv is installed and found: The extension creates its own isolated environment once the setting enabled, including Python 3.13 installation
     • If uv is not available, falls back to Python extension default behavior
   • Manage Extension Environment:
     • Press Ctrl+Shift+P (open command palette)
     • Type "Scientific Data Viewer: Manage Extension Virtual Environment"
     • Choose a command: create, update, delete, view information
   • Benefits of this approach:
     • Python 3.13: Uses uv to install and use Python 3.13 for optimal performance
     • Self-Contained: Works without external Python environment setup
     • Isolated: Won't interfere with your other projects
     • Storage: Stored in VSCode's extension storage space

📂 Opening Data Files

1. Click on file from File Explorer:

   • Click on any supported file in the File Explorer
   • File opens directly in the Scientific Data Viewer
   • Command "View: Split Editor" is supported

2. Drag and drop from File Explorer

   • Drag and drop any supported file (or folder)
   • File (or folder) opens directly in the Scientific Data Viewer
     • Multiple files (or folders) can be opened at once if they are selected
   • Command "View: Split Editor" is supported

3. Context menu from File Explorer:

   • Right-click on any supported file (or folder)
   • Select "Open Scientific Data Viewer" for single file or folder
   • Select "Open Scientific Data Viewer for Selection" to open multiple selected files or folders
   • Command "View: Split Editor" is NOT supported

4. From command palette:

   • Press Ctrl+Shift+P
   • Type "Open Scientific Data Viewer" (or "Open Scientific Data Viewer (Folder)")
   • Select a file (or folder) from the file picker
     • Multiple files (or folders) can be opened at once if they are selected
   • Command "View: Split Editor" is NOT supported

Note: the only current way to get access to the split editor for Zarr folders is drag and drop.

🔬 Exploring Data

You can explore the data via the editor itself, or via the Data Structure tree view displayed on the VSCode's left pane.

The data viewer editor shows:

• File Information: Path, size, format, and basic metadata
• Xarray HTML and Text Representations: Users that are used to xarray will be happy to see the well-known views. Uses DataTree or Dataset representation, depending on the file format.
• Xarray HTML and Text Representations (for each group): Relevant for multi-group datasets. Nested groups are flattened via DataTree.to_dict(). By default, group paths are sorted alphabetically; set scientificDataViewer.orderGroupsAlphabetically to false to preserve file order ([Issue #140](https://github.com/etienneschalk/scientific-data-viewer/issues/140)). Dataset representations are always used for groups.
• Global Plot Controls (:warning: EXPERIMENTAL): Use at your own risk. It will trigger plotting operations for all available variables. It is not optimized at all, and usage is not really recommended.
• Groups: The extension's data representation proposal. The view is inspired by the xarray HTML representation, with additional plotting controls. Feature parity is not reached yet as no sample data is currently displayed.
  • Dimensions: Dataset dimensions and their sizes
  • Coordinates: All coordinates with their types, shapes, dimension names, and memory usage. Attributes can be revealed when clicking on a coordinate.
  • Variables: All data variables with their types, shapes, dimension names, and memory usage. Attributes can be revealed when clicking on a variable.
    • Plot Controls (:warning: EXPERIMENTAL): "Create Plot" button for a variable, that tries the best effort to produce a plot of the variable using matplotlib. Currently, only an "auto" (best effort) plot mode is supported.
  • Attributes: Show group's attributes. Coordinate and variable attributes may include __xarray_encoding.* entries when scientificDataViewer.showXarrayEncodingAttributes is enabled (default).

📐 Dimension Slices

Dimension Slices let you subset data by dimension index or slice before plotting. They are available in Global Plot Controls (dimensions merged from all groups) and, when enabled, in each group's Group Plot Controls.

• Where to find it: In the plot controls area, look for the Dimension Slices section. Each dimension of the dataset (or group) has a text input.
• Slice syntax (Python-style):
  • Single index: 130 — use one position along that dimension.
  • Range: 100:120 — from index 100 up to (but not including) 120.
  • Range with step: 0:24:2 — from 0 to 24 in steps of 2 (e.g. every other time step).
• Slices are applied as xarray's isel() before plotting. Invalid slice strings produce a clear error.
• Facet row / Facet col: Use the dropdowns in the same section to choose which dimension drives rows and columns in faceted plots (e.g. 3D/4D data with multiple panels).
• col_wrap: Optional positive integer (next to facet row/col) to limit the number of columns in the faceted grid (xarray col_wrap kwarg).
• x, y, hue: Optional plot kwargs (see xarray plotting): choose a dimension or coordinate for the x-axis, y-axis, or hue (e.g. multiple lines). Same dropdown options as facet row/col.
• x increase / y increase: Checkboxes to control axes direction (xarray xincrease/yincrease; uncheck to reverse an axis).
• Aspect / Size: Optional integer inputs for figure size (xarray: figsize = (aspect * size, size) in inches).
• Robust: When checked, uses the 2nd and 98th percentiles of the data for color limits so outliers do not dominate the color scale (xarray Robust).
• Bins: For histogram-style plots, you can set the number of bins in the Dimension Slices row.

The Dimension Slices section includes a link to the xarray plotting guide for reference.

Global vs. Group (inheritance) The extension uses inheritance per field: for each plot parameter, the group value is used when set (non-empty), otherwise global is used. So the two can be mixed (e.g. group's dimension slices with global's facet row when the group left facet at "None"). Empty or "None" in group selectors (facet row/col, plot x/y/hue, cmap) falls back to global. Only dimension slices are atomic: they form one set of inputs (one per dimension); we use either the whole group's dimension-slice set or the whole global's—we do not merge dimension-by-dimension. So one change in a group's dimension slice inputs means that group's full set is used and global's dimension slices are ignored for that group; all other fields (facet row/col, plot x/y/hue, colWrap, aspect, size, robust, cmap, bins, checkboxes) inherit per field (group when set, else global).

Feature flags: Four settings control whether each block is shown. Global Dimension Slices and Group Dimension Slices are on by default; Global Time Controls and Group Time Controls are off by default (use Dimension Slices for time instead, e.g. 0:24:2). You can turn any block on or off in Settings under Feature Flags.

🖼️ Export Webview Content

The extension allows you to export complete data viewer content as self-contained HTML reports:

1. Using the Export Button:

   • Open a scientific data file in the Scientific Data Viewer
   • Click the export button (🖼️) in the header controls
   • Choose a location and filename for the HTML report
   • The report will be generated and you can choose to open it or reveal it in explorer

2. Using the Command Palette:

   • Press Ctrl+Shift+P (open command palette)
   • Type "Scientific Data Viewer: Export Webview Content"
   • Choose a location and filename for the HTML report

Report Contents:

• Complete file information (path, size, format, engines)
• Xarray HTML and text representations
• Data structure (dimensions, coordinates, variables, attributes)
• Technical information (Python path, extension configuration, versions)
• All content is self-contained with embedded CSS and JavaScript
• Professional layout with copy buttons for easy data extraction

Use Cases:

• Share data analysis results with colleagues
• Create documentation for datasets
• Archive data viewer sessions
• Generate reports for presentations or publications

🎮 Available Commands

Access these commands via the Command Palette (Ctrl+Shift+P):

🖱️ Context Menu Commands

Right-click on supported file types in the Explorer to access:

• Scientific Data Viewer: Open Scientific Data Viewer - Opens the file in the Scientific Data Viewer
• Scientific Data Viewer: Open Scientific Data Viewer for Selection - Opens all selected supported files or folders in the Scientific Data Viewer

⚙️ Settings

The extension can be configured through VSCode settings:

General Settings

• scientificDataViewer.maxFileSize
  • (type: number, default: 1000000000000)
  • Maximum file size in MB to load automatically. Files above this limit are not loaded.
• scientificDataViewer.defaultView
  • (type: string, default: "default")
  • Default view mode for data display (currently unused)
• scientificDataViewer.matplotlibStyle
  • (type: string, default: "" (empty string))
  • Matplotlib plot style for data visualizations. If empty, automatically detects VSCode theme and applies appropriate style (light theme → 'default', dark theme → 'dark_background'). If set, overrides automatic detection.
  • Examples: - default - Light theme with white background - dark_background - Dark theme with black background
  • Available styles: Any valid matplotlib style name (e.g., 'default', 'dark_background', 'seaborn', 'ggplot', etc.)
• scientificDataViewer.webviewExportTheme
  • (type: string, default: "" (empty string))
  • Theme to use when exporting webview content to HTML files. If empty, uses the current VS Code theme variables. If set, overrides with the specified theme for exports.
  • Note: Only affects exported HTML files, not the live webview display.
  • Values:
    • "" (empty string): Use the current VS Code theme
    • "Default Dark+": Default Dark+ theme
    • "Default Light+": Default Light+ theme
    • "Solarized Dark": Solarized Dark theme
    • "Solarized Light": Solarized Light theme
    • "High Contrast Dark": High Contrast Dark theme
    • "High Contrast Light": High Contrast Light theme
• scientificDataViewer.smallVariableBytes
  • (type: number, default: 1000)
  • Maximum size in bytes for variables and coordinates to have their values loaded and displayed in the UI (scalar and small array display, [Issue #102](https://github.com/etienneschalk/scientific-data-viewer/issues/102)). Variables/coordinates at or below this size get a display_value in the variable/coordinate details. If set to 0, the whole small-value display feature (Issue #102) is disabled and no variables/coordinates will show loaded values.
• scientificDataViewer.smallValueDisplayMaxLen
  • (type: number, default: 500)
  • Maximum character length for the string representation of small variable/coordinate values. Longer representations are truncated with "...". Only used when smallVariableBytes is greater than 0.
• scientificDataViewer.plotTimeoutMs
  • (type: number, default: 20000)
  • Maximum time in milliseconds to wait for a plot before it is cancelled and the backend process is terminated. Use a higher value (e.g. 120000 for 2 minutes) for large datasets when you want a quicklook without slicing first. Minimum 1000 (1s), maximum 600000 (10 min). Default: 20000 (20s).

🐍 Virtual Environment Settings

The extension includes specific settings for virtual environment management:

• scientificDataViewer.python.overridePythonInterpreter
  • (type: string, default: "" (empty string))
  • Override the Python interpreter path for the Scientific Data Viewer extension. If set, this will take precedence over the extension's own virtual environment, Python extension's interpreter, and any auto-detected environments.
  • Examples: - .venv/bin/python - Local virtual environment - C:\venv\Scripts\python.exe - Windows virtual environment - /usr/bin/python3 - System Python
  • Note: This setting has the highest priority and overrides all other interpreter selection methods.
• scientificDataViewer.python.useExtensionOwnEnvironment
  • (type: boolean, default: false)
  • When enabled, the extension will create and use its own isolated virtual environment stored in VSCode's extension storage.
  • Requires uv to be installed, otherwise this setting will have no effect, and the extension will fall back to using the Python extension's interpreter.
  • Benefits: - Semi-standalone: Only requires uv to be installed (responsability of the user) - Isolated: Won't interfere with other projects - Reliable: Always has the required packages - Python 3.13: Uses latest Python version for optimal performance

🚩 Feature Flags

• scientificDataViewer.allowMultipleTabsForSameFile
  • (type: boolean, default: false)
  • Experimental Feature - Allow opening multiple tabs for the same file. When enabled, each 'Open in Data Viewer' action creates a new tab. When disabled (default), focuses on existing tab if file is already open.
  • ⚠️ Warning: This feature is experimental and may cause unexpected behavior or performance issues.
• scientificDataViewer.devMode
  • (type: boolean, default: false)
  • Enable development mode. When enabled, automatically runs 'Show Extension Logs' and 'Open Developer Tools' commands when a scientific data file is opened. Also, reloads the webview script and CSS for faster development feedback loops.
• scientificDataViewer.convertBandsToVariables
  • (type: boolean, default: true)
  • When enabled, multi-band GeoTIFF files will have their bands converted to separate variables instead of a single 3D DataArray. This improves readability and plotting capabilities by treating each band as an individual variable.
  • Supported formats: GeoTIFF (.tif, .tiff, .geotiff)
  • Benefits: - Better color scale readability for different bands - Individual band plotting and analysis - Improved data structure visualization - Each band treated as a separate variable
• scientificDataViewer.outlineEnabled
  • (type: boolean, default: true)
  • When enabled, the extension builds the Scientific Data Structure tree in the Explorer sidebar. On by default. Set to false to skip outline build for faster loads.
  • Reload the window (Developer: Reload Window) after changing this setting — the sidebar pane and tree provider are registered at activation.

Plot controls (Global and Group)

• scientificDataViewer.globalTimeControls
  • (type: boolean, default: false)
  • When enabled, shows datetime variable selection and start/end time inputs in the plot area. Off by default — use Global Dimension Slices to subset time by index (e.g. 0:24:2) instead.
  • Dimension Slices (isel) is data-agnostic; a future sel (label-based) feature could complement isel for datetime and other coordinates.
• scientificDataViewer.globalDimensionSlices
  • (type: boolean, default: true)
  • Show Global Dimension Slices (dimension inputs, facet row/col, x/y/hue, bins) in the plot controls area, with dimensions merged from all groups. On by default.
• scientificDataViewer.groupTimeControls
  • (type: boolean, default: false)
  • Show Group Time Controls per group (datetime, start/end) in each group's Plot Controls section. Off by default — use Group Dimension Slices to subset time by index instead (e.g. 0:24:2).
  • When enabled, each group gets its own time/datetime controls.
• scientificDataViewer.groupDimensionSlices
  • (type: boolean, default: true)
  • Show Group Dimension Slices per group (dimension inputs, facet row/col, x/y/hue, bins) in each group's Plot Controls section. On by default. Per-field inheritance: group value when set (non-empty), else global. Only dimension slices are atomic (whole group set or whole global).

Display

• scientificDataViewer.orderGroupsAlphabetically
  • (type: boolean, default: true)
  • When enabled (default), groups from multi-group NetCDF / DataTree files are sorted alphabetically by path in the viewer. Disable to preserve the order returned from the file ([Issue #140](https://github.com/etienneschalk/scientific-data-viewer/issues/140)). Use Refresh (🔄) after changing.
• scientificDataViewer.showXarrayEncodingAttributes
  • (type: boolean, default: true)
  • When enabled (default), the viewer includes xarray encoding metadata as __xarray_encoding.* attribute entries (e.g. _FillValue, dtype, chunking) for groups, coordinates, and variables. Disable to hide these from attribute tables. Use Refresh (🔄) after changing.
• scientificDataViewer.nestedAttributesView
  • (type: boolean, default: true)
  • When enabled, group attributes are shown as an expandable/collapsible tree instead of a flat list. Useful for Zarr (and similar formats) where attributes are stored as nested JSON (e.g. .zattrs). On by default. Set to false to opt out and use the flat list. See [Issue #120](https://github.com/etienneschalk/scientific-data-viewer/issues/120).

🔧 Troubleshooting

⚠️ Common Issues

1. Windows: extension not working (0.8.0 / 0.8.1):

   • Versions 0.8.0 and 0.8.1 have known issues on Windows (e.g. "Invalid response format", "Python environment not ready"). v0.8.2 attempts to fix this. If the problem persists after updating to 0.8.2, use version 0.7.0 as a workaround.

2. Python not found:

   • Ensure Python is installed and in your PATH. Use the "Python: Select Interpreter" command to manually set the path. Consider using the extension's own virtual environment for a self-contained solution.

3. uv not available:

   • Consult the documentation: uv installation. Install uv manually: pip install uv or curl -LsSf https://astral.sh/uv/install.sh | sh. If uv is not installed, the extension will fall back to using the Python extension's interpreter.

4. Missing packages:

   • Install required packages: pip install xarray matplotlib. Install per-format packages: pip install netCDF4 zarr h5py numpy rioxarray. Or let the extension install them automatically (prompt when opening a file).

5. Large files not loading:

   • Increase the maxFileSize setting. Consider using data slicing for very large datasets.

6. Permission errors:

   • Ensure the extension has permission to read your data files. Check file permissions and VSCode workspace settings.

💬 Getting Help

• Consult the Troubleshooting section: Available at the end of the opened file. Copy buttons are present to help creating an issue.
• Check the logs: Ctrl+Shift+P (Command Palette) then type "Scientific Data Viewer: Show Extension Logs"
• Report issues: Create an issue (🐛 Bug Report) on the GitHub repository
• Ask questions: Create an issue (❓ Question / Discussion) on the GitHub repository
• I would like a specific feature: Create an issue (✨ Feature Request) on the GitHub repository to suggest a new feature or enhancement for the Scientific Data Viewer extension

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

🛠️ Development

See the Development Guide

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the NetCDF Viewer extension
• Built with xarray for scientific data processing
• Uses VSCode Extension API for integration