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

HorseHead.fitsF0378_3_FILE_13.BIDRNLA_406359343EDR_T0050104NCAM00505M1.IMGNLA_406359343EDR_M0050104NCAM00505M1.IMG1n128285132edn0000p1500l0m1.img114100.IMGNLF_0100_0675828717_276EDR_T0040218NCAM00503_01_600J03.IMGNLF_0100_0675828717_276EDR_N0040218NCAM00503_01_295J03.IMG

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 line

Command 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
INPInput file or http(s) URL.
OUTOutput file.
FORMATOutput format: vicar, pds, tif, png, jpg, jpeg2000, raw, ... (case-insensitive aliases).
ARGFILERead one set of arguments per line from a file (batch run).
PARALLEL_BATCHRun batch lines in parallel, N at a time, or AVAILABLE_CORES.
IMAGE_INDEXImage to read from a multi-image file (default 0).
SILENTNo printing to stdout.
Data type
OFORMOutput data type: BYTE, HALF, SHORT, USHORT, FULL, INT, REAL, FLOAT, DOUB, DOUBLE. Default: keep the input type.
RESCALERescale values into the new type (default true when OFORM changes the type).
RESCALE_CONSTANT, RESCALE_OFFSETExplicit scale and offset for the conversion.
VALID_MINIMUM, VALID_MAXIMUMUse 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_BANDSBands to read, from 0: READ_BANDS=0,1,2.
BANDSBuild a new image from these bands after reading.
SCALE(xFactor,yFactor,xShift,yShift): resample after reading.
2RGBExpand a single-band image to RGB.
PDS labels
XSLStylesheet that maps the input label to the PDS label. XSL=- uses the default in the jar.
PDS_LABEL_TYPEPDS3 (default), ODL3, MSL_ODL or PDS4.
PDS_STATSaddStatistics or calcStatistics: add image statistics to the label.
EMBED_VICAR_LABELEmbed the VICAR label in the PDS label.
PDS_DETACHED_LABEL, PDS_DETACHED_ONLYWrite a detached label, optionally without rewriting the image.
PDS_OBJECTWhich OBJECT of a PDS3 input label to read (e.g. RFL_IMAGE).
ADD_BINARY_HEADER, ADD_BLOBCarry the VICAR binary header into the output.
VELO_TEMPLATE, VELO_CONFIG, PDS4_NAMESPACE_FILEVelocity template and setup for a PDS4 detached label.
Help and debugging
HELPPrint the full keyword list.
PLUGINSList the registered ImageIO readers and writers.
XMLWrite the label as XML files (debugging).
DEBUGExtra 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

FormatReadWriteNotes
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✓labelReads PDS4 array products; PDS4 labels are generated from Velocity templates.
PDS4 tables✓textExported 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 report

Capabilities

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.

CapabilityTestsPassedFailed
VICAR image read/write
Reading and writing VICAR images in every data type (BYTE, HALF, FULL, REAL, DOUB) and organization (BSQ, BIL, BIP), in both byte orders, including degenerate shapes and damaged files.
suite 3 unit 12 nominal 30 lossless 18 legacy 3 off-nominal 3 regression 10 malformed-input 5
53 tests
TestScopeResult
byte: BSQ, BIL and BIP decode to the same pixelsnominalPassed
byte/bsq: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
byte/bil: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
byte/bip: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
half: BSQ, BIL and BIP decode to the same pixelsnominalPassed
half/bsq: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
half/bil: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
half/bip: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
full: BSQ, BIL and BIP decode to the same pixelsnominalPassed
full/bsq: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
full/bil: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
full/bip: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
real: BSQ, BIL and BIP decode to the same pixelsnominalPassed
real/bsq: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
real/bil: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
real/bip: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
doub: BSQ, BIL and BIP decode to the same pixelsnominalPassed
doub/bsq: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
doub/bil: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
doub/bip: VICAR to VICAR round trip keeps type and pixelsnominal losslessPassed
degenerate shape gen_byte_ns1_nl1024.vic survives VICAR and PDS round tripslegacy off-nominal losslessPassed
degenerate shape gen_byte_ns1024_nl1.vic survives VICAR and PDS round tripslegacy off-nominal losslessPassed
degenerate shape gen_real_100x100.vic survives VICAR and PDS round tripslegacy off-nominal losslessPassed
jConvertIIO decodes little-endian int16 (INTFMT/REALFMT LOW)nominalPassed
jConvertIIO decodes little-endian float32-bsq (INTFMT/REALFMT LOW)nominalPassed
little-endian float32 BSQ, BIL and BIP agree after conversionnominalPassed
ImageIO API decodes little-endian HALF the same as BYTE 1..24nominal regressionPassed
ImageIO API decodes little-endian int16 the same on every input streamnominal regressionPassed
ImageIO API decodes little-endian int32 the same on every input streamnominal regressionPassed
ImageIO API decodes little-endian float32-bsq the same on every input streamnominal regressionPassed
ImageIO API decodes little-endian float64 the same on every input streamnominal regressionPassed
reads bigendian-int16 (system label with DAT_TIM/BINC)malformed-input regressionPassed
reads bigendian-float32 (system label with DAT_TIM/BINC)malformed-input regressionPassed
reads vax-float32 (system label with DAT_TIM/BINC)malformed-input regressionPassed
big-endian and VAX float32 fixtures decode to the same valuesmalformed-input regressionPassed
jConvertIIO decodes little-endian DOUB (float64) and FULL (int32) fixturesnominalPassed
binary line prefix fixture decodes to its 1x1 imagenominalPassed
truncated VICAR file fails with a non-zero exitmalformed-input regressionPassed
malformedLabelFailsWithIIOExceptionForWidthunitPassed
malformedLabelFailsWithIIOExceptionunitPassed
littleEndianFileOnBigEndianStreamunitPassed
littleEndianThroughImageioExtStreamunitPassed
directPathOnlyForStreamsThatHonourByteOrderunitPassed
bigEndianThroughImageioExtStreamunitPassed
littleEndianThroughJdkStreamunitPassed
programmaticAddStillRejectsUserInPropertyLabelunitPassed
readMovesUserOutOfPropertySetunitPassed
testunitPassed
programmaticAddStillRejectsDatTimInSystemLabelunitPassed
readKeepsOrphanedHistoryItemsInUnknownTaskunitPassed
class is listed under a feature in features.ymlsuitePassed
class is listed under a feature in features.ymlsuitePassed
class is listed under a feature in features.ymlsuitePassed
53530
VICAR binary headers and prefixes
Images with binary label headers and per-line prefixes (NLB/NBB): decoding them, and keeping the prefix bytes when converting to VICAR or PDS (KEEP_LINE_PREFIX, ADD_BINARY_HEADER).
suite 1 unit 6 mission-data 8 lossless 9 regression 5 off-nominal 3 nominal 1
18 tests
18180
PDS3 products
Reading PDS3 products (attached and detached labels, dual PDS3/VICAR labels) and writing PDS3 with an embedded VICAR label, file name in the label, or ODL3 labels.
suite 2 unit 7 nominal 5 lossless 7 regression 6 off-nominal 1 mission-data 8 legacy 1
23 tests
TestScopeResult
VICAR to PDS3 writes a valid label and keeps pixelsnominal losslessPassed
EMBED_VICAR_LABEL=true embeds the VICAR labelnominal losslessPassed
PDS_FILENAME_IN_LABEL=true puts the output file name in the labelnominal regression losslessPassed
PDS_FILENAME (older spelling) still puts the file name in the labelnominal regressionPassed
without PDS_FILENAME_IN_LABEL, or with =false, the label names no fileoff-nominal regressionPassed
PDS_LABEL_TYPE=ODL3 writes an ODL3 labelnominalPassed
reads an MSL Navcam EDR thumbnail (attached PDS3 + VICAR labels)mission-data losslessPassed
reads an MSL Navcam EDR through its detached .LBLmission-data regression losslessPassed
namespaced PDS3 keywords (MSL:...) become legal VICAR keywordsmission-data regressionPassed
PDS-labelled input to FORMAT=pds with the default stylesheetmission-data regressionPassed
PDS-labelled input to FORMAT=pds with an explicit copy stylesheetmission-data losslessPassed
MSL Navcam full EDR reads and round-trips through VICARmission-data losslessPassed
MER Opportunity Navcam EDR reads (stand-in for the legacy mer_file.vic)mission-data legacyPassed
Cassini ISS: VICAR image and its detached PDS3 label decode identicallymission-dataPassed
fileChannelStreamSeekPastEndReadsEofunitPassed
headerPointerAtStartOfDataFileKeepsVicarLabelunitPassed
headerPointerPastEndOfLabelFileunitPassed
noImageObjectProducesEmptySystemLabelunitPassed
readsRflImageWithExplicitParamunitPassed
readsRflImageViaHeuristicWhenParamUnsetunitPassed
readsStandardImageObjectunitPassed
class is listed under a feature in features.ymlsuitePassed
class is listed under a feature in features.ymlsuitePassed
23230
PDS label transcoding (XSL)
Building PDS labels from VICAR labels with the bundled XSL stylesheets, the default stylesheet (XSL=-) and the legacy mission recipes.
nominal 3 lossless 3 legacy 3 mission-data 2 off-nominal 1 regression 1
5 tests
550
PDS4 images
Reading images through PDS4 XML labels; the PDS4 view must match the attached-label view of the same data.
mission-data 4 lossless 2 nominal 1
4 tests
440
PDS4 tables
Exporting PDS4 tables (character, delimited) as CSV or fixed-width text, with the bundled ExtractTableJPL tool and jConvertIIO's PDS4_TABLE_* keywords.
nominal 12 off-nominal 5 regression 13
17 tests
17160
ISIS cubes
Reading ISIS2 cubes with SFDU labels, such as Cassini VIMS spectral cubes (ISIS3 cubes are not supported).
nominal 2 regression 3 mission-data 1 off-nominal 1 malformed-input 1 suite 1 unit 3
7 tests
770
FITS images
Reading FITS images and converting them to other formats.
mission-data 1 lossless 1
1 test
TestScopeResult
reads HorseHead.fits and converts it to VICAR and TIFFmission-data losslessPassed
110
Magellan products
Reading Magellan F-BIDR radar image strips (full-resolution basic image data records). The resampled format (MgnResampImageReader) has no public sample and is not tested.
mission-data 2 regression 2 lossless 1
2 tests
TestScopeResult
F-BIDR reader decodes the orbit 378 image stripmission-data regressionPassed
jConvertIIO converts the F-BIDR to VICARmission-data regression losslessPassed
220
Output formats
Every FORMAT= name and alias used by the legacy test (TIFF, PNG, JPEG/JFIF, JPEG 2000, BMP, PNM, RAW, PDS, VICAR), for 8-bit, 16-bit and float images. The legacy test also listed ISIS, JPEG-LS and JPEG-LOSSLESS; those tests are skipped because this build has no writer for them. RAW is headerless band-sequential; PNM is written by vicario's own PGM/PPM writer. TIFF output can be read back as input.
suite 1 unit 4 legacy 29 lossless 36 nominal 26 regression 18 off-nominal 15
60 tests
TestScopeResult
FORMAT=tif (#01)legacy losslessPassed
FORMAT=tiff (#02)legacy losslessPassed
FORMAT=TIF (#03)legacy losslessPassed
FORMAT=TIFF (#04)legacy losslessPassed
FORMAT=png (#05)legacy losslessPassed
FORMAT=PNG (#06)legacy losslessPassed
FORMAT=jpeg2000 (#07)legacy losslessPassed
FORMAT=JPEG2000 (#08)legacy losslessPassed
FORMAT=JPEG 2000 (#09)legacy losslessPassed
FORMAT=jpeg 2000 (#10)legacy losslessPassed
FORMAT=pds (#11)legacy losslessPassed
FORMAT=vicar (#12)legacy losslessPassed
FORMAT=jpg (#13)legacy nominalPassed
FORMAT=JPG (#14)legacy nominalPassed
FORMAT=jpeg (#15)legacy nominalPassed
FORMAT=JPEG (#16)legacy nominalPassed
FORMAT=raw (#17)legacy nominal lossless regressionPassed
FORMAT=RAW (#18)legacy nominal lossless regressionPassed
FORMAT=bmp (#19)legacy lossless regressionPassed
FORMAT=BMP (#20)legacy lossless regressionPassed
FORMAT=pnm (#21)legacy nominal lossless regressionPassed
FORMAT=PNM (#22)legacy nominal lossless regressionPassed
FORMAT=jfif (#23)legacy nominalPassed
FORMAT=JFIF (#24)legacy nominalPassed
FORMAT=jpeg-ls (#25)legacy off-nominalKnown issue
FORMAT=JPEG-LS (#26)legacy off-nominalKnown issue
FORMAT=jpeg-lossless (#27)legacy off-nominalKnown issue
FORMAT=JPEG-LOSSLESS (#28)legacy off-nominalKnown issue
FORMAT=isis (#29)legacy off-nominalKnown issue
RAW output of gen_byte_bil.vic is exactly its samples, band sequentialnominal lossless regressionPassed
RAW output of gen_byte_bip.vic is exactly its samples, band sequentialnominal lossless regressionPassed
RAW output of gen_byte_gray.vic is exactly its samples, band sequentialnominal lossless regressionPassed
RAW output of gen_half_bsq.vic is exactly its samples, band sequentialnominal lossless regressionPassed
RAW output of gen_real_100x100.vic is exactly its samples, band sequentialoff-nominal lossless regressionPassed
RAW output of gen_byte_ns1_nl1024.vic is exactly its samples, band sequentialoff-nominal lossless regressionPassed
BMP output of a band-interleaved-by-line (BIL) image keeps its pixelsnominal lossless regressionPassed
HALF input to BMP without OFORM is refused with a non-zero exitoff-nominalPassed
a writer that crashes fails the conversion cleanlyoff-nominal regressionPassed
PNM output of gen_byte_gray.vic keeps its pixelsnominal lossless regressionPassed
PNM output of gen_half_bsq.vic keeps its pixelsnominal lossless regressionPassed
PNM output of gen_real_bsq.vic is refused with a messageoff-nominalPassed
PNM output of gen_byte_rgba.vic is refused with a messageoff-nominalPassed
a PNM file written by jConvertIIO can be read back as inputoff-nominalKnown issue
a TIFF file written by jConvertIIO can be read back as inputnominal lossless regressionPassed
HALF input to FORMAT=tif is losslessnominal losslessPassed
HALF input to FORMAT=png is losslessnominal losslessPassed
HALF input to FORMAT=jpeg2000 is losslessnominal losslessPassed
HALF input to FORMAT=pds is losslessnominal losslessPassed
HALF input to FORMAT=vicar is losslessnominal losslessPassed
REAL input to FORMAT=tif is losslessnominal losslessPassed
REAL input to FORMAT=pds is losslessnominal losslessPassed
REAL input to FORMAT=vicar is losslessnominal losslessPassed
a FORMAT with no registered writer is refused with a messageoff-nominalPassed
REAL input to PNG without OFORM is refused with a non-zero exitoff-nominalPassed
HALF input to JPEG without OFORM is refused with a non-zero exitoff-nominal regressionPassed
preferOverRemovesTheJaiImageioWriterunitPassed
writesEightBitGrayAsP5unitPassed
writesSixteenBitRgbAsBigEndianP6unitPassed
refusesFourBandsunitPassed
class is listed under a feature in features.ymlsuitePassed
60540
Data type conversion
Changing the output data type (OFORM) with or without rescaling, clamping, and float data to 8-bit display formats.
nominal 13 legacy 1 regression 7 lossless 4 off-nominal 1 mission-data 1
14 tests
14140
Regions, subsampling and bands
Cropping (SOURCE_REGION, CROP), subsampling, scaling, band selection and reordering (READ_BANDS, BANDS), single band to RGB (2RGB), and PNG alpha (WRITE_TRANSPARENCY).
nominal 11 off-nominal 2 regression 6 lossless 2
13 tests
13130
XML metadata and parser security
Label DOM utilities and XML debug output (XML=true), with every XML parser hardened against external entity (XXE) attacks.
suite 1 unit 12 nominal 1 security 4 malformed-input 4 regression 3
18 tests
18180
Batch, streaming and remote input
Batch runs from an argument file (serial and parallel), files without extensions, output to stdout, and https input from the public PDS archive.
nominal 4 lossless 6 off-nominal 4 regression 6 mission-data 1
9 tests
TestScopeResult
ARGFILE batch runs every linenominal losslessPassed
ARGFILE batch with PARALLEL_BATCH=2 runs every linenominal losslessPassed
input and output file names without extensionsoff-nominal regression losslessPassed
OUT=- with SILENT writes the image to stdoutnominal regression losslessPassed
OUT=- without SILENT keeps messages off stdoutnominal regression losslessPassed
FORMAT without OUT, and OUT=- without FORMAT, are refusedoff-nominal regressionPassed
OUT=- on an ARGFILE line is refusedoff-nominal regressionPassed
OUT=- on an ARGFILE line is refused (PARALLEL_BATCH=2)off-nominal regressionPassed
https input from the public PDS archive matches the local copymission-data losslessPassed
990
Visual check (replaces JADE review)
Every output a person would look at decodes to an image of the right size that is neither blank nor saturated, with a preview in the report. Replaces opening each output in the JADE viewer in the legacy procedure; the viewer itself is not tested.
legacy 8 nominal 1 mission-data 7
8 tests
880
Python label scripts
The Python utilities in src/main/scripts: xml_swap.py (replace, list and show modes, XXE hardening) and build_mesh_extras.py (mesh label extras, path validation).
nominal 3 security 2 malformed-input 1 regression 2 off-nominal 1
5 tests
550
PDS4 label generation (Labelocity)
Generating detached PDS4 labels from Velocity templates with the public Labelocity release (PDS4 writer and mission templates) and the vicario build under test. Generated labels must match the archive label's array structure and read back to the same pixels.
mission-data 2 nominal 2
2 tests
220