BGMEditor

Author

Gorton, Bec (Environment, Hobart)

Overview and Rationale

Note: this tool should be phased out in favour of the yet-to-be-developed BGM Editor, but for existing geometry information developed within ArcGIS it is a useful transformation tool. The reason this is not in fact the optimum solution is because shp files are not topological, and do not preserve face information.

The old rationale: It is proposed (read: Mark and Mike have been discussing it and think it’s a good idea) that all Atlantis geometry creation occurs within a shp-file editor such as ArcGIS. This enables all coordinates to be set, boxes to be labeled, bathymetry embedded – all in a single format, which can then be exported in a single one-way operation to a box-model (bgm) file. By making the bgm file effectively read-only, the process can be streamlined somewhat and the risk of data-loss or error by having multiple different data sources in different formats that must be reconciled at different points is reduced. Note: we’d still like a single data source, but due to the lack of topology in a shp file this will be the bgm file itself, once the editor is functional.

The bgmeriser is a simple command-line tool written in java to do this transformation.

Installing Java

To use the BGMeriser you need to have Java installed on your machine. Follow the instructions on the JAVA wesbite - http://www.java.com/en/download/manual.jsp?locale=en

Usage

The tool is distributed as a single self-contained executable jar file. It must be invoked on the command line as java -jar bgmeriser.jar. When invoked with no arguments it will display a usage string:

$ java -jar bgmeriser.jar
Usage: bgmeriser -from projection -to projection shpFile [bgmFile]
   or: bgmeriser -as projection shpFile [bgmFile]

    bgmFile is optional; if omitted, it defaults to the same name as the shape
    file, with 'bgm' appended (also appending digits if necessary to create a
    unique name).

    The projections may be specified as either a numeric EPSG code
    or a proj4 string.  If the source is not specified then easting/northing
    is assumed and converted to the destination projection; likewise if only
    the source is specified it is converted from that to easting/northing.  If
    both are needed, they may be specified in either order.  Note that if you
    use the proj4 format you will need to put quotes around it, for example
    "proj=latlon ellps=wgs84"

    In the second form, no reprojection is done, but the nominated projection
    is specified in the output bgm file.

Both forms will convert the specified shp file to a bgm file. The former will also do re-projection; either from a lon-lat projection to easting/northing, or from easting/northing to lon-lat, depending on whether -from or -to is specified. Ifboth{{-from}} and -to are specified it will convert between the two projections, via the easting/northing form (note that this may have implications on accuracy due to floating-point issues).

In the second form no re-projection is done at all, but you must still nominate a projection that will be specified in the bgm file.

If you do not specify the output file name, it will use the same base-name with the “.bgm” extension (which is probably what you want); it will also not over-write an existing file of the same name. That is, both of these are equivalent (assuming you don’t already have a file called “geometry.bgm”):

$ java -jar bgmeriser.jar -as 4326 geometry.shp geometry.bgm

and

$ java -jar bgmeriser.jar -as 4326 geometry.shp

The second time you run the latter command you will get an output file called “geometry-1.bgm”, followed by “geometry-2.bgm”, etc. The former will complain and quit if it’s asked to over-write anything.

Projection information

The box-model format requires a description of the coordinate-reference system used, in PROJ.4 format. For a few reasons it is not currently feasible to extract this from the shp file generated by ArcGIS, so it must be specified manually as an extra argument to the tool. You specify it using either the “-as” argument, or one of the conversion forms described above; it can be specified either as an EPSG code (either the number or something like “EPSG4326”), or just the literal proj string. The following are both equivalent:

$ java -jar bgmeriser.jar -as 4326 geometry.shp
$ java -jar bgmeriser.jar -as "+proj=longlat +ellps=WGS84 +datum=WGS84 +no_defs" geometry.shp

Note the need to have quotes around the proj string. Talk to Mike Fuller if you need a proj string to use for your shp file.

Also a useful site for projection info is: http://www.spatialreference.org/
You can paste in a time zone string (e.g. “NAD_1983_UTM_Zone_10N”) into search and (if it finds it) the page will return a list of formats for the projection type.

Shape File Requirements

Important: Some shp files seem to cause problems for the parser used in the code; if this is a problem (ie, if the tool aborts with errors that aren’t due to missing attributes, described below), try saving the file again using ArcGIS 3, or see your friendly local data guru to see if they can clean it up.

In order to do a successful conversion, the shp file you create must adhere to a few conventions: - Each box must have a “box_id” integer attribute, which must be consecutively numbered, starting from 0. The absence of this attribute, or any gaps in the numbering, cause the transformation to abort. - Each box must have a “boundary” integer attribute. This should be set to 1 for every boundary box, and 0 otherwise. The absence of this attribute will cause the transformation to abort. It will also abort if box 0 is not marked as a boundary box, or if box 1 is marked as a boundary box. Note: the tool does not at the moment attempt to verify that a boundary box is in fact on the boundary. - Each box must have a botz float attribute, which will be used in the bathymetry. It may be either negative or positive, but will always be converted to negative. It will also accept “depth” if botz is not found. - Each box can (read: “should”) have a “vertmix” numeric attribute. If it is not present NaN will be used and you will have to add it correct it manually later. - Each box can (read: “should”) have a “horizmix” numeric attribute. If it is not present NaN will be used and you will have to add it correct it manually later. - Islands should be represented as boxes with a depth of 0, not as empty regions. The conversion will abort if islands are detected.

All attribute checks are case-insensitive (ie, “boundary”, “Boundary”, and “BOUNDARY” will all work).

Shapefile Topology Management

Using GRASS-GIS for cleaning problem shapefiles.

Sometimes snapping is not enough to ensure the shapefile is topologically correct enough for the BGMeriser (ArcGIS snapping appears to not always snap all vertices resulting in dirty geometry). Problem shapefiles can be cleaned by loading them into GRASS and using the load tolerances to make sure adjacent polygon boundaries are coincident. This can be done in GRASS or QGIS-GRASS. Other cleaning options are also available in GRASS (but have not yet been explored). A rule of thumb for the snapping distance is less than 1/2 of the smallest arc segment in any box face, or gap between box boundaries. Any larger than this may result in unintended consequences (boxes may collapse as adjacent faces are merged). Always check the resulting output. Box numbers should remain the same before and after cleaning.

There are detailed instructions here -Using QGIS to clean Atlantis BGM Shapefiles

*****Editing QGIS 1.7.0******Enable snapping* Settings > Snapping Options > Enable Layer and set tolerance, and enable topological editing
Works OK - Beware of changes in the tolerance as it appears to snap to the coordinate system not layer features.

Additional notes:

Check the GRASS and QGIS manuals for setting up a GRASS workspace, location and mapset to load and process the shapefiles.

QGIS and GRASS cookbook - http://grass.osgeo.org/wiki/QGIS_GRASS_Cookbook

See:

http://www.geobbs.com/grass64/manuals/html64_user/v.in.ogr.html

http://grass.osgeo.org/gdp/html_grass64/v.clean.html

http://gis.stackexchange.com/questions/10380/how-to-handle-multiple-layers-when-importing-a-polygon-shapefile-into-grass

v.in.ogr -o dsn=/home/ful072/data/temp/BGM.shp  output=BGM_SNAPPED snap=0.01 min_area=0.0001
# Convert back to shapefile

v.out.ogr -c input=BGM_SNAPPED type=area dsn=BGM_SNAPPED.shp

(ESRI topology examples) - The BGM file is a topological model and requires a perfect shapefile for conversion.
The topological model requires (assuming a polygon shapefile is being used) - All arcs of adjacent polygons to be overlapping. Use feature snapping tools in GIS editors. Make sure snapping tolerances are appropriate for the mapping scale of the box model and coordinate system being used (example picture). - Islands need to be connected to their containing polygon. Yes this means you cannot have islands (there is some strong logic why this is the case but it currently escapes me, and the bgmeriser will complain) (example picture). - Currently the only software that correctly checks for and fixes all topology errors is ArcInfo workstation. Let us know if you have an open source package that will check for over and undershoots, donuts etc, and has user definable fuzzy tolerances for cleaning (maybe Grass, or ArcGIS editing or topology tools?) - Cleaning shapefiles - ArcView 3 snapping works very well
ArcInfo workstation - Clean with a very small tolerance to identify slivers (polygons with small area). Edit adjacent polygons to ensure arcs are coincident. - Remove them and re-clean until no slivers occur. A ballpark for the clean tolerance is < 1/2 of the longest arc length. If the number of arcs is very important (you have personally created every one with meaning) keep an eye on them. If they decrease a lot you probably have a clean tolerance too high. They will also disappear if adjacent arcs are being combined. - Avoid unnecessary vertices. e.g. in the middle of box faces remove all vertices with no change in direction if there is no requirement for different flows across the face. Split faces if values need to be partitioned (keep the model simple!)

Typical Topology Errors

Slivers - narrow gaps or overlaps between polygons. Typically caused by very small overlaps and undershoots.
Simple geometry is easy to create, fix errors in geometry and the model runs faster (number of faces has significant impact on runtime).

Overlaps - Polygons have overlapping regions

Error message from BGMeriser:
You appear to have an island in the model; these should be represented by a box with zero depth.

Gaps between polygons.

Error message from BGMeriser:
You appear to have an island in the model; these should be represented by a box with zero depth.

Inside Points not generated

If you have a concave box the inside point may not be correctly calculated.

Warning message from BGMeriser:

You have a box error; the inside point (243677.76085723966, 1475962.447055994 of box 5 is not inside the box. Please hand edit the bgm file. The inside value should be a point within the box.
Creating box model but changes need to be made.

If you see this the BGMeriser will generate inside values that look like the following:

Box number 5

box5.label Box5
box5.inside
box5.nconn 10
box5.iface 178 176 174 172 171 170 41 42 43 40

You will need to hand add inside points - Atlantis will not parse your BGM file unless these values are present.

Caveats: what the tool does not do

There are a few important restrictions on what the bgmeriser can do, apart from those mentioned above such as not checking the accuracy of boundary claims: - It does not currently detect “doughnuts” in the model (ie, interior polygons); these should be fixed with a “split” (extra face) in the enclosing box. - Faces are not guaranteed to be preserved under editing. This is due to shp files not preserving any information about them; the tool just enumerates them itself, which will not necessarily be identical between edits, particularly if boxes are added or removed.

Obtaining, Building, Technical info

You can download the tool from this page.

The source is currently maintained as a branch of the (GUI) BGMEditor tool in the subversion repository, at http://mir.hba.marine.csiro.au/svn/java/geomedit/branches/BGMeriser/ This needs access privileges, so contact Uwe Rosebrock if you don’t have permission. It depends on DMPL, so you will also need to check out dmpl, lib, libui, and javaproj besides bgmeriser. It’s probably still easiest to build it within eclipse, although there is an ant file now. The ant files for the dependencies are a bit clunky though. Ant is required for building the self-contained executable.

Also included is a file “proguard.pro”, which can be used to trim all the unused dmpl (etc) code – currently using this results in an executable size that is a fraction of the original (6.2M compared to 24M), so you probably should! This can also be run from ant using the “compress” target.

Attachments

	File	Modified
	Microsoft Powerpoint 97 Slideshow Welcome to the Box Geometry Model.ppt	Feb 11, 2011 by Fuller, Mike (Environment, Hobart)
	Labels - No labels - Edit Labels Preview [\(itemLabel](\)itemRenderedUrl) [\(itemLabel](\)itemRenderedUrl&isFromPageView=true) [\(itemLabel](\)itemRenderedUrl&isFromPageView=true)
	Java Archive bgmeriser-stripped.jar	Apr 27, 2015 by Gorton, Bec (Environment, Hobart)
	Labels - No labels - Edit Labels Preview [\(itemLabel](\)itemRenderedUrl&isFromPageView=true&isFromPageView=true) [\(itemLabel](\)itemRenderedUrl&isFromPageView=true&isFromPageView=true)
	File bgm_repair_centroid.R	Oct 28, 2021 by Zhao, Zhongfang (Ocean University of China)
	Labels - No labels - Edit Labels Preview [\(itemLabel](\)itemRenderedUrl&isFromPageView=true&isFromPageView=true&isFromPageView=true) [\(itemLabel](\)itemRenderedUrl&isFromPageView=true&isFromPageView=true&isFromPageView=true)

Drag and drop to upload or browse for files

Upload file

File description

Download All