Atlases

The most commonly used atlas is the simple Oxs_BoxAtlas. For combining multiple atlases, use Oxs_MultiAtlas.

Oxs_BoxAtlas:

An axes parallel rectangular parallelepiped, containing a single region that is coterminous with the atlas itself. The specify block has the form

Specify Oxs_BoxAtlas:atlasname {
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
name regionname
}

where xmin, xmax, ... are coordinates in meters, specifying the extents of the volume being defined. The regionname label specifies the name assigned to the region contained in the atlas. The name entry is optional; if not specified then the region name is taken from the object instance name, i.e., atlasname.

Examples: sample.mif, cgtest.mif.

Oxs_EllipseAtlas:

Defines a volume in the shape of a right elliptical cylinder with axes parallel to the coordinate axes. This functionality can be obtained using appropriate Tcl scripts with the Oxs_ScriptAtlas class, but this class is somewhat easier to use and runs faster. The Specify block has the form

Specify Oxs_EllipseAtlas:atlasname {
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
margin { margins }
axis axisdir
name { regions }
}

Here xmin, xmax, ... are coordinates in meters, specifying the bounding box for the atlas, similar to the layout of the Specify block for the Oxs_BoxAtlas class. The margin setting combines with the bounding box to determine the extent of the elliptical cylinder. The margins value is a list consisting of one, three, or six values, in units of meters. If the full six values {, , ..., } are specified they determine the bounding box for the elliptical cylinder as $[xmin+m_0,xmax-m_1]\times[ymin+m_2,ymax-m_3]\times[zmin+m_4,zmax-m_5]$ . If three values are given then they are interpreted as margins for the x-coordinates, y-coordinates, and z-coordinates, respectively. If a single margin value is listed then that value is applied along all six faces. If the two margin values for a given coordinate are not equal, then the center of the cylinder will be shifted from the center of the atlas. If a margin value is negative then part of the cylinder will be clipped at the atlas boundary. If margin is not given then the default is 0.

The axisdir should be one of x, y, or z, specifying the axis of symmetry for the cylinder. If not given the default is z.

The name setting is a list of one or two elements. A single value specifies the region name for the interior of the elliptical cylinder. In this case the exterior is automatically assigned to the global “universe” region. In the case of a two element list, the first element is the name assigned to the interior of the cylinder, the second element is the name assigned to the exterior of the cylinder. If desired, either one may be specified as “universe” to assign the corresponding volume to the global universe region. If name is not specified then it is treated by default as a one element list using the atlas object instance name, i.e., atlasname, as the interior region name.

Examples: ellipse.mif, ellipsea.mif.

Oxs_EllipsoidAtlas:

Conceptually analogous to Oxs_EllipseAtlas, this class defines an ellipsoidal region with axes parallel to the coordinate axes. With appropriate Tcl scripts, the Oxs_ScriptAtlas class can provide the same functionality, but this class is somewhat easier to use and runs faster. The Specify block has the form

Specify Oxs_EllipsoidAtlas:atlasname {
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
margin { margins }
name { regions }
}

All entries are interpreted in the same manner as for the Oxs_EllipseAtlas class.

Examples: ellipsoid.mif and ellipsoid.mif. See ellipsoid-atlasproc.mif and ellipsoid-fieldproc.mif for examples equivalent to ellipsoid.mif using Tcl scripts.

Oxs_FileAtlas:

The Oxs_FileAtlas class defines regions through an imported file, somewhat similar to Oxs_ImageAtlas, but using a three dimensional OIF file in place of a two dimensional image. The Oxs_FileAtlas Specify block has the following form:

Specify Oxs_FileAtlas:name {
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
regions { rname_1 rname_2 ... rname_n }
file filename
}

Here xmin, xmax, ... are coordinates in meters, specifying the extents of the axes-parallel rectangular parallelepiped enclosing the total volume being identified. This volume is subdivided into n sub-regions, using the names as given in the regions list. The integer field (OIF) file filename is used to assign points to the various regions, with value “1” in filename associated with rname_1, value “2” with rname_2, and so on. As with Oxs_ScriptAtlas, region index 0 is reserved for the implicit “universe” region, to which any otherwise unassigned points are assigned. If filename denotes a relative path, then it will be taken with respect to the directory containing the MIF file.

If filename includes the OIF optional labels record, then the Oxs_FileAtlas regions entry to is optional; if missing the regions list is constructed from the OIF file's labels record. If the region names are specified in both places, the Oxs_FileAtlas Specify setting takes precedence.

In a like manner, if filename includes the optional x/y/zbase and x/y/zstepsize records, then the x/y/zrange entries in Oxs_FileAtlas are optional; if missing the volume extent is taken from filename. If the volume extent is specified in both, then the setting from the Oxs_FileAtlas Specify block is used.

Regardless of the source of the volume extent, the data from filename are translated and scaled to fit that volume. You can truncate the extent by placing the Oxs_FileAtlas inside an Oxs_MultiAtlas with smaller, explicit x/y/zregion settings:

Specify Oxs_MultiAtlas:atlas {
   atlas { Oxs_FileAtlas {
      xrange { 0 240e-9 }
      yrange { 0 150e-9 }
      zrange { 0  18e-9 }
      regions {nonmagnetic cobalt iron}
      file filelayers.oif
   }}
   xrange { 150e-9 240e-9 }
   yrange {  90e-9 150e-9 }
   zrange {   0     12e-9 }
}

Here filelayers.oif is imported with its natural size and location ( $(0,400)\times(0,200)\times(0,20)$ , in nanometers), but only the corner $(200,400)\times(100,200)\times(0,10)$ is used in the simulation. Conversely, if the Oxs_FileAtlas volume is encompassed by the Oxs_MultiAtlas x/y/zrange settings, then the Oxs_FileAtlas regions would cover only a subset of the full simulation volume.

Examples: filelayers.mif

Oxs_ImageAtlas:

This class is designed to allow an image file to be used to define regions in terms of colors in the image. It is intended for use in conjunction with the Oxs_AtlasScalarField and Oxs_AtlasVectorField classes in circumstances where a small number of distinct species (materials) are being modeled. This provides a generalization of the mask file functionality of the 2D solver (Sec. 17.1.3).

For situations requiring continuous variation in material parameters, the script field classes should be used in conjunction with the ReadFile MIF extension command. See the ColorField sample proc in the ReadFile documentation for an example of this technique.

The Oxs_ImageAtlas Specify block has the following form:

Specify Oxs_ImageAtlas:name {
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
viewplane view
image pic
colormap {

color-1 region_name
color-2 region_name
...
color-n region_name
}
matcherror max_color_distance
}

The xrange, yrange, zrange entries specify the extent of the atlas, in meters. The viewplane view value should be one of the three two-letter codes xy, zx or yz, which specify the mapping of the horizontal and vertical axes of the image respectively to axes in the simulation. The image is scaled as necessary along each dimension to match the atlas extents along the corresponding axes. The image is overlaid through the entire depth of the perpendicular dimension, i.e., along the axis absent from the viewplane specification. If variation in the perpendicular direction is desired, for example to model a multilayer structure, then multiple Oxs_ImageAtlas objects with multiple images may be combined inside an Oxs_MultiAtlas object, as in example file imagelayers.mif. An alternative is to construct an equivalent three-dimensional OIF file and use the Oxs_FileAtlas class.

If the image aspect ratio doesn't match the ratio of the viewplane ranges, then the scaling will stretch or contract the image along one axis. One workaround for this is to set the extents in the Oxs_ImageAtlas to match the image aspect ratio, and use a separate atlas (perhaps an Oxs_BoxAtlas) to define the mesh and simulation extents. This approach can also be used to translate the image relative to the simulation extents. For an example see imageatlas2.mif.

The image entry specifies the name of the image file to use. If the file path is relative, then it will be taken with respect to the directory containing the MIF file. The image format may be any of those recognized by any2ppm. The file will be read directly by Oxs if it is in one of the PPM or Microsoft BMP (uncompressed) formats, otherwise any2ppm will be automatically launched to perform the conversion.

The colormap value is an even length list of color + region name pairs. The colors may be specified in any of several ways. The most explicit is to use one of the Tk numeric formats, #rgb, #rrggbb, #rrrgggbbb or #rrrrggggbbbb, where each r, g, and b is one hex digit (i.e., 0-9 or A-F) representing the red, green and blue components of the color, respectively. For example, #F00 is bright (full-scale) red, #800 would be a darker red, while #FF0 and #FFFF00 would both be bright yellow. Refer to the Tk_GetColor documentation for details. For shades of gray the special notation grayD or greyD is available, where D is a decimal value between 0 and 100, e.g., grey0 is black and grey100 is white. Alternatively, one may use any of the symbolic names defined in the oommf/config/colors.config file, such as red, white and skyblue. When comparing symbolic names, spaces and capitalization are ignored. The list of symbolic names can be extended by adding additional files to the Color filename option in the options.tcl customization file. Finally, one color in the colormap list may optionally be the special keyword “default”. All pixels that don't match any of the other specified colors (as determined by the matcherror option) are assigned to region paired with default.

Each of the specified colors should be distinct, but the region names are allowed to be repeated as desired. The region names may be chosen arbitrarily, except the special keyword “universe” is reserved for points not in any of the regions. This includes all points outside the atlas bounding box defined by the xrange, yrange, zrange entries, but may also include points inside that boundary.

Pixels in the image are assigned to regions by comparing the color of the pixel to the list of colors specified in colormap. If the pixel color is closer to a colormap color than max_color_distance, then the colors are considered matched. If a pixel color matches exactly one colormap color, then the pixel is assigned to the corresponding region. If a pixel color matches more than one colormap color, the pixel is assigned to the region corresponding to the closest match. If a pixel color doesn't match any of the colormap colors, then it is assigned to the default region, which is the region paired with the “default” keyword. If default does not explicitly appear in the colormap colors list, then universe is made the default region.

To calculate the distance between two colors, each color is first converted to a scaled triplet of floating point red, green, and blue values, , where each component lies in the interval , with representing black and representing white. For example, is bright blue. Given two colors in this representation, the distance is computed using the standard Euclidean norm with uniform weights, i.e., the distance between and and is

$\displaystyle \sqrt{(r_1-r_2)^2 + (g_1-g_2)^2 + (b_1-b_2)^2}.$

Since the difference in any one component is at most 1, the distance between any two colors is at most $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\sqrt{3}\\ \rule{1pt}{0pt}\end{array}$}$ .

As explained above, two colors are considered to match if the distance between them is less than the specified matcherror value. If max_color_distance is sufficiently small, then it may easily happen that a pixel's color does not match any of the specified region colors, so the pixel would be assigned to the default region. On the other hand, if max_color_distance is larger than $\mbox{\renewcommand {\arraystretch}{0}$\begin{array}[b]{@{}c@{}}\sqrt{3}\\ \rule{1pt}{0pt}\end{array}$}$ , then all colors will match, and no pixels will be assigned to the default region. If matcherror is not specified, then the default value for max_color_distance is 3, which means all colors match.

The following example should help clarify these matters.

Specify Oxs_ImageAtlas:atlas {
    xrange { 0 400e-9 }
    yrange { 0 200e-9 }
    zrange { 0  20e-9 }
    image  mypic.gif
    viewplane "xy"
    colormap {
        blue   cobalt
        red    permalloy
        green  universe
        default cobalt
    }
    matcherror .1
}

Blue pixels get mapped to the “cobalt” region and red pixels to the “permalloy” region. Green pixels are mapped to the “universe” non-region, which means they are considered to be outside the atlas entirely. This is a fine point, but comes into play when atlases with overlapping bounding boxes are brought together inside an Oxs_MultiAtlas. To which region would an orange pixel be assigned? The scaled triplet representation for orange is , so the distance to blue is , the distance to red is , and the distance to green is . Thus the closest color is red, but is outside the matcherror setting of , so orange doesn't match any of the colors and is hence assigned to the default region, which in this case is cobalt. On the other hand, if matcherror had been set to say 1, then orange and red would match and orange would be assigned to the permalloy region.

Pixels with colors that are equidistant to and match more than one color in the colormap will be assigned to one of the closest color regions. The user should not rely on any particular selection, that is to say, the explicit matching procedure in this case is not defined.

Examples: imageatlas.mif, imageatlas2.mif, imagelayers.mif, grill.mif.

Oxs_MultiAtlas:

This atlas is built up as an ordered list of other atlases. The set of regions defined by the Oxs_MultiAtlas is the union of the regions of all the atlases contained therein. The sub-atlases need not be disjoint, however each point is assigned to the region in the first sub-atlas in the list that contains it, so the regions defined by the Oxs_MultiAtlas are effectively disjoint.

The Oxs_MultiAtlas specify block has the form

Specify Oxs_MultiAtlas:name {
atlas atlas_1_spec
atlas atlas_2_spec
...
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
}

Each atlas_spec may be either a reference to an atlas defined earlier and outside the current Specify block, or else an inline, embedded atlas definition. The bounding box xrange, yrange and zrange specifications are each optional. If not specified the corresponding range for the atlas bounding box is taken from the minimal bounding box containing all the sub-atlases.

If the atlases are not disjoint, then the regions as defined by an Oxs_MultiAtlas can be somewhat different from those of the individual component atlases. For example, suppose regionA is a rectangular region in atlasA with corner points (5,5,0) and (10,10,10), and regionB is a rectangular region in atlasB with corner points (0,0,0) and (10,10,10). When composed in the order atlasA, atlasB inside an Oxs_MultiAtlas, regionA reported by the Oxs_MultiAtlas will be the same as regionA reported by atlasA, but regionB as reported by the Oxs_MultiAtlas will be the “L” shaped volume of those points in atlasB's regionB not inside regionA. If the Oxs_MultiAtlas is constructed with atlasB first and atlasA second, then regionB as reported by the Oxs_MultiAtlas would agree with that reported by atlasB, but regionA would be empty.

NOTE: The attributes key label is not supported by this class.

Examples: manyregions-multiatlas.mif, spinvalve.mif, spinvalve-af.mif, yoyo.mif.

Oxs_ScriptAtlas:

An atlas where the regions are defined via a Tcl script. The specify block has the form

Specify Oxs_ScriptAtlas:name {
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
regions { rname_1 rname_2 ... rname_n }
script_args { args_request }
script Tcl_script
}

Here xmin, xmax, ... are coordinates in meters, specifying the extents of the axes-parallel rectangular parallelepiped enclosing the total volume being identified. This volume is subdivided into n sub-regions, using the names as given in the regions list. The script is used to assign points to the various regions. Appended to the script are the arguments requested by script_args, in the manner explained in the User Defined Support Procedures section of the MIF 2 file format documentation. The value args_request should be a subset of {relpt rawpt minpt maxpt span}. If script_args is not specified, the default value relpt is used. When executed, the return value from the script should be an integer in the range to , indicating the user-defined region in which the point lies, or else 0 if the point is not in any of the regions. Region index 0 is reserved for the implicit “universe” region, which is all-encompassing. The following example may help clarify the discussion:

proc Octs { cellsize x y z xmin ymin zmin xmax ymax zmax } {
    set xindex [expr {int(floor(($x-$xmin)/$cellsize))}]
    set yindex [expr {int(floor(($y-$ymin)/$cellsize))}]
    set zindex [expr {int(floor(($z-$zmin)/$cellsize))}]
    set octant [expr {1+$xindex+2*$yindex+4*$zindex}]
    if {$octant<1 || $octant>8} {
       return 0
    }
    return $octant
}

Specify Oxs_ScriptAtlas:octant {
    xrange {-20e-9 20e-9}
    yrange {-20e-9 20e-9}
    zrange {-20e-9 20e-9}
    regions { VIII V VII VI IV I III II }
    script_args { rawpt minpt maxpt }
    script { Octs 20e-9 }
}

This atlas divides the rectangular volume between and (nm) into eight regions, corresponding to the standard octants, I through VIII. The Octs Tcl procedure returns a value between 1 and 8, with 1 corresponding to octant VIII and 8 to octant II. The canonical octant ordering starts with I as the space, proceeds counterclockwise in the half-space, and concludes in the half-space with V directly beneath I, VI beneath II, etc. The ordering computed algorithmically in Octs starts with 1 for the space, 2 for the space, 3 for the space, etc. The conversion between the two systems is accomplished by the ordering of the regions list.

Examples: manyregions-scriptatlas.mif, octant.mif, pattern.mif, tclshapes.mif, diskarray.mif, ellipsoid-atlasproc.mif.