dcmtalk 0.20.1

DICOM network (DIMSE) CLI: echoscu/storescu/findscu/movescu/storescp
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
use std::collections::HashMap;
use std::io::{self};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::Duration;

use clap::{ArgAction, Args, CommandFactory, FromArgMatches, Parser, Subcommand};
use dcmnorm::dicom_io::{
    echo_scu, find_scu, move_scu, start_scp, store_scu, DimseLogger, EchoScuOptions,
    FindScuOptions, MoveScuOptions, MoveScuResult, QueryRetrieveLevel, ScpHandlers, ScpOptions,
    StoreScuOptions, StoreScuResult,
};
use sha2::{Digest, Sha256};

/// Classic DICOM default proposed/accepted PDU length, matching dcmtk's SCU tools' own default.
const DEFAULT_SCU_MAX_PDU: u32 = 16_384;
/// Matches `ScpOptions::default()`'s own max PDU length.
const DEFAULT_SCP_MAX_PDU: u32 = 262_144;
const DEFAULT_SCP_IDLE_TIMEOUT_SECS: u64 = 300;
const DEFAULT_AE_TITLE: &str = "DCMTALK";

#[derive(Parser)]
#[command(name = "dcmtalk")]
#[command(
    about = "DICOM network (DIMSE) client/server: verify, send, query, retrieve, and receive"
)]
#[command(
    long_about = "A DIMSE command-line tool covering the same ground as dcmtk's echoscu/storescu/findscu/movescu/storescp, built on dcmnorm's native (non-dcmtk) DICOM Upper Layer implementation. Every subcommand accepts --verbose to log association negotiation, presentation contexts, and each DIMSE command/response exchanged."
)]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand)]
enum Command {
    /// C-ECHO SCU: verify connectivity to a DICOM peer
    Echoscu(EchoscuArgs),
    /// C-STORE SCU: send DICOM file(s)/director(ies) to a peer
    Storescu(StorescuArgs),
    /// C-FIND SCU: query a peer's studies (Study Root Query/Retrieve)
    Findscu(FindscuArgs),
    /// C-MOVE SCU: ask a peer to push a study to another AE title it knows
    Movescu(MovescuArgs),
    /// DICOM storage SCP: accept associations and receive C-STORE'd instances
    Storescp(StorescpArgs),
}

#[derive(Args)]
struct ScuCommonArgs {
    /// Peer address as HOST:PORT
    destination: String,

    /// Our AE title (Calling AE)
    #[arg(long = "calling-aet", short = 'a', default_value = DEFAULT_AE_TITLE)]
    calling_ae: String,

    /// Peer's AE title (Called AE), if it requires one to match
    #[arg(long = "called-aet", short = 'c')]
    called_ae: Option<String>,

    /// Absolute timeout in seconds for the whole operation (connect through release)
    #[arg(long)]
    timeout: Option<u64>,

    /// Log association negotiation, presentation contexts, and each DIMSE command/response to stderr
    #[arg(long, short = 'v', action = ArgAction::SetTrue)]
    verbose: bool,
}

#[derive(Args)]
struct EchoscuArgs {
    #[command(flatten)]
    common: ScuCommonArgs,
}

#[derive(Args)]
struct StorescuArgs {
    #[command(flatten)]
    common: ScuCommonArgs,

    /// DICOM file(s) or director(ies) to send (directories are scanned recursively)
    #[arg(required = true, num_args = 1..)]
    files: Vec<PathBuf>,

    /// Our advertised max PDU length
    #[arg(long = "max-pdu", default_value_t = DEFAULT_SCU_MAX_PDU)]
    max_pdu: u32,

    /// Propose only each file's native transfer syntax; a peer that can't accept it fails that
    /// file rather than receiving a transcoded copy
    #[arg(long, action = ArgAction::SetTrue)]
    never_transcode: bool,
}

#[derive(Args)]
struct FindscuArgs {
    #[command(flatten)]
    common: ScuCommonArgs,

    /// Query key as KEY=VALUE (match) or bare KEY (return key, universal match). Repeatable.
    #[arg(short = 'k', long = "key", action = ArgAction::Append, value_name = "KEY[=VALUE]")]
    keys: Vec<String>,

    /// Our advertised max PDU length
    #[arg(long = "max-pdu", default_value_t = DEFAULT_SCU_MAX_PDU)]
    max_pdu: u32,
}

#[derive(Args)]
struct MovescuArgs {
    #[command(flatten)]
    common: ScuCommonArgs,

    /// AE title to move the study to (must already be known to the peer)
    move_destination_ae: String,

    /// StudyInstanceUID to retrieve
    study_instance_uid: String,

    /// QueryRetrieveLevel: STUDY (the whole study), SERIES (needs --series-uid) or IMAGE (needs
    /// --series-uid and at least one --sop-uid)
    #[arg(
        long = "level",
        default_value = "STUDY",
        value_name = "STUDY|SERIES|IMAGE"
    )]
    level: String,

    /// SeriesInstanceUID to retrieve (SERIES/IMAGE level)
    #[arg(long = "series-uid", value_name = "UID")]
    series_uid: Option<String>,

    /// SOPInstanceUID to retrieve (IMAGE level). Repeatable; all are sent as one UID list.
    #[arg(long = "sop-uid", action = ArgAction::Append, value_name = "UID")]
    sop_uids: Vec<String>,

    /// Our advertised max PDU length
    #[arg(long = "max-pdu", default_value_t = DEFAULT_SCU_MAX_PDU)]
    max_pdu: u32,
}

#[derive(Args)]
struct StorescpArgs {
    /// Port to listen on (0 picks an ephemeral port)
    port: u16,

    /// Our AE title
    #[arg(long = "ae-title", short = 'a', default_value = DEFAULT_AE_TITLE)]
    ae_title: String,

    /// Directory to write received instances under (as S_<StudyInstanceUID>/<Modality>_<SOPInstanceUID>.dcm)
    #[arg(long = "cache-path", default_value = ".")]
    cache_path: PathBuf,

    /// Our advertised max PDU length
    #[arg(long = "max-pdu", default_value_t = DEFAULT_SCP_MAX_PDU)]
    max_pdu: u32,

    /// How long (seconds) an established association may sit idle before being dropped
    #[arg(long = "idle-timeout", default_value_t = DEFAULT_SCP_IDLE_TIMEOUT_SECS)]
    idle_timeout: u64,

    /// Optional target transfer syntax UID for on-the-fly streaming transcoding of received images
    /// directly to disk (e.g. 1.2.840.10008.1.2.4.201 for HTJ2K Lossless)
    #[arg(long = "transfer-syntax", value_name = "UID")]
    transfer_syntax: Option<String>,

    /// Log association negotiation, presentation contexts, and each DIMSE command/response to stderr
    #[arg(long, short = 'v', action = ArgAction::SetTrue)]
    verbose: bool,
}

struct StderrLogger;

impl DimseLogger for StderrLogger {
    fn log(&self, message: String) {
        eprintln!("[dcmtalk] {message}");
    }
}

fn logger_box(verbose: bool) -> Option<Box<dyn DimseLogger>> {
    if verbose {
        Some(Box::new(StderrLogger))
    } else {
        None
    }
}

fn logger_arc(verbose: bool) -> Option<Arc<dyn DimseLogger>> {
    if verbose {
        Some(Arc::new(StderrLogger))
    } else {
        None
    }
}

fn main() {
    let version_with_hash = cli_version_with_binary_hash();
    let version_static: &'static str = Box::leak(version_with_hash.into_boxed_str());
    let matches = Cli::command().version(version_static).get_matches();
    let cli = Cli::from_arg_matches(&matches).expect("clap generated invalid matches");

    if let Err(error) = run(cli.command) {
        eprintln!("dcmtalk: {error}");
        std::process::exit(1);
    }
}

fn cli_version_with_binary_hash() -> String {
    let base_version = env!("CARGO_PKG_VERSION");
    match running_binary_sha256_prefix(12) {
        Some(hash_prefix) => format!("{base_version}-{hash_prefix}"),
        None => base_version.to_string(),
    }
}

fn running_binary_sha256_prefix(prefix_len: usize) -> Option<String> {
    let exe_path = std::env::current_exe().ok()?;
    let exe_bytes = std::fs::read(exe_path).ok()?;

    let mut hasher = Sha256::new();
    hasher.update(&exe_bytes);
    let digest = hasher.finalize();

    let mut hex = String::with_capacity(digest.len() * 2);
    for byte in digest {
        use std::fmt::Write as _;
        write!(&mut hex, "{byte:02x}").ok()?;
    }

    Some(hex.chars().take(prefix_len).collect())
}

fn run(command: Command) -> Result<(), Box<dyn std::error::Error>> {
    match command {
        Command::Echoscu(args) => run_echoscu(args),
        Command::Storescu(args) => run_storescu(args),
        Command::Findscu(args) => run_findscu(args),
        Command::Movescu(args) => run_movescu(args),
        Command::Storescp(args) => run_storescp(args),
    }
}

/// PS3.7 Annex C status codes worth naming for a human reading CLI output; anything else is just
/// shown as hex. Not exhaustive - every peer's specific failure statuses aren't worth enumerating
/// here when the hex code plus the peer's own log is what actually diagnoses it.
fn status_description(status: u16) -> &'static str {
    match status {
        0x0000 => "Success",
        0xFF00 | 0xFF01 => "Pending",
        0xFE00 => "Cancel",
        0xA701 | 0xA702 => "Refused: Out of Resources",
        0xA801 => "Move Destination Unknown",
        0xA900 => "Identifier Does Not Match SOP Class",
        0xC000..=0xCFFF => "Unable to Process",
        0xB000..=0xBFFF => "Warning",
        _ => "Failure",
    }
}

fn other_error(message: impl Into<String>) -> Box<dyn std::error::Error> {
    io::Error::other(message.into()).into()
}

fn run_echoscu(args: EchoscuArgs) -> Result<(), Box<dyn std::error::Error>> {
    let common = args.common;
    let options = EchoScuOptions {
        calling_ae_title: common.calling_ae,
        called_ae_title: common.called_ae,
        timeout: common.timeout.map(Duration::from_secs),
        on_log: logger_box(common.verbose),
        cancel: None,
    };

    let status = echo_scu(&common.destination, options)?;
    println!(
        "C-ECHO status=0x{status:04X} ({})",
        status_description(status)
    );
    if status != 0x0000 {
        return Err(other_error(format!(
            "C-ECHO failed with status 0x{status:04X}"
        )));
    }
    Ok(())
}

fn collect_dicom_files(paths: &[PathBuf]) -> Vec<PathBuf> {
    let mut files = Vec::new();
    for path in paths {
        collect_dicom_files_from(path, &mut files);
    }
    files
}

fn collect_dicom_files_from(path: &Path, files: &mut Vec<PathBuf>) {
    if path.is_dir() {
        let Ok(entries) = std::fs::read_dir(path) else {
            return;
        };
        let mut entries: Vec<_> = entries.filter_map(Result::ok).collect();
        entries.sort_by_key(|entry| entry.file_name());
        for entry in entries {
            collect_dicom_files_from(&entry.path(), files);
        }
    } else if path.is_file() {
        files.push(path.to_owned());
    }
}

fn run_storescu(args: StorescuArgs) -> Result<(), Box<dyn std::error::Error>> {
    let common = args.common;
    let files = collect_dicom_files(&args.files);
    if files.is_empty() {
        return Err(other_error("no files found under the given path(s)"));
    }

    let options = StoreScuOptions {
        calling_ae_title: common.calling_ae,
        called_ae_title: common.called_ae,
        max_pdu_length: args.max_pdu,
        never_transcode: args.never_transcode,
        timeout: common.timeout.map(Duration::from_secs),
        on_log: logger_box(common.verbose),
        cancel: None,
    };

    let results: Vec<StoreScuResult> = store_scu(&common.destination, &files, options)?;

    let mut failures = 0usize;
    for result in &results {
        if result.status != 0x0000 {
            failures += 1;
        }
        println!(
            "{} status=0x{:04X} ({})",
            result.sop_instance_uid,
            result.status,
            status_description(result.status)
        );
    }
    println!("{} instance(s) sent, {} failed", results.len(), failures);

    if failures > 0 {
        return Err(other_error(format!(
            "{failures} of {} instance(s) failed",
            results.len()
        )));
    }
    Ok(())
}

fn parse_query_keys(keys: &[String]) -> HashMap<String, String> {
    let mut query = HashMap::new();
    for raw in keys {
        match raw.split_once('=') {
            Some((key, value)) => {
                query.insert(key.trim().to_owned(), value.to_owned());
            }
            None => {
                query.insert(raw.trim().to_owned(), String::new());
            }
        }
    }
    query
}

fn run_findscu(args: FindscuArgs) -> Result<(), Box<dyn std::error::Error>> {
    let common = args.common;
    let query = parse_query_keys(&args.keys);

    let options = FindScuOptions {
        calling_ae_title: common.calling_ae,
        called_ae_title: common.called_ae,
        max_pdu_length: args.max_pdu,
        timeout: common.timeout.map(Duration::from_secs),
        on_log: logger_box(common.verbose),
        cancel: None,
    };

    let matches = find_scu(&common.destination, &query, options)?;
    for json in &matches {
        println!("{json}");
    }
    eprintln!("{} match(es)", matches.len());
    Ok(())
}

fn run_movescu(args: MovescuArgs) -> Result<(), Box<dyn std::error::Error>> {
    let common = args.common;
    let level: QueryRetrieveLevel = args.level.parse()?;
    let options = MoveScuOptions {
        calling_ae_title: common.calling_ae,
        called_ae_title: common.called_ae,
        max_pdu_length: args.max_pdu,
        timeout: common.timeout.map(Duration::from_secs),
        stale_data_path: None,
        stale_data_timeout: None,
        on_log: logger_box(common.verbose),
        cancel: None,
        query_retrieve_level: Some(level),
        series_instance_uid: args.series_uid,
        sop_instance_uids: args.sop_uids,
    };

    let result: MoveScuResult = move_scu(
        &common.destination,
        &args.move_destination_ae,
        &args.study_instance_uid,
        options,
    )?;

    println!(
        "C-MOVE status=0x{:04X} ({}) completed={} failed={} warning={} remaining={}{}",
        result.status,
        status_description(result.status),
        result.completed,
        result.failed,
        result.warning,
        result.remaining,
        if result.cancelled { " (cancelled)" } else { "" }
    );

    if !result.cancelled && result.status != 0x0000 {
        return Err(other_error(format!(
            "C-MOVE failed with status 0x{:04X}",
            result.status
        )));
    }
    Ok(())
}

/// Minimal `ScpHandlers`: C-STORE is handled entirely by the library (this is what a standalone
/// receiver needs); C-FIND/C-MOVE have no backing query index or retrieve queue to serve from
/// here, so they're answered "unable to process" rather than pretending to support them.
struct StandaloneScpHandlers;

impl ScpHandlers for StandaloneScpHandlers {
    fn on_find(
        &self,
        _filter: &HashMap<String, String>,
    ) -> Result<Vec<HashMap<String, String>>, String> {
        Err("C-FIND is not supported by dcmtalk storescp".to_owned())
    }

    fn on_move(
        &self,
        _study_instance_uid: &str,
        _move_destination_ae: &str,
    ) -> Result<bool, String> {
        Err("C-MOVE is not supported by dcmtalk storescp".to_owned())
    }

    fn on_association_complete(&self, stored_instances_by_study: &HashMap<String, Vec<String>>) {
        for (study_instance_uid, paths) in stored_instances_by_study {
            println!(
                "stored study {study_instance_uid}: {} instance(s)",
                paths.len()
            );
            for path in paths {
                println!("  {path}");
            }
        }
    }
}

fn run_storescp(args: StorescpArgs) -> Result<(), Box<dyn std::error::Error>> {
    std::fs::create_dir_all(&args.cache_path)?;

    let options = ScpOptions {
        ae_title: args.ae_title.clone(),
        max_pdu_length: args.max_pdu,
        idle_timeout: Duration::from_secs(args.idle_timeout),
        on_log: logger_arc(args.verbose),
        storage_transfer_syntax: args.transfer_syntax.clone(),
        ..Default::default()
    };

    let scp = start_scp(
        args.port,
        args.cache_path.clone(),
        Arc::new(StandaloneScpHandlers),
        options,
    )?;

    println!(
        "dcmtalk storescp listening on port {} (AE title {:?}, cache {}). Press Ctrl+C to stop.",
        scp.local_port(),
        args.ae_title,
        args.cache_path.display()
    );

    loop {
        std::thread::park();
    }
}