Pixel Clarity

A fast scientific image viewer for VS Code, built for working on remote machines. It opens FITS, ASDF, HDF5 and NumPy files, plus TIFF and PNG, as an editor tab, lays out the detectors of a multi-detector exposure as one mosaic, and opens ECSV, CSV and Parquet tables (catalogs, curves, time series) in a table viewer with filtering, statistics and plots.

File formats

• FITS (.fits, .fit, .fts, .fits.gz, .fits.fz): every HDU, scaled and blank values, cubes and world coordinates. Tile-compressed images (RICE_1, GZIP_1, GZIP_2, NOCOMPRESS) are decompressed as they are read, so large ones stream instead of being unpacked whole.
• ASDF (.asdf): every array in the tree, listed by path, with units and the tree as searchable metadata. Uncompressed and lz4 blocks stream from disk. World coordinates come from the file's gwcs.
• HDF5 (.h5, .hdf5, .he5): every dataset, with its attributes.
• NumPy (.npy, .npz): integer, float and bool arrays, compressed or not.
• TIFF and PNG: 8/16-bit and float, multi-page, color. TIFF opens in Pixel Clarity by default; PNG keeps VS Code's preview unless you choose Open in Pixel Clarity.
• Tables: ECSV, CSV and TSV (also gzipped), with ECSV types, units and metadata, and sniffed delimiters and types for plain CSV; Parquet from astropy, pandas, pyarrow and other writers, with astropy's units, masked and time columns kept. 64-bit IDs stay exact. Very large Parquet files let you choose which columns to load.

Features

• Stretch: linear, log, pow, sqrt, squared, asinh, sinh, histogram equalization and midtone scales; min/max, zscale, percentile or typed limits, which can be locked across slices and reloads.
• Auto enhance: Auto in the toolbar (or Shift+A) stretches an image for sharing in one click: a dark background, faint structure lifted and bright parts kept. For color images the sky comes out neutral, the channels are balanced and the colors are saturated. Its menu sets the sky brightness, color, warmth and tint; Make this white balances the colors on a star or region; Revert goes back.
• Mouse and keyboard: right-drag adjusts contrast and bias, the wheel zooms about the pointer, and the arrow keys move the crosshair a pixel at a time.
• RGB composites: three planes or three files as red, green and blue, each with its own limits (linked by default). Files of different sizes or pointings are aligned through their WCS. A legend names each channel's file, and a toggle shows the composite only where every channel has data.
• Colormaps: classic astronomy maps plus matplotlib's perceptual and diverging maps, with invert.
• Cuts and histogram: row and column cuts aligned with the image, and a histogram with draggable limits and the stretch curve.
• World coordinates: RA/Dec (or galactic, ecliptic or linear axes) under the cursor, a compass, and plate scale and rotation in the Info panel, from common FITS projections with SIP distortion.
• Sky services: What is this? in the right-click menu lists the SIMBAD objects near a point, and the Aladin Lite panel shows a sky survey around the view, following its pan, zoom and orientation.
• Regions: box, circle, line and point, with statistics and a centroid. Type exact coordinates in image or sky units, show statistics on the image, plot a region through a cube's planes or a file's frames, and save and load .reg files compatible with DS9. Large region files load as a fast overlay.
• Text on the image: write labels anywhere; they keep their size as you zoom and are saved with the regions.
• Inspection: pixel table, magnifier, navigator, a searchable header and metadata panel, an array picker and a cube slider with play.
• Data quality masks: an image with a DQ array gets a panel listing the mask's bits and how many pixels have each, with flag names where the file's data model defines them. Tick bits to color them over the image; flags stay visible at any zoom.
• Export: a full-resolution PNG of the whole image, the view or a box, optionally block-averaged and with text, regions and a colorbar, rendered on the machine with the data. Save view as shown saves the screen.
• Live reload: the view refreshes when the file is rewritten, keeping zoom, stretch and regions.

Sharing a view

Share in the toolbar (or Pixel Clarity: Share View as Web Page…) saves the view as one HTML file that opens in any browser, with no install: the same viewer, opening as you left it, with its stretch, colors, regions and text, under a title, caption and credit. Readers can pan, zoom, restretch, read values and coordinates, measure regions, take cuts and export images.

• The page holds a preview of each image, so it opens at once anywhere.
• By default full resolution comes with it as compact data: only the images the view shows, each value kept to within a quarter of its noise (as fpack does), which no stretch can show. Every tool keeps working, at a fraction of the files' size. It goes in the page, or in a folder beside it for a web server. Integer images are kept exactly; data-quality and error arrays stay behind.
• Or full resolution is read from the files themselves, only for the part on screen, from wherever the reader can reach them:
  • In the page: the files themselves, for a page that works on its own.
  • A URL: by default the files' paths from where the page is saved, so a page uploaded with its data (to a web server or a storage bucket) finds it. You can give a base URL, or one URL per file; signed links to private storage work. The host must answer HTTP Range requests and, for a page served from elsewhere, allow it to read the files (CORS).
  • The reader's own copy: Data → Choose files… (or dropping the files on the page) reads them from the reader's disk. Nothing is uploaded.
• Each file is checked by size and a fingerprint, so a page never shows another file of the same name.
• Download saves the view as shown, a full-resolution image, or the data files.
• With the sky services on, readers have What is this? and the Aladin Lite panel too, beside the image; Aladin Lite loads from CDS only when they open it.
• h (or the toolbar's Hide tools) shows the image alone, here and in a shared page, for a clean look or a screenshot; h or Esc brings the tools back.
• Without the data the page shows the preview, and values come from what is on screen.

Defaults

The Pixel Clarity icon in the activity bar opens a Defaults panel for how new viewers start: colormap, scale, limits, zoom, coordinate format, Auto enhance, panels, RGB and mosaic options, tables, remote transfer and sky services. Use current image's look saves the focused image's look as the defaults, and Apply to open images applies them. The panel edits the ordinary pixelClarity.* settings.

Mosaics

Select the detector files of an exposure and choose Open as Mosaic, or right-click their folder. The mosaic is an ordinary image tab: stretch, regions, overlays and exports work as for one image.

• Layout: placed on a north-up plane by their sky coordinates, by the instrument's focal-plane layout when it is known, or side by side.
• Detectors panel: show, hide and pick detectors; one that differs from the rest is flagged.
• Matched levels: a calibration factor per detector, then sky offsets, so the edges don't show. Feather blends overlaps, Edges trims borders, and each detector can be trimmed by hand.
• Color mosaics: tiles in two or more filters can be shown as one color image, longest wavelength red. Select the tiles (or their folder), or one folder per filter, and choose Open as RGB. Each filter's color can be changed in the panel.
• Save mosaic writes a .pcmosaic file that brings the mosaic back.

Stacks of files

Frames written one per file can be viewed and plotted as one stack: select the files and choose Open as Stack, or right-click their folder. The slider and play step through the files, keeping the view, and regions plot through the stack as through a cube.

Table viewer

Catalogs, photometry tables, instrument curves and time series open as a grid that scrolls smoothly through millions of rows.

• Search and filters: filter with Python-like expressions, with autocomplete and inline errors, or from the data itself (a cell, a common value, a histogram range, a box on the plot).
• Sort, arrange and compute: multi-column sort, reorder, resize, pin and hide columns, and add computed columns.
• Inspect: a row panel for wide catalogs and a column panel with statistics, a histogram and common values.
• Plot: scatter (density-binned for large tables), lines, histograms, time and log axes, color by a column.
• Export: CSV, TSV, ECSV or a region file, or overlay the rows on an open image.

Built for remote work

When VS Code is attached over SSH or to a container, the data stays on the remote machine:

• Decoding, statistics and table operations run next to the file.
• The viewer renders locally on your GPU, so panning, zooming and re-stretching never touch the network.
• Only the tiles on screen are sent, coarse first, then detail; full-resolution tiles are lossless.
• Very large images are streamed from disk rather than loaded whole.
• SIMBAD and Aladin Lite are reached from your own computer and receive only sky positions; pixelClarity.online turns them off.

Keys

f fit · 1/2/4 zoom · z zscale · m min/max · s cycle scale · i invert · r reset contrast · Shift+A auto enhance · c crosshair · [ ] slices · space play · b/o/l/p region tools · t text · e region coordinates · g plot region vs plane · a statistics on the image · F2 label · Esc pan tool · ? help

Acknowledgements

Thanks to Maxime Rizzo and David Morgan, who tried Pixel Clarity early and whose feedback and feature requests helped shape it.

What is this? uses the SIMBAD database, operated at CDS, Strasbourg, France (Wenger et al. 2000, A&AS 143, 9). The sky panel is Aladin Lite (Boch & Fernique 2014, ASP Conf. Ser. 485, 277), also from CDS, loaded from aladin.cds.unistra.fr when the panel opens; it is not bundled with the extension. If SIMBAD or Aladin Lite helps your research, please acknowledge them as CDS asks.

The zscale algorithm is ported from astropy, which derives it from STScI's numdisplay. The colormap tables come from matplotlib. Licenses for these and for the bundled npm packages are in THIRD_PARTY_NOTICES.md, which ships with the extension.

License

MIT © 2026 Clarity Orbital Inc. See LICENSE.

Development

npm install
npm test                 # decoder + statistics tests against astropy/numpy/h5py fixtures
npm run dev              # build + browser harness at http://localhost:5178 (add &rtt=150&mbps=10 to throttle)
npm run package          # → pixel-clarity-<version>.vsix

To regenerate the test fixtures (nothing is installed into conda base):

uv run --no-project --with numpy --with astropy --with h5py --with tifffile --with pillow --with asdf --with asdf-astropy --with lz4 --with pyarrow --with pandas --with gwcs python scripts/make_fixtures.py

Releasing

1. Add notes under ## Unreleased in CHANGELOG.md as you go.
2. npm run release -- patch (or minor, major, 1.2.3). This bumps the version, moves the notes under it, commits Release vX.Y.Z and tags vX.Y.Z.
3. git push origin main --follow-tags. The Release workflow tests the tag, builds the extension and attaches it as pixel-clarity.vsix to a GitHub release named after the tag, with the same notes.
4. Download the .vsix from that release and upload it to the Marketplace (publisher clarity-orbital → Pixel Clarity → Update).