Exploring the XML File Format – Part 2

by Nate Hekman on November 3, 2009

XML File Format Series
1. Exploring the XML File Format
2. Exploring the XML File Format – Part 2
3. Exploring the XML File Format – Part 3 – SLOPE/W

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>

geometryitemspoints
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>

geometryitemslines

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>

geometryitemsregions

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!


{ 9 comments… read them below or add one }

1

Paul Grunau 11.04.09 at 11:07 am

Interesting post, Nate!

The <plane> keyword stores the information defined in the “KeyIn Generate Plan View” command. For example, in the SEEP/W “Relief well spacing” example, you’ll see the following Plane information:

  <Plane>
      <Coordinate1 X="0" Y="0" Z="10" />
      <Coordinate2 X="50" Y="100" Z="10" />
      <Coordinate3 X="50" Y="0" Z="10" />
      <Thickness1>10</Thickness1>
      <Thickness2>10</Thickness2>
      <Thickness3>10</Thickness3>
  </Plane>

In a plan view analysis, the element thickness and nodal z-coordinates can be varied across the domain by defining a planar surface with specific thicknesses and z-coordinates. Whenever the finite element mesh is regenerated, the plane is mapped to the mesh in order to generate the element thicknesses and nodal z-coordinates that are used in the plan view analysis. Note that the plane itself is “infinite”, and therefore the 3 points on the plane do not have to completely enclose the defined domain.

2

Giang 11.08.09 at 4:43 pm

Dear Nate,

Thank you very much for the 1st and 2nd part of XML. I am now working on the module which generates the xml file for geostudio. I surely need your 3rd part.

Giang

3

Nate 11.09.09 at 9:19 am

Hello Giang. Do you have any specific questions I can answer? You can email me back with any questions you have and I’ll try to answer them by email. Then I may use our email conversations to decide what to do as a Part 3 for other readers.

4

hunggeopro6 11.06.10 at 12:23 am

Dear Nate!
Now I try to make Slopew file by VB code! Please send to me Part 3.
Thank so much!

5

Nate 11.15.10 at 3:08 pm

@hunggeopro6 – I’d be happy to, but there are a lot of different parts of the file I could look at–more than I can cover on a blog–so I’d like to focus on just what would be useful to you. I think it would be most helpful if you took a look at the file yourself, started making some of it in VB, and then ask me some specific questions or tell me about one part of the file that you’d like more explanation for.

6

John 12.06.10 at 9:48 am

Would it not be more practical to have the xsd for the file? That way the total file is described at least at content level. And you could add comments about any “external logic” as well.

7

Nate 12.06.10 at 9:54 am

I agree. We don’t actually have an xsd file at the moment, but I’d like to see one added in the future.

8

John 12.10.10 at 5:10 am

Nate, the reason I asked for the XSD is that I would like to write an XML-file from scratch, perform a batch calculation with it (Bishop, using CU-values) and then read the stability result (Safety factor).
Could you tell me:
A) which blocks are realy needed in the XML to do this (I guess I do not have to write the View block for instance)?
B) where I can find the result in the XML? I see there are other (result) files but was wondering whether the result would be in the xml as well.

9

Nate 12.10.10 at 10:36 am

Great questions, John. That gave me enough fodder for Part 3. 🙂

Leave a Comment

You can use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>