نام (NAME)

dcm2json - تبدیل فایل‌ها و داده‌های DICOM به فرمت JSON

خلاصه دستور (SYNOPSIS)

dcm2json [options] dcmfile-in [jsonfile-out]

توضیحات (DESCRIPTION)

ابزار dcm2json محتویات یک فایل DICOM (قالب فایل یا مجموعه‌داده خام) را به JSON (JavaScript Object Notation) تبدیل می‌کند. خروجی به «مدل DICOM JSON» که در بخش F از بخش ۱۸ استاندارد DICOM (DICOM Part 18 Section F) تعریف شده است ارجاع دارد.

اگر dcm2json یک مجموعه‌داده خام (داده‌های DICOM بدون فراداده سرآیند قالب فایل) را بخواند، تلاش خواهد کرد با بررسی چند بایت اول فایل، نحو انتقال (transfer syntax) را حدس بزند. همیشه امکان حدس درست نحو انتقال وجود ندارد و هر زمان ممکن باشد، تبدیل مجموعه‌داده به یک قالب فایل (با استفاده از ابزار dcmconv) بهتر است. همچنین می‌توان از گزینه‌های -f و -t[ieb] برای وادار کردن dcm2json به خواندن یک مجموعه‌داده با نحو انتقال مشخصی استفاده کرد.

پارامترها (PARAMETERS)

dcmfile-in   نام فایل ورودی DICOM برای تبدیل ("-" برای stdin)
jsonfile-out نام فایل خروجی JSON (پیش‌فرض: stdout)

گزینه‌ها (OPTIONS)

گزینه‌های عمومی (general options)

-h   --help
       چاپ این متن راهنما و خروج
     --version
       چاپ اطلاعات نسخه و خروج
     --arguments
       چاپ آرگومان‌های بسط‌یافته خط فرمان
-q   --quiet
       حالت بی‌صدا، عدم چاپ هشدارها و خطاها
-v   --verbose
       حالت پرگو، چاپ جزئیات پردازش
-d   --debug
       حالت اشکال‌زدایی، چاپ اطلاعات اشکال‌زدایی
-ll  --log-level  [l]evel: string constant
       (fatal, error, warn, info, debug, trace)
       استفاده از سطح l برای ثبت‌کننده وقایع
-lc  --log-config  [f]ilename: string
       استفاده از فایل پیکربندی f برای ثبت‌کننده وقایع

گزینه‌های ورودی (input options)

قالب فایل ورودی:
  +f   --read-file
         خواندن قالب فایل یا مجموعه‌داده (پیش‌فرض)
  +fo  --read-file-only
         فقط خواندن قالب فایل
  -f   --read-dataset
         خواندن مجموعه‌داده بدون اطلاعات متای فایل
نحو انتقال ورودی:
  -t=  --read-xfer-auto
         استفاده از تشخیص خودکار نحو انتقال (TS) (پیش‌فرض)
  -td  --read-xfer-detect
         نادیده گرفتن نحو انتقال (TS) مشخص‌شده در سرآیند متای فایل
  -te  --read-xfer-little
         خواندن با نحو انتقال با VR صریح و ترتیب بایت little endian
  -tb  --read-xfer-big
         خواندن با نحو انتقال با VR صریح و ترتیب بایت big endian
  -ti  --read-xfer-implicit
         خواندن با نحو انتقال با VR ضمنی و ترتیب بایت little endian

گزینه‌های پردازش (processing options)

کدگذاری بی‌نهایت (infinity) و غیرعدد (not-a-number):
  -es  --encode-strict
         گزارش خطا برای 'inf' و 'nan' (پیش‌فرض)
  -ee  --encode-extended
         مجاز دانستن 'inf' و 'nan' در اعداد JSON
کدگذاری عناصر IS و DS (رشته‌های عدد صحیح/اعشاری):
  -ia  --is-ds-auto
         کدگذاری به‌صورت عدد در صورت معتبر بودن، در غیر این صورت به‌صورت رشته (پیش‌فرض)
  -in  --is-ds-num
         همیشه کدگذاری به‌صورت عدد، شکست در صورت نامعتبر بودن
  -is  --is-ds-string
         همیشه کدگذاری به‌صورت رشته
گزینه‌های URI داده‌های حجیم (bulk data):
  -b   --bulk-disabled
         نوشتن همه چیز به‌صورت داده باینری درون‌خطی (inline binary) (پیش‌فرض)
  +b   --bulk-enabled
         نوشتن مشخصه‌های بزرگ به‌صورت داده‌های حجیم (bulk data)
  +bz  --bulk-size  [s]ize: integer (پیش‌فرض: 1)
         استفاده از bulk data برای مشخصه‌های >= s کیلوبایت
  +bp  --bulk-uri-prefix  [u]ri prefix: string
         استفاده از پیشوند u هنگام تولید URIهای bulk data (پیش‌فرض: file URI)
  +bd  --bulk-dir  [d]irectory: string
         نوشتن فایل‌های bulk data در d (پیش‌فرض: '.')
  +bs  --bulk-subdir
         ایجاد زیرپوشه برای هر نمونه SOP
         (پیش‌فرض: بدون زیرپوشه)

گزینه‌های خروجی (output options)

قالب خروجی:
  +fc  --formatted-code
         فعال‌سازی قالب‌بندی با فاصله‌های خالی (پیش‌فرض)
         # چاپ فاصله‌ها و خطوط جدید اضافی برای افزایش
         # خوانایی
  -fc  --compact-code
         فقط چاپ نویسه‌های ضروری
  +m   --write-meta
         نوشتن مجموعه‌داده با اطلاعات متا
         (هشدار: با استاندارد DICOM مطابقت ندارد)

قالب JSON (JSON Format)

ساختار اصلی خروجی JSON ایجادشده از یک فایل DICOM به شکل زیر است (برای جزئیات به بخش F از بخش ۱۸ استاندارد DICOM مراجعه کنید):

{
    "00080005": {
        "vr": "CS",
        "Value": [
            "ISO_IR 192"
        ]
    },
    "00080020": {
        "vr": "DT",
        "Value": [
            "20130409"
        ]
    },
    "00080030": {
        "vr": "TM",
        "Value": [
            "131600.0000"
        ]
    },
    "00080050": {
        "vr": "SH",
        "Value": [
            "11235813"
        ]
    },
    "00080056": {
        "vr": "CS",
        "Value": [
            "ONLINE"
        ]
    },
    "00080061": {
        "vr": "CS",
        "Value": [
            "CT",
            "PET"
        ]
    },
    "00080090": {
        "vr": "PN",
        "Value": [
          {
            "Alphabetic": "^Bob^^Dr."
          }
        ]
    },
    "00081190": {
        "vr": "UR",
        "Value": [
            "http://wado.nema.org/studies/
            1.2.392.200036.9116.2.2.2.1762893313.1029997326.945873"
        ]
    },
    "00090010": {
        "vr": "LO",
        "Value": [
            "Vendor A"
        ]
    },
    "00091002": {
        "vr": "UN",
        "InlineBinary": "z0x9c8v7"
    },
    "00100010": {
        "vr": "PN",
        "Value": [
          {
            "Alphabetic": "Wang^XiaoDong"
          }
        ]
    },
    "00100020": {
        "vr": "LO",
        "Value": [
            "12345"
        ]
    },
    "00100021": {
        "vr": "LO",
        "Value": [
            "Hospital A"
        ]
    },
    "00100030": {
        "vr": "DA",
        "Value": [
            "19670701"
        ]
    },
    "00100040": {
        "vr": "CS",
        "Value": [
            "M"
        ]
    },
    "00101002": {
        "vr": "SQ",
        "Value": [
            {
                "00100020": {
                    "vr": "LO",
                    "Value": [
                        "54321"
                    ]
                },
                "00100021": {
                    "vr": "LO",
                    "Value": [
                        "Hospital B"
                    ]
                }
            },
            {
                "00100020": {
                    "vr": "LO",
                    "Value": [
                        "24680"
                    ]
                },
                "00100021": {
                    "vr": "LO",
                    "Value": [
                        "Hospital C"
                    ]
                }
            }
        ]
    },
    "0020000D": {
        "vr": "UI",
        "Value": [
            "1.2.392.200036.9116.2.2.2.1762893313.1029997326.945873"
        ]
    },
    "00200010": {
        "vr": "SH",
        "Value": [
            "11235813"
        ]
    },
    "00201206": {
        "vr": "IS",
        "Value": [
            4
        ]
    },
    "00201208": {
        "vr": "IS",
        "Value": [
            942
        ]
    }
}

داده‌های حجیم (Bulk Data)

به‌طور پیش‌فرض، داده‌های باینری، یعنی مقادیر عناصر DICOM با بازنمایی‌های مقدار (VR) شامل OB، OD، OF، OL، OV، OW و UN به‌صورت "InlineBinary" (کدگذاری base64) در خروجی JSON نوشته می‌شوند. گزینه --bulk-enabled باعث می‌شود که در صورت بزرگ‌تر بودن مقدار عنصر از آستانه قطع (پیش‌فرض: ۱ کیلوبایت)، داده‌های باینری و همچنین DS، FD، FL، IS، SV و UV با مقادیر "BulkDataURI" جایگزین شوند. آستانه قطع می‌تواند با گزینه --bulk-size مشخص شود. خود مقادیر عناصر به‌صورت فایل‌هایی در پوشه مشخص‌شده با گزینه --bulk-dir نوشته می‌شوند (پیش‌فرض: پوشه جاری). نام فایل بر اساس جمع‌آزمای SHA-256 مقدار عنصر تعیین می‌شود. به‌طور پیش‌فرض، URIهای فایلی تولید می‌شوند که به پوشه داده‌های حجیم اشاره دارند. برای استفاده در محیط عملیاتی، باید یک پیشوند URI برای سرویس WADO-RS که مقادیر عناصر را بتوان از طریق آن واکشی کرد با استفاده از گزینه --bulk-uri-prefix مشخص شود. این کار را می‌توان با پیکربندی یک وب‌سرور که دسترسی خواندن به پوشه bulk برنامه dcm2json را دارد پیاده‌سازی کرد. در نهایت، گزینه --bulk-subdir باعث می‌شود برای هر نمونه SOP متمایز، یک زیرپوشه جداگانه ایجاد شود (و در URI داده‌های حجیم استفاده گردد).

توجه داشته باشید که نحو JSON برای نمایش داده‌های پیکسلی کپسوله‌شده به فرم "InlineBinary" در استاندارد DICOM نامشخص است، همان‌طور که نمایش JSON داده‌های پیکسلی چندفریمی کپسوله‌شده نیز تعیین نشده است. این فایل‌های DICOM را نمی‌توان با استفاده از dcm2json به JSON تبدیل کرد.

پسوند نام فایل برای فایل‌های داده‌های حجیم تولیدشده می‌تواند برای تعیین نوع MIME که باید توسط کارساز WADO-RS بازگردانده شود استفاده گردد:

Extension     MIME Type
.bin          application/octet-stream
.jpeg         image/jpeg
.dicom-rle    image/dicom-rle
.jls          image/jls
.jp2          image/jp2
.jpx          image/jpx
.jphc         image/jphc
.jxl          image/jxl
.mpeg         video/mpeg
.mp4          video/mp4
.H265         video/H265

در نهایت، باید توجه داشت که داده‌های حجیم «همان‌گونه که هست» (as is) نوشته خواهند شد، یعنی dcm2json به هیچ وجه برای اعتبارسنجی یا تغییر مقدار عنصر تلاش نخواهد کرد. برای نمونه، در مورد تصاویر فشرده‌شده خط مبنای JPEG (baseline compressed)، که ممکن است برخی نمایش‌دهنده‌های JPEG انتظار آن را داشته باشند، dcm2json سرآیند JFIF را اضافه نخواهد کرد.

نکات (NOTES)

اعداد به‌صورت رشته (Numbers as Strings)

استاندارد DICOM اجازه می‌دهد بازنمایی‌های عددی معینی از مقادیر در DICOM، یعنی DS، IS، SV و UV، هم به یک عدد JSON و هم به یک رشته JSON تبدیل شوند. ابزار dcm2json مقادیر DS و IS را در صورتی که رشته‌های اعشاری یا رشته‌های عدد صحیح معتبری باشند به اعداد JSON، و در صورتی که حاوی هرگونه نویسه غیرمجاز باشند به رشته تبدیل می‌کند. ابزار dcm2json مقادیر SV و UV را در صورتی که بزرگ‌تر از 9007199254740991ll یا کوچک‌تر از -9007199254740991ll نباشند به عدد، و در غیر این صورت به رشته تبدیل می‌نماید. در حالی که مشخصات JSON اعداد بزرگ‌تر را نیز مجاز می‌داند، این مقادیر بزرگ‌ترین اعداد صحیحی هستند که جاوااسکریپت می‌تواند مدیریت کند. از این رو، بسیاری از تجزیه‌کننده‌های JSON نمی‌توانند اعداد بزرگ‌تر را پردازش کنند.

کدگذاری نویسه‌ها (Character Encoding)

همان‌گونه که توسط کدگذاری DICOM JSON الزامی شده است، dcm2json همواره خروجی را با کدگذاری یونیکد UTF-8 ایجاد کرده و مجموعه‌داده‌های DICOM را بر همان اساس تبدیل می‌کند. اگر این امر امکان‌پذیر نباشد، برای نمونه به این دلیل که DCMTK بدون پشتیبانی از تبدیل مجموعه نویسه کامپایل شده باشد، یک خطا بازگردانده می‌شود.

ثبت وقایع (LOGGING)

سطح خروجی ثبت وقایع ابزارهای مختلف خط فرمان و کتابخانه‌های زیرین می‌تواند توسط کاربر تعیین شود. به‌طور پیش‌فرض، تنها خطاها و هشدارها در جریان خطای استاندارد نوشته می‌شوند. با استفاده از گزینه --verbose پیام‌های اطلاعاتی مانند جزئیات پردازش نیز گزارش می‌شوند. گزینه --debug می‌تواند برای دریافت جزئیات بیشتر درباره فعالیت‌های داخلی، برای مثال جهت مقاصد اشکال‌زدایی استفاده شود. سایر سطوح ثبت وقایع را می‌توان با استفاده از گزینه --log-level انتخاب کرد. در حالت --quiet تنها خطاهای مهلک گزارش می‌شوند. در چنین شرایط خطای بسیار شدیدی، برنامه معمولاً خاتمه می‌یابد. برای جزئیات بیشتر درباره سطوح مختلف ثبت وقایع، به مستندات ماژول "oflog" مراجعه کنید.

در صورتی که خروجی ثبت وقایع باید در فایل نوشته شود (اختیاراً همراه با چرخش فایل وقایع)، یا به syslog (یونیکس) یا event log (ویندوز) فرستاده شود، گزینه --log-config می‌تواند استفاده شود. این فایل پیکربندی همچنین امکان هدایت تنها پیام‌های خاص به یک جریان خروجی مشخص و فیلتر کردن برخی پیام‌ها بر اساس ماژول یا برنامه‌ای که تولید شده‌اند را فراهم می‌کند. یک فایل پیکربندی نمونه در <etcdir>/logger.cfg ارائه شده است.

خط فرمان (COMMAND LINE)

تمام ابزارهای خط فرمان از نمادگذاری زیر برای پارامترها استفاده می‌کنند: کروشه‌ها مقادیر اختیاری (۰-۱) را احاطه می‌کنند، سه نقطه انتهایی نشان می‌دهد که چند مقدار مجاز است (۱-n)، و ترکیبی از هر دو به معنی ۰ تا n مقدار است.

گزینه‌های خط فرمان به ترتیب با یک علامت پیشوند '+' یا '-' از پارامترها متمایز می‌شوند. معمولاً ترتیب و موقعیت گزینه‌های خط فرمان اختیاری است (یعنی می‌توانند در هر جایی ظاهر شوند). با این حال، اگر گزینه‌ها مانعة‌الجمع باشند، راست‌ترین مورد به کار گرفته می‌شود. این رفتار با قواعد ارزیابی استاندارد در شل‌های متداول یونیکس مطابقت دارد.

علاوه بر این، یک یا چند فایل دستور را می‌توان با استفاده از علامت '@' به عنوان پیشوند نام فایل مشخص کرد (مانند @command.txt). چنین آرگومان دستوری پیش از هر ارزیابی بیشتر، با محتوای فایل متنی مربوطه جایگزین می‌شود (فاصله‌های خالی متعدد به عنوان یک جداکننده منفرد در نظر گرفته می‌شوند مگر اینکه میان دو علامت نقل قول قرار گیرند). لطفاً توجه داشته باشید که یک فایل دستور نمی‌تواند شامل فایل دستور دیگری باشد. این رویکرد ساده اما مؤثر امکان خلاصه کردن ترکیب‌های متداول گزینه‌ها/پارامترها را فراهم کرده و از خط فرمان‌های طولانی و گیج‌کننده جلوگیری می‌کند (یک مثال در فایل <datadir>/dumppat.txt ارائه شده است).

کدهای خروج (EXIT CODES)

ابزار dcm2json هنگام خاتمه از کدهای خروج زیر استفاده می‌کند. این امر کاربر را قادر می‌سازد دلیل خاتمه برنامه را بررسی کند.

عمومی (general)

EXITCODE_NO_ERROR                         0
EXITCODE_COMMANDLINE_SYNTAX_ERROR         1

خطاهای فایل ورودی (input file errors)

EXITCODE_CANNOT_READ_INPUT_FILE          20
EXITCODE_NO_INPUT_FILES                  21

خطاهای فایل خروجی (output file errors)

EXITCODE_CANNOT_WRITE_OUTPUT_FILE        40

خطاهای پردازش (processing errors)

EXITCODE_CANNOT_CONVERT_TO_UNICODE       80
EXITCODE_CANNOT_WRITE_VALID_JSON         81

محیط (ENVIRONMENT)

ابزار dcm2json تلاش خواهد کرد واژه‌نامه‌های داده DICOM مشخص‌شده در متغیر محیطی DCMDICTPATH را بارگذاری کند. به‌طور پیش‌فرض، یعنی اگر متغیر محیطی DCMDICTPATH تنظیم نشده باشد، فایل <datadir>/dicom.dic بارگذاری خواهد شد مگر اینکه واژه‌نامه درون خود برنامه تعبیه شده باشد (پیش‌فرض برای ویندوز).

رفتار پیش‌فرض ارجحیت دارد و از متغیر محیطی DCMDICTPATH تنها زمانی باید استفاده شود که واژه‌نامه‌های داده جایگزین مورد نیاز باشند. متغیر محیطی DCMDICTPATH قالبی مشابه متغیر PATH در پوسته یونیکس دارد به این صورت که علامت دونقطه (":") ورودی‌ها را جدا می‌کند. در سیستم‌های ویندوز، از یک نقطه‌ویرگول (";") به عنوان جداکننده استفاده می‌شود. کد واژه‌نامه داده تلاش خواهد کرد تا هر فایل مشخص‌شده در متغیر محیطی DCMDICTPATH را بارگذاری کند. بارگذاری نشدن هیچ واژه‌نامه داده‌ای یک خطا محسوب می‌شود.

ابزار dcm2json تلاش خواهد کرد جدول‌های نگاشت مجموعه نویسه را بارگذاری کند. این حالت زمانی رخ می‌دهد که DCMTK با کتابخانه oficonv کامپایل شده باشد (که پیش‌فرض است) و جدول‌های نگاشت درون کتابخانه تعبیه نشده باشند (پیش‌فرض هنگامی که DCMTK از کتابخانه‌های مشترک استفاده می‌کند).

فایل‌های جدول نگاشت در <datadir> برنامه DCMTK مورد انتظار هستند. متغیر محیطی DCMICONVPATH می‌تواند برای مشخص کردن مکان دیگری استفاده شود. در صورت مشخص شدن مکانی متفاوت، آن جدول‌های نگاشت جایگزین هرگونه جدول تعبیه‌شده نیز خواهند شد.