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 right rectangular prism, 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_ParallelepipedAtlas:

Similar to Oxs_BoxAtlas, this class defines a region bounded by a parallelepiped described by one vertex and the three edges connected to that vertex. The faces aren't restricted to being parallel to the mesh coordinate planes. Note, however, that when rendered onto the coordinate mesh the edges and faces of the hexahedron will follow the staircase outline of the mesh. The Specify block has the form

Specify Oxs_ParallelepipedAtlas:atlasname {
corner { x y z }
u { ux uy uz }
v { vx vy vz }
w { wx wy wz }
autorange { xcell ycell zcell [ xbase ybase zbase ] }
xrange { xmin xmax }
yrange { ymin ymax }
zrange { zmin zmax }
name regionname
}

where corner specifies one corner of the hexahedron, and u, v, and w are three vectors specifying the edge directions and lengths protruding from corner. An error will be raised if u, v, and w are co-planar.

The default bounding box for the atlas is the tightly fit coordinate-parallel cuboid. If this is used to define the simulation bounding box then an error will be raised by the mesh object if the bounding box is not an integral number of cells across. The first three parameters to the optional autorange entry, xcell, ycell, zcell, force the expansion of the atlas bounding box to an integral number of cells along each coordinate axis. If six parameters are specified, then the last three specify an alignment point on the simulation mesh, and the atlas bounding box is adjusted to align with that mesh. Otherwise the expanded atlas bounding box is centered about the parallelepiped.

The optional xrange, yrange, and zrange entries override the bounding box computation along the corresponding axis. In particular, in some circumstances the autorange calculation may yield an unnecessary margin outside the active cells in a simulation; the range options can be used to trim such margins.

The regionname label specifies the name assigned to the region contained inside the parallelepiped. The name entry is optional; if not specified then the region name is taken from the object instance name, i.e., atlasname.

Note: For rotated parallelepipeds it may be easiest in the MIF file to first describe the edge vectors in an unrotated coordinate system and then use Tcl expr commands to apply rotation matrices to orient u, v, and w before creating the atlas. See the sample parallelepiped.mif file as an example.

Examples: parallelepiped.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 }
file filename
regionmap {

region_name { index ... }
region_name { index ... }
...
region_name { index ... }
}
autofmt format_string
}

Here xmin, xmax, ... are coordinates in meters, specifying the extents of the axes-parallel rectangular parallelepiped enclosing the total volume being identified. If xrange/yrange/zrange are not specified, then the atlas bounding box will be imported from the OIF x/y/zbase and x/y/zstepsize records, if they exist.

The atlas volume is subdivided into regions using the names as given in the regionmap entry. The integer field (OIF) file filename is used to assign points to the various regions, with the file value (index) at each 3D location in filename mapping to the region_name in regionmap associated with the corresponding index. Each region_name may have as many indices associated with it as desired, but each index can map to at most one region_name. If optional autofmt is defined, then any file index not specified in regionmap is assigned to the region name generated by interpreting format_string (for example “region%d”) as a C-style format string with the file index as a parameter. If autofmt is not declared, or is declared as an empty string, then an error will be raised if any file index is found that does not map to a region_name. Alternatively, one can set format_string to a region name string, such as “universe,” to have all unmapped file indices assigned to that region.

If regionmap is missing then one will be constructed from the OIF file “labels” record, if any. The labels record is treated as equivalent to a regionmap with each label element as a region name associated with corresponding element index. For example, the OIF file record

# label: Fe Ni Co

is equivalent to the Oxs_FileAtlas Specify entry

regionmap {
   Fe 0
   Ni 1
   Co 2
}

An error will be raised if neither regionmap nor labels exist.

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 }
      regionmap {
         nonmagnetic {0 3}
         cobalt 1
           iron 2
      }
      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 discrete number of distinct species (materials or grains) 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
}
colorfunction function_type
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.

The colorfunction option is an alternative to colormap which is useful when the number of regions is very large, for example with machine-generated grain maps[19] as in example file grains.mif. The function_type field must be “auto”. With this option the image is scanned and region names are automatically generated and assigned to each distinct color (as defined by matcherror). The region name list may be accessed inside MIF 2.2 files via the GetAtlasRegions and GetAtlasRegionByPosition commands.

At least one of colormap or colorfunction must be specified. If both are used, then color designations from colormap take precedence over colorfunction.

Pixels in the image are assigned to regions by comparing the color of the pixel to the list of colors designated by colormap/colorfunction. If the pixel color is closer to a designated color than max_color_distance, then the colors are considered matched. If a pixel color matches exactly one designated color, then the pixel is assigned to the corresponding region. If a pixel color matches more than one designated color, the pixel is assigned to the region corresponding to the closest match. If a pixel color doesn't match any designated color, 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, grains.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.

OOMMF Documentation Team
September 30, 2025