.TH "dcm2json" 1 "Thu Jul 9 2026 18:43:40" "Version 3.7.0" "OFFIS DCMTK" \" -*- nroff -*- .nh .SH "نام (NAME)" dcm2json \- تبدیل فایل‌ها و داده‌های DICOM به فرمت JSON .PP .SH "خلاصه دستور (SYNOPSIS)" .PP .PP .nf dcm2json [options] dcmfile-in [jsonfile-out] .fi .PP .SH "توضیحات (DESCRIPTION)" .PP ابزار \fBdcm2json\fP محتویات یک فایل DICOM (قالب فایل یا مجموعه‌داده خام) را به JSON (JavaScript Object Notation) تبدیل می‌کند\&. خروجی به «مدل DICOM JSON» که در بخش F از بخش ۱۸ استاندارد DICOM (DICOM Part 18 Section F) تعریف شده است ارجاع دارد\&. .PP اگر \fBdcm2json\fP یک مجموعه‌داده خام (داده‌های DICOM بدون فراداده سرآیند قالب فایل) را بخواند، تلاش خواهد کرد با بررسی چند بایت اول فایل، نحو انتقال (transfer syntax) را حدس بزند\&. همیشه امکان حدس درست نحو انتقال وجود ندارد و هر زمان ممکن باشد، تبدیل مجموعه‌داده به یک قالب فایل (با استفاده از ابزار \fBdcmconv\fP) بهتر است\&. همچنین می‌توان از گزینه‌های \fI-f\fP و \fI-t[ieb]\fP برای وادار کردن \fBdcm2json\fP به خواندن یک مجموعه‌داده با نحو انتقال مشخصی استفاده کرد\&. .SH "پارامترها (PARAMETERS)" .PP .PP .nf dcmfile-in نام فایل ورودی DICOM برای تبدیل ("-" برای stdin) jsonfile-out نام فایل خروجی JSON (پیش‌فرض: stdout) .fi .PP .SH "گزینه‌ها (OPTIONS)" .PP .SS "گزینه‌های عمومی (general options)" .PP .nf -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 برای ثبت‌کننده وقایع .fi .PP .SS "گزینه‌های ورودی (input options)" .PP .nf قالب فایل ورودی: +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 .fi .PP .SS "گزینه‌های پردازش (processing options)" .PP .nf کدگذاری بی‌نهایت (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 (پیش‌فرض: بدون زیرپوشه) .fi .PP .SS "گزینه‌های خروجی (output options)" .PP .nf قالب خروجی: +fc --formatted-code فعال‌سازی قالب‌بندی با فاصله‌های خالی (پیش‌فرض) # چاپ فاصله‌ها و خطوط جدید اضافی برای افزایش # خوانایی -fc --compact-code فقط چاپ نویسه‌های ضروری +m --write-meta نوشتن مجموعه‌داده با اطلاعات متا (هشدار: با استاندارد DICOM مطابقت ندارد) .fi .PP .SH "قالب JSON (JSON Format)" .PP ساختار اصلی خروجی JSON ایجادشده از یک فایل DICOM به شکل زیر است (برای جزئیات به بخش F از بخش ۱۸ استاندارد DICOM مراجعه کنید): .PP .PP .nf { "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 ] } } .fi .PP .SS "داده‌های حجیم (Bulk Data)" به‌طور پیش‌فرض، داده‌های باینری، یعنی مقادیر عناصر DICOM با بازنمایی‌های مقدار (VR) شامل OB، OD، OF، OL، OV، OW و UN به‌صورت "InlineBinary" (کدگذاری base64) در خروجی JSON نوشته می‌شوند\&. گزینه \fI--bulk-enabled\fP باعث می‌شود که در صورت بزرگ‌تر بودن مقدار عنصر از آستانه قطع (پیش‌فرض: ۱ کیلوبایت)، داده‌های باینری و همچنین DS، FD، FL، IS، SV و UV با مقادیر "BulkDataURI" جایگزین شوند\&. آستانه قطع می‌تواند با گزینه \fI--bulk-size\fP مشخص شود\&. خود مقادیر عناصر به‌صورت فایل‌هایی در پوشه مشخص‌شده با گزینه \fI--bulk-dir\fP نوشته می‌شوند (پیش‌فرض: پوشه جاری)\&. نام فایل بر اساس جمع‌آزمای SHA-256 مقدار عنصر تعیین می‌شود\&. به‌طور پیش‌فرض، URIهای فایلی تولید می‌شوند که به پوشه داده‌های حجیم اشاره دارند\&. برای استفاده در محیط عملیاتی، باید یک پیشوند URI برای سرویس WADO-RS که مقادیر عناصر را بتوان از طریق آن واکشی کرد با استفاده از گزینه \fI--bulk-uri-prefix\fP مشخص شود\&. این کار را می‌توان با پیکربندی یک وب‌سرور که دسترسی خواندن به پوشه bulk برنامه \fBdcm2json\fP را دارد پیاده‌سازی کرد\&. در نهایت، گزینه \fI--bulk-subdir\fP باعث می‌شود برای هر نمونه SOP متمایز، یک زیرپوشه جداگانه ایجاد شود (و در URI داده‌های حجیم استفاده گردد)\&. .PP توجه داشته باشید که نحو JSON برای نمایش داده‌های پیکسلی کپسوله‌شده به فرم "InlineBinary" در استاندارد DICOM نامشخص است، همان‌طور که نمایش JSON داده‌های پیکسلی چندفریمی کپسوله‌شده نیز تعیین نشده است\&. این فایل‌های DICOM را نمی‌توان با استفاده از \fBdcm2json\fP به JSON تبدیل کرد\&. .PP پسوند نام فایل برای فایل‌های داده‌های حجیم تولیدشده می‌تواند برای تعیین نوع MIME که باید توسط کارساز WADO-RS بازگردانده شود استفاده گردد: .PP .PP .nf 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 .fi .PP .PP در نهایت، باید توجه داشت که داده‌های حجیم «همان‌گونه که هست» (as is) نوشته خواهند شد، یعنی \fBdcm2json\fP به هیچ وجه برای اعتبارسنجی یا تغییر مقدار عنصر تلاش نخواهد کرد\&. برای نمونه، در مورد تصاویر فشرده‌شده خط مبنای JPEG (baseline compressed)، که ممکن است برخی نمایش‌دهنده‌های JPEG انتظار آن را داشته باشند، \fBdcm2json\fP سرآیند JFIF را اضافه نخواهد کرد\&. .SH "نکات (NOTES)" .PP .SS "اعداد به‌صورت رشته (Numbers as Strings)" استاندارد DICOM اجازه می‌دهد بازنمایی‌های عددی معینی از مقادیر در DICOM، یعنی DS، IS، SV و UV، هم به یک عدد JSON و هم به یک رشته JSON تبدیل شوند\&. ابزار \fBdcm2json\fP مقادیر DS و IS را در صورتی که رشته‌های اعشاری یا رشته‌های عدد صحیح معتبری باشند به اعداد JSON، و در صورتی که حاوی هرگونه نویسه غیرمجاز باشند به رشته تبدیل می‌کند\&. ابزار \fBdcm2json\fP مقادیر SV و UV را در صورتی که بزرگ‌تر از 9007199254740991ll یا کوچک‌تر از \-9007199254740991ll نباشند به عدد، و در غیر این صورت به رشته تبدیل می‌نماید\&. در حالی که مشخصات JSON اعداد بزرگ‌تر را نیز مجاز می‌داند، این مقادیر بزرگ‌ترین اعداد صحیحی هستند که جاوااسکریپت می‌تواند مدیریت کند\&. از این رو، بسیاری از تجزیه‌کننده‌های JSON نمی‌توانند اعداد بزرگ‌تر را پردازش کنند\&. .SS "کدگذاری نویسه‌ها (Character Encoding)" همان‌گونه که توسط کدگذاری DICOM JSON الزامی شده است، \fBdcm2json\fP همواره خروجی را با کدگذاری یونیکد UTF-8 ایجاد کرده و مجموعه‌داده‌های DICOM را بر همان اساس تبدیل می‌کند\&. اگر این امر امکان‌پذیر نباشد، برای نمونه به این دلیل که DCMTK بدون پشتیبانی از تبدیل مجموعه نویسه کامپایل شده باشد، یک خطا بازگردانده می‌شود\&. .SH "ثبت وقایع (LOGGING)" .PP سطح خروجی ثبت وقایع ابزارهای مختلف خط فرمان و کتابخانه‌های زیرین می‌تواند توسط کاربر تعیین شود\&. به‌طور پیش‌فرض، تنها خطاها و هشدارها در جریان خطای استاندارد نوشته می‌شوند\&. با استفاده از گزینه \fI--verbose\fP پیام‌های اطلاعاتی مانند جزئیات پردازش نیز گزارش می‌شوند\&. گزینه \fI--debug\fP می‌تواند برای دریافت جزئیات بیشتر درباره فعالیت‌های داخلی، برای مثال جهت مقاصد اشکال‌زدایی استفاده شود\&. سایر سطوح ثبت وقایع را می‌توان با استفاده از گزینه \fI--log-level\fP انتخاب کرد\&. در حالت \fI--quiet\fP تنها خطاهای مهلک گزارش می‌شوند\&. در چنین شرایط خطای بسیار شدیدی، برنامه معمولاً خاتمه می‌یابد\&. برای جزئیات بیشتر درباره سطوح مختلف ثبت وقایع، به مستندات ماژول "oflog" مراجعه کنید\&. .PP در صورتی که خروجی ثبت وقایع باید در فایل نوشته شود (اختیاراً همراه با چرخش فایل وقایع)، یا به syslog (یونیکس) یا event log (ویندوز) فرستاده شود، گزینه \fI--log-config\fP می‌تواند استفاده شود\&. این فایل پیکربندی همچنین امکان هدایت تنها پیام‌های خاص به یک جریان خروجی مشخص و فیلتر کردن برخی پیام‌ها بر اساس ماژول یا برنامه‌ای که تولید شده‌اند را فراهم می‌کند\&. یک فایل پیکربندی نمونه در \fI/logger\&.cfg\fP ارائه شده است\&. .SH "خط فرمان (COMMAND LINE)" .PP تمام ابزارهای خط فرمان از نمادگذاری زیر برای پارامترها استفاده می‌کنند: کروشه‌ها مقادیر اختیاری (۰\-۱) را احاطه می‌کنند، سه نقطه انتهایی نشان می‌دهد که چند مقدار مجاز است (۱\-n)، و ترکیبی از هر دو به معنی ۰ تا n مقدار است\&. .PP گزینه‌های خط فرمان به ترتیب با یک علامت پیشوند '+' یا '\-' از پارامترها متمایز می‌شوند\&. معمولاً ترتیب و موقعیت گزینه‌های خط فرمان اختیاری است (یعنی می‌توانند در هر جایی ظاهر شوند)\&. با این حال، اگر گزینه‌ها مانعة‌الجمع باشند، راست‌ترین مورد به کار گرفته می‌شود\&. این رفتار با قواعد ارزیابی استاندارد در شل‌های متداول یونیکس مطابقت دارد\&. .PP علاوه بر این، یک یا چند فایل دستور را می‌توان با استفاده از علامت '@' به عنوان پیشوند نام فایل مشخص کرد (مانند \fI@command\&.txt\fP)\&. چنین آرگومان دستوری پیش از هر ارزیابی بیشتر، با محتوای فایل متنی مربوطه جایگزین می‌شود (فاصله‌های خالی متعدد به عنوان یک جداکننده منفرد در نظر گرفته می‌شوند مگر اینکه میان دو علامت نقل قول قرار گیرند)\&. لطفاً توجه داشته باشید که یک فایل دستور نمی‌تواند شامل فایل دستور دیگری باشد\&. این رویکرد ساده اما مؤثر امکان خلاصه کردن ترکیب‌های متداول گزینه‌ها/پارامترها را فراهم کرده و از خط فرمان‌های طولانی و گیج‌کننده جلوگیری می‌کند (یک مثال در فایل \fI/dumppat\&.txt\fP ارائه شده است)\&. .SH "کدهای خروج (EXIT CODES)" .PP ابزار \fBdcm2json\fP هنگام خاتمه از کدهای خروج زیر استفاده می‌کند\&. این امر کاربر را قادر می‌سازد دلیل خاتمه برنامه را بررسی کند\&. .SS "عمومی (general)" .PP .nf EXITCODE_NO_ERROR 0 EXITCODE_COMMANDLINE_SYNTAX_ERROR 1 .fi .PP .SS "خطاهای فایل ورودی (input file errors)" .PP .nf EXITCODE_CANNOT_READ_INPUT_FILE 20 EXITCODE_NO_INPUT_FILES 21 .fi .PP .SS "خطاهای فایل خروجی (output file errors)" .PP .nf EXITCODE_CANNOT_WRITE_OUTPUT_FILE 40 .fi .PP .SS "خطاهای پردازش (processing errors)" .PP .nf EXITCODE_CANNOT_CONVERT_TO_UNICODE 80 EXITCODE_CANNOT_WRITE_VALID_JSON 81 .fi .PP .SH "محیط (ENVIRONMENT)" .PP ابزار \fBdcm2json\fP تلاش خواهد کرد واژه‌نامه‌های داده DICOM مشخص‌شده در متغیر محیطی \fIDCMDICTPATH\fP را بارگذاری کند\&. به‌طور پیش‌فرض، یعنی اگر متغیر محیطی \fIDCMDICTPATH\fP تنظیم نشده باشد، فایل \fI/dicom\&.dic\fP بارگذاری خواهد شد مگر اینکه واژه‌نامه درون خود برنامه تعبیه شده باشد (پیش‌فرض برای ویندوز)\&. .PP رفتار پیش‌فرض ارجحیت دارد و از متغیر محیطی \fIDCMDICTPATH\fP تنها زمانی باید استفاده شود که واژه‌نامه‌های داده جایگزین مورد نیاز باشند\&. متغیر محیطی \fIDCMDICTPATH\fP قالبی مشابه متغیر \fIPATH\fP در پوسته یونیکس دارد به این صورت که علامت دونقطه (":") ورودی‌ها را جدا می‌کند\&. در سیستم‌های ویندوز، از یک نقطه‌ویرگول (";") به عنوان جداکننده استفاده می‌شود\&. کد واژه‌نامه داده تلاش خواهد کرد تا هر فایل مشخص‌شده در متغیر محیطی \fIDCMDICTPATH\fP را بارگذاری کند\&. بارگذاری نشدن هیچ واژه‌نامه داده‌ای یک خطا محسوب می‌شود\&. .PP ابزار \fBdcm2json\fP تلاش خواهد کرد جدول‌های نگاشت مجموعه نویسه را بارگذاری کند\&. این حالت زمانی رخ می‌دهد که DCMTK با کتابخانه oficonv کامپایل شده باشد (که پیش‌فرض است) و جدول‌های نگاشت درون کتابخانه تعبیه نشده باشند (پیش‌فرض هنگامی که DCMTK از کتابخانه‌های مشترک استفاده می‌کند)\&. .PP فایل‌های جدول نگاشت در \fI\fP برنامه DCMTK مورد انتظار هستند\&. متغیر محیطی \fIDCMICONVPATH\fP می‌تواند برای مشخص کردن مکان دیگری استفاده شود\&. در صورت مشخص شدن مکانی متفاوت، آن جدول‌های نگاشت جایگزین هرگونه جدول تعبیه‌شده نیز خواهند شد\&. .SH "حق نشر (COPYRIGHT)" .PP Copyright (C) 2016-2025 by OFFIS e\&.V\&., Escherweg 2, 26121 Oldenburg, Germany\&.