dcmcjpls(1)

🎀 dcmcjpls(1) — OFFIS DCMTK 🎀

Okay bestie, this is the dcmcjpls manual page, and it is literally the JPEG-LS encoder of the DCMTK lineup. We are keeping every flag, every default, every tag, and every caveat. No cap. 💅

🌸 NAME 🌸

dcmcjpls — Encode DICOM file to JPEG-LS transfer syntax.

✨ SYNOPSIS ✨

dcmcjpls [options] dcmfile-in dcmfile-out

💖 DESCRIPTION 💖

The dcmcjpls utility reads an uncompressed DICOM image (dcmfile-in), performs a JPEG-LS compression — i. e. conversion to an encapsulated DICOM transfer syntax — and writes the converted image to an output file (dcmfile-out). It is giving “compress the pixels and secure the bag” energy. 🦋

🎀 PARAMETERS 🎀

• dcmfile-in — DICOM input filename to be converted (- for stdin).
• dcmfile-out — DICOM output filename (- for stdout).

🔥 OPTIONS 🔥

🌸 general options 🌸

• -h, --help — print this help text and exit.
• --version — print version information and exit.
• --arguments — print expanded command line arguments.
• -q, --quiet — quiet mode, print no warnings and errors.
• -v, --verbose — verbose mode, print processing details.
• -d, --debug — debug mode, print debug information.
• -ll, --log-level — [l]evel: string constant (fatal, error, warn, info, debug, trace); use level l for the logger.
• -lc, --log-config — [f]ilename: string; use config file f for the logger.

🌸 input options 🌸

🌸 input file format 🌸

• +f, --read-file — read file format or data set (default).
• +fo, --read-file-only — read file format only.
• -f, --read-dataset — read data set without file meta information.

🌸 input transfer syntax 🌸

• -t=, --read-xfer-auto — use TS recognition (default).
• -td, --read-xfer-detect — ignore TS specified in the file meta header.
• -te, --read-xfer-little — read with explicit VR little endian TS.
• -tb, --read-xfer-big — read with explicit VR big endian TS.
• -ti, --read-xfer-implicit — read with implicit VR little endian TS.

🌸 JPEG-LS encoding options 🌸

🌸 JPEG-LS process 🌸

• +el, --encode-lossless — encode JPEG-LS lossless only TS (default).

This option selects the JPEG-LS lossless only transfer syntax and performs a lossless compression. Iconic behavior, honestly. ✨

• +en, --encode-nearlossless — encode JPEG-LS near-lossless TS (NEAR: 2).

This option selects the JPEG-LS lossy transfer syntax and performs a near-lossless compression. It is lowkey lossy but trying its best. 💅

🌸 JPEG-LS bit rate (near-lossless only) 🌸

• +md, --max-deviation — [d]eviation: integer (default: 2); defines maximum deviation for an encoded pixel.

This option specifies the maximum deviation for a single pixel from the original pixel value.

🌸 lossless compression 🌸

• +pr, --prefer-raw — prefer raw encoder mode (default).

This option enables the raw encoder. The raw encoder encodes the complete pixel cell as it was read from the source image without performing any modifications. Raw is the main character here. 👑

• +pc, --prefer-cooked — prefer cooked encoder mode.

This option enables the cooked encoder. The cooked encoder moves overlay data to separate tags (60xx,3000) and only encodes the stored bits in each pixel. Cooked, but make it DICOM. 🍓

🌸 JPEG-LS compression 🌸

• +t1, --threshold1 — [t]hreshhold: integer; set JPEG-LS encoding parameter threshold 1.
• +t2, --threshold2 — [t]hreshhold: integer; set JPEG-LS encoding parameter threshold 2.
• +t3, --threshold3 — [t]hreshhold: integer; set JPEG-LS encoding parameter threshold 3.

By default, the values for T1, T2, T3 are computed based on the number of bits per sample. The typo in threshhold is preserved exactly, because we do not fix the lore. 😭

• +rs, --reset — [r]eset: integer (default: 64); set JPEG-LS encoding parameter reset.

🌸 JPEG-LS interleave 🌸

• +il, --interleave-line — force line-interleaved JPEG-LS images (default).

This flag forces line-interleaved mode for the resulting image. In line-interleave mode each line from the source image is compressed separately for each component and then the next line is encoded.

• +is, --interleave-sample — force sample-interleaved JPEG-LS images.

This flag forces sample-interleaved mode for the resulting image. In sample-interleave mode each pixel's components are encoded before the next pixel is encoded.

• +iv, --interleave-default — use the fastest possible interleave mode.

This flag selects an interleave mode based on the source image's mode. If possible, the image is not converted to a different interleave mode.

🌸 JPEG-LS padding of odd-length bitstreams 🌸

• +ps, --padding-standard — pad with extended EOI marker (default).

Pad odd-length JPEG-LS bitstreams by writing an extended end of image segment marker FF FF D9, as required by the DICOM standard. Standard behavior ate. 💖

• +pz, --padding-zero — pad with zero byte (non-standard).

Pad odd-length JPEG-LS bitstreams by writing a zero byte after the end of image segment marker, i. e. FF D9 00. This is not DICOM conformant but required for interoperability with the HP LOCO reference implementation, which does not support extended JPEG-LS bitstreams.

🚨 Bestie, +pz is non-standard. It is not DICOM conformant. Use it only when you need that HP LOCO interoperability. Do not pretend it is standard, because it is not. 💀

🌸 encapsulated pixel data encoding options 🌸

🌸 encapsulated pixel data fragmentation 🌸

• +ff, --fragment-per-frame — encode each frame as one fragment (default).

This option causes the creation of one compressed fragment for each frame (recommended). Clean, simple, recommended. Periodt.

• +fs, --fragment-size — [s]ize: integer; limit fragment size to s kbytes.

This option limits the fragment size which may cause the creation of multiple fragments per frame. Tiny fragments, tiny vibes. 🎀

🌸 basic offset table encoding 🌸

• +ot, --offset-table-create — create offset table (default).

This option causes the creation of a valid offset table for the compressed JPEG fragments.

• -ot, --offset-table-empty — leave offset table empty.

This option causes the creation of an empty offset table for the compressed JPEG fragments.

🌸 icon image encoding 🌸

• +ic, --icon-compressed — compress icon images (default).
• +iu, --icon-uncompressed — keep icon images uncompressed.

🌸 SOP Class UID 🌸

• +cd, --class-default — keep SOP Class UID (default).

Keep the SOP Class UID of the source image.

• +cs, --class-sc — convert to Secondary Capture Image (implies --uid-always).

Convert the image to Secondary Capture. In addition to the SOP Class UID, all attributes required for a valid secondary capture image are added. A new SOP instance UID is always assigned.

🌸 SOP Instance UID 🌸

• +ud, --uid-default — assign new UID if lossy compression (default).

Assigns a new SOP instance UID if the compression is lossy JPEG-LS.

• +ua, --uid-always — always assign new UID.

Unconditionally assigns a new SOP instance UID.

• +un, --uid-never — never assign new UID.

Never assigns a new SOP instance UID.

🌸 output options 🌸

🌸 post-1993 value representations 🌸

• +u, --enable-new-vr — enable support for new VRs (UN/UT) (default).
• -u, --disable-new-vr — disable support for new VRs, convert to OB.

🌸 group length encoding 🌸

• +g=, --group-length-recalc — recalculate group lengths if present (default).
• +g, --group-length-create — always write with group length elements.
• -g, --group-length-remove — always write without group length elements.

🌸 length encoding in sequences and items 🌸

• +e, --length-explicit — write with explicit lengths (default).
• -e, --length-undefined — write with undefined lengths.

🌸 data set trailing padding 🌸

• -p=, --padding-retain — do not change padding (default).
• -p, --padding-off — no padding.
• +p, --padding-create — [f]ile-pad [i]tem-pad: integer; align file on multiple of f bytes and items on multiple of i bytes.

🦋 NOTES 🦋

The dcmcjpls utility compresses DICOM images of all SOP classes. It processes all Pixel Data (7fe0,0010) elements in the dataset, i. e. compression is also performed on an icon image. However, dcmcjpls does not attempt to ensure that the compressed image still complies with all restrictions of the object's IOD.

The user is responsible for making sure that the compressed images he creates are compliant with the DICOM standard. If in question, the dcmcjpls utility allows one to convert an image to secondary capture — this SOP class does not pose restrictions as the ones mentioned above.

💜 Translation: yes, it compresses all the Pixel Data it finds, including icon images. No, it will not babysit your IOD restrictions for you. You are responsible for DICOM compliance. If you are unsure, secondary capture is the escape hatch.

🌈 TRANSFER SYNTAXES 🌈

dcmcjpls supports the following transfer syntaxes for input (dcmfile-in):

• LittleEndianImplicitTransferSyntax — 1.2.840.10008.1.2
• LittleEndianExplicitTransferSyntax — 1.2.840.10008.1.2.1
• DeflatedExplicitVRLittleEndianTransferSyntax — 1.2.840.10008.1.2.1.99 (*)
• BigEndianExplicitTransferSyntax — 1.2.840.10008.1.2.2

(*) if compiled with zlib support enabled.

dcmcjpls supports the following transfer syntaxes for output (dcmfile-out):

• JPEGLSLosslessTransferSyntax — 1.2.840.10008.1.2.4.80
• JPEGLSLossyTransferSyntax — 1.2.840.10008.1.2.4.81

⭐ LOGGING ⭐

The level of logging output of the various command line tools and underlying libraries can be specified by the user. By default, only errors and warnings are written to the standard error stream. Using option --verbose also informational messages like processing details are reported. Option --debug can be used to get more details on the internal activity, e. g. for debugging purposes. Other logging levels can be selected using option --log-level. In --quiet mode only fatal errors are reported. In such very severe error events, the application will usually terminate. For more details on the different logging levels, see documentation of module "oflog".

In case the logging output should be written to file (optionally with logfile rotation), to syslog (Unix) or the event log (Windows) option --log-config can be used. This configuration file also allows for directing only certain messages to a particular output stream and for filtering certain messages based on the module or application where they are generated. An example configuration file is provided in <etcdir>/logger.cfg.

💬 COMMAND LINE 💬

okay bestie, before you go anywhere near the flags, let's talk about how these tools read what you type, because the notation is lowkey its own little language ✨

• Square brackets [...] mean the thing inside is optional — so that's 0-1 values, your choice 💅
• Three trailing dots ... mean "you can put more than one of these here" — as in 1-n values, go off 👑
• Both together (brackets and dots) mean 0 to n values — zero's fine, a whole pile's fine, no stress 🫶

Command line options get told apart from parameters by a leading + or - sign, respectively. Iconic. Usually the order and position of options is arbitrary — like, they can literally appear anywhere and the tool won't care 🙈. But if two options are mutually exclusive, the rightmost appearance wins. That's not a vibe, that's the standard evaluation rules of common Unix shells, fr fr.

---

And here's the fun part 🎀 — you can also hand over one or more command files by prefixing the filename with an @ sign, like @command.txt. That argument gets swapped out for the contents of the corresponding text file before anything else gets evaluated. And when it does that? Multiple whitespaces count as a single separator — unless they're sitting between two quotation marks, in which case they stay put 🦋.

⚠️ Heads up bestie: a command file cannot contain another command file. No nesting, no inception, we don't do that here 💀

This simple but effective approach is genuinely giving main character energy — it lets you bundle up common combos of options/parameters and dodge those longish, confusing command lines entirely. There's literally an example waiting for you in the file <datadir>/dumppat.txt 🌸

---

🌈 ENVIRONMENT 🌈

The dcmcjpls utility will attempt to load DICOM data dictionaries that you've specified in the DCMDICTPATH environment variable. But by default — meaning if DCMDICTPATH isn't set at all — the file <datadir>/dicom.dic gets loaded instead, unless the dictionary is built into the application (which is the default on Windows, iykyk) 🪟

💖 The default behavior should be preferred, okay? Only reach for the DCMDICTPATH environment variable when you actually need alternative data dictionaries. Trust the process ✨

DCMDICTPATH has the same format as the Unix shell PATH variable — a colon (":") separates the entries. On Windows systems though, it's a semicolon (";") doing the separating 🎀

The data dictionary code will attempt to load each file you list in DCMDICTPATH. And if no data dictionary can be loaded at all? That's an error. Full stop 😭

---

👀 SEE ALSO 👀

• dcmdjpls(1) — go read that one too, bestie, it's the whole reason this page exists 💜

---

©️ COPYRIGHT ©️

Copyright (C) 2009-2026 by OFFIS e.V., Escherweg 2, 26121 Oldenburg, Germany. 🫶

---

that's the whole page, babe — go forth and compress some JPEG-LS 💅✨

Version 3.7.1 🦋 Sat Oct 17 2026 09:34:01 🎀 slay, see you in the next manpage 💖