Image format translation for planetary science data
VICARIO is a Java library and command-line tool that converts images between planetary archive formats (VICAR, PDS3, PDS4, ISIS, FITS) and standard formats (TIFF, PNG, JPEG), keeping the label metadata. It is part of NASA's AMMOS Instrument Data Subsystem and is developed by JPL's Multimission Image Processing Laboratory.
Latest test run passed: 277 tests, 0 failed · 2026-11-20 21:46 UTC · commit 39ba569








Public mission products (Mars 2020, MSL, MER, Cassini and others) decoded by the latest test run.
What it does
Reads planetary formats
VICAR, PDS3 (attached or detached labels), PDS4 images and tables, ISIS cubes, FITS and Magellan products.
Writes archive and standard formats
VICAR, PDS3, TIFF, PNG, JPEG, JPEG 2000 and raw, with data type conversion, regions, subsampling and band selection.
Keeps the metadata
Labels are carried across conversions. XSL transcoders map VICAR labels to PDS labels; PDS4 labels are generated from Velocity templates.
Plugs into Java ImageIO
The readers and writers register as ImageIO plugins, so ImageIO.read opens VICAR and PDS files directly.
Install
VICARIO 2.7.2 is published to Maven Central. It is built for Java 8 and tested on Java 17.
Maven
<dependency>
<groupId>gov.nasa.jpl.ammos.ids</groupId>
<artifactId>vicario</artifactId>
<version>2.7.2</version>
</dependency>Gradle
implementation("gov.nasa.jpl.ammos.ids:vicario:2.7.2")
Build from source
git clone https://github.com/NASA-AMMOS/vicario.git
cd vicario
mvn -U -Pshade clean install # target/vicario-2.7.2-FAT.jar for the command lineCommand line: jConvertIIO
The FAT jar runs the converter. Arguments are KEYWORD=value pairs; keyword names are not case-sensitive, and a true/false keyword given alone means true.
java -jar vicario-2.7.2-FAT.jar inp=<input> out=<output> format=<format> [KEYWORD=value ...]
java -jar vicario-2.7.2-FAT.jar HELP # every keyword
VICAR to PNG
java -jar vicario-2.7.2-FAT.jar inp=image.vic out=image.png format=png
Floating-point image to an 8-bit PNG (stretched to 0..255)
java -jar vicario-2.7.2-FAT.jar inp=real.vic out=real.png format=png OFORM=BYTE
VICAR to PDS3 with an attached label
java -jar vicario-2.7.2-FAT.jar inp=image.vic out=image.img format=pds
PDS3 or PDS4 product to VICAR
java -jar vicario-2.7.2-FAT.jar inp=product.xml out=image.vic format=vicar
Cut out a region (x, y, width, height)
java -jar vicario-2.7.2-FAT.jar inp=image.vic out=region.vic format=vicar SOURCE_REGION=(10,10,200,100)
Quarter-size preview (every 4th sample and line)
java -jar vicario-2.7.2-FAT.jar inp=image.vic out=thumb.png format=png SUBSAMPLING=(4,4,0,0)
Batch: one conversion per line of jobs.txt, 4 at a time
java -jar vicario-2.7.2-FAT.jar ARGFILE=jobs.txt PARALLEL_BATCH=4
On recent JDKs, JAI prints a "Could not find mediaLib accelerator" warning; add -Dcom.sun.media.jai.disableMediaLib=true before -jar to silence it.
Keywords
The most used keywords. HELP prints the full list, including tiling and cache settings.
Input and output
| INP | Input file or http(s) URL. |
| OUT | Output file. |
| FORMAT | Output format: vicar, pds, tif, png, jpg, jpeg2000, raw, ... (case-insensitive aliases). |
| ARGFILE | Read one set of arguments per line from a file (batch run). |
| PARALLEL_BATCH | Run batch lines in parallel, N at a time, or AVAILABLE_CORES. |
| IMAGE_INDEX | Image to read from a multi-image file (default 0). |
| SILENT | No printing to stdout. |
Data type
| OFORM | Output data type: BYTE, HALF, SHORT, USHORT, FULL, INT, REAL, FLOAT, DOUB, DOUBLE. Default: keep the input type. |
| RESCALE | Rescale values into the new type (default true when OFORM changes the type). |
| RESCALE_CONSTANT, RESCALE_OFFSET | Explicit scale and offset for the conversion. |
| VALID_MINIMUM, VALID_MAXIMUM | Use this range instead of the data range when rescaling. |
| CLAMP | (min,max): clamp values after reading. |
Regions and bands
| SOURCE_REGION | (x,y,width,height): read only this region. |
| SUBSAMPLING | (xStep,yStep,xOffset,yOffset): read every Nth sample and line. |
| READ_BANDS | Bands to read, from 0: READ_BANDS=0,1,2. |
| BANDS | Build a new image from these bands after reading. |
| SCALE | (xFactor,yFactor,xShift,yShift): resample after reading. |
| 2RGB | Expand a single-band image to RGB. |
PDS labels
| XSL | Stylesheet that maps the input label to the PDS label. XSL=- uses the default in the jar. |
| PDS_LABEL_TYPE | PDS3 (default), ODL3, MSL_ODL or PDS4. |
| PDS_STATS | addStatistics or calcStatistics: add image statistics to the label. |
| EMBED_VICAR_LABEL | Embed the VICAR label in the PDS label. |
| PDS_DETACHED_LABEL, PDS_DETACHED_ONLY | Write a detached label, optionally without rewriting the image. |
| PDS_OBJECT | Which OBJECT of a PDS3 input label to read (e.g. RFL_IMAGE). |
| ADD_BINARY_HEADER, ADD_BLOB | Carry the VICAR binary header into the output. |
| VELO_TEMPLATE, VELO_CONFIG, PDS4_NAMESPACE_FILE | Velocity template and setup for a PDS4 detached label. |
Help and debugging
| HELP | Print the full keyword list. |
| PLUGINS | List the registered ImageIO readers and writers. |
| XML | Write the label as XML files (debugging). |
| DEBUG | Extra debug printing. |
PDS4 tables
java -cp vicario-2.7.2-FAT.jar jpl.mipl.io.util.ExtractTableJPL -c -o table.csv product.xml # -w for fixed-width text
Java library
With VICARIO on the classpath, the VICAR, PDS3, ISIS and FITS readers are found through the standard ImageIO plugin lookup:
import java.awt.image.BufferedImage;
import java.io.File;
import javax.imageio.ImageIO;
BufferedImage img = ImageIO.read(new File("image.vic")); // VICAR, PDS3, ISIS, FITS
ImageIO.write(img, "png", new File("image.png"));
The source has the full API, including the label (metadata) classes and the PDS4 readers.
Formats
| Format | Read | Write | Notes |
|---|---|---|---|
| VICAR | ✓ | ✓ | All data types and organizations (BSQ, BIL, BIP), binary headers and line prefixes. |
| PDS3 | ✓ | ✓ | Attached or detached labels; PDS3, ODL3 or MSL ODL labels written through XSL transcoders. |
| PDS4 images | ✓ | label | Reads PDS4 array products; PDS4 labels are generated from Velocity templates. |
| PDS4 tables | ✓ | text | Exported to CSV or fixed-width text with ExtractTableJPL. |
| ISIS cubes | ✓ | ISIS2 / ISIS3 cube reader. | |
| FITS | ✓ | Primary image HDU. | |
| Magellan | ✓ | F-BIDR and resampled products. | |
| TIFF, PNG, JPEG, JPEG 2000 | ✓ | ✓ | Through the Java ImageIO and JAI Image I/O plugins. |
| Raw | ✓ | Headerless pixel data. |
Testing
Every change runs a feature test suite: the real jConvertIIO command against synthetic images and public mission products from the PDS, with each output decoded and compared pixel for pixel. The full suite runs on every merge to main and every release, and publishes the report linked here.
Latest test run passed: 277 tests, 0 failed · 2026-11-20 21:46 UTC · commit 39ba569
Test proceduresTest reportCapabilities
Each capability is a feature in the test suite. Click one to read its test procedures: what each test does and what makes it pass. Open its test list for a summary of every test, linked to that test's procedure. The tags count tests by the kind of testing (nominal, off-nominal, malformed input, lossless, mission data, ...). Passed excludes tests that document a known bug.