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

Table of Contents Overview

SSIArcPoly produces polygon shape files 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.

SSIArcPoly 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.

SSIArcPoly 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 the polygons on the left and the right of each line are required, SSIArcPolyTopo will clean and build polygons, and produce a line file with links to the left and right polygons.

Return to Table of Contents

Download and Installation Instructions

SSIArcPoly, 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 SSIArcPoly are provided here.

Instructions on running SSIArcPoly 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,
    SSIArcPoly Help,
    About SSIArcPoly and
    SSIArcPoly Log File.
SSIArcPoly Help will bring up this help screen. It utilizes EvokeBrowser to evoke the standard browser with SSIArcPoly.htm.

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

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

To run SSIArcPoly, 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.

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 three 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,
  • 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.

In the bottom right of the window, 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 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. The legend is in the \Symbols subdirectory under ArcView. 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 ArcGis. A similar legend is used in ArcGIS. To find out how to customize this and other SSI legends, please click here.

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

Run from Avenue Script

Included with the SSIArcPoly installation are two additional scripts. SSIArcPoly.Run takes the program parameters and calls the DLL. SSIArcPoly.Sample provides a sample script that will evoke SSIArcPoly.Run. To call SSIArcPoly directly from your Avenue script, open a script and choose Script > Load System Script. From the dialogue, scroll down to SSIArcPoly.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 SSIArcPoly.Run to open the required DLL's directly.

Return to Table of Contents

Run from C++

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

typedef DWORD (_cdecl *DWLPSSD)(LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR, LPSTR);
HINSTANCE hDll = NULL;
DWLPSSD lpProc = NULL;
hDll = LoadLibrary("c:\\Program Files\\Spatial Online\\SSIArcPoly\\SSIArcPolyCleanBuildCI.DLL");
if (hDll) {
    lpProc = (DWLPSSD)GetProcAddress(hDll, "SSIArcPoly");
} 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 * 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, pErrorFile, pDangleFile,
    "1", "2", "3", "4", "5", "0");
FreeLibrary (hDll);
if (nReturn) AfxMessageBox("Run successful");
else AfxMessageBox("Run failed");
free (pOutputFile);
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, 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

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 SSIArcPoly button is clicked in ArcView.

Clicking the Purchase SSIArcPoly 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 SSIArcPoly 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 SSIArcPoly 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.

      SSIArcPoly correctly handles these polygons, nested to any level. For example, SSIArcPoly 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 SSIArcPoly 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 SSIArcPoly 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. SSIArcPoly 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, SSIUnresolved.Avl for the unresolved lines and SSIDangles.Avl for the dangles. Next time you run SSIArcPoly 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 SSIArcPolyAM, c:\Program Files\Spatial Online\SSIArcPolyAM if you used the defaults. Choose to overwrite SSIPolyStatus.Lyr for the polygon legend, SSIUnresolved.Lyr for the unresolved lines and SSIDangles.Lyr for the dangles. Next time you run SSIArcPoly with ArcMap, you'll get the new color scheme.

    Return to Table of Contents

    Other SSI Products

    Spatial Solutions Inc. offers four 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, this product, 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 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 SSIArcPoly

    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.

    SSIArcPoly Copyright ©1997-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