Launch Options

Last updated: 2026-10-08

This page covers how Perspecta opens local files, grouped review sets, reports, and perspecta:// URLs from external systems.

For keyboard, mouse, layout, and overlay behavior after content opens, see Viewer Basics.

CLI Inspection

Run perspecta --version to print perspecta <version> and exit without a graphical display or log output. The version includes any local build suffix, as in the viewer.

Use inspect to read a technical summary of one local DICOM file:

perspecta inspect example-data/image.dcm
perspecta inspect --help

The command runs without a graphical display. The default file size limit is 4096 MiB (4 GiB). It rejects files above the selected limit before it calls the reader. For files within this limit, it reads the complete file into memory through the viewer’s reader, including its existing repairs. It does not modify the file or decode pixels. Successful inspection does not confirm that the pixels can be decoded or validate DICOM conformance.

An NHS evaluation (Table 3) reports uncompressed HD tomosynthesis files up to 2835.4 MB. The default leaves room above that example. Larger objects require an explicit limit.

Use --max-file-mib before the file name to set a different limit, such as 8 GiB:

perspecta inspect --max-file-mib 8192 example-data/image.dcm

The value must be a positive whole number of MiB (1 MiB = 1048576 bytes). Zero, fractions, duplicate options, and values that overflow the byte count produce invalid_arguments. The limit applies to the file size. Parsing and repairs can require additional memory beyond that size.

JSON Output

Success writes one JSON object and a newline to standard output. Standard error is empty, even when RUST_LOG is set.

Absent fields are null. Empty text fields are also null. Image and Parametric Map objects can have dimensions and frame counts. These fields are null for all other kinds.

An absent NumberOfFrames remains null, without an assumed value of 1. For images and Parametric Maps, present numeric fields must contain one positive integer within the stated range. Empty, negative, fractional, multiple, or oversized values produce invalid_metadata.

{"schema_version":1,"kind":"image","modality":"MG","sop_class_uid":"1.2.840.10008.5.1.4.1.1.1.2","transfer_syntax_uid":"1.2.840.10008.1.2.1","rows":1024,"columns":1024,"number_of_frames":1}

The summary includes only the fields in this table. It excludes patient fields, study/series/instance identifiers, file paths, and free-text descriptions. The command reports selected metadata. It does not anonymize the source file.

Errors and Exit Codes

File, data, and argument errors leave standard output empty. Standard error contains one JSON error object and a newline:

{"schema_version":1,"error":{"code":"invalid_metadata","message":"Invalid NumberOfFrames value in the DICOM dataset."}}

Use error.code for programmatic decisions. Error messages exclude input paths and raw DICOM values. For file_too_large, the message gives the file size in bytes, the active limit, and the minimum required --max-file-mib value. This required value rounds up to the next whole MiB when necessary. The message also explains that memory use can exceed the file size. An output error can leave a partial result. Discard output when the exit code is not 0. If standard error is unavailable, the command still returns a failure code.

File Names and Viewer Launch

Use -- before a file name that starts with a hyphen:

perspecta inspect -- -example.dcm

perspecta inspect --help, perspecta inspect -h, and perspecta --help print usage text and exit with 0. To open a file named inspect in the viewer, use perspecta --open inspect or perspecta ./inspect. Existing file, grouped, and perspecta:// launches continue to open the viewer.

CLI PNG Export

Use render to export one frame from one local DICOM image without a graphical display:

perspecta render --output-file preview.png --frame 1 -- example-data/image.dcm
perspecta render --max-file-mib 8192 --frame 2 --output-file frame-2.png -- example-data/multiframe.dcm
perspecta render --window-center 40 --window-width 400 --max-dimension 2048 -- example-data/image.dcm > windowed-preview.png
perspecta render --help

The output format defaults to PNG. --output png makes this choice explicit. Other formats are not supported. --frame accepts a positive whole number and defaults to 1. Frame numbers follow stored DICOM order. The viewer can reverse its display order based on patient position, so its frame numbers can differ.

An absent NumberOfFrames means one frame for export. inspect continues to report the absent field as null.

Options must precede the file name and can appear in any order. Duplicate options produce invalid_arguments. Use -- before a file name that starts with a hyphen. Native file names do not need UTF-8 encoding. To open a file named render in the viewer, use perspecta --open render or perspecta ./render.

Export shares the inspection limit of 4096 MiB (4 GiB) and accepts --max-file-mib to change it. It reads the complete file, with the same repairs, and decodes only the selected frame. The file size limit does not bound total memory use. Repairs, pixel decoding, and PNG encoding require additional memory.

--max-pixels limits the selected frame’s declared Rows × Columns before pixel decoding. The default is 192,000,000 pixels per frame. Use a positive whole number, for example --max-pixels 240000000, when the frame and available memory require a larger limit. The error reports the declared pixel count, active limit, and minimum required value. This limit is not a hard RAM bound or validation of dimensions inside compressed data.

Pixels and Metadata

Export supports 8-bit and 16-bit monochrome and RGB images. Compressed images require a decoder supported by the installed build. The selected frame keeps its stored dimensions by default, and always keeps its stored orientation.

--max-dimension reduces the longest PNG side to the given positive number of pixels, without upscaling. It preserves the aspect ratio within integer pixel rounding, with at least one pixel per side. Resizing uses triangle filtering after decoding and windowing. It does not reduce the input pixel requirement or bypass --max-pixels. Export adds no crop, rotation, or supplemental overlays.

Monochrome export applies the modality rescale and the viewer’s window/level render function, including MONOCHROME1 inversion. It uses the first root WindowCenter and WindowWidth values when available. Otherwise, it derives the window from the selected frame’s minimum and maximum rescaled samples.

Set both --window-center and --window-width to override these defaults in rescaled sample units. Center must be finite. Width must be finite and at least 1. Values must produce finite window endpoints. These options apply only to monochrome images. Supplying them for color images produces invalid_arguments.

RGB export uses the viewer’s RGB render function. For 16-bit color, it shifts samples to retain the highest eight stored bits. The PNG has eight bits per channel.

Structured Reports, presentation states, Parametric Maps, and unsupported pixel layouts produce errors. The PNG contains only image dimensions and rendered pixels, without DICOM metadata or text chunks. Export does not anonymize pixel content. Identifying text already present in pixels remains visible.

Output and Errors

Success leaves standard error empty and exits with 0. By default, or with --output-file -, it writes PNG bytes to standard output. Help prints usage text instead of PNG. Redirect PNG output to a file or capture it as binary data. Shell redirection can overwrite an existing destination. Use a new destination when you need to preserve an existing file.

--output-file <file> saves the complete PNG to a new file and leaves stdout empty. It refuses existing destinations, including symbolic links, and never overwrites them. The parent directory must already exist. The command writes a temporary file in that directory before installing the completed output without overwriting a concurrently created destination.

Failures use the same versioned JSON error envelope and exit codes as inspect. Read, file size, metadata, and output errors keep their existing error codes. PNG encoding failures also use output_error. These additional errors use exit code 1:

Invalid option values, incomplete window pairs, unsupported output formats, or invalid option syntax use invalid_arguments and exit code 2. Errors exclude source and destination paths, raw metadata values, and decoder diagnostics. File and decode failures leave standard output empty. Output failures can leave partial bytes on stdout. Discard captured stdout after a nonzero exit. With --output-file, preserve any destination that existed before the command.

Local Files

Open one or more DICOM files from the UI menu.

The UI file picker accepts .dcm and .dicom suffixes case-insensitively, plus extensionless Part 10 files with a DICM prefix.

Supported local file counts:

• 1 file: opens single-image view (1x1)
• 2 files: opens 1x2
• 3 files: opens 1x3
• 4 files: opens 2x2
• 8 files: opens 2x4
• GSPS DICOM files can be included alongside image DICOM files in the same selection; GSPS files are used as overlays and do not count as display slots.

Grouped Local Launch

Use grouped launch arguments when you need to preload multiple review sets and choose which group opens first. This is useful for current/prior mammography comparisons and image-plus-report launch bundles.

Custom URL Scheme

Perspecta supports perspecta:// URLs for both local launch and DICOMweb handoff.

perspecta://open?path=example-data%2Fimage.dcm
perspecta://open?path=example-data%2FRCC.dcm&path=example-data%2FLCC.dcm&path=example-data%2FRMLO.dcm&path=example-data%2FLMLO.dcm
perspecta://open?group=example-data%2FRCC.dcm|example-data%2FLCC.dcm|example-data%2FRMLO.dcm|example-data%2FLMLO.dcm&group=example-data%2Freport.dcm&open_group=0
perspecta://open?group=example-data%2Fcurrent-RCC.dcm|example-data%2Fcurrent-LCC.dcm|example-data%2Fcurrent-RMLO.dcm|example-data%2Fcurrent-LMLO.dcm|example-data%2Fprior-RCC.dcm|example-data%2Fprior-LCC.dcm|example-data%2Fprior-RMLO.dcm|example-data%2Fprior-LMLO.dcm
perspecta://open?dicomweb=http%3A%2F%2Flocalhost%3A8042%2Fdicom-web&study=<StudyInstanceUID>&series=<SeriesInstanceUID>

Launch Parameter Reference

Notes

• URL values should be percent-encoded.
• Do not embed credentials or tokens in URLs outside local testing; URLs are commonly logged and persisted.
• If dicomweb is provided as a server root (for example http://localhost:8042), Perspecta normalizes it to /dicom-web.
• You cannot mix local grouped launch (group=...) with DICOMweb launch in the same URI.

Related Guides

• Viewer Basics
• DICOMweb
• Install Perspecta DICOM Viewer