|The SIMION SL Toolkit (version 188.8.131.52 - 2004-11-09)|
--Describing the import of CAD models into SIMION, plus other potential array manipulation capabilities of the SL Tools ("sltools.exe") program now available in the SL Toolkit.
April 2004, David Manura, Scientific Instrument Services, Inc. Updated $Date: 2004/07/20 05:26:13 $.
The SL Tools utility in the SIMION SL Toolkit expands the functions that can be performed on PA files:
- Import/export 3D CAD models to/from 3D SIMION potential array (PA) files.
- Import/export scalar potential and vector field data of refined potential arrays from/to ASCII text files for use in third-party or custom programs.
- Import/export 2D bitmap images to/from 2D SIMION potential array (PA) files.
- Quickly view PA files from Windows Explorer (OpenGL).
Figure: (left) CAD model of a quadrupole drawn in CADKEY and exported to STL format. (right) STL file converted to a PA file (160 x 1120 x 260) using the new PA tools and then loaded into SIMION.
Figure: CAD model of a teapot imported into SIMION for demonstration using the new SL Tools (350 x 350 x 350). STL Source: 3D CAD Browser (www.3dcadbrowser.com) (2004) http://www.3dcadbrowser.com/register.aspx
Shown above are two examples of solids models drawn in a CAD program and exported as STL surface files. We then converted the STL file into a SIMION potential array file (PA or PA#) for use in SIMION. "What is an STL file?" you ask. The STL format is a triangulated surface mesh format exportable by most CAD programs. STL comes in two formats (binary and ASCII), both of which are supported by the SL Tools.
Here is more complex model imported into SIMION:
Below demonstrates how the CAD import feature can significantly expand the possibility to import and simulate non-ideal grid geometries in SIMION:
The software has only been tested under WinNT/2000/XP. It probably will not work under Win9X, as is, due to the reliance on OpenGL for the Quick View window. (If you need Win9X support, let us know, and we can build a non-OpenGL version.) The OpenGL rendering can be intensive, so a reasonably good graphics card is recommended if you wish to make use of the (optional) Quick View window.
SL Tools is installed by default when you run slsetup.exe in the SL Toolkit v. 1.2 and above.
Alternately, you may download the sltools.exe program individually. In this case, after you run the sltools.exe program, click the "install file associations" link and then click "install". This will allow the SL Tools to be easilly accessed from Windows Explorer by right clicking on data files. If you later wish to uninstall, just select the "uninstall" link instead. Then delete the program file.
Converting from 3D CAD (STL) Format to PA format
Now, let's convert a CAD model into a SIMION potential array (PA) file.
First obtain a CAD model that you wish to import into SIMION. In your CAD program, export the CAD model as STL format. The STL format is a triangulated surface mesh format supported by many CAD programs.
For testing, you might wish to use one of the many STL files available on the Internet. We found many quality STL models at 3D CAD Browser (http://www.3dcadbrowser.com), including a freely downloadable teapot example on the REGISTER page. You may also wish to try our simple Spring (spring.stl) model or quadrupole rough draft (sis_source.stl) which we drew using CADKEY.
In Windows Explorer, navigate to a directory containing an your STL file. Right click on the file and choose "SIMION SL Toolkit Functions" to pass the file to SL Tools.
Next, select which function you want to perform on this file. If you wanted to just preview the file, you would click "View." Let's lick "Vector --> PA" instead to convert this (vector) STL file to a SIMION PA file. A conversion page appears:
Here you can adjust various parameters on the conversion process. (You may wish to expand the window size.) Most of the parameters are already filled in with defaults. The input file and output file are specified first. You may use the "..." buttons to browse for a different file or click the "V" button to preview the STL or PA model (if it exists). Below is the preview of the input file:
Drag with the mouse to rotate the model, or press ESC to close the Quick View window.
The nx, ny, and nz parameters specify the x, y, and z size of the output PA file in grid units. Changing this value will cause the num_points to be recalculated automatically. Beware that the more points you have, the more computationally and memory intensive the PA is. SIMION has a 50 million point maximum (~400 MB) per array.
num_points is the number of grid points to use in the PA. This value will be calculated automatically from nx, ny, and nz. Changing this value will automatically adjust nx, ny, nz, and scale.
The min and max values for x, y, and z (which can be largely ignored for now) define a boundary box around your CAD model. These coordinates are in CAD model units (whatever those may be in your CAD software). By default, a minimum enclosing boundary box around your model is given.
The scale value (which can also be largely ignored for now) will multiply the CAD units in order to obtain PA grid units. The smaller the scale value, the smaller the model inside the array. Scale will be automatically computed for you (unless you change it) so that the model's boundary box fills up the PA grid as much as possible. Changing the scale valuve will result in the nx, ny, and nz value to be adjusted automatically.
When view output? is enabled, the generated PA file will display immediately after the conversion process. If unchecked, you may instead use the "V" button on the output file field to view the result.
For this example, the "num points" field was set to about 5 million.
We're now ready to perform the conversion. Click "Convert." The bottom status bar should display "Converting..." followed by "Success." If "view output?" was enabled, the output file will load (a progress bar displays) and the following Quick View window appears:
As before, you can rotate the model by dragging the mouse, or press ESC to quit. The PA file can now be loaded into SIMION. See the previous screenshots in the Introduction section showing the cart simulated in SIMION.
Multiple electrode systems. By default, all solid points will be set to 1V solid electrodes due to limitations in the STL format. If your model has multiple electrodes, there are at least two ways to resolve this:
(1) You can use the Modify function in SIMION to adjust the voltage on certain regions of your generated PA or make further changes. In particular, the "Find" function comes in handy to change the potentials of all solid points in a region to some other value. This is what we did for the quadrupole example above.
(2) SL Tools v.beta2 and above supports loading multiple overlapping STL files, one per each electrode, directly into a single PA file, so that Modify/Find becomes unnecessary. In your CAD software, simply export each electrode or component as an individual numbered STL file (this is trivial in SolidWorks)--e.g. myfile-1.stl, myfile-2.stl, and myfile-3.stl. Then in SL Tools, specify a template for the input file name using the "%" character as a placeholder (e.g. "myfile-%.stl"). SL Tools will search for and read all matching SL files and assign these voltages of 1V, 2V, and 3V respectively.
Converting from a 2D Bitmap (BMP/PNG/JPEG/PNM) to PA Format
It is also possible to convert a 2D bitmapped image (e.g. BMP/PNJ/JPEG/PNM file) into a 2D SIMION potential array (planar or cylindrical).
Below we created a simple 2D image of an electrode system in MS Paint. We drew each electrode in its own color so that the SL Tools will assign a different fast adjustable potential to each electrode (1, 2, 3, ...).
To convert this image, navigate to the image file in Windows Explorer, right click on the file, and choose "SIMION SL Toolkit Functions" as shown above and then select "Raster --> PA".
All the fields are filled in with defaults. The fields have similar meaning as described in the previous section. You can use the "..." buttons to browse for a file or the "V" button to quickly view a generated PA file. When view output? is selected, the generated PA file will display immediately after conversion.
Press "Convert" to perform the conversion. The PA file is generated and the following quick view displays (before cylindrical revolution):
Press ESC to exit the quick view. You can now load the file into SIMION. Below is the result after changing the symmetry to cylindrical via the Modify function:
Note that this 3D model is a surface of revolution of your bitmap with respect to the x-axis.
Converting a PA File to ASCII Text
The SL Tools can also convert SIMION PA files to ASCII text. For example, the SL Tools can generate a text file listing the solid points, potentials, or potential gradient vectors at each point (x, y, z) in the PA file. This text file then may be imported into other programs or used directly for special applications.
For this example, we will ASCII-tize the 2D "DRAG.PA0" potential array (refined, fast adjusted, and saved) that comes with SIMION:
To convert a PA file, first locate the file in Windows Explorer, right click on the file, and select "SIMION SL Toolkit Functions" and select "PA --> Text".
You can convert any type of PA file (PA, PA#, PA0, PA1, ...). However, if we want to generate a text file containing potentials or potential gradient vectors, we must select use a refined and fast adjusted PA or PA0 file, else all the values at space points will be zero.
The following screen then displays allowing you to modify conversion parameters.
As before, the "..." button may be used to browse for an input or output file. The V button will display a preview of the selected PA or text file.
The Data values selection may be either "potential" to generate potential values or "field" to generate potential gradient vectors (fields). Sampling dx represents the sampling width in grid units. The default (1) will sample at every grid point. If this value is fractional, interpolation will be performed between grid points. The various include ...? options can be unchecked if you want the output to be more terse. Check view output? if you want the generated text file to immediately display after conversion (if not, you can still use the "V" button on the output file to view the file). You might want to uncheck this if the file will be very large.
Below is the output.
Here is the output if we instead set dx = 1.5 and data values to "fields."
Converting from ASCII Text to a PA File
We can also go the reverse direction (ASCII to PA).
Giving the output:
Importing magnetic fields: One particular application of the "Text --> PA" function is importing x, y, z magnetic field vectors into a PA file. SL Tools will take care of the numeric line integration for you in converting the field vectors into the scalar potentials used in the PA file.
Converting a PA File to STL
To convert a PA file to an STL file, right click on the PA file in Windows Explorer and select "SIMION SL Toolkit Functions" and then "PA --> Vector".
The parameters are as before. Click "Convert."
The "keep symmetry" option preserves and cylindrical symmetry or mirroring in the PA (otherwise, the STL model will be flat).
The "num sectors" option defines the number of circle sectors used in approximating the solid of revolution (applicable only to cylindrical symmetry PAs). The higher the valve, the better the quality.
A preview of the generated STL file is displayed:
The Quick Viewer
As shown in the previous sections, the SL Tools can display STL and PA files via the "V" buttons. You can also invoke the quick viewer by right clicking on a PA or STL file in Windows Explorer and selecting the SIMION SL Toolkit Functions and then selecting the "View ..." function. This provides a fast way to see what is inside files.
Advanced: Command-line Usage
For advanced users, the SL Tools program can also be fully controllable from the command-line.
sltools [opt1] v2pa [opt2] filename # convert vector --> PA sltools [opt1] r2pa [opt2] filename # convert raster --> PA sltools [opt1] pa2t [opt2] filename # convert PA --> text sltools [opt1] pa2v [opt2] filename # convert PA --> vector sltools [opt1] view [opt2] filename # quick view STL or PA file sltools [opt1] install # install file associations sltools [opt1] uninstall # uninstall file associations where opt1 is an optional set of global options: --help # top-level help --console # non-GUI mode and opt2 is a set of options specific to the current function.
For additional help on each function, add a "--help" option after the function name (e.g. "sltools v2pa --help").
Some command-line functionality may be missing at this time. Let us know if this is the case for your application so we can correct this.
We've described how to use the new sltools.exe program to import 3D CAD and 2D raster files into SIMION. We also looked at exporting PA files to text or STL files, as well as the quick view features.
SIS would by glad to know of anything you'd like to see added to the PA tools.