Editing Scanco Administration (section)

=Evaluation=

==Analysis Topics==

===Cortical thickness analysis in standard evaluation===

!!Note - with ipl v5.42 this should be changed to <code>/dt_cortical_thickness</code>

Use the IPL command <code>/dt_cortex_obj_param</code> to measure cortical thickness using direct methods.

When extracting the results from the database using <code>uct_list</code>, specify the <code>UCT_3D_LIST_W_CTH.TXT</code> template in directory <code>DISK0:[MICROCT_COMMMON.UIL]</code>.

<pre>
$ uct_list
UCT_LIST.EXE Version V5.1
Template-File [UCT_3D_LIST_SHEET]: DISK0:[MICROCT_COMMON.UIL]UCT_3D_LIST_W_CTH.TXT
</pre>

UCT_3D_LIST_W_CTH.TXT is now the default template as of March 2009.


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

===Cortical porosity and finite element analysis on XtremeCT===

* This procedure is broken down into 3 separate components
* All Scripts mentioned be copied directly from DISK3:[MICROCT.PROJECTS.KYLE.SCRIPTS]
* Files should be copied from data to projects prior to running analysis (see bonelab procedures.doc on sodor) 

1. Autocontour the image <br>
2. Calculate and extract cortical measurements <br>
3. Create FE files and run FE <br>


====Autocontour====
* The main autocontour script is located in the ue: directory, this should NOT be modified!
* The procedure is executed using a "hijack" script [[Media:HIJACK_AUTOCONTOUR.TXT|'''HIJACK_AUTOCONTOUR.TXT''']], but the filename must be changed to .COM or found in the directory mentioned above.
* Files should already have a _SEG.AIM created and should be in the same directory as the raw .AIM file.

* You then create a SUBMIT.COM script as you would for other files. For example:
 $  QQ = "SUBMIT/NOPRINT/QUE=SCEVAL_FAST/LOG=SYS$SCRATCH com:HIJACK_AUTOCONTOUR.COM"
 $ 'QQ' /PARA=DISK3:[MICROCT.PROJECTS.'''PROJECT_NAME'''.MODELS]'''FILENAME'''.AIM

* This command will then create various files for examination and further analysis. These include:
** FILENAME_COMBI.AIM - shows cortical, trabecular, and pores all in different colors
** FILENAME_COMBIPO.AIM - shows only the cortex with porosity as different color
** FILENAME_CRTXFILL.AIM - gives sold mask of cortex, porosity filled (can be used to calculate Ct.Th)
** FILENAME_CRTXPO.AIM - shows only the pores
** FILENAME_TRAB.GOBJ - gobj of trabecular region
** FILENAME_CRTX.GOBJ - gobj of cortical region
** FILENAME_AUTO2.GOBJ - gobj of whole bone region

* Further technical details and references can be found in the following publications:
** Buie, H., Campbell, G., Klinck, R., MacNeil, J., & Boyd, S. (2007). Automatic segmentation of cortical and trabecular compartments based on a dual threshold technique for in vivo micro-CT bone analysis. Bone, 41(4), 505-515. 
** K.K. Nishiyama, Macdonald, H., Buie, H., Hanley, D., & Boyd, S. (2010). Postmenopausal Women With Osteopenia Have Higher Cortical Porosity and Thinner Cortices at the Distal Radius and Tibia Than Women With Normal aBMD: An In Vivo HR-pQCT Study. Journal of Bone and Mineral Research, 25(4), 882-890.

====Evaluate Cortex====

*This Step 2 method of doing the cortical analysis is no longer used now that we have the IPL_UPAT_CALGARY_EVAL_XT1.COM or XT2.COM version. The problem with this approach is that it is a Frankenstein of the standard analysis and the advanced analysis. The cortical bone assessment is correct, but the trabecular compartment from the standard analysis is not a perfect match. Instead, we should be using the GOBJs described in IPL_UPAT_CALGARY_EVAL_XT1.COM so that we have a perfect mix. 
  
Nevertheless, we keep this information here for now for posterity.


*After the autocontour is computed we used to call IPL_EVAL_CORTEX.COM that will calculate the cortical parameters:
**Cortical porosity (%)
**Direct cortical thickness (mm)
**Cortical density (mg HA/ccm)

This WAS called as the following:
 $  QQ = "SUBMIT/NOPRINT/QUE=SCEVAL_FAST/LOG=SYS$SCRATCH com:IPL_EVAL_CORTEX.COM"
 $ 'QQ' /PARA=DISK3:[MICROCT.PROJECTS.'''PROJECT_NAME'''.MODELS]'''FILENAME.AIM''' -
        /LOG=DISK3:[MICROCT.PROJECTS.'''PROJECT_NAME'''.LOG]'''FILENAME'''_EVAL_CRTX.LOG


* The results of this script are outputed into individual log files for each file being evaluated.
* To extract these results into one file use:
 $ search/output=output_results_filename.txt *EVAL_CRTX.LOG "!% ov/tv","!> C.Th","!% mean_unit"
*A learn command in the eve editor can be used to extract the specific results desired:
**!% ov/tv is the amount of bone in the cortex (ie. 1- ov/tv =  cortical porosity)
**!> C.Th is the direct cortical thickness in mm
**!% mean_unit is the cortical density in mg HA/ccm

====Create and run FE models====

*The most current common FE model to run is a homogeneous model where all elements have the same material properties and the cortex and trabecular regions are labeled separately in order to determine the percentage of load carried by each region.
*The other option is to create a model where the material properties are scaled based on the density values and scripts for this can be found in the COM directory.

*The script IPL_FEM_HOMOGEMOUS_LS.COM will use files created by the autocontour and appropriately label the cortex and trabecular regions as well as remove any disconnected pieces of bone.
 $  QQ = "SUBMIT/NOPRINT/QUE=SCEVAL_FAST/LOG=SYS$SCRATCH com:IPL_FEM_HOMOGENOUS_LS.COM"
 $ 'QQ' /PARA=DISK3:[MICROCT.PROJECTS.'''PROJECT_NAME'''.MODELS]'''FILENAME'''.AIM

*Files will now be created with the suffix _HOM_LS.AIM and can be moved to Mighty-Mac or Mavis for FE analysis.  You will require user accounts for these computers and can contact Eric or Steve. If using FTP be sure to transfer the files in binary mode (further documentation on this can be found in this Wiki)

*[[Media:2009-10-15_FEM_Tutorial.pdf|'''FEM tutorial main steps''']] to submit the FE files with a detailed manual is recommended for first time users.
*This is now out of date, but is kept here because it still contains useful information about preparing AIM files and post-processing.  
*For running the FE itself, please refer to the current manual at [[FAIM Finite Element Solver]].


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

===Cortical midshaft analysis with moment of inertia calculation===

This explains what happens when you type

<pre> 
$ midshaft       ! or
$ eval_midshaft 
</pre>

Draw a rough contour around your slices: open the Contouring Sub-window, double-click on the big image, and it automatically finds the best contour. Then click on 'Selection' 'Forwards', then 'Iterate Forwards'.

Then 'cancel' the contouring sub-window, and start the 3D evaluation.  Make sure you have already set the correct threshold, sigma, support in file
<pre>DISK2:[MICROCT.EVAL]IPL_FIXED_BATCH_MIDSHAFT.COM</pre>

When you type

<pre>$ show queue</pre>

you should find a job called UCT_EVALUATION_MIDSHAFT and a SYS$SCRATCH:*_MIDSHAFT_*.LOG

The IPL_FIXED_BATCH_MIDSHAFT.COM by default does not calculate the direct measurement results because you must have many more than 20 slices for these to be valid.  You can uncomment these parts of the file if you contoured the whole stack (i.e., stack thickness is >> than cortex thickness).

TILDE: Note that you will see lots of tildes (~) on the result sheets. This is to tell you that, if the measurements were trabecular bone, those values would only be approximate. But now for the cortex, they are actually correct! (see below for more explanation about this) I would now use the tildes to check the 'excel' table that the operator has taken the correct script for the trab. or cort. evaluations for the respective measurements!

So what's the advantage of all this?  Now, also VOX-TV is correct!  So VOX-TV is the whole area, VOX-BV the doughnut, so TV - BV is the marrow area!  And still, TRI-Tb.Th is the cortical thickness (TRI-TV is NOT correct, because the .gobj feature was turned off).

I say 'area' above: depending on how many slices one individual scan has,
VOX-BV (and VOX-TV) might be different for different scans, so you will HAVE to
convert the volumes to area again:

<pre>
volume equals area times height
--> Bone Area = VOX-BV / height = BV / (dim.z * el_size_mm.z)
</pre>

and same for Total area, of course :-)

POROSITY: If you want porosity of the bone itself draw two contours: one around, counter-clockwise, on on the inside, clock-wise (thus a 'negative', excluding contour). Now, TV will be just that ring area, BV will be the bone within that ring area, and BV/TV will be 1 - porosity, thus BV/TV 94% means 6% porosity.

METAPHYSIS: Application of this script to metaphysis scan (with trab. in middle):

<pre>
$ midshaft
</pre>

Draw one contour around the cortex, and in the same slices, a NEGATIVE contour on
the inside (CW contour) to exclude the trabecular bone. You may potentially work with the BP (break-point) system to be able to morph the negative contours, even though there is already an 'outer' contour around the bone in every slice.

Start 3D eval, read out the data-base with <code>$ uct_list</code>.

NOTE: You CANNOT give the .gobj a special name such as c0001234_cortex.gobj if you are using the automatic evaluation button on UCT_EVALUATION.  Only after the eval (or midshaft eval) has finished, you may copy it to a more meaningful name, but all of the evaluations are just taking the STANDARD gobj name!

Afterwards (after renaming or copying the _seg.aim to _cortex.aim, and .gobj to _cortex.gobj), you may want to start the very normal eval with normal (inner) contours to evaluate the trabecular compartement.

<pre>
Remember: the values in our 3D result database then are OVERWRITTEN.
</pre>

If you have a large study, I would recommend to run the $ midshaft for ALL
samples, <code>$ uct_list</code> to e.g. <code>sys$scratch:mystudy_cortex.txt</code>, 
rename/copy gobj and seg for all, and THEN run the trabecular evaluation for all samples.  <code>$ uct_list</code> and you have two nice complete excel sheets.


NOTE ON PLATE MODEL: More explanations of why the plate model is correct

Assume a ring (cortex).

<pre>
Area = thickness * 'middle line'.
'middle line' = average of outer and inner circumference
--> 'middle line' = 0.5 * 'bone surface'

--> thickness = bone volume * 2 / bone surface.
</pre>

And this is nothing else but the 'plate model' formula for Tb.Th!

NORMAL TRABECULAR EVALUATION?  And why not just run the 'normal trabecular eval'?  Because in the 'normal' TRI calculation, we are EXCLUDING all surfaces that are created artificially by a gobj line that cuts through a trabecula.

However, for the midshaft, this means the whole outer (or even inner, if also
inner contour is there) is SUPPRESSED, because it is touching the gobj line. So
this is where that midshaft script comes in: it turns off that suppression.

MORE EXPLANATIONS: Why the direct DT-Tb.Th* is NOT correct for a scan with
just 12 slices.

If we fill the structure with spheres, those spheres should be bounded by the
width of the cortex, not just by the fact that we only have 12 slices (and even more so, we are always doing 'aim box' suppression with the spheres) if a sphere touches the boundary of the aim box, it is suppressed!

So this is quite crucial for Tb.Sp and Tb.N. To get meaningful Tb.Sp, you would
need a LOT of slices. Also, then, you cannot have the inner contour - otherwise
the negative inner contour will delete the Tb.Sp. spheres.

If you have enough slices, you may opt to turn the <code>/dt_object</code> on again in the
midshaft script (second half). Then DT-Tb.Th* and TRI-Tb.Th just have a slightly different behaviour if there are little pores within the cortex:

<pre>
TRI: the little pore just adds a little BS, thus the influence is not that big.
DT: the little pore cuts the thickness sphere in half, thus at that location, the thickness is halved.
</pre>

MEAN1 and MEAN2: The script is also calculating Mean1 and Mean2 now.

<pre>
Mean1: 'apparent' density, average over whole TV
Mean2: 'tissue' density: average over what was segmented as bone only.
</pre>

These mean values will be in mg HA/ccm if you have the calibration option for bone density installed (and activated for those scans).  Remember: the bone has to have some soft-tissue (or equivalent) on the inside, and preferably also on the outside then.


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

===Joint Thickness Measurements===
*Sample script to search histogram files for results: [[Media:Summarize_Joint_Th_Measurements.pdf|Summarize Joint Th Measurements]]


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

===Scanco Joint Space Width (JSW) analysis===
The scripts published in [https://doi.org/10.21037/qims.2019.12.11 Stok et al. 2020], and released by Scanco, are available for XCT1 and XCT2.

On XCT2 they have been installed as Tasks #112 to #116.

Instructions to run this analysis are available here [[Media:ESD_Joint_Space_Width_v2.3.pdf]].

The full citation for this work is: 
<pre>
Stok KS, Burghardt AJ, Boutroy S, Peters MPH, Manske SL, Stadelmann V, Vilayphiou N, van den Bergh JP, Geusens P, Li X, Marotte H, van Rietbergen B, Boyd SK, Barnabe C; SPECTRA Collaboration. Consensus approach for 3D joint space width of metacarpophalangeal joints of rheumatoid arthritis patients using high-resolution peripheral quantitative computed tomography. Quant Imaging Med Surg. 2020 Feb;10(2):314-325. doi: 10.21037/qims.2019.12.11. PMID: 32190559; PMCID: PMC7063288.
</pre>


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

==UCT_EVALUATION==

===UCT_EVALUATION SOP===
====Start 3D evaluation from terminal for XtremeCT II====

Logged into the terminal as "xtremect2" you can see the evaluation scripts in <code>IDISK1:[XTREMECT2.EVAL]</code>

The morphological evaluation: Control file #25. It basically runs auto contouring (#23) and then the morphological analysis.
* <code>UCT_EVALUATION_V6_XT2_DT61.COM</code>
* <code>IPLV6_EVAL_CORT.COM</code>
* <code>IPLV6_EVAL_TRAB.COM</code>
* <code>IPLV6_EVAL_TOTAL.COM</code>


* <code>UCT_3D_LIST_CORT_XT2.TXT</code>
* <code>UCT_3D_LIST_TRAB_XT2.TXT</code>
* <code>UCT_3D_LIST_TOTAL_XT2.TXT</code>

Contouring scripts:
* <code>IPLV6_AUTOK.COM</code>: Creates automatically the standard GOBJ. Control file #22.
* <code>IPL_AUTOK_CTTB.COM</code>: Creates automatically the CORT, TRAB and PORE.GOBJ (previously CRTXPO). Control file #23.
* <code>IPLV6_AUTOK_CTTB_CORR.COM</code>: Creates automatically the CORT and PORE.GOBJ, after manual correction on the TRAB.GOBJ. Control file #24.

Laplace- Hamming scripts:
* <code>IPLV6_UPAT_EVAL_LH61_XT1DB.COM</code>
* <code>IPLV6_UPAT_EVAL_LH82_XT1DB.COM</code>

Results will be generated in the <code>IDISK2:[XTREMECT2.RESULTS]</code> directory, in the same way as they are generated for the cortical analysis on XtremeCT I, i.e. using the uct database and appended text files.

Laplace Hamming evaluations will generate results in the upat_list database. The direct measurements will be stored in the uct_list database.


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

====Symbols for XtremeCT II vs XtremeCT I====
<code>microct</code> account you get

  "MICROCT_BIN" = "DISK1:[MICROCT.]" (LNM$PROCESS_TABLE)
       = "DISK0:[MICROCT_COMMON.3309.]"
       = "DISK0:[MICROCT_COMMON.]"

for <code>xtremect2</code>

  "MICROCT_BIN" = "DISK1:[XTREMECT2.]" (LNM$PROCESS_TABLE)
       = "DISK0:[MICROCT_COMMON.]"

So 3309 has its own directory where the software versions for the two scanners are different, e.g.

  xtremect: DISK0:[MICROCT_COMMON.][MAIN]IPL_SCANCO_M.EXE
  microct: DISK0:[MICROCT_COMMON.3309.][MAIN]IPL_SCANCO_M.EXE

We have defined some symbols for the different ipl versions:

  IPL
  IPLREG
  IPLFE
  IPL_BATCH
  IPLREG_BATCH
  IPLFE_BATCH

In the scripts you can directly use these symbols instead of ipl_scanco_prog (old style).

IPL and IPL_BATCH are different for the two scanners because the newest version is not officially released for XT1.
IPL of the microct account (XT1) cannot read data of the xtremect2 account (XT2). The other way around it works.

IPLREG and IPLREG_BATCH point to <code>$DISK1:[XTREMECT2.MAIN]IPL_SCANCO_REGIS_V107.EXE</code> for both accounts.


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

====Stop the annoying beep====

Typically a job ends and a beep is sounded in the user window. This can be annoying if somebody is running many jobs.

You cannot add a <code>/nonotify</code> via the advanced parameters in uct_evaluation script editing. However, you
could:

a) Create a copy of <code>uct_evaluation_v6.com</code>, e.g. <code>uct_evaluation_v6_nonotify.com</code> and change the line from

  $ SUBMIT/NOPRINT/NOTIFY/QUE='EVAL_EQUEUE'/LOG='EVAL_LOGFILE2'/NAME='JOBNAME' -

to

  $  SUBMIT/NOPRINT/QUE='EVAL_EQUEUE'/LOG='EVAL_LOGFILE2'/NAME='JOBNAME' -

or

b) Turn of the beep on the workstation you are sitting at:
Go to the session manager, <code>Session -> Keyboard ... -> Bell Volume disable</code>

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

====Start 3D evaluation from terminal for microCTs====

[[Image:Bones2.jpg|20px]] <b>Warning:</b>Do not change <code>uct_evaulation_v4.com</code> and <code>ipl_fixed_batch_v4.com</code> in .eval, but only work on your own file (i.e., eval_steve).

First, an explanation of how the normal evaluation runs by hitting the 'Start 3d' button.
<pre>$ scanco_submit_command ue:uct_evaluation_v4.com/para=(xxx,yyy,zzz,…)</pre>
There are 8 parameters:
*P1: number of print outs of our results sheet
*P2: the ISQ filename
*P3-5: start x (pos x), y, z
*P6-8: dim x, y, z
The parameters p3-p8 come from the white bounding box. The problem is that when you start from the terminal you do not have these. This problem can be overcome by using the <code>isq_to_aim_gobjbox.exe</code> and then give the relevant parameters. You can 
<code>$ run um: isq_to_aim_gobjbox.exe </code>
to see what it's asking for.
By using gobjbox you do not need p3-p8. Therefore you can start the evaluation by giving:
<pre>$ scanco_submit_command ue:uct_evaluation_special_josh.com –
/para=(1,dk0:[microct.data.0000275.0000245]c0000332.ISQ)</pre>
*You can make <code>uct_evaluation_special_josh.com</code> such that there is no need for P1 (change p2 to p1 in the script, etc).
*Alternatively to using the gobjbox you could use the normal isq_to_aim, but hard code the dim and pos.
*Then call whatever IPL files you want to call. Look into <code>fixed_batch_v4</code> to see how we turn on the database always on the first line of every IPL part, and how we calculate parameters.


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

====Temporarily change evaluation for UCT_EVALUATION====

In a terminal window, we need to redefine the logical that determines which
3D evaluation is associated with the <code>UCT_EVALUATION</code> tool.

For example, typing <code>VOI</code> runs the <code>UCT_EVALUATION</code> tool
by executing <code>UE:UCT_EVALUATION_VOI.COM</code>

Type
<pre>$ show logical UCT_EVALUATION</pre>
and then you can redefine this to point to another evaluation script.
<pre>$ define UCT_EVALUATION UE:UCT_EVALUATION_CUTOUT.COM</pre>

This is only redefined in the particular terminal you are using, and it
will reset to its default in a new terminal.  It will also not work if you
try to submit the job to a queue.  It only works interactively.


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

====Assign special evaluation to UCT_EVALUATION====

'''Warning''': This is for advanced users ONLY.  Do not attempt this without contacting Steve!

This will show how to set up <code>$ eval_kyle</code>:
It is easy to set up multiple .COM files for the 3D evalulation tool, one such set-up is already prepared on your computer:
<pre>
$ eval_special
</pre>
will do something similar to <code>$ voi</code> where the normal contour program opens, but if you start the 3D eval, the special script <code>um:uct_evaluation_special.com</code> is called (associated with eval_special), which then in turn calls <code>ipl_fixed_batch_special.com</code>, where you can specify your own set of thresholds, etc.

So it is a daisy chain of files which we will need to follow to set up a special <code>xxx_kyle.com</code> script, and where ever we encounter <code>_special.com</code>, we copy and change it to <code>_kyle.com</code>.

So to set up <code>$ eval_kyle</code> you will need to do the following:

*1. Edit <code>disk1:[microct]microct_setup_user.com</code> (double-click on file), please be careful here, it's very important! (and I hope you have done your 'weekly full backup' regularly, so you could always retrieve a good version of login.com...)

*2. Then, towards to bottom and duplicate the line
<code>$ eval_special :== @com:eval_var.com um:uct_evaluation_special.com</code>
and change duplicate to
<code>$ eval_kyle    :== @com:eval_var.com um:uct_evaluation_kyle.com</code>

This will make this command <code>eval_kyle</code> available after you login freshly. Save and Exit.

*3. Then go to <code>disk1:[microct.eval]</code> and copy the file <code>uct_evaluation_special.com</code> to the name <code>uct_evaluation_kyle.com</code> ('Commands', 'Copy ...', BUT CLICK ON THE THREE DOTS and give new output name. 
If you do not see the <code>eval_special:</code> go to terminal, <code>$ dir ue:*special*.com</code> and take it from the <code>microct_common</code> directory)

*4. Edit the <code>_kyle.com</code> file: at the top, change <code>ipl_......_special.com</code> to <code>_kyle.com</code>

*5. Copy <code>ipl_fixed_batch_special.com</code> to <code>ipl_fixed_batch_kyle.com</code>

*6. Edit <code>ipl_fixed_batch_kyle.com</code> to your liking. If you want <code>$ eval_kyle</code> to not perform the full evaluation, but only something akin to <code>voi</code>, then, in the steps above, copy <code>uct_eval_voi.com</code> to <code>uct_evaluation_kyle.com</code>, and <code>ipl_voi.com</code> to <code>ipl_fixed_batch_kyle.com</code> (thus you take the <code>voi</code> script as template for the <code>_kyle</code> script).

*7. Then open a new terminal ('applications', 'decterm'), <code>$ eval_kyle</code> should work now!

'''Notes''': When you start the 3D eval, then
<code>$ que</code>
will show you your batch job with your name on it now!

And now a few more explanations how the whole thing works: in all eval programs, hitting 'Start 3d' just submits the logical <code>uct_evaluation</code>, <code>$ show log uct_evaluation</code> shows you that by default, this points to <code>ue:uct_evaluation_v4.com</code>.

Those little <code>voi</code> and <code>eval_steve</code> scripts then just temporarily redefine this logical so that a different script is submitted when you <code>'start 3d eval'</code>.

About the '''corelut eval''': Then we start a whole different eval program: the <code>.exe_corelut</code>. So, if you set up a <code>eval_steve_c</code> (or whatever you want to call it): Produce a <code>eval_var_c.com</code> in the directory commands (maybe copy from microct_common to [microct.commands]), and there, on the last line, instead of starting
<code>$ uct_evaluation</code>
(the normal program), replace by
<code>$ evalc</code>
which starts the <code>.exe_corelut</code> - and because the <code>eval_var.com</code> has over-ridden the <code>uct_evaluation</code> logical just before, then you are starting different script upon starting 3d eval.
NB: we have a logical AND a symbol called <code>uct_evalution</code>. Sorry for confusion. Symbol <code>uct_evaluation</code> starts normal <code>eval</code> program, so this is what you replace by symbol <code>evalc</code> now).


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

===UCT_EVALUATION FAQ===
====Warning: Not all required GOBJ files found, Continue anyway?====
This occurs when the chosen evaluation script is looking for a contour file, but can't find it.  
*To see what contours the script is looking for go to "File" then "Save GOBJ As...".  You can now see the list of required gobj files.  
*For some scripts, it may not be necessary to supply a gobj and you can continue with the evaluation without it.  For example, the "3D Segmentation of VOI, 1 solid object" applies the contour to isolate the region of interest, however, this may not be necessary if the object of interest can be extracted from thresholding.
[[File:Save_gobj_as.jpg|400px]]


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

====Warning: Attempt to access non-existent record CODE: 36====
The scan is most likely still in the process of being reconstructed.  Try to access the scan again in a few hours.


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

====Error: Insufficient logical unit numbers CODE: 1409716====
Exit the evaluation program and restart it.


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

====Error: Process quota exceeded====

[[Image:Process_quota_error.JPG|300px]]

When running UCT_EVALUATION from a dec terminal, an error when starting an evaluation may occur if there are to many dec terminals opened. 
*The easy fix for this is to open the terminals from the applications menu in the [[Scanco_User_Instructions#Session_Manager|'''session manager''']] instead of using the dec command. 
*Alternatively you can set up a new login script and add <code>/DETACH</code> to the dec definition 
<pre>
$ DEC == "CREATE/TERMINAL=DECTERM/DETACH". 
</pre>
An example script can be found here @DISK5:[BONELAB.PROJECTS.BUIE]SETUP.COM.


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

====Error: Writing to UPAT database fails====

Sometimes when performing a morphological evaluation we get an error when writing to the UPAT database. This is entirely preventable. The error may look like this snippet from the LOG file:

<pre>
...snip...
Reading AIM file 6
DK0:[XTREMECT2.DATA.00002783.00016788]D0014390_TRAB_1N.AIM...
!> Reading AimVersion020
!> Image size after D1charCmp (run-length) uncompression will be:
!> Type of data               Char       1 byte/voxel
!> Total memory size          82.7       Mbyte
Trabecular Analysis (5)
starting calculations
Scanner-ID: 3401
Updating old record 16788
getting new eval record...
New Eval record:       58416
getting new slice records...
TIME:  8-MAR-2024 10:41:00.63
ERROR:
Writing indexed record (upat slice)
MESSAGE: %FOR-W-INCKEYCHG, inconsistent key change or duplicate key!
STATUS:            2
CODE:           50
FACILITY: FORTRAN
--------------
UPAT_FILL_DB V2.0-1
   Eval-Type: [5]:    Group-Code: [0]: Evaluation Type 6 Cortical
Analysis
    ISQ-File: [isqfile.ISQ]:      Aim-File: [aimfile1.AIM]:
Ct.Mask-File: [aimfile7.AIM]:       Ct-File: [aimfile8.AIM]:
...snip...
</pre>

The problem is because when running several jobs at once on the cluster there could be parallel attempts to write to the database. The solution is to ensure that all jobs that write 
to the database are run on the exact same queue. However, to leverage the cluster performance and running parallel jobs, we can split a typical morphological evaluation into two parts.
The first part is spread across all available queues, and the second part directs the final writing to database to a single queue (e.g., <code>SCEVAL_FAST</code>).

In <code>UCT_EVALUATION</code> or any <code>HIJACK</code>scripts, we need to replace:

<pre>
$ PAR1 = "EVAL:UE:UCT_EVALUATION_V6.COM|UE:IPLV6_UPAT_REDO_E5E6_XT2.COM|UE:UCT_EVALUATION_V6_UPAT_FILL_E5E6.COM|UE:UCT_EVALUATION_V6_CREATE_TIF.COM|UE:UCT_EVALUATION_V6_UPAT_PRINT_E5E6_NM.COM|"
</pre>

with 
<pre>
$ PAR1 = "EVAL:UE:UCT_EVALUATION_V6.COM|UE:IPLV6_UPAT_REDO_E5E6_XT2.COM|UE:STARTER_UPAT_POSTPROCESS_NM.COM|"
</pre>

The script <code>UE:STARTER_UPAT_POSTPROCESS.COM</code>, or in this case the version that does no matching (<code>UE:STARTER_UPAT_POSTPROCESS_NM.COM</code>) replaces the following three scripts:

 UE:UCT_EVALUATION_V6_UPAT_FILL_E5E6.COM
 UE:UCT_EVALUATION_V6_CREATE_TIF.COM
 UE:UCT_EVALUATION_V6_UPAT_PRINT_E5E6_NM.COM

We still can call <code>UE:IPLV6_UPAT_REDO_E5E6_XT2.COM</code> if we need to re-run the morphological analysis, but the other three scripts are specifically sent to <code>SCEVAL_FAST</code> to avoid any conflicts writing to the database.

If this doesn't fix the problem then also double-check that the sample/measurement number of the scan embedded in the ISQ is correct. There are occasions when that's been mistaken. See other FAQ entry about adjusting file header

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

====UCT_EVALUATION customization====

When you start <code>UCT_EVALUATION</code> and select <code>Scripts</code> from the top menu, and then <code>Modify</code>, select a script. You can choose the radio button for <code>Basic</code> or <code>Advanced</code>. In the <code>Basic</code> you'll see something like this:

 Project: UPAT_XT2
 Eval-Script: UE:UCT_EVALUATION_V6.COM
 IPL-Script: UE:IPLV6_UPAT_E5E6_XT2.COM
 User-Script: UE:STARTER_UPAT_POSTPROCESS.COM

Make sure that IPL-Script always has a script named IPLV6_... and that User-Script always has names like EVAL_...

Switch into <code>Advanced</code> mode and you'll see all the variables explicitly set. For example, a typical <code>P1</code> value is:

 EVAL --> UE:UCT_EVALUATION_V6.COM|UE:IPLV6_UPAT_REDO_E5E6_XT2.COM|UE:STARTER_UPAT_POSTPROCESS.COM

If you select <code>EVAL</code> you will see the window at the bottom explain what each parameter is. For example for <code>EVAL</code> it says:

 EVAL: evalfile | iplfile | userfile0 | userfile1 [| userfileN ...] (Nmax = 5)

So, that means <code>Eval-Script</code> is <code>UE:UCT_EVALUATION_V6.COM</code>, <code>IPL-Script</code> is <code>UE:IPLV6_UPAT_REDO_E5E6_XT2.COM</code> and <code>User-Script</code> is <code>UE:STARTER_UPAT_POSTPROCESS.COM</code>.

When you run an evaluation with this script it will create a file in the measurement directory called something like <code>E0000684_EVAL_UPAT_XT2.COM</code>, which will contain:

 <--snip-->
 $ IPL_CALC2   :== 
 $ IPL_CALC3   :== 
 $ IPL_CALC4   :== 
 $ IPL_CALC5   :== 
 $ IPL_CALC6   :== 
 $ IPL_CALC7   :== 
 $!
 $! Defining entry point for IPL Loops:
 $!
 $ UCT_EVALUATION_CUSTOM_TARGET:
 $!
 $!
 $! Starting IPL
 $!
 $ @UE:IPLV6_UPAT_E5E6_XT2.COM
 $!
 $! User Procedure 0:
 $ SET NOON 
 $ @UE:UCT_EVALUATION_V6.COM -
 "EVAL:UE:UCT_EVALUATION_V6.COM||UE:UCT_EVALUATION_V6_UPAT_FILL_E5E6.COM|UE:UCT_EVALUATION_V6_CREATE_TIF.COM|UE:UCT_EVALUATION_V6_UPAT_PRINT_E5E6.COM" -
 <--snip-->

The <code>UCT_EVALUATION_V6.COM</code> does the parsing of all variables passed by the GUI and then writes a script that is executed, beginning with all definitions of all the symbols. It then calls the IPL-script, which is written to the output file (command procedure to be executed as a batch job) as

 write outfile "$ @UE:''iplfile'"

Your User-Script(s) are then <b>EXECUTED</b> during the parsing, so they need to add (write) content to the script rather than do something. So these scripts need to <b>WRITE</b> the <b>COMMANDS</b> of what has to be done later, not contain the commands itself. For example, rather than

 $ delete 'ipl_file'

It needs to be 

 $ write outfile "$ delete ''ipl_file'"

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

====Bug: UCT_EVALUATION v6 in customizing EVAL scripts====

<pre>$ run um:uct_k_v6</pre>

The new evaluation tool v6 should be used in place of the older v5.  Please see the Documents section of this wiki for a manual on its use.

Known bugs:

When you are producing your own EVAL scripts, and want to call your own ipl file
or such:

The 'EVAL:' keyword in the scripts has the filenames of the
uct_evaluation_v6.com, then the ipl_v6_xxxx.com, then additional filenames (such
as the _prs.com to print and the 3dresults_append.com)

Now, if you are in BASIC mode in the modify window, and you change any of the 3
filename fields, the last of the additional filenames is 'dropped'... ooops...

So please go to Advanced mode and check the long 'EVAL:' keyword that all wished
files are still in the list, otherwise add the last again (most of the time,
that's the useful _3dresult_append.com script...)

Will correct that of course in the next version.


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

====Not work: Left mouse button====
When the left mouse button doesn't work in the µCT evaluation program:
*Turn off caps lock.  
*For remote sessions, turn of the Num Lock key (this will also allow you to use Ctrl-C and Ctrl-V to copy and paste contours).


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

====Not work: Remove and insert keys====

The remove and insert buttons on the keyboard don't work in the µCT evaluation program:
*Turn off caps lock.


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

==Evaluation FAQ==

===Customize your evaluation script===
The basic procedure is to create your customized evaluation script is:
#Clear the database of existing results
#Do your evaluation
#Extract the results
#Paste results into excel template.  
You could repeat as necessary to evaluate a measurement multiple times and write out the results to a file.  
*You must submit all jobs to a single queue!!!


'''1) Start ipl and clear the database of existing results.'''
<pre>
$ IPL_BATCH

/db_clear_eval
-input        "IPL_AIM

..
</pre>

'''2) Insert your IPL evaluation.'''


'''3) Extract the results.'''
<pre>$@com:extract_results.com P1 P2</pre>
*P1 is the aim file (including path) and P2 is the result file (including path)

Example:  
<pre>
$@com:extract_results.com   DISK5:[BONELAB.PROJECTS.BUIE]MYAIM.AIM   DISK5:[BONELAB.PROJECTS.BUIE]MYRESULTS.TXT
</pre>
*P2 should be the same for all samples in your project so that results are compiled into a single file.


'''4) Paste results into excel template.'''
*Refer to the  [[Media:Extract_Results_Template.xlsx |'''Excel Extract Results Template''']]. 
*Open your results text file and copy and paste the contents into cell A2.  There's no need to use paste special since the sheet is protected.


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

===Create your own IPL script===

To make a script that would submit a job to the queue with the command as follows:
<pre>
$ @um:ipl_eval_only.com 'aim_file' 'gobj_file' 'p1' 0
</pre>

you need to create your own IPL file would be translated to the following command:
<pre>
$ submit /noprint /que=sys$slow ue:IPL_VOI_JOSH_M.COM 
  - /log=sys$scratch:test.log /para=('aim_file','gobj_file','seg_file')
</pre>
The IPL file would look something like this…
<pre>
$   if p1 .EQS. "" 
$ 	THEN 
$	write sys$output "Give DK0:[xxx]C0001234_SEG.aim on the line."
$	write sys$output "Or: "
$	write sys$output "Type $ scanco_submit_command um:ipl_eval_autostart/para=(dk0:[xxx]c00123_seg.aim) "
$ 	exit
$   endif
$
$ gobj_file = p1-F$PARSE(p1,,,"VERSION")-"_SEG.AIM" + ".GOBJ"
$ aim_file = p1-F$PARSE(p1,,,"VERSION")-"_SEG.AIM" + ".AIM"
$
$!
$ @um:ipl_eval_only.com 'aim_file' 'gobj_file' 'p1' 0
$ exit
</pre>

Some more handy IPL sequences are:
<pre>
$    INPUT = F$SEARCH("UCT_MEASUREMENT_DATA:[*.*''P1']*.RSQ",1)
</pre>

and then you just need to give meas. number as P1 (and maybe slice range as p2),
<pre>
$ if p2 .eqs. "" then p2 := A
</pre>
OR, some nice starts are:
<pre>
$    IF P3 .EQS. ""
$    THEN
$      WRITE SYS$OUTPUT "P1: Measurement Number to duplicate"
$      WRITE SYS$OUTPUT "P2: New Sample Number from Database"
$      WRITE SYS$OUTPUT "P3: New Start Letter of ISQ file"
$      WRITE SYS$OUTPUT "P4: Optional: Operator Number"
$      WRITE SYS$OUTPUT "P5: Optional: Controlfile Number"
$      EXIT
$    ENDIF
</pre>
where you say which parameters HAVE to be there (up to p3), and which ones are optional.

All together, the script may look like this:
<pre>
$    IF P1 .EQS. "" 
$    THEN 
$      WRITE SYS$OUTPUT "P1: Measurement Number to reco" 
$      WRITE SYS$OUTPUT "P2: Optional: Slice number N or Range M:N. Auto:All" 
$      WRITE SYS$OUTPUT "P3: Optional: Queue. Auto: sys$slow" 
$      EXIT 
$    ENDIF 
$ if p2 .eqs. "" then p2 := A 
$ if p3 .eqs. "" then p3 := SYS$SLOW 
$ slices  = p2 
$ quename = p3 
$ INPUT = F$SEARCH("UCT_MEASUREMENT_DATA:[*.*''P1']*.RSQ",1) 
$ INPUT = INPUT - F$PARSE(INPUT,,,"VERSION") 
$ logfile = "sys$scratch:RECO_" + f$PARSE(input,,,"NAME") + ".LOG" 
$ submit/noprint/queue='quename' uct_reconstruction_file - 
    /para=('input','slices','logfile') 
$ exit
</pre>
Note that <code>uct_reconstruction_file</code> is a logical that points to <code>um:uct_reconstruction.com</code>. 

Logicals are preferred in scripts to make them more universal.


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

===Valid and Locked Settings for an eval script===

Each evaluation when running <code>UCT_EVALUATION</code> can be made <code>VALID</code> and <code>LOCKED</code>.

:<code>VALID</code>: The evaluation script shows up as an option to execute when running <code>UCT_EVALUATION</code>. When you notice script numbers missing in the list, it is because they have had <code>VALID=0</code>

:<code>LOCKED</code>: The evaluation script can be used, but the user cannot make changes to the script settings in <code>UCT_EVALUATION</code>. This is to protect from somebody causing an error in the script settings that affect all users.

It is not possible to delete a script, and it is not possible to add a script at an arbitrary script number. So, any newly added script gets the next monotonically increased script number. This can lead to scripts that have similar purposes being spread throughout the list of scripts, which is annoying.

It is possible to organize the scripts, although it is a fair amount of work and easy to make a mistake. As a normal user (e.g., 'xtremect2') run the script. If you are a different user you may need to set  the correct evalscript database first.

The most simple executable to run is

<pre>
run ut:UCT_UPD_EVALSCR_MISC.EXE

 <...snip...>
 * 578    127/563  (ML) Knee Segmentation
  579    128/569  NO PRINT - Patient Analysis 61µm, After manual corr. on GOBJ,NM
  580    128/570  NO PRINT - Patient Analysis 61µm, After manual corr. on GOBJ,NM
* 581    128/580  NO PRINT - Patient Analysis 61µm, After manual corr. on GOBJ,NM
  582    129/572  XtremeCT II - Standard Radius/Tibia Patient Post-processing,NM
  583    129/573  XtremeCT II - Standard Radius/Tibia Patient Post-processing,NM
* 584    129/574  XtremeCT II - Standard Radius/Tibia Patient Post-processing,NM
Choose evalscript Record (IDX): [584]: 337
Description [XtremeCT II - Standard Radius Patient Analysis 61µm]: 
Valid [1]: 
Locked [1]: 
Favourite [0]: 
Category [32]: 

Save Record ? [Y]: 
</pre>

A more comprehensive executable that allows the user to edit parameters in the script is:

<pre>
run UT:UCT_UPDATE_EVALSCRIPT.EXE

<...snip...>
V IDX escript/Rec. Description
    1      1/1    XtremeCT Standard Patient Evaluation (RL,RR,TL,TR,CU)
    2      1/7    XtremeCT Standard Patient Evaluation (RL,RR,TL,TR,CU)
*   3      1/9    XtremeCT Standard Patient Evaluation (RL,RR,TL,TR,CU)
    4      2/2    QC1 Trabecular Morphometry
    5      2/8    QC1 Trabecular Morphometry
    6      2/384  QC1 Trabecular Morphometry
*   7      2/401  QC1 Trabecular Morphometry
    8      3/3    QC2
    9      3/6    QC2
   10      3/385  QC2
*  11      3/402  QC2
*  12      4/4    3D Segmentation of VOI, 1 solid objectAIM
*  13      5/5    3D Seg. of 2 VOIs: solid dense in transparent low dens obj obj
*  14      6/10   Bone Trab. Morphometry (3D Seg, 3D Calc, Print Sheet)et)eet)
*  15      7/11   Convert to DICOM
   16      8/12   RESOLUTION, Standard Pat Eval, copy to UR, submit AutoCont
   17      8/13   RESOLUTION, Standard Pat Eval, copy to UR, submit AutoCont
   18      8/14   RESOLUTION, Standard Pat Eval, copy to UR, submit AutoCont
   19      8/15   RESOLUTION, Standard Pat Eval, copy to UR, submit AutoCont
   20      8/16   RESOLUTION, Standard Pat Eval, copy to UR, submit AutoCont
   21      8/17   RESOLUTION, Mimic, Std Pat Eval, copy to UR, submit AutoCont
   22      8/18   RESOLUTION, Standard Pat Eval, copy to UR, submit AutoCont
   23      8/23   RESOLUTION, Mimic, Std Pat Eval, copy to UR, submit AutoCont
   24      8/24   RESOLUTION, Mimic, Std Pat Eval, copy to UR, submit AutoCont
   25      8/33   RESOLUTION, Mimic, Std Pat Eval, copy to UR, submit AutoCont
   26      8/57   RESOLUTION, Mimic, Std Pat Eval, copy to UR, submit AutoCont
   27      8/58   RESOLUTION, Mimic, Std Pat Eval, copy to UR, submit AutoCont
   28      8/71   RESOLUTION, Mimic, Std Pat Eval, copy to UR, submit AutoCont
   29      8/72   RESOLUTION, Mimic, Std Pat Eval, copy to UR, submit AutoCont
   30      8/79   RESOLUTION, Mimic, Std Pat Eval, copy to UR, submit AutoCont
   31      9/19   RESOLUTION, Standard Pat Eval, copy to UR, submit AutoCont
   32      9/20   RESOLUTION, Standard Pat Eval, copy to UR, submit AutoCont
   33      9/21   RESOLUTION, Standard Pat Eval, copy to UR, submit AutoCont
   34      9/22   RESOLUTION, XCT2STD, Std Pat Eval, copy to UR, submit AutoCont
 <snip>
  572    127/559  (ML) Knee Segmentation
  573    127/561  (ML) Knee Segmentation
* 574    127/563  (ML) Knee Segmentation
  575    128/569  NO PRINT - Patient Analysis 61µm, After manual corr. on GOBJ,NM
* 576    128/570  NO PRINT - Patient Analysis 61µm, After manual corr. on GOBJ,NM
  577    129/572  XtremeCT II - Standard Radius/Tibia Patient Post-processing,NM
  578    129/573  XtremeCT II - Standard Radius/Tibia Patient Post-processing,NM
* 579    129/574  XtremeCT II - Standard Radius/Tibia Patient Post-processing,NM
  580    130/0    New Record
Choose evalscript Record (IDX,*=Valid): [579]: 
</pre>

Press Enter many times until you are prompted with <code>Save [Y]</code>

The <code>*</code> indicates which scripts are active. You can see there are multiple versions of the same script in many cases. If you want to activate or deactivate a script you must use the IDX number (not the script number). For example, if you want to edit script 128, you select the active IDX, which is 576.

Copying script information from one IDX entry to another is a manual process you can do in <code>UCT_EVALUATION</code>. Be careful!

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

===Exporting evaluation script parameters to text===

Nik at Scanco installed a program onto our system, but it is only to be used VERY carefully. <b>Never</b> use the <code>import</code> function, only the <code>export</code> function.

It's reading the evalscript database defined by the logical <code>UCT_EVALSCRIPT_DATABASE</code>. The file is usually located at <code>UCTD:UCT_EVALSCRIPTS_*.DAT</code> and is part of the weekly database backup.

  $ run ut:uct_impexp_evalscripts

It will output an interactive session as following:

<pre>
UCT_IMPEXP_EVALSCRIPTS V1.0

Export (0) or Import (1) [0]:                                                       ! 0 for export
EXPORT File [SYS$SCRATCH:EVALSCRIPTS.TXT]:                                          ! output file
V No  IDX/INDEX  Description                                                        ! list of scripts
   1      1/2489 3D Segmentation of VOI, 1 solid object
   2      3/862  3D Segmentation of 3 VOIs, concatenation of all 3ionenation of
   3      4/608  3D Segmentation of 4 VOIs, concatenation of all 4ionicatenati
   4      5/2711 Bone Trab. Morphometry (3D Seg, 3D Calc, Print Sheet)
....
 342    460/2945 XtremeCT II - Standard Radius Patient Evaluation 61µm
 343    461/2946 XtremeCT II - Autocontour Largest bone (Radius or Tibia)
 344    463/2965 NK frequency table, histogram
 345    464/2968 Convert to DICOM
Export evalscript Record (IDX): [1]:                            ! enter the number of the eval script to export

</pre>

To export all scripts, just press <code>Enter</code> through the whole list. To stop, enter number 0. Afterwards check the output file <code>SYS$SCRATCH:EVALSCRIPTS.TXT</code>.

Please give it a try and let me know if you have any questions.

<b>Interpretation of output</b>

There will be records for each entry. Currently there are 76 entries:

<pre>
!
! Script           23
!
         594
          34
NO PRINT - Patient Analysis 61µm, After manual corr. on GOBJ    
  1357462144
    11358111
  1513331376
    12153769
           1
           0
           0
!!! Installed on request only !!! �Starts the standard patient analysis (segmentation and evaluation), �after manual correction on _TRAB.GOBJ ; _CORT.GOBJ will be corrected accordingly.�Same script for Radius and Tibia analyses�Send postprocessing to SCSRV1_FAST. No results sent to printer.                                                                                                                                                                                                                 
           0
           0
           0
           0
           0
                
           0
           0
          10UE:UCT_EVALUATION_V6.COM|UE:IPLV6_UPAT_REDO_E5E6_XT2.COM|UE:STARTER_UPAT_POSTPROCESS_NOPRINT.COM                                                                                                                                                                
           1?|?|+.ISQ|+.AIM|+_SEG.AIM|+_CORT_MASK.GOBJ|+_TRAB_MASK.GOBJ|+_CORT_MASK.AIM|+_TRAB_MASK.AIM|+_CORT_SEG.AIM|+_TRAB_SEG.AIM|+_PORE.AIM|+_TRAB_TH.AIM|+_TRAB_SP.AIM|+_TRAB_1N.AIM|+_CORT_TH.AIM|+_CORT_SP.AIM                                                      
           26|+.GOBJ|0|+_CORT_MASK.GOBJ|0|+_TRAB_MASK.GOBJ                                                                                                                                                                                                                  
           0                                                                                                                                                                                                                                                                
           8UPAT_XT2|?|?|?|?|SYS$SCRATCH:|+.LOG|SYS$FAST                                                                                                                                                                                                                    
           40.8|1|450|3000|2|0.8|1|320|3000|2                                                                                                                                                                                                                               
           6AUTO_UPAT_SHEET|0|SYS$PRINT|PS,PDF|1024                                                                                                                                                                                                                         
           0                                                                                                                                                                                                                                                                
           0                                                                                                                                                                                                                                                                
           0                                                                                                                                                                                                                                                                
           0                                                                                                                                                                                                                                                                
           0                                                                                                                                                                                                                                                                
           0                                                                                                                                                                                                                                                                
           0                                                                                                                                                                                                                                                                
                                                                                                                                
                                                                                                                                
                                                                                                                                
                                                                                                                                
   538976288
   538976288
     2105376
      0.0000000
      5.0000000
                
           0
           0
           3
      0.0000000
      0.0000000
                
           0
           0
           3
      0.0000000
      0.0000000
                
           0
           0
           3
      0.0000000
      0.0000000
                
!
!
</pre>

The first number after the line <code>! Script           23</code>, in this case <code>594</code> is the IDX number. The next number <code>34</code> is the position of the script in the list.

In the output file, each row is marked with a number. You have to be careful to not interpret the line incorrectly. The single-digit number that precedes the script value has a meaning:
 26|+.GOBJ|0|+_CORT_MASK.GOBJ|0|+_TRAB_MASK.GOBJ
means type <code>2</code> with script info: <code>6|+.GOBJ|0|+_CORT_MASK.GOBJ|0|+_TRAB_MASK.GOBJ</code>

 40.8|1|450|3000|2|0.8|1|320|3000|2
means type <code>4</code> with script info: <code>0.8|1|450|3000|2|0.8|1|320|3000|2</code>

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

===Run Scanco cut and match function (on Percy)===

;At DATA DISK: 
Run<code>$ upat_list</code>
*mode 1, list mode.
*Select patients and site, etc.
*Select the appropriate template file, e.g. <code>UE:UPAT_TEMPL_CUTMATCH_AUTO_PATTB_CT.TXT</code>
*Output to a file, then run that file.


;At PROJECT DISK: 
If you have moved the files to the project directory and renamed them, you can generate a script from:
<pre>
$ @UE:SEARCH_PROJECTS_CUTMATCH.COM
-P1 = filename with device and directory
-P2 = site (RR, RL, TR, TL)
-P3 = output filename
</pre>
For example, if we run:
<pre>
$ @UE:SEARCH_PROJECTS_CUTMATCH.COM DISK3:[MICROCT.PROJECTS.GRACE]GRACE_01_00MTH_RR.AIM RR MYFILE.COM
</pre>
The script will search <code>DISK3:[MICROCT.PROJECTS.GRACE]</code> for files in the form <code>G*RR*.AIM</code> with the same
length as <code>GRACE_01_00MTH_RR</code>, then check sample numbers to determine if the file is a follow-up scan.
*Upat_list is called to obtain position and dimension data for matching slices.  
*The output file <code>DISK3:[MICROCT.PROJECTS.GRACE]MYFILE.COM</code> is created to submit and run the cut and match.  

Before running, open the file and add <code>$ exit</code> at the end.
<pre>$ @DISK3:[MICROCT.PROJECTS.GRACE]MYFILE.COM</pre>


For multiple files, do something like the following.
<pre>
$ @UE:SEARCH_PROJECTS_CUTMATCH.COM DISK3:[MICROCT.PROJECTS.GRACE]GRACE_01_00MTH_RR.AIM RR MYFILE.COM
$ @UE:SEARCH_PROJECTS_CUTMATCH.COM DISK3:[MICROCT.PROJECTS.GRACE]GRACE_02_00MTH_RR.AIM RR MYFILE.COM
</pre>
Open MYFILE.COM and add <code>$ exit</code> at the end.
<pre>$ @MYFILE.COM</pre>

*The script assumes all follow-ups are provided.  
*If follow-up scans are missing, it will be necessary to modify the output file so that the position and dimension data matches the files or update the <code>SEARCH_PROJECTS_CUTMATCH.COM</code> script.


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

==IPL FAQ==
===Submit a job to the queue===

<pre>
$ submit/noprint /que=sys$slow ipl_voi_josh_m.com /log=sys$scratch:test.log
</pre>


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

===Rotate with turn3d / turn2d===

The turn3d function can be used to perform a single rotation about any axis in 3d.  The turnaxis_angle input is the angle between the x, y, and z axes and the line about which the rotation will be performed.  The turnangle input is the amount to be rotated about the specified line.  To use this function to perform three sequential rotations about the image's original x, y, and z axes requires compensation for the previous rotations.

To rotate an image from the axial view in the z plane to the sagittal view in the z plane: 

<pre>
$ipl
/turn3d
  -input &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;   in
  -output &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;     out
  -turnaxis_angles     90 0 90
  -turnangle           90
  -img_interpol_option        0
</pre>

No interpolation is necessary as this is "pure reformatting" (turning +-90 or 180 degrees around x,y or z axis)

For knee images, to put the femur above the tibia, you further add the step:

<pre>
/turn2d
  -input                      out
  -output                     happyFemur
  -turnangle                  270
  -turnpoint_global_not_local true
  -turnpoint                  -1 -1
  -img_interpol_option        0
 </pre>

Refer to [[Media:turn3d.pdf |'''turn3d.pdf''']] for further instructions. 


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

===Noise removal by component labeling===
*Refer to [[Media:ComponentLabeling.pdf|'''Noise removal by using component labeling''']]


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

===Create MSQ image and view===

This is based on marching cubes.  See <code>IPL_UPAT_EVAL.COM</code> for an example as per below:

<pre>
/read seg C0000214_SEG.AIM

/sup_divide                               ! careful of the order of inputs here
  -input                     seg
  -suppos_pixels_local       -1 -1 -1
  -supdim_numbers            1 2 1
  -subdim_pixels             -1 -1 -1
  -testoff_pixels            0 0 0

/sub_pick
  -input                     seg
  -output                    segsub
  -subpos_numbers            0 1 0

/tri
  -input                     segsub
  -output                    tri
  -gobj_filename             none
  -peel_iter                 0
  -ip_sigma                  0.8
  -ip_support                1
  -ip_threshold              40
  -nr_ave_iter               2
  -size_image                512 512
  -scale_image               0.800000
  -edges                     false
  -nr_views                  1             ! Important

/msq_from_aim
  -aim_name                  tri
  -msq_filename              C0000123_3D.MSQ
</pre>

Then, use <code>UCT_3D</code> to view it.  If you click on "animations" it will give you the option to read the MSQ file.


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

===db_scanco_activate associate evaluation database===

When <code>/db_scanco_activate</code> is used in the IPL files, the correct association with the evaluation database is through the Index Patient and Index Measurement in the AIM header.

<pre>
Index Patient                                    3095
Index Measurement                                5962
!-------------------------------------------------------------------------------
</pre>

Using IPL
<pre>
$ ipl
$ read in xxx.aim
$ examine in log
$ db true           {activates database}
$ dt_object         {at end "writing results to database for measurement 1234"}
</pre>


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

===dicom_to_aim bug in IPL v5.03===

In IPL, use the /dicom_to_aim function.  There is a bug in pre IPL v5.03 which requires that a small AIM be read in before doing the DCM conversion.
<pre>
ipl> read in tmp.aim
ipl> dicom_to_aim
  -aim_name                  [in] > 
  -dicom_filename            [default_file_name] > 4F65038B3986.DCM
  -multifile                 [false] > true
ipl> write in MYFILE.AIM
</pre>


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

===Understand "New" DT functions in IPL v5.42===

This applies to:
<pre>/distance_map              /dt_ow_thickness           /dt_number                
/dt_thickness              /dt_spacing                /dt_cortical_thickness
</pre> 

XT1 (old dt) and XT2 (new dt) use 0.5 for assign_epsilon and 0.9 for
ridge_epsilon.

µCT uses 1.8 for assign_epsilon and 0.9 for ridge_epsilon (old dt).

Therefore I recommend to take 0.9 and 1.8 also for the new dt functions
for µCT/vivaCT measurements.

The <code>suppress_boundary</code> feature is new and works as follows:

0: The ridges and spheres are calculated on the full seg AIM, also
outside the gobj. At the end the gobj is applied.

1: The ridges that are on the AIM boundary are not used for the
calculation of the maximal spheres.

2: The ridges are calculated on the full seg aim but then the gobj is
applied to the ridges. This means that at the end there are only spheres
that have the center inside the structure (gobj). The maximal sphere
filling algorithm still accounts for the structure outside the gobj, but
only uses center points inside the gobj.


<code>dt_thickness</code> for example can be used in two different ways in a script:

1) cut out aim - apply threshold - apply gobj - dt_thickness
This way the suppress_boundary options do influence the results
because there are no ridges outside the gobj anyway.

2) cut out aim - apply threshold - dt_thickness (with corresponding gobj)
This calculates the dt on the full aim first and applies then the
gobj and suppress options.

If you examine for example trabecular bone only on a small area bounded
by a gobj then the most accurate way to calculate the dt is to cut out a
much larger area (still containing trabecular bone) and use way 2) above
with suppress_boundary 0.


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

===Develop new IPL commands in C===
*Refer to [[Media:IPL programming.doc|'''A short manual on how to develop new IPL commands in C'''.]]


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