Exploring the XML File Format - Part 2

Last month I gave an overview of the major blocks within GeoStudio’s xml file format.  Today I’m going to dig a little deeper into one of those xml blocks.

I’ll start with the <GeometryItems> section because it’s something all GeoStudio users should be familiar with.  It will demonstrate some guidelines common to the other blocks as well.

<GeometryItems>

The “geometry” of your problem, as we refer to it, is composed of points, lines and regions.  But regions and lines are just collections of points, so let’s look at the <Points> block first.

<Points>

The <Points> block is a collection of <Point>s.  You’ll see this type of xml construct often in our files, as much of the data you define involves collections of objects.

Len=”8″

The first thing to notice is the Len=”8″ in the opening tag, which indicates that there are eight points in this collection.  This is not required in standard xml, but it is required for GeoStudio.  Specifying the size of the list up front allows GeoStudio to read the file more quickly because it knows how much memory to allocate.

ID=”1″

The next thing to point out is that each point has a unique ID.  This ID is what is used elsewhere in the xml to refer to a particular point.  I can’t remember off-hand if the IDs must start at one and be sequential, but since this file format was intended to be written and read by GeoStudio, not by humans, you’d be advised to stick to that rule.

X=”0″ Y=”40″

Now we finally get to the actual definition of the point, which is just an x,y coordinate, in the units you specified in Set Units & Scale (or in the <Coordinates> block of the xml file).

<Mesh>

You should generally leave this alone.  It indicates the version of the mesh generator that was used to generate a mesh.  If you’re generating your own file, just leave this out completely.

<Plane>

I have no clue what this is about!  Anybody else know?!

<Lines>

You can see that Lines are similar to Points in some ways.  There’s that Len=”9″.  There’s the ID.  But why does the <Lines> collection contain <Lines> instead of containing <Line>s?  And why are each of the nine <Lines> a block instead of a single element like the <Point>?  Wouldn’t it be more succinct to say <Line ID=”1″ PointID1=”1″ PointID2=”2″/>?

I wish I knew the answer.  Probably an oversight.  But the problem with publishing a file format is that once it’s out there, it’s very tough to change without breaking old files, so now that’s the way it is.

Both formats are valid xml, but GeoStudio will expect one or the other so always use another gsz file as an example when hand-crafting your own.

And that’s the inside scoop you only get on GrokkingGeoStudio.com!

<PointID1>, <PointID2>

Now we see why it was important for each <Point> to have an ID field.  A line is made up of two points, identified by the point IDs.

Note that the order of the two points does matter in some situations.  While it’s not legal to have two lines with the same points just in a different order, still the order is used when you get into things like interface lines, which allow you to assign a material to one side or the other of the line.

<Regions>

Regions, like lines, are a collection of point IDs.  Only in this case there can be any number of points, so they are presented as a comma-separated list.

A region is always a closed polygon, so it’s implied that the last point in the list connects back to the first point.

The order of the point IDs is obviously important for regions, as they define the region edges.

Interestingly, a region is not a collection of Line IDs.  That used to be the case, but as we’ve begun adding circular regions and lines that don’t belong to regions, that has become too restrictive.  As you work with the user interface you can think of a region as being composed of lines, but in the data file that is not the case.

Summary

So we’ve seen several common themes:  the Len tag, the ID tag, collections of objects.  We’ve seen how some things are done differently:  using a single xml element vs using a block.  And we’ve seen how the ID is used to point to one object from another.

If I write a Part 3 I’ll add to those concepts by digging into a more complicated part of the file.  I’m open to suggestions!