Editing Scanco User Instructions (section)

=Import and Export=
==Import Foreign Data to Scanco System==
Only RSQ and ISQ files can be imported into the database, however it is possible to convert other types of data into ISQ files (i.e., stacks of BMPs into ISQ).

<b>PART 1:</b>

After transfering your data to the VMS system (use the data disk <code>disk2</code>, NOT the user disk <code>disk1</code>), use the IPL commands <code>/import_freeformat</code> or <code>/read_aim function</code> to import your data for conversion to an ISQ.

For AIM files, navigate to the location of the AIM file.  Then open IPL by:

<pre>$ IPL</pre>

In IPL, read in the .AIM file:

<pre>ipl> read in [.AIM file]</pre>

IPL will do the following:

<pre>ipl> read in STUDYID_001_RL.AIM

/read
  -name                      in
  -filename                  STUDYID_001_RL.AIM
!> Reading AimVersion020 

!%  /read completed:  CPU: 00:01.03  ELAP: 00:01.55  </pre>

For DICOM files, start IPL and run the <code>/dicom</code> function to import. For DICOM, if your object is a single 3D file (-multifile false) or many many individual slice files (-multifile true, and give beginning of filenames, and –extension).

There may be requests by IPL to convert your data to <code>signed short</code> or <code>signed char</code> from other data types. Obey these requests and do it by running the <code>/convert_unsigned</code> function.

Then, write the ISQ file using either the "toisq" or "from_aim" commands:
<pre>ipl> toisq
-aim_name                  [in] >[leave blank as you defined “in” as .AIM file.]              
  -isq_filename              [default_file_name] > C0001234.ISQ [Create a 1 letter and 7 digit file name]
  -square_flag               [true] > false
  -original_position         [true] > false

ipl>toisq_from_aim
  -aim_name                  in
  -isq_filename              C0001234.ISQ
  -square_flag               false
  -original_position         false

!%  Dimensions of ISQ file: dim.x dim.y dim.z 558 638 168
Write_ctdata_headerext_new: no mhext found. Init mhext.
Extended header successfully added of type            8

!%  Writing ISQ slice   167  (Done:   168/168)

!%  /toisq_from_aim completed:  CPU: 00:05.12  ELAP: 00:10.47  </pre>
 
Type ipl>help toisq [or ipl>help from_aim] to see details of the command.

This writes the ISQ file. Make note of the ISQ file name.

<b>Remember</b>, the ISQ name must be 8 characters long (1 character followed by seven digits)!!! The letters and numbers can be chosen freely.

Exit IPL:

<pre>ipl>quit</pre>

<b>PART 2:</b>

To VIEW the ISQ, refer to [[Scanco_User_Instructions#Open_default_ISQ|'''Open default ISQ''']].

The measurement can be verified by looking at the Header Information. (File, Header)

If you only needed to view the ISQ, delete the file when finished by:

<pre>$ dir/sincet
$del [.ISQ file]</pre>

<b>PART 3:</b>

To use the ISQ further (e.g. for evaluations, contouring, etc.) create a sample in the database and write down the sample and measurement number. Then, run:

<pre>$ run um:uct_import   ! will import both RSQ and ISQ (modify patient index, etc)</pre>

and give the new ISQ file, the new sample-number and check that the feedback is correct (i.e., that the name from the database is matching the name from the ISQ file header).  If the Patient Name in the ISQ header doesn't match the measurement database Patient Name (very likely), then upon importing the RSQ/ISQ the headers will be updated to the new Patient Name.

Operator and controlfile can be left 0 if you want.  However, controlfile should be set appropriately if the data being imported is for the XtremeCT patient database.

If you are also importing the RSQ, put it in the same directory as the ISQ.

Then it changes the sample and measurement number in the ISQ file, makes the correct directory on <code>DK0</code>, and gives you the line on the screen of how to rename the file to the correct, new directory. Take this line and use it on the command line.  Done!  

You can now use the normal <code>uct_evaluation</code> program with this file.  If the control file was set properly, then the evaluation will be done correctly (i.e., for XtremeCT patient measurements).

<b>Note:</b> Any AIMs created from the original ISQ should be recreated.  So, it is important that you re-evaluate your newly imported ISQ.  It is OK to move the GOBJ from the old directory to the same directly as the newly imported ISQ (it does not have a 'registry' in the database).


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]

==Import DICOM to Scanco System==
#Load MRI's or CT's DICOM data in Osirix
#Export from Osirix
#*Click export button in top left in osirix.  
#*Select "flat" and "decompress all DICOM files"
#Copy files to correct folder in scanco system
#*Use Fillezilla or FTP (make sure it's set to binary mode)
#Use IPL to convert dicom to aim or isq

<pre>
/dicom_to_aim
  -aim_name                  in
  -dicom_filename            IM-0001-0001.DCM   ! Note - choose the first filename of the series
  -multifiles                true

/convert_unsigned
  -input                     in
  -shift_flag                false
  -divide_by_2               true

/write_v020
  -name                      in
  -filename                  PREOA_023_L_MR.aim
  -compress_type             bin
  -version_020               true

/toisq_from_aim
  -aim_name                  in
  -isq_filename              MROA023L.isq
  -square_flag               true
  -original_position         true''

</pre>

5. Delete dicoms

<pre>
/del *.dcm;1
</pre>


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]

==Import Xradia *.bin to Scanco System==
Xradia scanner exports a *.bin image that is:

 - 16-bit unsigned          ! This is "short" (8-bit is char - we don't want this for a grey-scale image)
 - 2 bytes per voxel
 - little endian notation

To upload this binary image to Scanco database, the steps are as follows:

#Ftp the *.bin to Scanco system using binary transfer (not ascii)
#Convert it to an AIM or ISQ in IPL

 $ipl
 
 /import_freeformat  
 -internal_name             in
 -file_name                 BMLPL_006.BIN
 -sample_name               BMLPL_006
 -data_offset               0
 -data_dim                  1000 1024 1016    !dimensions from header file
 -data_el_size              0.013 0.013 0.013 !voxel size from header file
 -bytes_per_voxel           2          
 -data_endian               little_endian
 -data_type                 integer
 -signed_type               unsigned          !correct
 -multifiles                false
 
 /convert_unsigned
 -input                     in
 -shift_flag                true              !shift_flag = TRUE will produce an ISQ/AIM with negative values which may not be visualized properly using uct_evaluation, but keeps the original image resolution.
 -divide_by_2               false             !divide_by_2 = TRUE will down grade image resolution, but all positive values in an ISQ/AIM will be visualized properly using uct_evaluation.
 
 /write_v020 
 -name                      in   
 -filename                  test.aim   
 -compress_type             bin   
 -version_020               true
 
 /from_aim_to_isq
  -aim_name             in
  -isq_filename         bmlpl006.isq !ISQ name requires 8 characters   
  -square_flag          true
  -original_position  true
 
quit 

To VIEW the ISQ, refer to [[Scanco_User_Instructions#Open_default_ISQ|'''Open default ISQ''']].

Alternatively the image can be converted to a 16-bit signed in ImageJ (and cropped) before importing to ipl. It then becomes:

 - 16-bit signed
 - 2 bytes per voxel
 - big endian notation

It can then be imported into ipl without the need to run <code>/convert_unsigned</code>.

[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]

==Import foreign data with calibration information for BMD mg HA/ccm or Hounsfield Units==

Data can be converted from any other source (e.g. mha, nii, png, bmp, dicom, etc) into an AIM format using the BoneLab GitHub repository, which includes <code>blImageConvert</code>. However, those data should be represented as 'short' (2 byte) integers. Obviously that data cannot be used directly to measure BMD without conversion. Normally, an AIM file will contain the following information in the extended header (use aix -l to read the AIM header). 

 !-------------------------------------------------------------------------------
 Patient Name                  PATIENT_001                                         
 Index Patient                                      28
 Index Measurement                                 641
 !-------------------------------------------------------------------------------
 Site                                               39
 Scanner ID                                       3418
 Scanner type                                        9
 Position Slice 1 [um]                          163359
 No. samples                                      2304
 No. projections per 180                           900
 Scan Distance [um]                             139852
 Integration time [us]                           43000
 Reference line [um]                            141359
 Reconstruction-Alg.                                 3
 Energy [V]                                      68000
 Intensity [uA]                                   1470
 Angle-Offset [mdeg]                                 0
 Default-Eval                                        3
 !-------------------------------------------------------------------------------
 Mu_Scaling                                       8192
 Calibration Data              68 kVp, BH: 200 mg HA/ccm, Scaling 8192           
 Calib. default unit type      2 (Density)                                       
 Density: unit                 mg HA/ccm                                         
 Density: slope                         1.55715601e+03
 Density: intercept                    -3.82782013e+02
 HU: mu water                                  0.24220
 !-------------------------------------------------------------------------------

The slope and intercept is the calibration data that came from the scanner. Normally, when creating an AIM from an ISQ, the calibration data will come from the ISQ, which in turn came from the database of the scanner. 
When an evaluation of BMD is made in IPL, the calibration data is taken from the extended header.

Since the imported data converted to an AIM does not have calibration data in the header, you must use the following options in IPL. When you read in the AIM into IPL using <code>/import_freeformat</code> it assumes
the data to be µ values with scaling 1. You can then use <code>/header_log_set</code> to change the µ scaling. If you do not follow this procedure (i.e., no calibration data) then the IPL output for BMD will be in the units of your input (i.e., 2-byte short).

More information about the calibration information and µ scaling is found in the Scanco FAQ. Some key parts are copied to here:

A physical CT image contains the values for the Linear Attenuation Coefficients at each voxel. These are floating point values, typically between 0.0 and about 4.0 for bone (at our energies). To store them in our files, we scale these numbers with typically 4096 (XtremeCT: 8192) to a short integer value to be able to save a 2-byte number (-32768 to 32767, negative values not physically meaningful, but exist because of detector noise) instead of a 4-byte float.

BMD (mg HA/ccm):
 For the bone density measure, the µ-values are converted to mg HA/ccm units by 'Density: slope and intercept'. This conversion is linear, so slope and y-intercept defines the equation:
 mg HA/ccm = µ-value * slope + intercept

Hounsfield units:

SCANCO data files do not directly contain the image values in Hounsfield Units, but they contain scaled µ-values. To get Hounsfield Units, the µ-value of water is needed, and then the conversion formula is this: 
 HU(pixel) = -1000 + µ(pixel)*1000/µ(water)
 where the µ-values are the native image values divided by the above mentioned µ-scaling 4096 or 8192.
 An approximation for the µ of water can be found in the AIM or ISQ header, if (and only if) the scan was performed with the bone density calibration turned on.

[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]

==Get Your Files==
===MAC/Linux Options===
====Fetch====
#Download and install [http://fetchsoftworks.com/fetch/|'''Fetch''']
#*This program is free for university staff and students. 
#Fill out [http://fetchsoftworks.com/fetch/free|'''a form''']. 


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]

====FTP from Terminal====
#Open a terminal
#*MAC: open the "Applications" folder, choose "Utilities", then "Terminal".
#Navigate to where you want to transfer the files to.
#Connect to the micro-CT ftp server using the ftp command in the terminal:
#*Login with the micro-CT user account and password.
#Navigate to the directory of interest on the micro-CT system.
#*Logicals such as "ur" can be used as short cuts. Whole directory names must be used.
#Set a filename mapping convention to remove OpenVMS version numbers.
#*The command <code>ftp> nmap $1;$2 $1</code> sets anything before the version number to parameter $1 and anything after the version number to $2. The file output will be set to $1, therefore the version number will not be kept. 
#Set the file transfer mode.
#*[[File:Important.JPG|20px]] If you transfer an .AIM file in ascii mode, you will receive a "mesh generation" errors and "material ID out of range" message.
#Transfer your files.
#*Option: Turn off prompt so does not ask you whether or not to transfer each file.
#*If you do not turn off the prompt prior to transferring the files, press "a" (for all) to transfer all files at once.
#Exit FTP.

<pre>
$ FTP 136.159.74.231	              !Connect to an FTP Server. Need to input user name and password.	
$ FTP emily.ucalgary.ca	              !Connect to an FTP Server. Need to input user name and password.	
$ FTP microct@emily.ucalgary.ca       !Connect to an FTP Server. Need to input password. 

FTP> cd ur                            !Navigate to the directory containing the target files.
FTP> cd sys$scratch                   !Navigate to the directory containing the target files.

FTP> nmap $1;$2 $1                    !Set a filename mapping convention to remove OpenVMS version numbers.

FTP> bin	                      !Set transfer mode to binary (.aim, .gobj, .isq, and most image file types).
FTP> ascii	                      !Set transfer mode to ascii (.txt, .log, .com, .ps, .pdf and all other files in general).

FTP> put test.aim                     !Put the file
FTP> get test.aim                     !Get the file

FTP> prompt                           !Interactive mode off before transferring multiple files without having to be prompted.
FTP> mput *.aim	                      !Put all files with the .aim extension on the FTP server (mput = multiple put).
FTP> mget *.aim	                      !Get all files with the .aim extension from the FTP server (mget = multiple get).
FTP> mget *.aim;	              !Transfer the latest version of all aim files in a directory.

FTP> quit	                      !Disconnect from the FTP Server.
</pre>
 

[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]

===Windows Options===
====Scanco Medical µCT FTP====
#Downlod '''Scanco Medical MicroCT FTP 3.4''' from BoydDrive:\\04 - Resources\04 - Software\Scanco Medical MicroCT FTP 3.4\
#Install the software using the default parameters.
#Click on FTP Connection and input the host to connect to, the username, password. 
#Give this profile a name.
#:[[File:Microct_FTP_pic01.jpg|600px]]
#Click on the options tab to set the locations to connect to (e.g., project disk, scratch) and the location on your computer to transfer files to.
#:[[File:Microct_FTP_pic02.jpg|600px]]
#Go back to FTP Connection and press the Connect button.  
#*If you are connecting from off campus to the XtremeCT you will need to use the VPN to gain access through the firewall.
#Use the left tree to navigate folders.  
#*Use the file filter to search for specific file types or file names (bottom left).  
#Select files to download and press the Download Selected Files button (bottom right).
#:[[File:Microct_FTP_pic03.jpg|600px]]
#Press the Exit button to disconnect.


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]

====Filezilla====
#Download '''Filezilla 2.2.32''' from BoydDrive:\\04 - Resources\04 - Software\Filezilla 2.2.32\  
#*This version of Filezilla will remove the OpenVMS version number from files, the new version will not! 
#*The left side of the program shows your computer, the right side will show the micro-CT system once you have connected.
#:[[File:Filezilla_pic01.jpg|500px]]
#On the top menu, choose "File", then "Site Manager".  
#Create a "New Site" for all the directories that you frequently access.  
#*Give the site a meaningful name.  
#*For the host, you may connect to "emily.ucalgary.ca" or "sceval.ucalgary.ca".   
#*For the logon type choose "Normal" and input the micro-CT user name and password.
#:[[File:Filezilla_pic02.jpg|400px]]
#Click on the "Advanced..." button to set the default remote directory (i.e., on the micro-CT system).
#Set the default local directory if there is a specific location you plan to always transfer files to. 
#Setup any additional sites you want then press "Save and Exit".
#:[[File:Filezilla_pic03.jpg|300px]]
#To connect to a session, hold the left mouse button down over the arrow next to the site manager button (computer icon under "File") to bring up your list of sites.  Highlight the site of interest then release the mouse button to connect.  
#Once connected, you can drag and drop files from the remote site to your local computer.


;*Common FTP locations
{| class="wikitable"
|-
! scope="col"| Account
! scope="col"| Location
! scope="col"| Path
|-
| microct / vivact ||	Data Disk	||DISK2:[MICROCT.DATA]
|-
| microct / vivact ||	Projects Disk	||DISK3:[MICROCT.PROJECTS]
|-
| microct / vivact ||	Scratch Disk	||ADISK1:[MICROCT.SCRATCH]
|-
| invivo / invitro ||	Data Disk	||DISK4:[BONELAB.DATA]
|-
| invivo / invitro ||	Projects Disk	||DISK5:[BONELAB.PROJECTS]
|-
| invivo / invitro ||	Scratch Disk	||ADISK1:[BONELAB.SCRATCH]
|}


[[Image:Redirect.jpg|15px]] [[#top|''Return to Contents'']] or [[Main_Page|''Return to Main Page'']]