Docs /Command-Line Client

Loading Patients

Each patient is created with a name and one CT series. Before you start, sign in.

One patient

climed-client import-dicom --name "John Doe" --series /data/cts/john_doe -d demo_db

Option	Meaning
`--name`	The patient name, exactly as it will appear in LeaRes
`--series`	A folder with the DICOM files of one series (sub-folders are included), or a ZIP archive
`-d`	The database. Left out, the account’s only database is used
`--sid`	The name given to the series when you upload a folder. Default `PRE`; letters, digits, `_` and `-` only

On success it prints one line, <patient-id> <event-id> <series-name>. Progress and messages go to the error stream, so a script can capture that line on its own (see Scripting).

A patient with that name already exists in the database: nothing is imported, nothing is changed (exit status 2).
The upload fails: the patient just created is removed again, so a failure never leaves a half-loaded patient.
A ZIP is sent as it is and may contain only one series. The series name comes from the archive: a folder inside it (study/<series name>/…) or, for a flat archive of files, the name of the first file. --sid does not apply to ZIP files.

Many patients at once

import-dicom-batch does the same for many patients in one command. It is a sequence of single loads, so everything above applies to each patient. There are two ways to say who the patients are.

Many patients from a folder

Put each patient’s series in its own folder (or ZIP) under one parent folder. The folder name becomes the patient name, exactly as written.

cts/
├── John Doe/               <- the DICOM files of one CT series
│   ├── IM0001.dcm
│   └── IM0002.dcm
├── Jane Smith/
├── Michael Johnson/
└── Emily Davis.zip         <- a ZIP works too (name = file name without .zip)

climed-client import-dicom-batch --root cts -d demo_db

Folders and files starting with a dot are ignored. If the folder names are not the names you want (for example john_doe), use a list instead.

Many patients from a list

A list is a CSV file with a header line. name and path are required, sid is optional (it names that patient’s series; without it --sid or PRE is used):

name,path,sid
John Doe,/data/cts/john_doe,
Jane Smith,/data/cts/smith_2024,POST
Michael Johnson,/data/archive/mjohnson.zip,

A JSON list works the same way:

[
  {"name": "John Doe", "path": "/data/cts/john_doe"},
  {"name": "Jane Smith", "path": "/data/cts/smith_2024", "sid": "POST"}
]

climed-client import-dicom-batch --manifest patients.csv -d demo_db

Relative paths start from the folder that contains the list file, so a list and its images can be moved together.

Check first: `--dry-run`

Add --dry-run to see what would happen, without sending anything:

climed-client import-dicom-batch --root cts --dry-run -d demo_db

  4 patients:
    Emily Davis  <-  /data/cts/Emily Davis.zip  (series PRE)
    Jane Smith  <-  /data/cts/Jane Smith  (series PRE)
    John Doe  <-  /data/cts/John Doe  (series PRE)
    Michael Johnson  <-  /data/cts/Michael Johnson  (series PRE)
  dry run: nothing imported

The whole input is checked before the first upload, with or without --dry-run. A mistake in row 18 is reported at once, not after 17 uploads:

  ERROR: row 2 (John Doe): name already used by row 1
  ERROR: row 3 (Alice Lee): /data/cts/missing does not exist
  ERROR: 2 problem(s) in the input: nothing imported

Checked: an empty or repeated patient name, a missing or empty folder, a file that is not a ZIP, an unusable series name.

The result

For each patient the client prints a progress line, and at the end a summary:

[1/4] John Doe
  -> ok
[2/4] Jane Smith
  -> skipped: a patient named 'Jane Smith' already exists in demo_db: nothing imported
[3/4] Michael Johnson
  -> failed: series not imported (HTTP 500) — too few files
...
  done: 2 imported, 1 skipped (already present), 1 failed, 0 not attempted

Result	Meaning
ok	The patient was created and the series uploaded. It is in your patient list
skipped	A patient with that name already exists. Nothing is changed or overwritten. This is not an error
failed	The reason is printed. The patient is removed again, nothing stays half-loaded

A failure on one patient does not stop the others.
After an interruption (a failure, a lost connection, Ctrl-C) run the same command again: patients already loaded are skipped, so only what is left is done. The patient being loaded at the moment of a Ctrl-C is removed again.
The tool stops with an error status if at least one patient failed or was not attempted (see Scripting).

Good to know

Names only. Patients are created with their name. Complete the record (date of birth, sex, notes) in the web app afterwards.
One series per patient in each load. To add more series to a patient, upload them from the web app (see Uploading and Viewing DICOM Data).
Large series may take several minutes each: keep the terminal open, or run it as described in Scripting.
Patient names are unique within a database: two lists can reuse a name in two different databases.