SL Tools Tutorial

SL Tools Tutorial: Importing/Exporting PA Files–Describing the import of CAD models into SIMION, plus other potential array manipulation capabilities using the SL Tools utility.

_images/teapot-tiny.png

Abstract

This article describes how to import 3D CAD models into SIMION as 3D PA files, import 2D bitmap images into SIMION as 2D PA files, and convert SIMION potential arrays to text format, all using the SL Tools (sltools.exe) program available with SIMION (8.1/8.0/SL).

Introduction

The SL Tools utility in SIMION 8.1/8.0 (and also in the older SIMION SL Toolkit 1.2) 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).

Some examples of the CAD import feature are given below:

quadrupole drawn in CAD software and then imported into SIMION.

Figure: (left) CAD model of a quadrupole drawn in CAD software 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.

Shown above is a solids model 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 are more complex models imported into SIMION, not that it makes any sense to do these, but it gives an idea of the types of geometries that may be done–e.g. complex surfaces and intricate non-ideal grids.

dinosaur model imported into SIMION (3D and YZ views)

Figure: Dinosaur held at +24V between two grounded walls (front wall cut out for display). Positive ions fly toward dinosaur (190 x 350 x 750). STL Source: (c) 3D CAD Browser (www.3dcadbrowser.com) (2001), by Ross Blackburn). 24723 polygons, 22969 points.

shopping cart CAD model
shopping cart model in SIMION with ions flying through it and SIMION potential energy view

Figure: (top) original “shopping cart” STL model, (c) 3D CAD Browser (www.3dcadbrowser.com), by Wenet Locker (2001). 13314 polygons, 13907 points. (bottom left) Model acting as a non-ideal grid (300 x 350 x 300). The shopping cart is held at 120V. Not shown is an enclosing cube held at ground potential. (bottom right) potential energy view of XZ cross section.

Installation

System Requirements

This utility has the same System Requirements as SIMION. The OpenGL rendering can be intensive for large PAs, so a reasonably good graphics card is recommended if you wish to make use of the (optional) Quick View window.

Installation

SL Tools is installed by default by SIMION. It is accessible via the “SL Tools” button on the SIMION main screen.

You may wish to use the “install file associations” function in the SL Tools software to allow SL Tools to be easily accessed from Windows Explorer by right clicking on data files. You may need to run SL Tools as administrator to make that change though (right click sltools.exe in Windows Explorer and select “Run as Administrator”). If can anytime use the “uninstall” link to remove associations.

main menu of SL Tools software

Converting from 3D CAD (STL) Format to PA format

This section describes how to convert a CAD model into a SIMION potential array (PA) file. The STL format is a triangulated surface mesh format supported by many CAD programs.

First obtain a CAD model that you wish to import into SIMION. In your CAD program, export the CAD model as STL format. For testing, you may use the two_cylinder.stl included (zipped) in SIMION Example: geometry [8.1.0], which is a simple 2D cylindrical lens and can be useful to test the accuracy of the conversion (e.g. hole radius). 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 (www.3dcadbrowser.com), including a freely downloadable teapot example on the “register” page. You may also wish to try our simple Spring (External: ../docs/resources/toolstut/spring.stl) model or quadrupole rough draft (External: ../docs/resources/toolstut/sis_source.stl) which we drew using CADKEY.

In SL Tools, select the “STL -> PA” function and select your STL file from the “…” button next to “input file (STL)”. The conversion page appears as follows (you may wish to expand the window size):

STL to PA function in SL Tools

(If you had used the “Install” function in SL Tools to install file associations, you could have instead right clicked on the STL file in Windows explorer and selected SIMION SL Toolkit Functions, as shown below, to view or convert the file.)

opening STL file into SL Tools by right clicking on file from Windows Explorer

Clicking Convert will perform the conversion. 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:

3D view of PA file in SL Tools

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.

Note

This page is abridged from the full SIMION 8.1.1 "Supplemental Documentation" (Help file). The following additional sections can be found in the full version of this page accessible via the "Help > Supplemental Documentation" menu in SIMION 8.1.1:
  • Conversion Options - Detailed Description

CAD Export Topics

How you export your STL file from your particular CAD program can affect the results. Here are some tips for STL export.

STL Accuracy: Beware that exporting from your CAD model to STL format itself can lose some fidelity for any curved surfaces. STL represents a triangular surface mesh, so curved surfaces are approximated with flat triangles. Your CAD software may present you options during the STL export that control the accuracy of the export, such as in the number of triangles, the maximum triangle size, or the maximum angle the STL triangles are allowed to deviate from the curved surface. Refer to your CAD software documentation for details on your STL export options. You should use enough triangles, though it’s not necessary (though probably not harmful apart from the waste of disk space and increased processing time) to make STL triangles much smaller than your PA grid units. This is not a concern if all surfaces in your CAD model are flat polygons, for then there is not accuracy loss in the STL conversion. Use the “STL->PA” input and output “View” windows to examine the triangulation in the STL object.

Visual comparison: As of SIMION 8.1.1.1, there are “PA” and “STL” check boxes on the conversion output View window. You can use these to display both the PA and STL object simultaneously on the screen or toggle back and forth between them. This is useful for checking accuracy of the conversion.

My electrodes are hollow.

It is expected that imported electrodes are hollow. The STL file only represents surfaces. This is ok because electric fields derived from the Laplace Equation are uniquely determined solely by the shapes and potentials on the surfaces (e.g. electrode surfaces) bounding the volume of interest, not by what the inside of those electrodes look like (First Uniqueness Theorem).

This, however, might not be true if you were using SL Tools to import dielectric material (see below). Initial work has begun to allow STL definitions to be imported as filled solids to support dielectric material better. Contact us if you need this. If you really want your electrodes to be filled, you may touch up the electrodes in Modify or with Lua code.

As of 8.2 early access (20150727), there is a new “flood fill” command available via Modify or the Lua API (pa:flood_fill) that can fill in hollow electrodes. Below is one possible usage:

local pa = simion.pas:open("example.pa")
local xi,yi,zi = 20,30,40   -- coordinates in grid units
local new_potential = 100   -- volts
pa:flood_fill(xi,yi,zi, new_potential, true)
pa:save()

So depending on what you need, there are ways to automate such things.

Mixing STL with GEM and other SIMION drawing

After you import an STL file into a PA, you can draw additional objects into the PA using the other Geometry Input Methods. For example, load the PA into the SIMION Modify screen and use the “GeomF” button to “Insert” a GEM file into the existing PA (optionally positioning it).

Dielectric material

Ths current version of SL Tools is not ideally situated for importing dielectric material for two reasons.

First, the imported shapes are hollow, which doesn’t matter for conductors but is important for dielectric material since the inside of the dielectric does affect fields outside of it. See comments above on “My electrodes are hollow” for details and workarounds.

The second issue is that points in the dielectric PA are interpreted slightly differently from the electrostatic array (see Dielectrics), and SL Tools isn’t currently aware of this. Point (x,y,z) in the electrostatic array represents the potential and point type at location (x,y,z) in space. However, point (x,y,z) in the dielectric array represents the dielectric constant filling the volume of the cell bounded by points (x,y,z) and (x+1,y+1,z+1). If you don’t take this into account, the positions of your dielectric surfaces will be off by 1 grid unit, which reduces accuracy. This is easy to fix though by adding another option in SL Tools. (Actually, you need to be aware of this when creating dielectric PA’s from GEM files or other methods as well.)

STL File Size (Binary v.s. ASCII): Your CAD software may support exporting both ASCII and binary formats of STL files. SL Tools can read both, but it’s suggested to use binary files because they have a smaller file size and are more efficient to deal with.

Multiple electrode systems. By default, all solid points will be set to 1V solid electrodes. This is because STL files do not store electrode voltages. If your model has multiple electrodes, there are at least two ways to to avoid that:

(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. There is a screencast on Find/Replace that may be helpful, and Find/Replace is further described in Chapter 5 of the print manual. In 8.2 EA-20151103, there is also “Flood Fill” function that alternately can be used (available in Modify or alternately in Lua pa:flood_fill).

(2) SL Tools 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–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. This is shown in the figure below.

Importing multiple electrodes (two_cylinder-1.stl and two_cylinder-2.stl) simultaneously by specifying two_cylinder-%.stl as the input file name.

This relies on the assumption that the coordinate system in all the STL files is the same, as is usually in CAD softwares (if not, there may be still be some ways to force it, such as adding a common box around all components). The details are specific to your CAD software; for example,

Note

This page is abridged from the full SIMION 8.1.1 "Supplemental Documentation" (Help file). The following additional sections can be found in the full version of this page accessible via the "Help > Supplemental Documentation" menu in SIMION 8.1.1:
  • More CAD Package Specific Hints
  • Merging STL Files

Converting from a 2D Bitmap (BMP/PNG/JPEG/PNM) to PA Format

It is also possible to convert a 2D bitmap image (e.g. BMP/PNG/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, …).

three electrodes, each of different color, drawn in MS Paint
opening electrodes.png file into SL Tools from Windows Explorer

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.

Raster to PA function in SL Tools

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):

view of 2D image

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:

generated PA file loaded into SIMION

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:

SIMION potential energy plot of DRAG.PA0

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.

loading DRAG.PA0 into SL Tools from Windows Explorer
PA functions listed in SL Tools

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.

PA to Text function in SL Tools

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.

view of DRAG.patxt file showing PA header info and info on each electrode point

Here is the output if we instead set dx = 1.5 and data values to “fields.”

view of DRAG.patxt after setting dx = 1.5

Converting from ASCII Text to a PA File

We can also go the reverse direction (ASCII to PA).

opening DRAG.patxt into SL Tools from Windows Explorer
PATXT functions listed in SL Tools
Text to PA function in SL Tools

Giving the output:

3D view of PA showing three concentric cylindrically symmetric electrodes

Importing electric and magnetic field vectors: One particular application of the Text –> PA function is importing field vectors into PA files. You have two options here. First, you can convert each component of the field into a separate PA file, and then use techniques like in SIMION Example: field_array (solenoid_pa.iob) to represent a vector field in SIMION 8.1 based on those three PA’s. That is the most direct route and avoids additional numerical loss in precision. Second, you may be able to convert the field into a scalar potential and then represent it as a single PA. The latter is not generally possible for magnetic fields in regions where there are non-negligible currents (see Magnetic Potential).

SL Tools “Text -> PA” will take care of the converting the vector E-field into an electric potential or converting a vector H-field into magnetic scalar potential. This is done via a numeric line integration (simple trapezoidal integration, averaged over multiple paths, with single grid unit integration steps). Beware that if using a magnetic field, you should enter the H-field, not necessarily the B-field (which is related by B = (mu_r * mu_0) * H). The E-field should be in units of V per grid unit. The H-field should, like the B-field, be in units of gauss (i.e. H*mu_0).

SIMION Example: magnetic_potential (spotential_from_bfield.iob) demonstrates another way to convert vector fields to scalar potential PA’s via Lua, which can provide a bit more flexibility and also works on analytically defined fields.

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 –> STL.

opening magnet1.pa# into SL Tools from Windows Explorer

The parameters are as before. Click Convert.

PA to STL function in SL Tools

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:

_images/pa2v_view.png

For converting an entire IOB file to an STL, see simion.wb:save_stl() in SIMION.

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 controlled from the command-line:

sltools - SL Tools for SIMION SL
(c) 2003-2011 Scientific Instrument Services, Inc.
usage: sltools [command] [--help] [--nogui] args...

Top-level options:
  --help    - Displays this help message.
  --version - Displays SIMION version.
  --nogui   - Disable GUI (console mode only).
  --reserved-memory arg  - Number of bytes of memory to reserve for PAs.
Command may be one of
  stl2pa    - Convert STL to PA.
  bitmap2pa - Convert bitmap (BMP/PNG/PNM/GIF) to PA.
  pa2text   - Convert PA to text.
  text2pa   - Convert text to PA.
  view      - Quick view of STL or PA file.
  install   - register Windows file extensions.
  uninstall - unregister Windows file extensions.

For additional help on each function, add a --help option after the function name (e.g. sltools stl2pa --help).

Conclusion

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.