map_spheres

Map_Spheres

$image\sphmod.jpg$

This is a deprecated module that has been supplanted by post_samples

(This module has some features available only in EVS PRO and MVS)

General Module Function

The Map Spheres module is used to visualize sampling locations and the values of the properties in .csv files, or the lithology specified in a .geo file, along with a representation of the borings from which the samples/data were collected. Map Spheres has the capability to process property values to make the posted data values consistent with data used in kriging modules, to post spheres, or square or hexagonal discs at the sampling locations that are colored and sized according to the magnitude of the property value, and to label the sampling locations with several different types of information. An interpolation functionality is now available with Map_Spheres whereby the user may calculate a linear interpolation (range 0 to 100 percent) between two consecutive data components. This functionality is useful for creating animations of time-series data with Map_Spheres. Mouse interactive querying of data is now available with Map_Spheres by clicking the left mouse while holding the alt key.

Map Spheres can also represent downhole geophysical logs or Cone Penetration Test (CPT) logs with colored and sized tube diameters according to the magnitude of the data. Map Spheres can display nonvertical borings and data values collected along their length, and can also explode borings and sample locations to show their correct position within exploded geologic layering. When used to read geology files, map spheres will place sample indicators at the top surface of each geologic layer, that are colored according to the layer they are depicting and/or will color the borings by lithology.

Module Input Ports

Map Spheres has four input ports. The first (leftmost) port can only be connected to Krig 3D Geology, which provides the geologic layering information that allows the boreholes and spheres to be exploded (This feature available only in EVS PRO and MVS) into their appropriate geologic layers. The second, and third rightmost ports can be connected to explode and scale, which provides the explode and scale factors, respectively. If geologic layering is not being modeled, then only the right port needs to be connected to Explode and Scale to provide the scale factor for displaying the boreholes and spheres.

The Yellow-Blue-Orange port (second from left to right) allows the sharing of Chemistry or Geology file names between similar modules. This should simplify the task of specifying data file names common to multiple modules in your application. The output ports come in 3 color varieties:

Module Output Ports

Map Spheres has five output ports:

The leftmost Yellow-Blue-Orange port allows the sharing of Chemistry or Geology file names between similar modules.

The second (gray-green) port is the explode factor.

The third (gray-brown) port is the Z-exaggeration factor.

The fourth (red) port outputs a geometry that can be input to the Viewer for rendering.

The last (blue-black) port outputs the bounds of the data field to the Generate Axes module, which provides automatic placement of the axes in the scaled or unscaled data field.

$image\sph_panel.jpg$

Module Control Panel

The control panel of Map Spheres is shown in the figure above. The Read Input File button opens a File Browser which lists the *.geo, *.pgf, or *.csv files that are present in the current directory shown in the directory window. The format of .csv files is described in the csv file format help topic. The format of .geo files is described in the geo file format help topic.

Note that this module will not begin running until a valid chem file has been selected and the Accept All Current Values button is pushed.

To display nonvertical boreholes, the only requirement is that samples from any given borehole have the same location name, with the actual coordinates of each sampling location. The Data Component slider allows the user to select which of the property values in a .csv file will be displayed by Map Spheres. For example, when reading CPT data the user may choose either tip resistance, sleeve friction or friction ratio using the slider. When reading contaminant data the user may choose among the various contaminants listed in the file. The default value is 0, which selects the first value of 15 that can be present in the file. When reading .geo files, the data for all of the geologic layer tops will be read and displayed when the module is executed. When the Data Component slider is set to 1 for .geo files, the tubes and spheres will be colored by the geologic material color ID specified in the .geo or .gmf file.. Note that this module will not begin running until a valid input file has been selected and the Accept All Current Values button is pushed.

The Interpolation slider performs a linear interpolation between two consecutive data components The selected data component is considered as the first and the next consecutive data column in the .csv file is second. For example, if the data component slider is set to 0, an interpolation slider setting of 0.25 would produce a value one-quarter of the way between data component #0 and data component #1.

Module Parameter Subpanels

Map Spheres has three subpanels, which allow the user to set the parameters used for data processing the input data, to specify the type of connector to be used to represent a boring, and to specify the types of labeling that will be displayed. Clicking on either the check boxes next to the subpanel names, or on the names themselves will bring up the subpanel parameter screens. Note that the subpanels must be closed by clicking on the box in the Module Control Panel. They cannot be closed by double clicking on the subpanel's window control icon (the small horizontal bar in the upper left corner of the window).

$image\sphprp.jpg$

The Data Processing Parameters subpanel is shown in the figure above. It is important to note that all data processing actions are applied directly to the data in memory, and that the original data file is not altered. Because Map Spheres only outputs a data field to Generate Axes, or a geometry to the viewer, the data processing within Map Spheres applies only to the Sample indicators or tube coloring in the display. When setting data processing parameters in Map Spheres, the user should refer back to the preprocessing and/or postprocessing parameters set in any other modules that will contribute to the final display to assure that consistent parameters are being used (i.e., to correctly specify whether the data has been log transformed, scaled, and/or clipped). This is particularly important when a color scale is being used to display parameter value distributions on an isosurface and spheres in the same display.

The Data Processing Options radio buttons (below and to the right of the Explode Distance input field) allow the user to specify whether the data will be used as is, or will be processed to compute the log base 10 of the parameter value before kriging. This parameter should be set to be consistent with the data processing that is being performed by the kriging or other modules that are contributing to the display.

The number entered into the Clip Min input field will be used during data processing to replace any sample property value that is less than the specified number. The default value for Clip Min is 0.001, but the user can enter any number. The number entered into the Clip Max input field will be used during preprocessing to replace any nodal property value that is greater than the specified number. The default value for Clip Max is 1000000.00, but the user can enter any number less than your data maximum to adjust the color mapping by clamping.

The Reset MinMax to Above Values toggle uses the Clip Min and Clip Max values to set clamping and to reset the Min and Max values used for coloring. This allows multiple datasets or data measured at different times to have exactly the same datamaps for coloring.

This is accomplished by adding 2 invisible spheres (having zero radius) to your dataset located inside of one of the existing points. This can create a problem if the output of Map_Spheres is connected to other modules such as glyph. It this case we recommend NOT using this toggle and using the set_minmax module between Map_Spheres and glyph.

Note that setting the clip max outside your data maximum will not shift the datamapping outside your data range unless the above toggle is on.

Note that if the log10 of the data is taken, the Clip Min value must be used to replace any zero values in the data with a specified Clip Min value that is greater than zero, to eliminate possible errors associated with attempting to take the log of 0 or negative number (which is undefined). If duplicate data values exist in .csv files (data points with exact X, Y, and Z coordinates), these values are averaged to produce one data point for each unique coordinate.

The Det. Limit refers to the detection limit used when creating the input file. Any non-detect flag in the file (please see the help file for the file type being read in for a list of non-detect flags) will be replaced by the Det. Limit value.

The LT mult field is used to input the Less Than Multiplier. This value is used whenever the '<' character preceeds a file value. The file value will be replaced by the product of the file value and the LT multiplier.

The Rmin / Rmax input fields are used to specify the minimum and maximum radii of the spheres (or other sample indicators in user units), that will be used to scale the sample indicators to the value of the property being represented. The scaling procedure considers the extent in X-Y of the domain of the .CSV file being read by Map_Spheres, to produce sample indicators that are easily seen on the display. If the X-Y domain is less than 100 user units, than the Rmin and Rmax parameters specify the actual radii of the sample indicators in user units. If the X-Y domain is greater than 100 user units, then Rmin and Rmax specify the radius of the sample indicators as a percentage of the total extent of the domain. As an example, if the X-Y domain in the .CSV file is 100 feet, than Rmin and Rmax values of 10 will produce sample indicators that have a constant 10 foot radius. If the domain is 1000 feet, than Rmin and Rmax values of 10 will produce sample indicators that are 100 feet in radius. The default values for Rmin and Rmax are both 1.0. If different values are specified for Rmin and Rmax, then the sample indicators will be sized according to the data values which are normalized to a scale ranging between Rmin and Rmax units (either in user units, or a percentage of the total X-Y domain extent as described above). The user can specify any values for Rmin and Rmax that provide the display desired. When posting geophysical logs or CPT logs (with csv files), the Rmin and Rmax are commonly adjusted to different values to display the relative magnitude of the deflections along the borehole trace.

The Zscale parameter specifies a multiplier by which all Z coordinate values in the data input set will be multiplied before displaying. This parameter is used to incorporate vertical exaggeration into the display, and should match the scaling parameters used in other modules that will contribute to the display. The default value of Zscale is 5, but the user can enter any value that will provide the display desired. Note that if the right port of Map Spheres is being connected to Explode and Scale, the Zscale parameter is overridden by the Z Exaggeration factor being passed to Map Spheres from Explode and Scale.

The Top parameter specifies the elevation at which all tops of the sphere connectors will be uniformly placed. Note that if the boring top elevations are specified in the .csv file, then this parameter is not used, and the sphere connectors will be placed at the actual top surface of the model. A discussion of how to use either depths or elevations for the top coordinates of boreholes is provided in the csv file format section of the Help System. However, if the site has relatively little topography, and the user wishes to quickly prepare a display with posted sample indicators and borings, then this parameter can be used to set a uniform top elevation for all borings. The default value is 0, which will work well with .csv files that only specify the depth to each sample. The user can use any value for Top that will provide the display desired.

The Explode Distance parameter (This feature available only in EVS PRO and MVS) specifies the distance in user units that the sample indicators (and connectors) will be exploded at geologic layer boundaries supplied by Krig_3D_Geology. Note that if the second port of Map_Spheres is connected to the Explode and Scale module, then the explode distance will be passed to Map Spheres. It can be overridden by entering a different value for the Explode Distance in this panel if there is no connection.

The Extents Display Options radio box provides a means to subset the display of your sample data. The default is all which will display all of your data. When Rectangular Region (shown above) is selected four type-in fields become visible and can be used to specify a rectangular region within which data will be displayed. Similarly, Circular region causes three type-in fields to become visible and can be used to specify a circular region (x-y center and radius) within which data will be displayed.

The Indicator Display Options radio box also provides a means to subset the display of your sample data. The default is all which will display all of your data. The other options define range domains within which data will be displayed. Note that these ranges apply to the only the sample results and should not be confused with the range of data extents (coordinates) which are adjusted using the Extents Display Options.

The Data Extents display at the bottom provides a display of the extents of the entire dataset.

$image\sphcon.jpg$

The Sphere Connectors subpanel is shown in the figure above. It provides means to specify the Sample Indicator and the Type of Connection via radio buttons which allow the user to select: Spheres, Squares, Hexagons, or None for glyphs located at each sample location, and whether: Tubes, Colored Tubes, Wires, or None will specify the items in the display to connect the posted indicators, or whether no connection will be used. Note that for large and/or tightly spaced (downhole) data sets, the spheres should be turned off, and only colored tubes should be used. See the Module Hints at the end of this help section for more details.

NOTE: The non-sort toggle is currently functional, but unsupported. One requirement with the non-sort is that the CSV file must contain a "name" column and a "top" column, or a crash will result.

The Tube Ratio parameter sets the ratio of the radius of the tube to the radius of the spheres. For example, if Rmin of the spheres is 8, and the Tube Ratio is set to 0.5, then the tube radius displayed will be 4 user units. The default value of 0.4 generally produces good results, but the user can input any value from 0 to 1. The Number of Faces parameter applies only to Tube connectors, and specifies the type of geometry that will be displayed. The default Number of Faces is 8, which produces a fairly smooth sided cylinder. If a value of 3 was used, then the connectors would represent a triangular tube. This value should also be adjusted when trying to reduce memory overhead during processing. See the Module Hints at the end of this help section for more details.

The Tube Scale Distance parameter specifies the length (in user units) along the tube at which the tube will be displayed with contrasting colors. This parameter allows a direct indication of depth down the tube to be displayed. The default value of 10 gives the tube alternating colors in 10 user units increments, but any user convenient value can be input by the user. The Tube Scale Contrast parameter specifies the change in hue of the tube between alternate scale distances. The default value of 0.5 produces tubes which alternate from gray to black at the specified scale distances. A Tube Scale Contrast of 1 will produce colors which alternate from light gray to dark gray, and a value of 0 will make the entire tube medium gray.

$image\sphlab.jpg$

The Labeling Parameters subpanel is shown in the figure above. This panel allows the user to specify which types of information will be displayed as labels at each boring and sample location. The current labeling parameters that have been set are listed along the bottom of the subpanel. The Type of Labeling push buttons are used to specify which information will be displayed next to the boring or sphere. Each button specifies a certain type of value that will be displayed. The top row of buttons provide the type of coordinate information to be displayed. The default value is to display the well name next to the top of the boring location, but the X, Y, or Z coordinates (and combinations thereof) can also be displayed at the top of the borehole or next to the spheres. The first two buttons on the bottom row specify whether the property value, or the Log 10 of the property value will be displayed. Note that the property values displayed do not reflect any clipping that was done on the data. The Well button displays the well name at the Top of the boring (the default). The W+V button displays the Well Name at the top of the boring, and the Value of the property next to each sphere.

For more information on Font Selection Click Here.

Because all of EVS's displays are in three dimensional space, the user has to specify which plane the label text strings will be written onto, what direction they will be written, and the justification to be used to allow the text to be viewed correctly from a given perspective. The justification push buttons are used to set the location of the label relative to the center of the sphere to be labeled. The layout of these push buttons corresponds to the location of the sphere relative to the label location. The label can exist in any of nine locations relative to the sphere. For example:

- Selecting MC (middle center) the center of the label is placed directly over the center of the sphere.

- Selecting UC (upper center) places the center of the label directly below the center of the sphere (sphere is above the center of the label).

- Selecting LL (lower left) places the left end of the label just above the center of the sphere.

- Selecting MR (middle right) places the right end of the label directly to the left of the center of the sphere.

The other justification push buttons act in a similar manner.

The Label Plane push buttons define which plane the label is to reside in. There are 6 possible planes which correspond to the six faces of a box. The label planes are defined as being parallel to the axes listed in the push button name. The order of the axes in the plane names define the side from which the plane is viewed. For example, the XY label plane will produce labels in a plane parallel to the X and Y axes that can be viewed correctly from a viewpoint along the positive Z axis (the normal vector in a right handed coordinate system). The YX label plane will produce labels in the XY plane that can be viewed correctly from a viewpoint along the negative Z axis. Again, the order of the axis listing determines whether a label is forward and right side up when viewed from the negative or positive end of the third axis, relative to a right handed coordinate system.

The Orientation Within Plane buttons define which axis the labels should parallel within the label plane. Within any given label plane, there are four possible label orientations. For example, in the XZ plane the labels can be parallel to the +X, +Z, -X or -Z axis. A +X orientation will cause the labels to parallel the +X axis in the XZ plane and read from left to right, right side up when viewed from along the +Y axis. A -X orientation creates labels parallel to the -X axis in the XZ plane, which, when viewed from along the +Y axis, will appear upside down.

The orientation of the label also affects how the Justification push buttons affect the label. As was described above, the Justification push buttons move the text around a label box relative to the center of the sphere. The label string can be thought of being contained in a box that is oriented parallel to the Orientation Within Plane push button selection. Therefore, if +Z orientation is chosen, the UC justification location appears to move the label to the middle left of the tick mark in Cartesian coordinates, when viewed normal to the XZ plane. The LL will appear to move the label to the lower right of the tick mark when viewed normal to the XZ plane.

The user will need to experiment with the values of Label Plane, Justification, and Orientation to obtain the label justification desired. The best way to understand the effects of setting different Label Planes and Orientations with the planes is to experiment with posting a set of axes using the Generate Axes module along with Map Spheres, and trying different settings for the labels.

The Label Height parameter allows the user to specify the height of the label in user units. The default value is one, but any value between 0 and 5 can be selected.

The Angle parameter specifies the radial angle that the label justification point will be positioned at a distance of R Offset (see below) in the Label Plane. An angle of 0 places the label directly to the right of the sphere, and an angle of 90 places the label justification point directly above the sphere.

The R Offset parameter specifies the radial distance, in user units, in the Label Plane, that the label justification point will be offset from the sphere position. The Z Offset parameter specifies the distance, in user units, that the label string will be placed away from the central Z coordinate of the Sphere. Note that an appropriate value for this parameter should be greater than the Sphere Rmax value chosen, or else the label will appear within the sphere.

The Precision parameter specifies the number of decimal places that will be displayed in the label

The X Blank and Y Blank parameters specify the X and Y distances that must exist between adjacent labels, or else only the greatest of the overlapping labels will be posted. This parameter allows the user to avoid having many overlapping labels that are unreadable in the display.

The Gray parameter specifies what shade of gray will be used for the text of the label. A value of the default value of 128 produces a gray label, a value of 0 produces a black label, and a value of 256 produces a white label. The font specifies which of 6 available fonts will be used for the label text.

Interactive Querying of Your Data

$image\map_spheres_boring.jpg$

Map_Spheres allows you to probe any sphere (.csv, .geo, .pgf files) and determine information about that sample and its borehole ID. To probe a sample (spheres must be on), click on it with the Alt key and Left Mouse Button. The following window will appear in the upper right hand corner of your desktop.

X (Easting)

Y (Northing)

Z (Elevation)

Concentration (Attrib)

Radius

Further explanations of the various parameter settings and their effects on the visualization are presented in Workbook2.

Map_Spheres Module Hints

Using Map_Spheres with .geo files

When using Map Spheres to post lithologic layer data (.geo files), the user must NOT connect to/from Explode and Scale. This is due to competing functionality for posting chemical data with the exploded layers from Krig 3D Geology. Therefore if viewing lithologic layer data (.geo files), the user must simply read the .geo file on a path parallel to the Krig 3D Geology module, and then send that data to the viewer. The parallel network containing Krig 3D Geology and Explode and Scale MUST have explode distance set to 0.0.

The .geo files read into Map Spheres MUST contain boring names.

Using Map_Spheres with geophysical logs in .csv files

When using Map Spheres to post tightly spaced downhole data such as geophysical logs, the user must turn Sample Indicators to None and Sample Connectors to Color Tubes. The Tube Ratio may be adjusted, but the output is directly related to the Rmin and Rmax values chosen in the Data Processing Parameters.

Map_Sphere's "Sphere Connector" panel also has a parameter that is "Number of Faces". This is how many sides the "cylindrical" tubes have. The default is 8 meaning that the tubes are actually octagonal. To keep the memory overhead of large files down, try setting it to a lower number such as:

2 gives a flat planar strip which is oriented in the "X-Z" plane

3 gives triangular tubes

4 gives square tubes, etc.