Segmentation and STL Export

The client can run the same automatic segmentation as the web app on a patient’s CT series, list the anatomies it produced, and save them on your computer as STL files, one anatomy at a time or a whole group at once. Before you start, sign in and load the patient.

The segmentation runs on the server, and the anatomies are stored with the patient, exactly as when you segment from the web app (see Segmentation Methods). Only the STL files you ask for are written on your computer.

Which patient and series

These commands work on one CT series of one patient:

Option	Meaning
--patient	The patient ID, or the patient’s exact name. If two patients have the same name, use the ID
--series	The series ID or name. Leave it out when the patient has a single CT series

climed-client patients lists what you can work on, one line per CT series: <patient-id> <event-id> <series-id> <patient name>. Add -d <database> to see one database only.

climed-client patients

6a57ab4e6450e59d5a51856a 967572dd1f389f36 PRE John Doe
6a57ab546450e59d5a518a63 mQRwqHSmWCriILbe PRE Jane Smith

Segment a group

There are three groups of anatomy, the same as the Target choices in the web app:

Group	Contains, for example
cardiac	heart, aorta, the large vessels around the heart
lungs	the five lobes, trachea, pulmonary vessels (the bronchial tree with --airways, see below)
whole_body	organs, bones and muscles of the body

climed-client segment --patient "John Doe" --group lungs

Several groups in one command: repeat --group or separate them with commas (--group cardiac,lungs). whole body with a space works too.

The command waits until the server has finished, usually a few minutes per group, and prints one line per anatomy: <anatomy> <group> created or <anatomy> <group> existing.

• Already segmented. A group whose anatomies are all there is not segmented again: its anatomies are listed as existing and the command ends in seconds. Running the same command twice is safe.
• Scan too short. The lungs are segmented only when the scan covers enough of the chest (200 mm along the body). Otherwise the group is reported as not segmented, with the length of your scan, and the command ends with exit status 3. A group that is only partly covered is segmented, with a warning that lists the key structures missing.
• Several groups and one fails. The groups run one after the other and each one is saved when it ends: the groups finished before the failure are kept. Run the same command again to do the rest.
• Stopped waiting (Ctrl-C, or --timeout reached, default 3600 seconds): the segmentation goes on on the server. Run the command again later: what is done is not repeated.

Add the airways

The lungs group gives the trachea only, not the bronchi. The bronchial tree comes from a separate model, the one the web app runs when you tick Airways segmentation. It is not run unless you ask for it: add --airways.

climed-client segment --patient "John Doe" --group lungs --airways

lung_upper_lobe_left lungs created
...
airways lungs created

• --airways goes with --group lungs: the server looks for the tree inside the lobes, so the lobes come first, in the same command. Without --group lungs the client stops before sending anything.
• It is slow: a few minutes, up to half an hour on a large scan. The command waits for it, with the same --timeout.
• Already there: the line reads airways lungs existing and nothing is run again.
• Scan too short for the lungs: the airways are skipped as well, with a warning (exit status 3).
• No airways at the timeout. The server may still be working: check later with climed-client anatomies --group lungs. If they never appear, the model failed on the server; the reason is in the server’s log, so ask your administrator.
• The airways are an anatomy of the lungs group, ID airways: download-stl --group lungs saves them with the lobes.
• Where your installation uses credits, the GPU time of the airways is charged on its own, when they are created.

Client version. --airways is not in climed-client 0.3.0: update the client if segment --help does not list it.

Module and credits. Segmentation needs the Segment and Reconstruct module on your account; without it the client stops before sending anything. Where your installation uses credits, the GPU time of each segmentation is charged to your account when it succeeds (a failed one, or a group already there, costs nothing), from the web app and from the client alike. If your credits do not cover a run, the server refuses it and the client says so (not enough credits, with the amount needed and available): nothing is started. Your balance is in the web app.

List the anatomies

climed-client anatomies --patient "John Doe"
climed-client anatomies --patient "John Doe" --group cardiac

One line per anatomy: <anatomy> <group> <name>. The anatomy ID (for example lung_upper_lobe_left) is what download-stl --anatomy takes. The airways belong to lungs and the coronary arteries to cardiac; an anatomy drawn by hand, or from an older run, may have no group and shows -. With --json, each line also carries the volume and surface statistics.

Download STL files

# a whole group
climed-client download-stl --patient "John Doe" --group lungs --out ./john_doe_stl

# single anatomies, or a group plus some more
climed-client download-stl --patient "John Doe" --anatomy heart --anatomy aorta --out ./john_doe_stl
climed-client download-stl --patient "John Doe" --group lungs --anatomy Vessels --out ./john_doe_stl

Option	Meaning
--group	Every anatomy of a group: cardiac, lungs, whole_body. Repeatable
--anatomy	One anatomy by its ID (see anatomies). Repeatable, or comma-separated
--out	The folder to write to. It is created if needed
--format	stl (default, binary STL) or vtp (the surface as the server stores it)
--overwrite	Replace files that are already there

The files are written in one sub-folder per group, named after the anatomy:

john_doe_stl/
├── lungs/
│   ├── lung_upper_lobe_left.stl
│   ├── lung_lower_lobe_left.stl
│   └── trachea.stl
│   └── airways.stl
├── cardiac/
│   └── heart.stl
└── other/                  <- anatomies without a group
    └── Vessels.stl

One line per file is printed: <anatomy> <path> <number of triangles>.

• Everything is checked first. An anatomy ID that is not in the series, or a group that has not been segmented yet, stops the command before any download.
• Files already there are skipped, so running the command again after an interruption only fetches what is missing. Use --overwrite to replace them.
• A file is written only when it is complete: an interrupted download leaves no half file behind.
• The coordinates are those of the CT scan, in millimetres, as in the web app. The surface is the same one the web app shows: same triangles, same volume.

Good to know

• One anatomy, two groups. Some structures are produced by two models (for example pulmonary_vein, by both lungs and cardiac). The patient keeps one copy, and it belongs to the group segmented last: if it is missing from a group download, add it with --anatomy.
• The airways are segmented only with segment --airways, or by a virtual spirometry, which segments them itself when they are missing (see Virtual Spirometry). Either way they are stored once and used by both.
• Cleaning and smoothing a surface is done in the web app (see 3D Reconstruction); download-stl saves the anatomy as it is stored.