Working with Geosoft Maps

Views and Groups

A Geosoft map is a document that is designed to hold spatially referenced graphical information.  A map represents “sheet of paper”, that when printed, is a true map.  Everything that you see on a map is drawn in a map View, which is fundamentally a coordinate system that is located somewhere on the map drawing area.  A map may contain any number of Views, each with its own coordinate system and located as required.  Views normally represent a 2D coordinate system, but may also represent a 3D coordinate system (version 5.1.2 and later).

Graphics features that are drawn in a map View are placed in named Groups.  For example, contours may be drawn in a “Contour” group, survey locations may be drawn in a “Survey” group, and images are each placed in their own group.  Organizing graphical information into groups allows us to deal conveniently with certain types of information.  For example, by selecting an image group we are able to bring up an image manipulation tool; by selecting a flight-line plan we can activate a direct database line link; or by selecting a graphics group we can edit graphic features in the group.

3D Views also contain groups, but groups in a 3D View must be drawn on a specific Plane within the view.  3D Views may contain any number of drawing planes, and each plane may be oriented independently in space and have a relief surface defined by a relief grid.

Base and Data Views

Most standard maps created by Geosoft applications will have at least two views – a Base view and a Data view.  The Base Viewuses the paper coordinates, with the origin in the bottom left corner, and the units of measure is mm, and the Data View normally uses the default ground coordinate system of the project, which is most often a projected coordinate system.  In some cases the Data view may use an arbitrary coordinate system in which the “X” and “Y” scales are different, which would be the case when plotting an X-Y graph of a function or data distribution.

It is possible to attach a coordinate map projection to a view. The view then becomes “aware” of data in other projections. This extremely powerful mechanism allows images created with one projection to be rendered in the view’s projection automatically, without the intervention of the user.  Similarly, links between different maps and databases are aware of projections, and make any necessary conversions so that the cursor positions are consistent between maps and data.

Opening and Locking Maps

As with databases, a distinction exists between the edited map object (EMAP), and the map object itself (MAP). An EMAP is a handle to a map already open in Oasis montaj, and under the control of the Oasis montaj interface.  Through EMAP, you can obtain information about how the map is displayed and you can control user interface features, such as getting the current cursor position, determining the currently selected view, or requesting the user to draw a polygon on a map. 

To make changes to the map requires you to get a MAP handle, which is a two step process:

EMap = Current_EMAP();
Map  = Lock_EMAP(EMap);

While you have the MAP handle, you cannot use any EMAP functions.  On completion of the GX, or when you need to use EMAP functions, the map can be released:

UnLock_EMAP(EMap);

This allows Oasis montaj to update the map as it is displayed to the user.

Accessing Views

Whether you work with the Base view, Data view or some other view depends on the type of operation to be performed.  Annotations such as labels, title blocks, legends, scale bars are usually done in the Base view, while geographically located objects, such as postings, images, symbols, are drawn in the Data view. Access to a view is obtained with a call to Create_MVIEW, as in the following example:

View = Create_MVIEW(Map,"*Data",MVIEW_WRITEOLD);

Often maps contain more than one view for drawing data..  The “*” in “*Data” means that you want to access the currently selected data drawing view, which is the last view selected by the user, but never the “Base” view.  

The MVIEW_WRITEOLD opens the view so you can to the existing view.  Specifying MVIEW_WRITENEW will create a new view (replacing an view if it already exists), and MVIEW_READ lets you read from a view.  When creating a new view, the coordinate system will be in millimetres relative to the map sheet, which is the same as the Base view.  Use the MVIEW coordinate scaling functions to establish a coordinate system for a view (TranScale_MVIEW, SetWindow_MVIEW, FitWindow_MVIEW, ScaleWindow_MVIEW).

Starting a Drawing Group

A group is collection of related objects plotted in a view.  Each group in a view has a unique name. Individual groups are normally created for things like images, sets of symbols, line paths and annotations. It is recommended that you create a new group each time you add a distinctive “feature” to the map. Because groups may be conveniently selected as a whole, operations such as moving, hiding or changing particular plotting attributes may be easily applied to all items in the selected group or groups in a single operation.

Although groups may be named arbitrarily, each group in a view must have a unique name.  When Geosoft applications create groups, we normally place a type prefix at the beginning of the name:

TYPE_my_name

Where:

Groups derived from a database will usually include the database name, and possible channel in the group name.  For example, an ITR-based (colours based on data value ranges) symbol plot produced from the database “chem.gdb”, produced from selected values from the channel Ag, would be named “CSYMB_chem_Ag”. Methods have been created to automate this procedure. The naming process and group creation process is illustrated in the following posting example:

GetName_DB(Data,DB_NAME_FILE,sDB);              // Get database name
FileNamePart_STR(sDB,sDB,STR_FILE_PART_NAME);   // Get root name of database
GenGroupName_STR("POST",sDB,sChan,sGroup);      // Make a group name
StartGroup_MVIEW(View,sGroup,MVIEW_GROUP_NEW);  // Start the group

Setting Drawing Group Attributes

Group Attributes are drawing attributes that describe how to draw things in a group.  A new group has default attribute values, and normally you will want to reset some yourself, using the appropriate MVIEW functions. There are no fewer than 24 attributes currently defined for map objects, and more may be added in the future. These are listed in the following table, along with default values, and the function to call to change the value. Note that linear dimensions are always specified in the coordinates of the view, which may be ground units in the case of a “Data” view.  For example, if the view unit is metres, then setting the font size to 1.0 would mean that the text height would be 1 metre according to the view scale. Angles are measured in degrees, counter clockwise from the X-Axis.

Drawing Groups in a 3D View

In a 3D view, the StartGroup_MVIEW will create a new group on the default drawing plane, which will normally be the last plane created.  You can change the default drawing plane to a different existing plane by calling SetDefPlane_MVIEW.

If you apply a 3DN to a view that already contains groups, the groups will not have an assigned plane, and will not appear in the 3D view.  You should create a drawing plane as required and call SetAllNewGroupsToPlane_MVIEW to place the unassigned groups on the new plane.

Groups drawn in 3D vies cannot be edited.  It is common to let your user create what they want to see in 3D on a 2D View first so that they can edit the material before it is placed in 3D.  Refer to the V3DIMG GX for an illustration of how to do this.

After you have created a 3D view, you can activate the 3D viewer to allow your user to manipulate the view right away.   To do this, call ActivateView_EMAP after unlocking the map.

Adding an Image to a Map

Image data is handled using the AGG class. Images may have one or more layers, and the brightness and colour sequence of layers may be altered using the AGG class functions. Below is an example, adapted from the GRIDIMG1 GX, of how to place an image of a grid into a map. Remember that the grid name requires whatever file type decorations are necessary to identify its format for the call to LayerIMG_AGG. (See the FEDIT examples in the GRC Resources and Dialogs section of Part 1.)

// --- create aggregate ---
 
Agg = Create_AGG();
 
// --- add grid to the AGG ---
 
Progress_SYS(1);
ProgName_SYS("Layer",1);
LayerIMG_AGG(Agg,sGrid,0,sColor,rDUMMY);
Progress_SYS(0);
 
// --- open the current data view ---
 
View = Create_MVIEW(Map,"*Data",MVIEW_WRITEOLD);
 
// --- create a group name for the AGG, using the grid name without decorations ---
 
Strcpy_STR(sAgg,"AGG_");
FileNamePart_STR(sGrid,sGrid,STR_FILE_PART_NAME);
ToLower_STR(sGrid);
Strcat_STR(sAgg,sGrid);
 
// --- put the AGG in the view ---
 
Aggregate_MVIEW(View,Agg,sAgg);

Clipping Objects in a View

Each view contains a “poly-polygon” object (PLY) which specifies the area or areas where plotting is to occur. Initially, when a view is created, this PLY is not defined and no clipping occurs. Both inclusive and exclusive PLY objects can be created (and individual polygons in the PLY object can be of either type). Once a clipping PLY is added to the view, clipping can be turned on or off for individual groups within the view. Whether clipping is applied to a new group when it is created can be controlled using the GroupClipMode_MVIEW function. The following is an example, adapted from the TINVORONOI GX, of how a clipping region is defined and added to a view, and how the clipping may be applied to a group. In this case, the Voronoi cells of a Triangular Irregular Network (TIN) are plotted, and the user can specify whether to clip the cells to the outside boundary (convex hull) of the nodes:

// --- Get the Voronoi Cell edges (returned as line segments) ---
 
VVv = Create_VV(-32,0);    // sizeof(GS_D2LINE)
GetVoronoiEdges_TIN(Tin, VVv);
 
// --- Get the Convex Hull ---
 
Ply = Create_PLY();
GetConvexHull_TIN(Tin, Ply);
 
VVx = CreateExt_VV(GS_DOUBLE, 0);
VVy = CreateExt_VV(GS_DOUBLE, 0);
 
GetPolygon_PLY(Ply, VVx, VVy, 0);
 
// --- open the data view ---
 
View = Create_MVIEW(Map,"*Data",MVIEW_WRITEOLD);
 
Progress_SYS(1);
 
if(iClip) GroupClipMode_MVIEW(View, CLIP_ON);
 
// --- create path group ---
 
StartGroup_MVIEW(View,"Voronoi_Cells",MVIEW_GROUP_NEW);
 
// --- set line characteristics ---
 
LineColor_MVIEW(View,iColor_MVIEW(sLineColor));
LineThick_MVIEW(View,rThickness*rScale);
LineStyle_MVIEW(View,0,0.0);
 
// --- Set the view"™s clipping PLY ---
 
if(iClip) SetClipPLY_MVIEW(View, Ply);
 
// --- Plot the Voronoi Cells ---
 
LineVV_MVIEW(View, VVv);
 
// --- Turn off clipping for subsequent plotting ---
 
if(iClip) GroupClipMode_MVIEW(View, CLIP_OFF);

To set clipping for one or more groups that already exist, use the MarkGroup_MVIEW function to select the groups, and then call the ClipMarkedGroups_MVIEW function.

Version 6.0. introduced group based clipping that allows multiple clipping PLYs masks to be added to a view. These masks are named by using a text description or identifier and can be assigned to one or more groups in the view. The following functions manipulates and sets this inside a view:

A “maker” is information added to the group, which allows the user to recreate the group, using the same process which created it initially. For instance, the following maker is created in the POST GX:

Maker_MVIEW(View,1,1,"POST",MAKER_GX,"Posting...","POST;");

This maker indicates that both a map and database are required, that the POST GX was run, and that the “POST” settings from the workspace parameter block are required. When the user selects this group and brings up the right mouse-button menu, the item “Posting...” appears at the bottom, and by selecting it the POST GX will be run again, allowing the user to alter settings.

Working with 3D Views

A 3D View represents a 3D coordinate system and were introduced in version 5.1.2.  3D views may contain one or more drawing “planes”, on which normal 2D drawing can take place.  A drawing plane represents a 2D coordinate system oriented in the 3D space of the 3D view.  The drawing plane surface may be flat, or it may have relief defined by grid, which defined the relief in the plane’s Z axis direction.

3D views are created from 2D views by providing a 3D viewing object called an 3DN.  To create a 3D view, first create a 2D view, establish the 2D coordinate system of the view (this will represent the X,Y axis of the 3D coordinate system), create a 3DN that defines the starting 3D viewing parameters, and apply the 3DN to the view:

   // --- create and scale a 2D view ---
 
   View = Create_MVIEW(Map,s3DView,MVIEW_WRITENEW);
   TranScale_MVIEW(450000.0,6000000.0,10.0,10.0);
 
   // --- create a 3DN ---
 
   h3DN = Create_3DN();
   SetPointOfView_3DN(h3DN,6.0,20.0,25.0);
   SetRenderControls_3DN(h3DN,TRUE,FALSE,"X","Y","Z");
 
   // --- apply the 3DN to the 2D view ---
 
   SetH3DN_MVIEW(View,h3DN);

Now that the view is a 3D view, it must be located on the map using FitMapWindow3D_MVIEW.  By locating a 3D view on a map, we make the view appear to be a 2D view for any functions that need to work with the view in 2D.  For example, a 3D view can be selected, moved and resized on a 2D map just like any other 2D view. 

In the following example, we have previously determined a location and data range that we would like to fit.  The data range is not really important, but we normally choose a range that is similar to the X,Y range of the 3D view:

   // --- locate the 3D view on the map ---
   FitMapWindow_MVIEW(View,
                      rMinX,rMinY,rMaxX,rMaxY,
                      rDminX,rDminY,rDmaxX,rDmaxY);

Before drawing to the 3D view, we must create a drawing plane.  It is then oriented with respect to the 3D coordinate system by specifying:

1.      The pitch (rotation around X), yaw (rotation around Y) and roll (rotation around Z) of the new plane surface relative to the 3D coordinates system of the 3D view.

2.      The X, Y and Z offset of the plane origin relative to the origin of the 3D view.

3.      The X, Y and Z axis scale of the plane surface relative to the Plane coordinate system.

Examples:

   // --- Create an X-Y drawing plane on the X-Y axis of the view ---
 
   iPlane = iCreatePlane_MVIEW(View,"X-Y");
   SetPlaneEquation_MVIEW(View,iPlane,
                          0.0,0.0,0.0,   // no rotation
                          0.0,0.0,0.0,   // no offset
                          1.0,1.0,1.0);  // unit scaling
 
 
   // --- Create an Y-Z drawing plane offset 100 units in X ---
 
   iPlane = iCreatePlane_MVIEW(View,"Y-Z");
   SetPlaneEquation_MVIEW(View,iPlane,
                          0.0,90.0,0.0,  // Y-Z plane
                          100.0,0.0,0.0, // offset 100 units in X
                          1.0,1.0,1.0);  // unit scaling
 

If you would like the plane to have a relief surface, this can be established from any grid file that registers within the plane 2D coordinate system.  You specify the grid file, then the relief parameters:

   // --- use an SDTS DEM to define surface relief ---
 
   SetPlaneSurface_MVIEW(View,iPlane,"topo.sdt(SDT)");
 
 
   // ---
   // Apply 2x vertical exaggeration and remove 150m base.  Sample
   // the grid to produce a 400x400 resolution relief surface.
   // ---
 
   SetPlaneSurfInfo_MVIEW(View,iPlane,400,
                          150.0,2.0,rDUMMY,rDUMMY);

Now you can create new groups and draw to this plane using the normal 2D drawing commands in MVIEW.  Anything that can be drawn on normal 2D view can be drawn on a plane in a 3D view.