SSIArcPolyTopo              from Spatial Solutions Inc.
available through www.spatial-online.com
...clean and build polygons from your ArcView or ArcGIS workstation

Table of Contents Overview

SSIArcPolyTopo produces polygon shape files, and line shape files with left and right polygons, from line shape files, describing the boundaries, and point shape files, linked to the attributes of the polygons. In the process, it will close gaps and eliminate overshoots and sliver polygons within the user specified tolerance. It will always intersect lines, thus dealing with "spaghetti" digitizing.

SSIArcPolyTopo correctly deals with any level of "donuts", that is a polygon, or group of polygons, that are completely contained within a single polygon. These are also referred to as "island" polygons. They can be nested to any level, such as a lake on an island within a larger lake.

SSIArcPolyTopo cleans and builds the polygons in one process. If you wish to clean the lines separately, then build the polygons, this can be done using two other Spatial Solutions products, SSIArcPolyClean and SSIArcPolyBuild. If you do not want the line file with left and right polygons, please see SSIArcPoly.

Return to Table of Contents

Download and Installation Instructions

SSIArcPolyTopo, amongst other ArcView and ArcGIS extensions, can be downloaded and installed for a free trial from www.spatial-online.com. Choose the installation for either ArcView or ArcGIS. Double click on the downloaded file, and an Install Wizard will guide you through the installation.

After installation, the extension will be available through the usual ArcView extension directory or will appear on the menu bar of your ArcMap.

Return to Table of Contents

Run from ArcView

To load the extension into ArcView,

After the extension is loaded, when the View Menu is visible, there will be an ArcPoly option.

Information on the input parameters for SSIArcPolyTopo are provided here.

Instructions on running SSIArcPolyTopo directly from your Avenue script or calling it from C++ code are provided below.

Return to Table of Contents

Run from ArcGIS

After installation, the ArcPoly option will appear next time ArcMap is opened.

Return to Table of Contents

Input Parameters

Beneath the ArcPoly option, the following items will appear:

    Clean and Build Polygons,
    SSIArcPolyTopo Help,
    About SSIArcPolyTopo and
    SSIArcPolyTopo Log File.
SSIArcPolyTopo Help will bring up this help screen. It utilizes EvokeBrowser to evoke the standard browser with SSIArcPolyTopo.htm.

About SSIArcPolyTopo will bring up the registration screen described below if you have not purchased the product, followed by the about screen, also described below.

SSIArcPolyTopo Log File will bring up an information box showing statistics on the last run of SSIArcPolyTopo.

To run SSIArcPolyTopo, make all line shape files that you wish to utilize visible in a view. Also make the point shape file that is linked to the polygon attributes visible, such as shown above. Then choose ArcPoly > Clean and Build Polygons.

If you are running the software in trial mode, the registration screen described below will appear first, then the following screen will appear.

In the first line of the dialog, Line Files, all line files that were visible in your current view will be listed and selected. The ones selected are highlighted. You may toggle the selection by clicking on the name of the file. If it was selected, it will become de-selected. If it was not selected, it will become selected. You may also add new files to the list by clicking the Browse button. Any (ordinary, Z or M) line files can be used. If you browse for a shape file that is not a line file, an error message will appear. Otherwise the file will be added to the list and will be selected.

The second line of the dialog, Point File, provides a list of all the point files that were visible in your current view with the first one selected. Only one point file can be selected. If the point file you wish to use is not in the list, you can click the Browse button on this line. Any (ordinary, Z or M) point files can be used. If you browse for a shape file that is not a point file, an error message will appear. Otherwise the file will be added to the list and will be selected.

Tolerances can be specified by two means. The simplest means is to specify one tolerance. This tolerance, in Map Units is utilized for all cleaning processes. It defaults to 0. All tolerances are specified in Map Units.

Alternately, you can click on the Extended Tolerances button which will bring up the screen described below.

The next four lines on the main window provide default names for the shape files to be built. You may accept the default names or specify new names. The files are:

  • The file to hold the polygons,
  • The file to hold the polygon boundaries,
  • A line file representing lines that are not in the polygon file and were not removed by the cleaning process.
  • A point file with points marking the end of each remaining dangle.

The polygon boundary file will by default be linked to the identifying record number of the polygons on the right and left of the line. Additional attributes can be copied into the line attributes. Click the Attributes button to bring up the screen below.

In the bottom right of the window, below the Attributes button, there are four more buttons:

  • About: This button will provide the About box described below.
  • Help: This button will open this help in your default browser.
  • Process: This button will cause the program to run. Progress will be reported in the progress bar and the message line at the bottom of this window.
  • Cancel: The cancel button can be clicked at any time, either before or after clicking Process.

When the process is complete, the polygons, the boundary lines, and both the unresolved lines and dangle points will be added to the active view.

The polygons will have all of the attributes of the original points. As well as these, an attribute SSITheme will indicate the status of the polygon, that is whether it contains lines that are not part of any polygon (potentially undershoots or overshoots) and whether it contains exactly one point as it should, or either no points or more than one point. The area and the perimeter. in map units, will also be calculated and added to the attributes.

The polygons will be color coded to show their status. Correctly formed polygons, that is those with no inside lines and with exactly one point contained, will be white. Any potential problem will be colored according to the legend using SSITheme. The diagram below shows one polygon without a point, and a second polygon that has some additional lines in ArcView. A similar legend is used in ArcGIS. To find out how to customize this and other SSI legends, please click here.

The lines will have all of the attributes of the original lines if only one input file has been used. If more than one has been used, then attributes of the lines in the file with the most lines will be maintained. Other lines will not have their original attributes. As well as these, an attribute Length will provide the new length of the line in map units.

Overshoots, undershoots and small polygons will be handled as below. Note, they are not removed from the original data, but will not be in the new file.

Return to Table of Contents

Extended Tolerances

When you click the Extended Tolerances button in the main dialog it will bring up the screen below.

The first tolerance, representing an area, is defaulted to the square of the default tolerance on the main screen. The remaining four, representing lengths, are defaulted to the default tolerance. The diagram above would be the result of default tolerance being 5 (rather than the 0 shown in the main dialog above). All tolerances are specified in Map Units. The five cleaning tolerances are:

  • Remove Polygons with Area Less Than: Any polygons with area less than this area measure are simply removed from the map with one exception. If the polygon has a point inside it linked to the database, it will not be removed. These polygons are likely to come from "snap-backs", that is when digitizing, overshooting the meeting line then snapping back to it. Sliver polygons, with larger areas but very narrow, are dealt with in the last tolerance discussed below.
  • Remove Dangles with Length Less Than: Any line which is connected to another line at one end at most, and is less than this in length, will be removed, with one exception. If the line appears to be attempting to join two other lines (See the following Extend Dangle tolerance discussion), then the dangle will be extended rather than removed.
  • Extend Dangles to Join Other Lines to a Maximum Length: Any line which ends within this distance of another line will be joined to the other line. If it ends within the tolerance distance of itself, it will also be joined unless it is considered an aberration as in the next tolerance discussion. Note that in this process, the line to which the dangle is joined can be simultaneously moved within the relevant tolerance. If this line is joining another dangle, both ends can be moved by the Extend Dangle tolerance, resulting in the closing of a gap twice this tolerance. If this dangle is joining the mid-point of a line, that mid-point can also be moved the Merge tolerance discussed below.
  • Remove Small Aberrations of Length Less Than: When digitizing, a final point can be added to a line by accident as the hand is moving to the next line to be digitized, causing the line to reverse direction at the end. In this case, if there is a sudden change of direction at the end of a line that is not joined to another line, the end portion is removed if it is less than this tolerance in length.
  • Merge Lines if no Point on either Line Moves More than Length: When the same information from different sources are combined, it is often the case that a single line has two different representations, causing many sliver polygons. This test allows for the two lines to be merged in case no point on either line moves more than this tolerance. Note that that means polygons of twice this width can be eliminated, but only if they do not contain an interior point linked to the database.
  • Maximum Angle between a Dangle and its Extension: While this software was designed for polygonal lines, it can also be used with other types of data including dense contour data. With such data, the closest point to a dangle end is often the contour on either side rather than the matching dangle straight ahead. This tolerance restricts how many degrees to each side the algorithm searches for a possible point to match a dangle. It will default to 180 degrees (no restriction) but for contour data can be set to 10 or 15 degrees to maximize the chance of avoiding a different contour.
When the Extended Tolerances have been specified, click OK to utilize any changes that you made or Cancel to return to the previous values.

Return to Table of Contents

Choosing Attributes

When you click the Attributes button in the main dialog it will bring up the screen below.

You specify attributes separately for the right and left polygons. The top line in the dialog lets you choose to modify either the left or right polygon attributes to copy to the line file.

Choose the polygon attribute you wish to transfer from the drop-down list under the caption Polygon Attribute. To specify the name of the attribute in the line file, you have three options:

  • Key in the name in the edit box immediately below the caption Line Attribute,
  • Choose the attribute from the drop-down list immediately below (Note, this list is only available if exactly one line file is chosen.), or
  • Leave the line name field blank to automatically produce the names as either L_ or R_ followed by the original attribute name.
Then click the Add button to add this transfer to the list of attributes to be transferred.

In the bottom left corner there is a list of attribute transfers that will occur.

To remove a transfer, select it in the list then click the Remove button.

Click the OK to return to the main dialog.

Return to Table of Contents

Run from Avenue Script

Included with the SSIArcPolyTopo ArcView 3.x installation are two additional scripts. SSIArcPolyTopo.Run takes the program parameters and calls the DLL. SSIArcPolyTopo.Sample provides a sample script that will evoke SSIArcPolyTopo.Run. To call SSIArcPolyTopo directly from your Avenue script, open a script and choose Script > Load System Script. From the dialogue, scroll down to SSIArcPolyTopo.Sample, choose it and click OK. The sample code will be loaded into the open script. Change the names of the files as indicated in the script. Alternately, choose SSIArcPolyTopo.Run to open the required DLL's directly.

Return to Table of Contents

Run from C++

To run SSIArcPolyTopo directly from C++, include the following code:

typedef DWORD (_cdecl *DWLPSSD)(LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR);
HINSTANCE hDll = NULL;
DWLPSSD lpProc = NULL;
hDll = LoadLibrary("c:\\Program Files\\Spatial Online\\SSIArcPolyTopoAM\\SSIArcPolyTopoCI.DLL");
if (hDll) {
    lpProc = (DWLPSSD)GetProcAddress(hDll, "SSIArcPolyTopo");
} else {
    AfxMessageBox("Could not Load Library");
    return 0;
}
if (!lpProc) {
    AfxMessageBox("GetProcAddress Failed");
    FreeLibrary (hDll);
    return 0;
}
char * pOutputFile;
pOutputFile = (char *) malloc (1000*sizeof(char));
pOutputFile[0] = 0;
char * pLineFile;
pLineFile = (char *) malloc (1000*sizeof(char));
pLineFile[0] = 0;
char * pErrorFile;
pErrorFile = (char *) malloc (1000*sizeof(char));
pErrorFile[0] = 0;
char * pDangleFile;
pDangleFile = (char *) malloc (1000*sizeof(char));
pDangleFile[0] = 0;
int nReturn = (*lpProc)("(d:\\data\\Simple\\SimpleLines.shp)(d:\\data\\Simple\\SimplePoints.shp))", "20.0",
    pOutputFile, pLineFile, pErrorFile, pDangleFile,
    "1,2,3,4,5", "(l_poly,RecNum)(area)", "(r_poly,RecNum)(area)", "0");
FreeLibrary (hDll);
if (nReturn) AfxMessageBox("Run successful");
else AfxMessageBox("Run failed");
free (pOutputFile);
free (pLineFile);
free (pErrorFile);
free (pDangleFile);
return nReturn;

More than one line file can be included. To do this, format the first parameter by concatenating all the files as done above with the line and point file. The point file may be omitted.

pOutputFile, pLineFile, pErrorFile and pDangleFile will contain the names of these files as chosen by the user. They will not be more than 1000 characters in length.

All tolerance values can be set. In the above code, the default tolerance is 20. The detailed tolerances are as follows:

  • Small polygon area is 1
  • Arc merge distance is 2
  • Remove dangle distance is 3
  • Extend dangle distance is 4
  • Small aberration distance is 5

Any number of attribute pairs can be added for either the left polygon or the right polygon. If only one attribute name is specified, it will be assumed to be a polygon attribute and the line attribute name will be the default. If no attributes are passed, the defaults will apply.

If the last variable is non-zero, the user will not have the opportunity to modify the parameters before the program runs unless there are errors in the passed values.

Return to Table of Contents

Registration

If the product is still being evaluated, the registration screen below will appear when the program is run or when the About SSIArcPolyTopo button is clicked in ArcView.

Clicking the Purchase SSIArcPolyTopo button will evoke your browser with www.spatial-online.com to enable you to purchase single or multiple copies of the product. You can purchase on-line, through the Fax, via Purchase Order or with an invoice. Once you have purchased the product, you will be required to supply your site code(s) (just below the Purchase SSIArcPolyTopo button). In return, you will get a product key. Insert that key into the Text Box next to Product Key and click OK to register the product. Once you have done this, this registration box will no longer appear.

To run the product in trial mode, click the Run in Demo Mode button. Below the button, the remaining trial period is shown.

Clicking the Cancel button will stop the process.

Return to Table of Contents

Frequently Asked Questions

  • Does SSIArcPolyTopo handle nested polygons?
      • Nested polygons are also referred to as "donut" or "island" polygons. They refer to one or more adjacent polygons that are completely surrounded by another polygon. Many topology building modules have difficulty with these types of polygons.

      SSIArcPolyTopo correctly handles these polygons, nested to any level. For example, SSIArcPolyTopo will correctly handle a lake on an island within a larger lake.

  • What tolerance(s) should I use?

      • The critical distance for a map is the smallest distance between two distinct objects. To have the objects remain distinct, even if there is a problem with the polygon formation at that point, the tolerance should be less than half the critical distance.

      You may find it useful to first run SSIArcPolyTopo with a 0 tolerance. The error file for lines that do not form part of a polygon can be overlaid with the original file to see what problems there are. This can help in choosing a tolerance.

      As one further consideration, the cleaning process is compute intensive. With a tolerance of 0.0, the program runs considerably faster.

      In SSIArcPolyTopo you can specify a single tolerance to be used for all linear tests. It's square is used for all area tests. Alternately, the different tolerances can be individually specified. Click here to find out the details of the tolerances that can be specified.

  • Are there any limitations?
      • There are no software limitations. SSIArcPolyTopo was built to handle large data sets efficiently. The cleaning time tends to be proportional to the number of lines that must be cleaned.

  • I am not real fond of your color scheme. Am I able to customize the legends?
      • All legend can be customized for both ArcView or ArcGis.

      • For ArcView: Double click on the legend of the layer that was created and the Legend Editor will appear. Double click on the color you wish to change and the Palette box will appear. The paint brush brings up the color choice. When you've changed the colors as you wished, click the Save button in the top right corner of the Legend Editor. Navigate to the symbols sub-directory under the installation of ArcView, C:\ESRI\AV_GIS30\ARCVIEW\symbols if you used the defaults. Choose to overwrite SSIPolyStatus.Avl for the polygon legend, SSIBoundary.Avl for the boundary line legend, SSIUnresolved.Avl for the unresolved lines and SSIDangles.Avl for the dangles. Next time you run SSIArcPolyTopo with ArcView, you'll get the new color scheme.
      • For ArcGis: Right click on the layer that was created and choose Properties. Select the Symbology tab. Select the palette of your choice from the drop-down menu in the top right. Double click any color you wish to change, and choose a new color from the palette that appears. When you've changed the colors as you wished, exit the properties box. Right click again on the layer and choose Save as Layer File. Navigate to the installation of SSIArcPolyTopoAM, c:\Program Files\Spatial Online\SSIArcPolyTopoAM if you used the defaults. Choose to overwrite SSIPolyStatus.Lyr for the polygon legend, SSIBoundary.Lyr for the boundary line legend, SSIUnresolved.Lyr for the unresolved lines and SSIDangles.Lyr for the dangles. Next time you run SSIArcPolyTopo with ArcMap, you'll get the new color scheme.

    Return to Table of Contents

    Other SSI Products

    Spatial Solutions Inc. offers five products for the cleaning and building of polygons.

    • SSIArcPolyClean cleans line work. It computes intersections, removes overshoots, undershoots and sliver polygons such as caused by snap backs or multiple sources of data, and produces a shape file containing the clean lines as well as a shape file containing lines that are not part of polygon boundaries and a point shape file noting where the lines are dangling. Click here to download a free evaluation of this product.
    • SSIArcPolyBuild builds polygons. It produces polygon shape files from line shape files, describing the boundaries, and point shape files, linked to the attributes of the polygons. It correctly deals with any level of "donuts", that is a polygon, or group of polygons, that are completely contained within a single polygon. These are also referred to as "island" polygons. They can be nested to any level, such as a lake on an island within a larger lake. Click here to download a free evaluation of this product.
    • SSIArcPoly cleans and builds polygons, including all the functionality above, in one step. Click here to download a free evaluation of this product or purchase the product online.
    • SSIArcPolyTopo, this product, cleans and builds polygons in one step, and in addition, produces a boundary file which identifies the polygons on the left and right. Click here to download a free evaluation of this product or purchase the product online.
    • SSIArcWeed removes redundant points from lines while retaining the essential shape. It is particularly useful when data has been stream digitized or originated from a map at a lower scale. Click here to download a free evaluation of this product.

    This help is provided from within ArcView by the assistance of a free utility called EvokeBrowser. This product enables one to evoke the default browser from within Avenue code. Click here to download the free utility EvokeBrowser.

    While modifying the registry is dangerous, it is also sometimes necessary. SSI provides a free utility to access the registry from within Avenue. Click here to download the free utility Registry.

    Return to Table of Contents

    About SSIArcPolyTopo

    If the product is not registered, the About Box below is shown.

    Clicking Register will bring up the Registration Screen which will show the number of days left in demo mode and provide you with the opportunity to go on-line and purchase. Once the product is registered, this button will be replaced with notification that the product is registered.

    SSIArcPolyTopo Copyright ©2002 is a product of Spatial Solutions Inc. All rights reserved.

    Warning: This computer program is protected by copyright law and international treaties. Unauthorized reproduction of it, or any portion of it, may result in severe civil and criminal penalties, and will be prosecuted to the maximum extent possible under the law.

    The software comes "as is". Neither Spatial Solutions Inc. or www.spatial-online.com make any warranty, representation, promise or guarantee of any kind, either expressed or implied, statutory or otherwise, including, but not limited to the implied warranties of quality, performance, non-infringement, merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the software is with the user. We do not warrant that the functions contained in the software will meet your requirements or that the operation of the software will be uninterrupted or error free.

    Return to Table of Contents