Skip to content

Latest commit

 

History

History
164 lines (138 loc) · 8.33 KB

README.md

File metadata and controls

164 lines (138 loc) · 8.33 KB
Raw

Open BirdcageBuilder

Open Source capacitor calculator for tuning Birdcage RF Coils.

Douglas Brantner1, Giuseppe Carluccio1, Chih-Liang Chin2, Christopher Collins1
1NYU Langone Health CAI2R + CBI
2Merck

Intro/Background

Estimates the capacitor value for building cylindrical Birdcage Coils.
Updated version of Birdcage Builder Android app, to run in any web browser, on any device (desktop or mobile).
This is the first fully open-source, cross-platform/cross-device version of BirdcageBuilder, released in 2023.

Version Notes

  • Version 1.0.0, 29 April 2024 - Updated for ISMRM 2024, minor clean ups, fixed unit tests- All Tests Passing.
  • Version 0.0.8 Beta WIP, 02 November 2023 (new official repo & name change, no major functionality changes, as submitted to ISMRM 2024)
  • Version 0.0.7 Beta WIP, 18 October 2023 (first public soft release at NYU CAI2R i2i Conference 2023)

Prior Versions

  • This new JavaScript version (2023) is based largely on the Java codebase from the Android version, available here:
  • The original version was written in Visual Basic and released in 2002 for Windows
    • See Chin, Collins, et al. 2002 referenced below

Caveats/Limitations

  • First pass capacitor prediction only
  • Does not take into account high frequency effects (Biot-Savart only)
  • Does not consider capacitive coupling (only mutual inductance)
  • Currently only for cylindrical birdcage coils

Usage

Webapp Usage

  • Enter all required values (including any necessary optional values for bandpass predefined capacitors or tubular leg dimensions)
  • For "No Shield" enter zero for the shield radius
  • For solid wire Legs or End Rings, select "Tubular" and set the Inner Diameter to 0.
  • If a larger number of legs is needed, it is a simple exercise in HTML hacking to achieve any number of legs (must be a multiple of 4)
  • Input errors will be highlighted in red.
  • Click "Calculate!"

Code Documentation

Workflow

See freqshifttest.html for a simple commented example of how the code works.

  • Live demo: freqshifttest.html
  • This demonstrates the basic class setup & code structure
    • The code in this demo runs in a loop to calculate multiple capacitor values, for changing center frequency (ie. to simulate B0 drift)
  • This also demonstrates code extendability and plotting with Plotly.js

Main Files

  • index.html - Main GUI for webapp
    • BBGuiHandler.js - Handles all input/output & main functionality for index.html interactive webapp
    • Try it live here: Live Webapp
  • BirdcageBuilder.js - Main class for capacitor math - see calc_capacitor() function
  • BCLegs.js - Class for Birdcage Legs, self- and mutual inductance
  • BCEndRings.js - Class for Birdcage End Rings, self- and mutual inductance
  • Other files:
    • helpers.js - Math & unit conversion helper functions.
    • debug.js - Handles debug output to browser console and/or HTML DOM.

Future Possibilities include:

  • Prediction of all resonances of a given coil design
  • Design of non-cylindrical birdcage coils
  • 3D CAD model output

Unit Tests

Testing against 2002 paper results (1) and Android app values (run both on Android and desktop Java)

  • Unit Tests require the QUnit.js in-browser testing framework

Unit Test Setup

Set up your working folder to match this folder structure, so that you won't have to adjust the import paths for the QUnit files (alternatively, you can use the CDN links without downloading QUnit; but please do not commit any path changes here).

   <parent folder>
   │
   ├── OpenBirdcageBuilder    (this repo)
   │   │
   │   └── OpenBirdcageBuilder
   │       ├── BBGuiHandler.js
   │       ├── BCEndRings.js
   │       ├── BCLegs.js
   │       ├── BirdcageBuilder.js
   │       ├── helpers.js
   │       ├── index.html
   │       ├── qunit_full_dom_tests.js
   │       ├── qunit_overview.html
   │       ├── qunit_test_all_math.html
   │       ├── qunit_test_endrings.html
   │       ├── qunit_test_helpers.html
   │       ├── qunit_test_legs.html
   │       ├── README.md
   │       └── ...
   │
   ├── qunit-2.19.4
   │   │
   │   ├── qunit-2.19.4.css
   │   ├── qunit-2.19.4.js
   │   └── ...
   │
   ├── qunit-assert-close-git
   │   │
   │   └── qunit-assert-close
   │       │
   │       ├── qunit-assert-close.js
   │       └── ...
   │
   └── qunit-composite    (optional - WIP)
       │
       └── qunit-composite
           │
           ├── qunit-composite.css
           ├── qunit-composite.js
           └── ...

See the qunit_...[.]html files for the current version of QUnit we are testing against, and file path structure.

  1. Clone this repository onto your local machine, following the above folder structure.
  2. Create additional folders (see file tree above) for QUnit files and clone these repositories:
  3. The unit tests should now run if the file paths are correct.
    • qunit_overview.html simply links to each of the 4 main unit test files
  4. Click and run each test page to ensure all tests are passing.
    • qunit_test_all_math.html - Validate output values
    • qunit_test_endrings.html - Test EndRing class
    • qunit_test_helpers.html - Test helper functions
    • qunit_test_legs.html - Test Leg class
  • (Automated testing - see _qunit_composite_wip.html - WIP, not working yet)

See In-Browser QUnit Documentation for more details.

Citation

In work utilizing this webapp or associated source code, please cite:
Chin CL, Collins CM, Li S, Dardzinski BJ, Smith MB. BirdcageBuilder: Design of specified-geometry birdcage coils with desired current pattern and resonant frequency. Concepts Magn Reson. 2002;15(2):156-163. doi:10.1002/cmr.10030
PubMed Free Full Text

License

GNU AGPL 3.0

References

  1. Chin CL, Collins CM, Li S, Dardzinski BJ, Smith MB. BirdcageBuilder: Design of specified-geometry birdcage coils with desired current pattern and resonant frequency. Concepts Magn Reson. 2002;15(2):156-163. doi:10.1002/cmr.10030
    PubMed Free Full Text
  2. Brantner D, Carluccio G, Collins CM. Open BirdcageBuilder. ISMRM 2024. Poster #1569.

Other References

All NYU, CBI, CAI2R names & logos are trademarks of NYU and may not be used without written permission.