Working with Images in NBIA 7.0

The following table describes the data available for each study and image series in that study.

Click View Image under any thumbnail to save the image as a file or open it in the DICOM viewer.

• On the Search Results (Studies for Subject) page, you can launch an animation of thumbnails if there is more than one image in the series. Click in a series record in the search results.
  
  OR
• You can launch the animation of an image series from the data basket. In the View column of the data basket, click the magnifying glass symbol,, corresponding to the series you want to view. On the View Series Images page, click the View Series in Cine Mode link.
  
  When the viewer opens (figure above), the animation controls display below the image. When you use the controls, NBIA proceeds to display the images sequentially, like a movie.

The following table describes the action of each of the animation controls.

Downloading the NBIA Data Retriever

Installing the NBIA Data Retriever

To install the NBIA Data Retriever on Windows

1. Download the installer package for Windows using the link above.
2. Save the installer package file to your computer.
3. Install the app by double-clicking the installer package file.
4. Agree to the terms in the License Agreement and click Install.
5. When the Setup Wizard ends, click Finish.

To install the NBIA Data Retriever on Mac

1. On your Mac, find the NBIA Data Retriever on the Mac App Store.

   The NBIA Data Retriever is free but still requires you to log in to download it. Consider changing your macOS Password Settings so that you can download free software without having to log in separately for it.

2. Click Get, then click Install App. The NBIA Data Retriever is free.
   The app starts downloading to your Mac. When the download is complete, you can open a manifest file with the NBIA Data Retriever.

To install the NBIA Data Retriever on Linux (centOS or Ubuntu)

You must have the sudo privilege on your computer and a sudo password to install the NBIA Data Retriever on CentOS and Ubuntu.

1. Download the installer package for centOS or Ubuntu using the links above.
2. Save the installer package file to your computer.
3. Open a command window and go to the location where you saved the installer.

• • For a centOS system, enter the following at the command prompt:
    sudo yum -v -y remove TCIADownloader.x86_64;sudo yum -y install NBIADataRetriever-3.3-1.x86_64.rpm

  • For an Ubuntu system, enter the following at the command prompt:
    sudo -S dpkg -r tciadownloader;sudo -S dpkg -i nbia-data-retriever-3.3.deb
    Enter the sudo password when prompted.

Downloading Images Using the NBIA Data Retriever

When you start downloading the images you have added to the data basket, NBIA provides a list of those images in a manifest file (manifest-xxx.tcia). You must have already installed the NBIA Data Retriever to open this manifest file and download the images.

1. Search for images of interest.
2. Add those images to your data basket.
3. Open the My Data Basket page and click Start Download.

4. Click the manifest-xxx.tcia file.
   If you are only downloading public images, the NBIA Data Retriever appears, listing the items in your data basket. If you are downloading any private images, see the section about downloading private data.
   
   
   

   The NBIA Data Retriever lists all items you selected in the data basket. You can hover your mouse over the Patient ID, Study Instance, and Series Instance columns to reveal the complete corresponding IDs. You can also resize a column by selecting and dragging the column border.

   If you do not want to download any of those items, select them in the Downloads table and then click Delete. When you remove an item from the Downloads table, it stays in your data basket.

5. Click Browse to navigate to the destination where you want the images/annotations to be downloaded.

6. Click Start to begin the download. You can monitor the download in the Progress column. The Status column indicates when the download for each item is complete.

   At any point in the process, you can click the Pause and Resume buttons to temporarily stop and restart the process.

   Note that files downloaded this way are not compressed. The downloaded files are stored in a child folder under the destination folder such as Collection Name > Patient ID > part of Study Date + part of Study ID + part of Study Description + last 5 digits of Study Instance UID > part of Series Number + part of Series Description + last 5 digits of Series Instance UID.
   
   

   Network Error?

   If network errors occur during large downloads, the NBIA Data Retriever retries the files the number of times that your administrator has configured.

Downloading Private Data

If you are downloading any private data, you are prompted to log in.

Once you log in, the NBIA Data Retriever appears.

If you do not have permission to access even one of the collections/sites to which the images you have in your manifest file, you are prompted to contact the help desk to request permission to access all of the images.

However, if you cannot download the application, the alternative is to use the TCIA Download Manager, a Java Network Launch Protocol (JNLP) file.

The TCIA Download Manager allows you to replicate items in your Data Basket, downloading them to your local machine. It is a Java program and requires that you install a Java Runtime Environment (JRE^TM) on your machine to run it. You can download the JRE . The TCIA Download Manager does not limit the total size of the download.

To download objects using the TCIA Download Manager

1. At the top of the My Data Basket page, click the Temporary TCIA Downloader link. You are prompted to open or save the TCIA Download Manager. Open it in the JRE^TM you installed. If you have any issues opening the TCIA Download Manager, see the note about Java Security settings.
   
   The page lists all items you selected in the data basket. You can hover your mouse over the Patient ID, Study Instance, and Series Instance columns to reveal the complete corresponding IDs. You can also resize a column by selecting and dragging the column border.
   
   
2. Click Browse to navigate to the destination where you want the images/annotations to be downloaded.

3. Click Start to begin the download. You can monitor the download in the Progress column. The Status column indicates when the download for each item is complete.

   At any point in the process, you can click the Pause and Resume buttons to temporarily stop and restart the process.
   
   

   Note that files downloaded this way are not compressed. The downloaded files are stored in a child folder under the destination folder such as Collection name/patient id/study instance UID/series instance UID/image SOP instance UID.

• Using the NBIA data portal,
• Using the Manifest API,
• Using the Shared List API, and

• Using the JNLP data API.

Creating a Manifest File Using NBIA

To use the NBIA Data Retriever, you must already have a manifest file that lists the files you want to download. You create the manifest file by searching the data portal of NBIA. After installing the NBIA Data Retriever, double-click this manifest file to invoke the application.

To create a manifest file:

1. Search for images of interest.
2. Add those images to your data basket.
3. Open the My Data Basket page and click Start Download. 
   A manifest file is created and downloaded to your computer. 

• • If you have already installed the NBIA Data Retriever, double-click the manifest file to open it using the NBIA Data Retriever. Click Open when your web browser prompts you to open the file. 
  • If you want to use this manifest file to download images more than once or download images you select on other machines, click Save at the web browser prompt. You can then double-click the saved manifest file in Windows Explorer on Windows, Finder on Mac, or File Manager on Linux to invoke the NBIA Data Retriever.

Creating a Manifest File Using the Manifest API

Refer to the Manifest API documentation for instructions on how to use the API. The outcome of the REST API call must be saved as a text file with the extension .tcia. 

Example Manifest Query 

curl -H "Authorization:Bearer d98c390f-b53d-4456-beb3-110e63663762" -k "http://localhost:8080/nbia-api/services/getManifestTextV2" -d "list=1.3.6.1.4.1.9328.50.3.336&includeAnnotation=false"

The API returns text that can be used as a manifest file for the NBIA Data Retriever.

downloadServerUrl=https://imaging-devcm.nci.nih.gov/nbia-download/servlet/DownloadServlet
includeAnnotation=false
noOfrRetry=4
databasketId=manifest-1523866570303.tcia
manifestVersion=3.0
ListOfSeriesToDownload=
1.3.6.1.4.1.9328.50.3.336

Creating a Manifest File Using the Shared List API

If you have a shared list, you can use the Shared List Query API to create a manifest file. Refer to the Shared List Query API documentation for instructions on how to use the API.

Example Manifest from Shared List Query 

curl -H "Authorization:Bearer a99171a1-b289-4700-9e4e-1bd73ce1bbb5" -k "http://localhost:8080/nbia-api/services/getManifestTextFromSharedList" -d "sharedList=scottslist&includeAnnotation=false"

The API returns text that can be used as a manifest file for the NBIA Data Retriever.

downloadServerUrl=https://imaging-devcm.nci.nih.gov/nbia-download/servlet/DownloadServlet
includeAnnotation=false
noOfrRetry=4
databasketId=manifest-1523866570303.tcia
manifestVersion=3.0
ListOfSeriesToDownload=
1.3.6.1.4.1.9328.50.3.336

Creating a Manifest File Using the JNLP Data Query API

If you have a JNLP file, you can use the JNLP Data Query API to create a manifest file. Refer to the JNLP Data Query API documentation for instructions on how to use the API.

Example Manifest from JNLP Data Query 

curl -H "Authorization:Bearer 3b2bf812-a97e-454e-af94-623b868a2955" -k "http://localhost:8080/nbia-api/services/getManifestFromJNLPFileData" -d "jnlpArgument=C:\Apps\nbia\apache-tomcat-7.0.68\temp\jnlp-data1521628213301.txt&includeAnnotation=false"

The API returns text that can be used as a manifest file for the NBIA Data Retriever.

downloadServerUrl=https://imaging-devcm.nci.nih.gov/nbia-download/servlet/DownloadServlet
includeAnnotation=false
noOfrRetry=4
databasketId=manifest-1523866570303.tcia
manifestVersion=3.0
ListOfSeriesToDownload=
1.3.6.1.4.1.9328.50.3.336

• Click  to select the record and  to clear it.
• To mark all records in the search results as records you want to add to your data basket, click the basket icon in the column header or click .

You select items to download by first searching for them in NBIA and then adding them to your data basket.

The following is an example of the My Data Basket page with just one image collection in it. The estimated download time and the total size of your data basket appear at the bottom.

The following table describes each item in the table.

To delete all items from your basket, click the Empty Data Basket link. You can continue to add items to your data basket from the Search Results pages.

You can now download the data in your data basket using the NBIA Data Retriever.

Once you are satisfied with your selections, click Start Download at the top left of the results table to use the NBIA Data Retriever.

To create a shared list

You can create a shared list from data basket or the Tools menu. Procedures for both methods follow.

Data Basket

1. Add an image series that you want to include in the shared list to the data basket.
2. Click the Create Shared List button.
3. Do the following:
   
   1. Enter a Name for the list (required).
   2. Optionally, add a description and a URL. The URL links to relevant or more detailed information about the list.
   3. Click Browse to upload a file in comma separated value format (.csv) that includes all of the series instance IDs you want to be in the shared list. This file should have one series instance UID per line.
4. Click Submit.
   The image series from the uploaded file is added to the data basket.

Menu Option:

1. Click Tools > Create Shared List.
   The Create Shared List page appears.
   
2. On this page, do the following:
3. 1. Enter a Name for the list (required).
   2. Add Comments and a Hyperlink, where appropriate, which links to relevant or more detailed information about the list (optional).
   3. In the Upload File field, enter the name of a file that includes all of the series instance IDs you want to be in the shared list. This file should have a series instance UID per line.
   4. For your convenience, a Java tool is available to aid in generating a CSV of your series instance UIDs. 
      Download: ExtractSeriesUIDs.zip
      Do the following to use this tool to generate the file to upload in the last field of our online Create Shared List form:
      1. Download the zip file, then move it to a top-level directory of DICOM files you want indexed.
      2. Extract the zip file to the top level directory where your DICOM data resides (all sub-directories will be scanned). It should extract two things.
      3. Then run ExtractSeriesUIDs.bat which should flash a quick command line window and then automatically disappear.
         A file with a name similar to SeriesUIDs.CSV is created as an output.
      4. Enter the output filename into the form.
4. Click Submit.
   The image series from the uploaded file is added to the data basket.

To edit a shared list

1. Click the Edit Shared List link under Tools on the menu bar.
   The Edit My Shared List page appears, displaying a list of shared lists you have created.
   
2. Click the name of the shared list you want to edit.
   List details appear.
   
3. In the description field, optionally enter a comment about the list or your edit.
4. In the URL field, optionally enter a web address that provides more information about the shared list.

5. Click Browse to locate the file you want to upload. Doing this replaces the current shared list.

To delete a shared list

Because editing a shared list is only possible by replacing it, you might consider backing up a shared list when you create it. To do so, export the shared list as a file when you create it. See Exporting a Shared List.

To search for a shared list

1. Log in to NBIA.
2. Click Tools > Search Shared List.
   The Search Shared List page appears.
   
3. Enter the name of an existing shared list. To retrieve the list, you must know the exact name given to the shared list.
4. Click Submit to launch the search or Reset to clear the field and start again.

If the search is successful, all image series in the shared list are added to the data basket. If the shared list includes series for which you do not have visibility rights, a message appears that informs you that the displayed shared list is not complete.

To export a shared list

1. Above the data table, click Shared List > Export Series ID.
   The shared list opens in the data basket.
   
   The export begins immediately. A dialog box appears, prompting you to open (in Excel) or save the file.
2. Select to open or save the file.

 To delete a shared list, follow these steps:

1. Click Admin > Manage Shared List.
   The Manage Shared List page appears.
   
2. Select a user name from the list.
   That user's shared list(s) appear.
   

3. Click the name link to review the shared list's details or click to delete shared the shared list.