/usr/share/pixelmed/DicomCleanerUsage.html is in pixelmed-www 20150917-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <html>
<head>
<title>How to use DicomCleaner™</title>
</head>
<body>
<table width="100%">
<tr>
<td><img SRC="images/PixelMedLogoAndTitle.gif" ALT="PixelMed Publishing™" BORDER=0></td>
<td><A HREF="http://www.opensource.org/"><IMG SRC="images/osi_standard_logo.png" width="90" height="103" border="0"/></A></td>
</tr>
</table>
<hr/>
<table>
<tr>
<td><a href="DicomCleaner.html"><IMG SRC="images/DicomCleanerMainPanelAfterClean.png" width="800" BORDER=0/></a></td>
</tr>
</table>
<hr/>
<a href="DicomCleaner.html"><IMG SRC="icons/DicomCleaner.png" ALT="Click here to start the DicomCleaner™" BORDER=0/></a>
<a name="Description"><h1>What is <a href="DicomCleaner.html">DicomCleaner™</a>?</h1></a>
<p><a href="DicomCleaner.html">DicomCleaner™</a> is a free open source tool with a user interface for importing, "cleaning" and saving sets of DICOM instances (files). It can:</p>
<ul>
<li>Import files from a CD or the local hard drive or a shared network drive or any other media, with or without a DICOMDIR</li>
<li>Query and retrieve from remote DICOM devices</li>
<li>"Clean" the DICOM "header" of a selected set of instances</li>
<li>Blackout burned in annotations in the pixel data of the cleaned files</li>
<li>Export the cleaned instances to a folder with a DICOMDIR, which can be burned to a CD or DVD</li>
<li>Send the cleaned instances over the network to a remote DICOM device</li>
</ul>
<a name="Cleaning"><h2>What does "cleaning" mean?</h2></a>
<p>"Cleaning" is used to refer to the process of removing and/or replacing information in the DICOM "header". The user is given control over
what to remove and replace, including the ability to import and export without doing any cleaning at all, or to completely de-identify
the header and replace the identifying attributes with new values. Use cases that are supported include:</p>
<ul>
<li>Importing images into the local PACS, changing the Patient ID and Accession Number to local values</li>
<li>Cleaning images for research or teaching, by removing identifiers and replacing them with dummy values</li>
</ul>
<p>The user is provide with control over:</p>
<ul>
<li>Replacement values for Patient's Name, Patient's ID and Accession Number</li>
<li>Modification of dates and times (e.g., Study Date), in a manner that preserves temporal relationships</li>
<li>Replacement of all other identifying attributes (e.g., Referring Physician's Name, etc.)</li>
<li>Removal or retention of descriptions (e.g., Study Description), which though useful may sometimes have identifying information, with separate options to remove or retain the Series Description and Protocol Name (which are generally both useful and safe)</li>
<li>Removal or retention of patient characteristics (e.g., sex and weight), which are essential for PET SUV but otherwise often removed</li>
<li>Removal or retention of device identifiers (e.g., serial number), which may be needed to track device performance but otherwise may be removed</li>
<li>Removal or retention of institution identifiers, which may be needed to track facility performance but otherwise may be removed</li>
<li>Removal or retention of clinical trial attributes, which may need to be removed for secondary re-use of clinical trial images</li>
<li>Replacement of DICOM unique identifiers, which is performed consistently for a set of instances to maintain referential integrity</li>
<li>Removal or retention of private attributes, except those that are known to be safe to leave and are important (e.g., SUV scale factor)</li>
<li>Addition of a description of the <a href="DicomCleaner.html">DicomCleaner™</a> software as contributing equipment, to maintain a record in the cleaned instances of what tool was used</li>
<li>Export of DICOM files and DICOMDIR directly into a folder (intended for CD burning) or a zip file</li>
<li>Whether or not to accept any Transfer Syntax over the network or during file importation, or only those that can be decoded and displayed (blacked out)</li>
</ul>
<p>The following panel shows the control panel with default values for the checkboxes suitable for a typical de-identification scenario:</p>
<center>
<table>
<tr>
<td><IMG SRC="images/DicomCleanerControlPanel.png" width="800"/></td>
</tr>
</table>
</center>
<p>As an example of how to perform the cleaning process, the following steps might be performed to query, retrieve, de-identify, blackout and export images to a zip file (assuming that the network has already been configured; see <A HREF="#Configuration">How to configure it</A>):</p>
<ol>
<li>Enter the first few letters of the desired subject's name in the query patient's name field with a trailing asterisk ("*") wildcard (if left blank, the PACS will be queried for all patients)</li>
<li>Press Query and select the remote system to query from the popup and press OK</li>
<li>Observe the result of the query of the remote system in the left hand panel</li>
<li>Select in the left hand panel the patient to be retrieved (or expand the tree and select a study or series as required)</li>
<li>Press Retrieve</li>
<li>Observe the retrieved patient appear in the middle (Original) panel</li>
<li>Check or uncheck the boxes in the control panel as appropriate for the level of de-identification required</li>
<li>Populate the replacement Patient's Name, ID and Accession Number fields as required (or uncheck the boxes of those fields not to be replaced)</li>
<li>Select in the middle (Original) panel the patient to be cleaned (or expand the tree and select a study or series as required)</li>
<li>Press Clean to perform the de-identification</li>
<li>Observe the cleaned patient appear in the right (Cleaned) panel</li>
<li>If necessary, select in the right (Cleaned) panel a patient to be blacked out (or expand the tree and select a study or series as required) and press Blackout (see <A HREF="#Blackout">Blackout (Redaction)</A>)</li>
<li>Make sure that the "Zip exported files" checkbox is checked</li>
<li>Select in the right (Cleaned) panel a patient to be exported (or expand the tree and select a study or series as required)</li>
<li>Press Export, select a destination for the zip file in the popup dialog, and press Open (Windows) to perform the export to a file named "export.zip"</li>
</ol>
<p>To import images from media such as CDs or the local file system instead or retrieving over the network, replace steps 1 through 5 with a press of the Import button and navigate using the popup dialog to the
drive, folder or DICOMDIR and press Open (Windows) or OK (Mac); no network configuration is required.</p>
<p>Any steps of this process can be repeated as necessary; retrieved, imported and cleaned patients, studies, series and images remain until the application is closed unless they are explicitly selected and purged.</p>
<p>If desired, the process can be executed without performing any de-identification (leaving the DICOM headers and pixel data intact) by setting the following configuration of checkboxes,
allowing images to be imported or retrieved, then exported or transferred elsewhere, with a "dummy" cleaning step, and in this case, since no Blackout is required, any Transfer Syntax (type of compression) can be accepted:</p>
<center>
<table>
<tr>
<td><IMG SRC="images/DicomCleanerControlPanelPassThru.png" width="800"/></td>
</tr>
</table>
</center>
<a name="DatesAndTimes"><h2>Dates and Times</h2></a>
<p>If the "Dates and Times - Move earliest date to" checkbox is left unchecked then all dates and times are left unchanged. This is the recommended setting when studies need to be related longitudinally, and are
de-identified on separate occasions, and when dates are used to correlate images with other sources of information. However, the policy governing de-identification may require that dates be modified, and if the box
is checked, then all the dates and times are shifted relative to the same epoch, such that the earliest date and time in the entire set of selected instances is moved to the epoch. The epoch can be specified
explicitly in the text box, which has a default date of 20000101. Alternatively, the earliest year amongst the selected set can be detected by pressing the appropriate button, and the text box values will
change to January 1st of the earliest year. Another option is to choose a random year.</p>
<center>
<table>
<tr>
<td><IMG SRC="images/DicomCleanerControlPanelDates.png" width="800"/></td>
</tr>
</table>
</center>
<p>There is no mechanism provided to re-use the same offset when studies are de-identified on different occasions. However, if the earliest date method is used, and the earliest previous original images are
imported and selected, and Earliest Year is pressed, and then the studies that do not need to be cleaned are de-selected, then it may be possible to obtain consistency across the set.</p>
<p>Note that a particular effort is made to retain temporal relationships within a study, such as is necessary for perfusion timing and radioactive decay calculations (such as for PET SUV), by pairing
time attributes that are unaccompanied by a date with an alternative appropriate date. This may fail, however, if the original related times spanned midnight.</p>
<a name="Blackout"><h2>Blackout (Redaction)</h2></a>
<p>Some types of images, particularly ultrasound, screen shots of analysis panels and 3D rendering, digitized film or paper documents, and some nuclear medicine images, contain
identifying information not just in the DICOM "header", but also burned in to the pixel data, which needs to be "blacked out" (redacted) by replacing the pixel values using an image editor.</p>
<p>The "Blackout" button in the main <a href="DicomCleaner.html">DicomCleaner™</a> control panel provides this capability. When a set of images has been cleaned and selected in the "Cleaned" panel,
pressing "Blackout" brings up an image editor that allows rectangular regions of the image to be filled with black pixels.</p>
<center>
<table>
<tr>
<td><IMG SRC="images/DicomImageBlackoutColorUltrasound.png" width="600"/></td>
</tr>
</table>
</center>
<p>The application of the "blackout" process will cause the images to be decompressed, if they are compressed.</p>
<p>Images encoded in the JPEG baseline (8-bit) Transfer Syntax are treated specially, and are not decompressed,
in order to prevent loss of information caused by decompressing and then recompressing a lossy JPEG compressed image.
Rather, only those 8x8 blocks that are to be blacked out are affected, and all other 8x8 blocks are untouched.
A side effect is to increased the blacked out regions in size to align with block boundaries.
Also, rather than black being used as the replacement value, the average color of the block is used (current DC coefficient value).</p>
<center>
<table>
<tr>
<td><IMG SRC="images/DicomImageBlackoutJPEG.png" width="600"/></td>
</tr>
</table>
</center>
<p>If the "Accept any Transfer Syntax" checkbox was set during import or network reception, any image that is
not encoded in one of the Transfer Syntaxes supported for decoding will cause the "Blackout" process to fail (see also <a href="#TransferSyntax">Transfer Syntax and Compression Support</a>).</p>
<p>The user has control over which value is used to replace the blacked out pixels (except for lossy JPEG images that are not decompressed). If Use Padding and Use Zero are unchecked,
then the lowest possible pixel value given the signedness and bit depth of the pixel data will be used. If Use Padding is checked
(which it is by default), then Pixel Padding Value, if present in the header, will be used instead of the lowest possible value. If
Use Zero is checked, than a value of zero will always be used, regardless of the lowest possible value or Pixel Padding Value; this
is sometimes necessary if no windowing information is present in the header, and the lowest possible value turns out to be very -ve
(everything turns white after Save is pressed).</p>
<p>Some images also contain information in overlay planes that are intended to be displayed on top of the pixel data, and this also can contain identifiable information that needs
to be removed.</p>
<p>The "Overlays" checkbox in the "Blackout" panel activates display of this information, which can then be blacked out, in which case the remaining overlay information will
be "burned in" to the saved pixel data and the overlays themselves removed. Indeed, even if there is no need to blackout the overlay information, the side effect of burning in the overlay
may be useful, particularly if downstream viewers do not support overlay display, as many do not.
A side effect of the use of the "Overlays" checkbox is to suppress the lossy JPEG selective block redaction, and trigger decompression of the JPEG image before burning in overlay information
(if any); the image is not recompressed.</p>
<center>
<table>
<tr>
<td><IMG SRC="images/DicomImageBlackoutOverlayDose.png"/></td>
</tr>
</table>
</center>
<a name="Usage"><h2>How to start it</h2></a>
<p><a href="DicomCleaner.html">DicomCleaner™</a> is a Java Web Start (JWS) application that you can run from within a web browser. It runs on any platform that supports Java 1.5 or greater,
and does not require any "installation" per se. Just click on the <a href="DicomCleaner.html">DicomCleaner™</a> link, and confirm all security requests to run the application.
Java must not be disabled in your browser (check browser security settings).
If Java is not already installed, you may be prompted to install it or allow automatic installation to proceed. After Java installation, you may need to reload the link to get
the application to start.
In MacOS Safari, the 'Open "safe" files after downloading' checkbox in Preferences>General must be enabled (otherwise you will have to double-click the JNLP file in the Downloads window).</p>
<p>Whenever you use the web start application, it will automatically check for the
latest version on the web site and use that, so you never need to be concerned about upgrading or maintenance.</p>
<p>If you like, you can right-click on the <a href="DicomCleaner.html">link</a> to save it as a Desktop Shortcut to make it as easy to start up as any other application, but this is not required, since you can always start it from a browser.
If you make such a shortcut, you can give it an icon by downloading <a href="http://www.dclunie.com/pixelmed/software/webstart/icons/DicomCleaner.ico">this Windows icon (.ico) file</a>, and right-clicking the shortcut and selecting its Properties, and browsing to the downloaded .ico file.</p>
<center>
<table>
<tr>
<td><IMG SRC="images/DicomCleanerCopyShortcut.png"/></td>
<td><IMG SRC="images/DicomCleanerPasteShortcut.png"/></td>
</tr>
</table>
</center>
<p>You can do something similar on the Mac by dragging this <a href="DicomCleaner.html">link</a> to the Desktop, and can give it an icon using the Get Info (Cmd-I) dialog, renaming the file to "DicomCleaner.fileloc" and downloading <a href="http://www.dclunie.com/pixelmed/software/webstart/icons/DicomCleaner.png">this PNG file</a> and dragging it on top of the icon in the dialog.</p>
<a name="Configuration"><h2>How to configure it</h2></a>
<p>If you want to use a DICOM network (rather than importing from or exporting to folders and files), you can use the "Configure" button to enter information
about remote DICOM network devices and the port and AET of the DicomCleaner™ itself.</p>
<center>
<table>
<tr>
<td><IMG SRC="images/DicomCleanerLocalConfiguration.png"/></td>
<td><IMG SRC="images/DicomCleanerRemoteConfiguration.png"/></td>
</tr>
</table>
</center>
<p>This information will be saved in a properties files located in
the user's home directory, called ".com.pixelmed.display.DicomCleaner.properties", so that you do not have to re-enter it next time. The
property file can also be created or edited manually, though any comments will be lost when the "Configure" button in the user interface is used to
update it. Here is an <a href="sample.com.pixelmed.display.DicomCleaner.properties">example</a> properties file.
The application also supports DNS self-discovery of other DICOM applications, though this is not widely deployed.</p>
<a name="Installation"><h2>How to install it (locally)</h2></a>
<p>If for some reason you do not want to start the application using Java Web Start, but instead want to download it and install it, several versions are available:</p>
<ul>
<li><a href="http://www.dclunie.com/pixelmed/software/winexe/DicomCleanerWithOwnJRE.zip">Windows executable that does not require Java to be installed</a> [approx. 45 MB] (includes its own JRE, internationalized fonts, and JIIO libraries)</li>
<li><a href="http://www.dclunie.com/pixelmed/software/winexe/DicomCleanerAssumingJREInstalled.zip">Windows executable that requires Java 1.5 or later to already be installed</a> [approx. 3.9 MB] (includes its own JIIO libraries, since these are often not installed)</li>
<li><a href="http://www.dclunie.com/pixelmed/software/macexe/DicomCleanerMac.zip">MacOS executable that requires Java 1.5 or later to already be installed</a> [approx. 2.1 MB] (includes pure Java JIIO libraries for limited decompression support)</li>
</ul>
<p>The downloaded installable version does NOT automatically update when new versions are released, however.</p>
<p>If you need to report a problem, and want to know what version you are using, look at the status bar immediately after starting the application:</p>
<center>
<table>
<tr>
<td><IMG SRC="images/DicomCleanerShowVersion.png" width="300"/></td>
</tr>
</table>
</center>
<p>The open source code is contained within the <a href="http://www.dclunie.com/pixelmed/software/">PixelMed™ toolkit</a>.</p>
<a name="TransferSyntax"><h2>Transfer Syntax and Compression Support</h2></a>
<p>All of the standard uncompressed Transfer Syntaxes, as well as baseline 8 bit JPEG and JPEG 2000 are supported for by default on all platforms (with the Oracle JRE).
If the Java JAI Image I/O native codecs are also installed (only available for Windows and Linux and not the Mac), then lossless JPEG and JPEG-LS are also supported.</p>
The user can select to "Accept any Transfer Syntax", and if instances are received in a recognized standard (but unsupported) Transfer Syntax, the "Clean" step can
be used, since only non-PixelData attributes need to be changed, but the "Blackout" process cannot be applied.</p>
<hr/>
<a href="DicomCleaner.html"><IMG SRC="icons/DicomCleaner.png" ALT="Click here to start the DicomCleaner™" BORDER=0/></a>
<p></a>Click here to start the <a href="DicomCleaner.html">DicomCleaner™</a>.</p>
</body>
</html>
|