rpeltekov / ge3t_shim_tool

Conformal Shimming for GE3T using ExSI and OpenSourceImaging Shim Drivers

ge3t_conformal_shim

Custom Conformal Shimming Calibration and Computation Tool for GE3T MRI Scanner

• Automated using ExSI. A tool made by GE for the GE
• Built for use with OpenSourceImaging Shim Drivers
• Runs on ajacent machine to scanner computer, so that you have access to latest python environment
• GUI built using PyQT6

Setting up and using the Shim Tool

1. Navigate to the directory and install the required packages

$ cd <path/to/shimTool>
$ pip install -r requirements.txt

2. Fill in the empty lines in configs.json. These will be dependent on personal preferences and scanner setup. The passwords / host ids are generally common for the GE Nspire

3. Launch the tool

$ python shimTool.py

Using just the ExSI Client

ge3t_shim_tool's Issues

when background scan is done, the button doesn't ungrey till after you switch tabs

if you do background scan, then the radio button to view it stays grey if you are on the ROI tab when the scan finish.

probably some update function is not called when the scan finishes, and it only rerenders it when it switches tabs or smth idk...

should be really easy...

some errors when trying to save the results and plots

when saving and only background has been obtained... probably something to do with the stats array being [none, none, stats, stats, none, none,...]

integrate phase unwrapping

try with scikit, to implement some phase unwrapping on the phase images before increasing the deltaTE

show the actual value in Hz offset of CF, not just the value of intensity that the image has...

should see also actual Hz offset. not grayscale img value.

then fix why the image so dark when "corrected" when it should really be close to zero.

Get back to original pre-refactor performance

• fix the eval scan procedure as well, so that i can queue basis check comparisons
• need to make sure shim scan ALL slices works and schedules all relevant slices properly
• that the histograms are being saved correctly,
• #17
• make sure shim actually works effectively
  - this involves making sure the scans are actually performing optimally, as they are expected to be doing so.
  - will likely need to increase the TE to reduce noise in the B0Map acquisitions, and then can hopefully get clearer image
  - to increase TE, will probably need to finish #5
  - if that still does not work, will need to characterize gradients better to see if they are actually linear #16, which is dependent on #2

create the views that allow user to see histograms and results performance on the third tab

make exsi_client.py self sufficient

the exsi_client has some dependence on the gui right now with respect to the threading variables that are used within it. it hangs whenever you try to run it on its own without the gui / shimTool driving it.

make sure that those are not necessary and that you can create an exsi_client instance and drive the scanner completely on your own from the python CLI

also add documentation to further explain how the exsi_client works so that others can easily grab it and use it.

update shimClient to handle multiple boards / driver systems

note: everything from the perspective of the tool, should abstract away the notion of shim boards. this should only be a concept that the shimClient handles.

Buff the --no-gui mode for the tool

make it generally easier to use the tool from the command line

• add help menu to the --no-gui option
• allow loading custom basis functions and whatnot
• add some autocomplete? i dunno maybe not

use the fancy logging.error and logging.debug

i learned you could log better than the weird functions that im using right now.

probably better to standardize it using this stuff here:

https://github.com/rpeltekov/ge3t_shim_tool/blob/main/shimTool/exsiProcess.py#L18

logging and debug messages are different across different files and they should be refactored to just be more consistent...

Useability Fixes that are necessary

After talking / showing Miki the UI, there were a series of usability fixes that should be implemented to make the tool actually useful

• AutoPrescan checkbox: just a checkbox that should default on for first scan, to show it will autoprescan, then it checks off for subsequent scans. should allow the user to check it on in the future too. doing so should scrap the old default CF / linear shim values
• Single Fieldmap Button only: there should be only one button to do a fieldmap. currents / correct values should be computed off just the latest scanned fieldmap

dependent on #2

Where I am leaving off June 5 evening:
it looks like it can properly obtain the first fieldmap and then do the basis map scan after that and generate expected fields, etc...

• the autoprescan /overwrite backgorund buttons seem to not uncheck in the gui properly. need to make sure that they function properly
• need to then make sure that clicking the fieldmap button a second time performs as expected and saves a shimmed fieldmap again at the position that I expect it
• then need to test things again with the ROI selected, and start developing things on the third checkmark here.

make gradient shimming work as good as possible...

should be able to achieve mean = 0 at the very least, with marginal improvement on STD.

• if that still does not work, will need to characterize gradients better to see if they are actually linear #16 which is dependent on #2 so that you could more adhoc test random things...

characterize performance / linearity of the gradients

collect scan data for a bunch of gradient strengths, and then plot the relationship of scaling factor of gradient tick to slope / gradient strength for each direction. use a large phantom to do this, maybe the big box phantom to do this.

this is dependent on the following tasks:
#2 because this will make it much easier to script this in a jupyter notebook and generate the plots easily after that fact

This is a precursor to the following task:
#8 This needs to be done before we can eliminate the need to pre-record gradients in the calibration sequence.

add colorbar to the ImageViewer

once you figure out how to run this (maybe it might be worthwhile to figure out how to create a mock scanner so that we can test things....):

currently, the color for the images is determined by the dynamic range of the entire 3d dataset. i.e. the values from every slice. however, this leads to it being very hard to see any visual differences in the b0 map or the actual non b0map image.

to further make it easier to understand what we look at when we check out the images, the colorbar would be nice. like the ones that you can spawn with plt.colorbar() when using matplotlib. it should just show what the max min and midpoint values are next to the spectrum of color seen in the image. since images are b/w, it will just grayscale values that you need to worry about for now.

• fix dynamic range of the views
• add some value to show the max / min value
• think about a colorbar

some tips or places to start:
for dynamic range, look here and maybe best to remove the attribute viewMaxAbs, and just use the max(abs(of the slice that is being shown)) for scale.

after that look for a way to have the min / max values in the original slice show up when the slice is rendered before you start attempting a color bar. depending on how hard that will be, this will be enough. this is one of 3 places imageViewer is created, and notice the viewLabel. This is what gui object gets updated with the pixel value when you click on the image. this function modifies the contents of the label, and i want you to simple make sure that a string like "Max {max} Min {min} | " is always displayed regardless of if you are clicking on the image.

in gui.py, add colorbar item near where the image views are created (here for example), and figure out how to sync the update sequence to these images (here) so that the color bar works well?.

probably also make an update function for the colorbar in guiUtils to create the imageViewer, the label for the mouse hover/click event, and also for the color bar at this point so the code isn't repeated to generate all those three times in gui.py

add a progress bar for scans at the bottom of the gui

right now we are essentially relying on the output to the console on whether the scans are actually going as planned. add a little progress bar or something somewhere to the gui such that you can see the progress of the scan / operation of the button that you clicked, which made every other button grey out.

make the log views tabbed and allow the user to switch between which one they wanna see

allow user to switch the tab to which log they want to view.

basically i should be able to see the exsi log or the shim log when i am on the shim control tab window

add context for orientation of data when you pull it from the dicom

there is currently no concept of orientation, and manually throughout the whole codebase we are extracting a slice, i, by using the naive "[:,i,:]" numpy slice indexing but this results in a lot of missed bugs, and some unexpected flipping / orientation loss.

i propose to add a class that handles all the 3d image data and exposes functions that allow you to more easily get any slice you want in any orientation easily. the original information should be extracted from the dicom when it gets ingested.

make shimTool completely independent of the GUI

there is a desire to untwine the connection of the GUI with the shimtool itself.

currently the shimTool directly calls on a few specific members from the gui directly whenever it is doing some operations. search for "gui" within shimTool.py and you will see what I mean.

ideally, the shimtool should be able to be instantiated by itself, in some python cli forexample, and you should be able to drive shimming from the python CLI.

save the linear gradient basis maps and remove the need to scan basis maps for them

the linear gradients are currently recorded like the other basis functions. this could be done away with because you technically don't need to do this every single time...

they are simply affine functions, and they should scale linearly with the strength that you add to them.

will need to:

• figure out how to model the gradient properly...
• update all the references to basisMaps[0-2] and devise some data structure within the shimTool class to store the data
• figure out a linear gradient calibration sequence, and save data to a file
• add gui functionality for this button

re-enable volume shimmin

• volumewise shim: should have a button that does volumewise rather than just slicewise shim computation. essentially it does not make that much sense for the shimming to be just slice by slice for now i think

button is made, just need to finish delivering the feature and testing it

fix the checkmarks

make the checkmarks for set optimal currents and perform shimmed scan on currently selected slice dependent on the slice that it is currently on. i.e. once you do it once, the checkmarks turn on, but then if you switch to a slice which has not had it's performance measured yet, then uncheck them...

Set S/I position of FOV relative to where the last scan was done.

need the shim tool to perform shimming at isocenter around where the user actually wants to scan. currently the shim tool prescribes a scan with a preset S/I position. it really needs to be set based on where the last scan was done. either extract this information from a previous scan, or just take the last set patient table position.

thanks to help from miki, found the information is logged to /usr/g/service/log/irmJvm.log, within lines like:

Sat 05/25/2024 10:53:03.473 AM PDT::::TablePositionApplication: Table Position=0
Sat 05/25/2024 10:53:03.521 AM PDT::::TablePositionApplication: Table Position=0
Sat 05/25/2024 10:53:03.581 AM PDT::::TablePositionApplication: Table Position=S1
Sat 05/25/2024 10:53:05.675 AM PDT::::TablePositionApplication: Table Position=S42
Sat 05/25/2024 10:53:05.681 AM PDT::::TablePositionApplication: Table Position=S42

Note: this then requires the user to do a scan in the position they desire to begin with first... or at the very leat they need to set their FOV, save scan, and then advance patient table so that information is then available to the shim GUI.

remove circular imports between shimTool and gui

gui should launch shimTool whenever gui is being used. this should be done from the main.py

if the gui is not being used, then it should just launch the shim tool and the interactive python environment.

Separate UI style/construction from Action Definition

In GUI, move all the definitions of handler functions and triggers to separate functions from UI and Style Creation.

this would make the gui code a lot easier to look at and more simple to debug / add new code cleanly

figure out how to apply shimming for real scans. connect FOV to ROI and view using localizer scan?

Add more ROI class

make more different kind of ROI that you can select.
is dependent on #1 though
currently it is only an ellipsoid, but it should be a couple more objects like

• cube / square
• drawable manually?
• combination of square and maybe you can cut it off somehow?

Might also be worth it to in here or in another issue, add the capability for adjusting the ROI by dragging the actual display of the ROI. idk really how to do it im not that big of a gui wizard...

make the shim view use the jet color map instead of grayscale...

might just make things a lot easier to see...

make exsi_client useable in jupyter notebook

it would be nice and useful to launch exsi_client in a jupyter notebook. mutlti threads don't really work between cell contexts in jupyter notebook though, so might need to figure out a multiprocessing solution for it.