dicom-organizer 0.1.1

Local DICOM organizer with CLI and optional PySide6 GUI

dicom-organizer

A command-line tool that organizes DICOM files by acquisition date and series, and writes CSV summaries of DICOM acquisition parameters.

DICOMファイルを日付・シリーズごとに整理し、撮像条件のCSVを作るコマンドです。

English

Installation

Install the command-line tool:

uv tool install dicom-organizer

From this repository:

git clone https://github.com/SugimotoKohei/dicom-organizer.git
cd dicom-organizer
uv tool install --editable . --force

Usage

Run the organizer:

dicom-organizer --input /path/to/dicom-root --force-read --if-exists skip

Check the installed version:

dicom-organizer --version

A dry run is optional, but useful when checking a new input folder or output template before writing files:

dicom-organizer --input /path/to/dicom-root --dry-run --force-read --if-exists skip

By default, files are copied to <input>/organized/. Source files are not removed. The default metadata profile is auto, which writes a single dicom_parameters.csv for supported image modalities (MR, CT, US, XA, PT) and expands columns based on the modalities actually present. Use --profile generic for common columns only, or --profile mr|ct|us|xa|pt to focus the CSVs on one modality.

dicom-organizer --input /path/to/dicom-root --profile generic
dicom-organizer --input /path/to/dicom-root --profile ct

The default series folder name uses a normalized series label: usually ProtocolName, but on vendors where SeriesDescription better matches the console-visible sequence name (for example Philips, GE, and Canon/Toshiba-family systems), it prefers SeriesDescription. If a Philips series contains multiple reconstruction types in the same SeriesInstanceUID, the default folder name also appends a reconstruction label derived from ImageType. When a Philips series label is only a number, the default name also prefixes the descriptive anchor label from the same acquisition when one is available.

Output:

organized/<AcquisitionDate>/<SeriesNumber>_<SeriesFolderLabel>/000001.dcm
organized/<AcquisitionDate>/dicom_parameters.csv
organized/<AcquisitionDate>/series_summary.csv
organized/organize_summary.json

dicom_parameters.csv and series_summary.csv focus on supported image objects. Presentation states and vendor-private helper objects may still be organized into folders, but they are excluded from these parameter tables.

Run summaries report both the total organized DICOM files and the files included in the CSV parameter tables:

profile=auto
organized_files=12
csv_target_files=10
csv_excluded_non_image_files=2

During --dry-run, no files are written. The summary also lists the metadata files that would be created.

CSV Columns

dicom_parameters.csv always starts with common identifiers, dates, patient fields, geometry, manufacturer information, source filename, image type, and spatial orientation columns. The patient columns follow --patient-mode: keep writes PatientName and PatientID, hash writes sha256: digests, and drop writes N/A; hash helper columns are still written for checking.

Profile-specific columns are appended after the common columns:

• mr: TR/TE, bandwidth, echo train length, flip angle, averages, field strength, sequence fields, inversion time, echo numbers, acquisition matrix, phase encoding, sampling, SAR, coil, MR acquisition type, and Siemens channel helper fields.
• ct: kVp, tube current, exposure time, convolution kernel, and reconstruction diameter.
• us: transducer, mechanical/thermal index, and color data flag.
• xa: kVp, tube current, exposure time, frame time, and source-detector/source- patient distances.
• pt: radiopharmaceutical, dose, half-life, and decay correction.

--profile auto writes the union of columns for supported modalities present in the input. --profile generic writes common columns only. Repeatable --dicom-tag columns are appended after the profile columns.

Common Options

Avoid writing patient identifiers to CSV:

dicom-organizer --input /path/to/dicom-root --patient-mode hash
dicom-organizer --input /path/to/dicom-root --patient-mode drop

Add extra DICOM tags to the CSV:

dicom-organizer --input /path/to/dicom-root --dicom-tag EchoTime --dicom-tag InPlanePhaseEncodingDirection

Use the optional GUI:

uv tool install 'dicom-organizer[gui]'
dicom-organizer-gui

Try it without real DICOM data:

uv run python examples/synthetic_quickstart.py

Note: the default --patient-mode keep writes PatientName and PatientID to CSV files. Use hash or drop, and inspect generated CSV files before sharing outputs.

日本語

インストール

コマンドラインツールをインストールします。

uv tool install dicom-organizer

このリポジトリから使う場合:

git clone https://github.com/SugimotoKohei/dicom-organizer.git
cd dicom-organizer
uv tool install --editable . --force

使い方

整理を実行します。

dicom-organizer --input /path/to/dicom-root --force-read --if-exists skip

インストール済みバージョンを確認します。

dicom-organizer --version

dry-runは必須ではありませんが、新しい入力フォルダや出力テンプレートを使う前に、 書き込みなしで確認したい場合に便利です。

dicom-organizer --input /path/to/dicom-root --dry-run --force-read --if-exists skip

既定では <input>/organized/ にコピーされます。元ファイルは消えません。 既定の metadata profile は auto で、対応している画像モダリティ（MR, CT, US, XA, PT）を 1 つの dicom_parameters.csv にまとめ、実際に含まれる モダリティに応じて列を広げます。共通列だけ欲しい場合は --profile generic、 単一モダリティに絞りたい場合は --profile mr|ct|us|xa|pt を使います。

dicom-organizer --input /path/to/dicom-root --profile generic
dicom-organizer --input /path/to/dicom-root --profile ct

シリーズフォルダ名の既定値は正規化した series label で、通常は ProtocolName、 ただし Philips や GE、Canon/Toshiba 系のように SeriesDescription のほうが コンソール上の系列名に近い装置では SeriesDescription を優先します。さらに、 Philips で同じ SeriesInstanceUID に複数の再構成が含まれる場合は、ImageType 由来の再構成ラベルもフォルダ名に付きます。また、Philips でラベルが数字だけの 系列は、同一 acquisition 内の説明的な系列名を前置して分かりやすくします。

出力:

organized/<AcquisitionDate>/<SeriesNumber>_<SeriesFolderLabel>/000001.dcm
organized/<AcquisitionDate>/dicom_parameters.csv
organized/<AcquisitionDate>/series_summary.csv
organized/organize_summary.json

dicom_parameters.csv と series_summary.csv は対応している画像オブジェクトを 対象にしています。プレゼンテーションステートやベンダー独自の補助オブジェクトも フォルダ整理はされますが、パラメータ表からは除外されます。

実行サマリには、整理されたDICOMファイル総数と、CSVパラメータ表の対象になった ファイル数が分かれて表示されます。

profile=auto
organized_files=12
csv_target_files=10
csv_excluded_non_image_files=2

--dry-run ではファイルは書き込まれません。サマリには、作成予定のメタデータ ファイルも表示されます。

CSV列

dicom_parameters.csv は、共通の識別子、日付、患者情報、幾何情報、メーカー情報、 元ファイル名、ImageType、空間位置・方向の列から始まります。患者情報列は --patient-mode に従い、keep では PatientName と PatientID をそのまま書き、 hash では sha256: ダイジェストを書き、drop では N/A を書きます。確認用の hash列はどのモードでも出力されます。

profile別の列は共通列の後ろに追加されます。

• mr: TR/TE、bandwidth、echo train length、flip angle、加算回数、磁場強度、 sequence系、inversion time、echo number、acquisition matrix、phase encoding、 sampling、SAR、coil、MR acquisition type、Siemens channel補助列。
• ct: kVp、tube current、exposure time、convolution kernel、reconstruction diameter。
• us: transducer、mechanical/thermal index、color data flag。
• xa: kVp、tube current、exposure time、frame time、source-detector/source-patient距離。
• pt: radiopharmaceutical、dose、half-life、decay correction。

--profile auto は入力内に存在する対応モダリティの列をまとめて出力します。 --profile generic は共通列だけを出力します。繰り返し指定できる --dicom-tag 列はprofile列の後ろに追加されます。

よく使うオプション

患者情報をCSVに残したくない場合:

dicom-organizer --input /path/to/dicom-root --patient-mode hash
dicom-organizer --input /path/to/dicom-root --patient-mode drop

任意のDICOMタグをCSVに追加する場合:

dicom-organizer --input /path/to/dicom-root --dicom-tag EchoTime --dicom-tag InPlanePhaseEncodingDirection

GUIを使う場合:

uv tool install 'dicom-organizer[gui]'
dicom-organizer-gui

実DICOMなしで試す場合:

uv run python examples/synthetic_quickstart.py

注意: 既定の --patient-mode keep では PatientName と PatientID がCSVに残ります。共有前は hash または drop を使い、出力CSVを確認してください。

Development

uv sync --locked
uv run python -m pytest
uv run ruff check
uv build

MIT License. See LICENSE.