Atlases

Geometric volumes of spaces are specified in Oxs via atlases, which divide their domain into one or more disjoint subsets called regions. Included in each atlas definition is the atlas bounding box, which is an axes parallel rectangular parallelepiped containing all the regions. There is also the special universe region, which consists of all points outside the regions specified in the atlas. The universe region is not considered to be part of any atlas, and the universe keyword should not be used to label any of the atlas regions.

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 {m₀, m₁, ..., m₅} are specified they determine the bounding box for the elliptical cylinder as [xmin + m₀, xmax - m₁] x [ymin + m₂, ymax - m₃] x [zmin + m₄, zmax - m₅]. 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_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. The Oxs_ImageAtlas class can be used inside a Oxs_MultiAtlas object to specify regions in a multilayer structure, as in example file imagelayers.mif. Note that 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, (r, g, b), where each component lies in the interval [0, 1], with (0, 0, 0) representing black and (1, 1, 1) representing white. For example, (0, 0, 1) 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 (r₁, g₁, b₁) and (r₂, g₂, b₂) and is

$$\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 (1, 0.647, 0), so the distance to blue is 1.191, the distance to red is 0.647, and the distance to green is 1.06. Thus the closest color is red, but 0.647 is outside the matcherror setting of 0.1, 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 1 to n, indicating the user-defined region in which the point lies, or else 0 if the point is not in any of the n 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 (- 20, - 20, - 20) and (20, 20, 20) (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 + x, + y, + z space, proceeds counterclockwise in the + z half-space, and concludes in the - z half-space with V directly beneath I, VI beneath II, etc. The ordering computed algorithmically in Octs starts with 1 for the - x, - y, - z space, 2 for the + x, - y, - z space, 3 for the - x, + y, - z 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.

OOMMF Documentation Team
September 30, 2022