نام (NAME)

xml2dcm - تبدیل ساختار سند XML به قالب دودویی DICOM

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

xml2dcm [options] xmlfile-in dcmfile-out

توضیحات (DESCRIPTION)

ابزار xml2dcm محتویات یک سند XML (زبان نشانه‌گذاری گسترش‌پذیر) را به یک فایل یا مجموعه داده DICOM تبدیل می‌کند. انتظار می‌رود سند XML با DTD (تعریف نوع سند) که در فایل dcm2xml.dtd شرح داده شده است، اعتبارسنجی شود. یک فایل XML مناسب را می‌توان با استفاده از ابزار dcm2xml ایجاد کرد (گزینه +Wb برای گنجاندن داده‌های دودویی توصیه می‌شود).

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

xmlfile-in   نام فایل ورودی XML برای تبدیل ("-" برای stdin)
dcmfile-out  نام فایل خروجی DICOM ("-" برای 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-meta-info
         خواندن اطلاعات متای فایل در صورت وجود (پیش‌فرض)
  -f   --ignore-meta-info
         نادیده گرفتن اطلاعات متای فایل

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

اعتبارسنجی:
  +Vd  --validate-document
         اعتبارسنجی سند XML در برابر DTD
  +Vn  --check-namespace
         بررسی فضای نام XML در ریشه سند
شناسه‌های یکتا (UIDs):
  +Ug  --generate-new-uids
         تولید Study/Series/SOP Instance UID جدید
  -Uo  --dont-overwrite-uids
         عدم بازنویسی UIDهای موجود (پیش‌فرض)
  +Uo  --overwrite-uids
         بازنویسی UIDهای موجود

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

قالب فایل خروجی:
  +F   --write-file
         نوشتن قالب فایل (پیش‌فرض)
  -F   --write-dataset
         نوشتن مجموعه داده بدون اطلاعات متای فایل
  +Fu  --update-meta-info
         به‌روزرسانی اطلاعات متای خاص فایل
نحو انتقال خروجی:
  +t=  --write-xfer-same
         نوشتن با همان TS ورودی (پیش‌فرض)
  +te  --write-xfer-little
         نوشتن با TS صریح VR و ترتیب بایت little endian
  +tb  --write-xfer-big
         نوشتن با TS صریح VR و ترتیب بایت big endian
  +ti  --write-xfer-implicit
         نوشتن با TS ضمنی VR و ترتیب بایت little endian
  +td  --write-xfer-deflated
         نوشتن با TS فشرده‌شده deflated صریح VR و ترتیب بایت little endian
مدیریت خطا:
  -E   --stop-on-error
         عدم نوشتن در صورت نامعتبر بودن سند (پیش‌فرض)
  +E   --ignore-errors
         تلاش برای نوشتن حتی در صورت نامعتبر بودن سند
نمایش‌های مقداری (VR) پس از ۱۹۹۳:
  +u   --enable-new-vr
         فعال‌سازی پشتیبانی از VRهای جدید (UN/UT) (پیش‌فرض)
  -u   --disable-new-vr
         غیرفعال‌سازی پشتیبانی از VRهای جدید، تبدیل به OB
کدگذاری طول گروه:
  +g=  --group-length-recalc
         محاسبه مجدد طول گروه‌ها در صورت وجود (پیش‌فرض)
  +g   --group-length-create
         همیشه نوشتن با عناصر طول گروه
  -g   --group-length-remove
         همیشه نوشتن بدون عناصر طول گروه
کدگذاری طول در توالی‌ها و آیتم‌ها:
  +e   --length-explicit
         نوشتن با طول‌های صریح (پیش‌فرض)
  -e   --length-undefined
         نوشتن با طول‌های تعریف‌نشده
پدینگ انتهایی مجموعه داده (نه با --write-dataset):
  -p=  --padding-retain
         عدم تغییر پدینگ (پیش‌فرض در صورت عدم استفاده از --write-dataset)
  -p   --padding-off
         بدون پدینگ (ضمنی در صورت استفاده از --write-dataset)
  +p   --padding-create  [f]ile-pad [i]tem-pad: integer
         تراز کردن فایل روی مضربی از f بایت و آیتم‌ها روی
         مضربی از i بایت
سطح فشرده‌سازی deflate (فقط با --write-xfer-deflated):
  +cl  --compression-level  [l]evel: integer (پیش‌فرض: 6)
         0=بدون فشرده‌سازی، 1=سریع‌ترین، 9=بهترین فشرده‌سازی

نکات (NOTES)

ساختار پایه ورودی XML مورد انتظار به صورت زیر است:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE file-format SYSTEM "dcm2xml.dtd">
<file-format xmlns="http://dicom.offis.de/dcmtk">
  <meta-header xfer="1.2.840.10008.1.2.1" name="Little Endian Explicit">
    <element tag="0002,0000" vr="UL" vm="1" len="4"
             name="MetaElementGroupLength">
      166
    </element>
    ...
    <element tag="0002,0013" vr="SH" vm="1" len="16"
             name="ImplementationVersionName">
      OFFIS_DCMTK_353
    </element>
  </meta-header>
  <data-set xfer="1.2.840.10008.1.2" name="Little Endian Implicit">
    <element tag="0008,0005" vr="CS" vm="1" len="10"
             name="SpecificCharacterSet">
      ISO_IR 100
    </element>
    ...
    <sequence tag="0028,3010" vr="SQ" card="2" name="VOILUTSequence">
      <item card="3">
        <element tag="0028,3002" vr="xs" vm="3" len="6"
                 name="LUTDescriptor">
          256\0\8
        </element>
        ...
      </item>
      ...
    </sequence>
    ...
    <element tag="7fe0,0010" vr="OW" vm="1" len="262144"
             name="PixelData" loaded="no" binary="hidden">
    </element>
  </data-set>
</file-format>

تگ‌های "file-format" و "meta-header" ممکن است برای مجموعه‌های داده DICOM وجود نداشته باشند.

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

کدگذاری نویسه DICOM به‌طور خودکار از عنصر با تگ "0008,0005" (Specific Character Set) در صورت وجود تعیین می‌شود. مجموعه‌های نویسه زیر در حال حاضر پشتیبانی می‌شوند (نیازمند پشتیبانی iconv در libxml است، خروجی --version را ببینید):

ASCII         (ISO_IR 6)    (UTF-8)
UTF-8         "ISO_IR 192"  (UTF-8)
ISO Latin 1   "ISO_IR 100"  (ISO-8859-1)
ISO Latin 2   "ISO_IR 101"  (ISO-8859-2)
ISO Latin 3   "ISO_IR 109"  (ISO-8859-3)
ISO Latin 4   "ISO_IR 110"  (ISO-8859-4)
ISO Latin 5   "ISO_IR 148"  (ISO-8859-9)
ISO Latin 9   "ISO_IR 203"  (ISO-8859-15)
Cyrillic      "ISO_IR 144"  (ISO-8859-5)
Arabic        "ISO_IR 127"  (ISO-8859-6)
Greek         "ISO_IR 126"  (ISO-8859-7)
Hebrew        "ISO_IR 138"  (ISO-8859-8)

استفاده از چندین مجموعه نویسه پشتیبانی نمی‌شود (در صورت چندگانگی مقدار، تنها اولین مقدار "Specific Character Set" برای کدگذاری نویسه استفاده می‌شود).

برای جزئیات بیشتر در مورد ساختار XML به مستندات dcm2xml مراجعه کنید.

داده‌های دودویی (Binary Data)

داده‌های دودویی (*) را می‌توان به صورت توالی‌ای از اعداد هگزادسیمال که با اسلش وارونه "\" از یکدیگر جدا شده‌اند یا در قالب Base64 با (binary="base64") کدگذاری کرد. علاوه بر این، داده‌های دودویی می‌توانند از یک فایل نیز خوانده شوند (binary="file"). در این حالت، نام فایل باید به عنوان مقدار عنصر مشخص شود، به عنوان مثال:

<element tag="7fe0,0010" vr="OW" ... binary="file">subdir/pixeldata.raw</element>

لطفاً توجه داشته باشید که محتویات فایل همان‌گونه که هست (as is) خوانده خواهد شد. انتظار می‌رود داده‌های OW دارای ترتیب بایت little endian باشند و در صورت لزوم جابه‌جا (swap) خواهند شد. هیچ بررسی انجام نخواهد شد تا اطمینان حاصل شود که مقدار داده با توجه به سایر ویژگی‌ها مانند Rows یا Columns منطقی است یا خیر.

(*) لطفاً توجه داشته باشید که در حال حاضر تنها داده‌های OB و OW پشتیبانی می‌شوند؛ یعنی مقادیر عناصر با VRهای OD، OF، OL و OV به عنوان «داده دودویی» در نظر گرفته نمی‌شوند و مانند تمام VRهای دیگر با آن‌ها رفتار می‌شود.

فشرده‌سازی (Compression)

اگر libxml با پشتیبانی از zlib کامپایل شده باشد، فایل ورودی (xmlfile-in) می‌تواند با ZIP نیز فشرده شود که معمولاً منجر به فایل‌های بسیار کوچک‌تری می‌شود. برای بررسی اینکه آیا پشتیبانی از zlib در دسترس است، خروجی گزینه --version را مشاهده کنید.

محدودیت‌ها (Limitations)

نسخه‌های مختلف libxml ممکن است محدودیت‌های متفاوتی برای حداکثر طول مقدار یک عنصر XML داشته باشند. بنابراین، باید از استفاده از مقادیر بسیار طولانی عناصر (مثلاً برای داده‌های پیکسل) خودداری شود.

لطفاً توجه داشته باشید که xml2dcm در حال حاضر به‌طور کامل از فایل‌های DICOMDIR پشتیبانی نمی‌کند. به‌طور مشخص، مقدار عناصر داده‌ای مختلف offset به‌طور خودکار توسط این ابزار به‌روزرسانی نمی‌شود.

گزارش‌گیری (LOGGING)

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

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

خط فرمان (COMMAND LINE)

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

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

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

محیط (ENVIRONMENT)

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

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