Friday, July 31, 2009

Yet Another ArcObjects API Adventure

If you develop software with ArcObjects long enough, you will come to learn that experience is what matters the most. The Developer docs that come distributed with the SDK are only the first stop to finding out the real story of what to do with an ArcObject. I've been bitten several times by different ArcObjects and today is yet another one of those times. When it comes to doing GeoProcessing, the idea behind it is simple.
  1. Create a Geoprocessor
  2. Set some properties
  3. Create a geoprocessing tool instance
  4. Set some propertites
  5. Call the Geoprocessor with the instance of the tool
  6. Done
It's cake, at least in theory. Today, I had the need to do some geoprocessing using the ExtractByPolygon operation. According to the docs, the polygon property can be set with an "object" that is a polygon:
Polygon that defines the area to be extracted. X,Y coordinates define the vertices of the polygon. (In, Required)
I proceed to do what feels like the right thing to do. Create my PolygonClass, start creating a square that represents my extents and voila!
Failed to execute (Extract by Polygon). Parameters are not valid. Invalid value type for parameter polygon
That's actually a good error message! Now, I have seen this type of thing before with using the geoprocessing library and new exactly what to do; Go to the support forums and start searching. I was bit by a different operation once, that took a string as the object parameter. If you didnt put a literal "; " at the end of the string the operation would fail (without any indication of why). So I began to adventure into the infamous forums. I dug up an old desktop help article from 9.1 here and noticed the way they were calling it in a script:
ExtractByPolygon_sa C:/data/raster1 "0 0;1 1;2 2;3 3;4 4;5 3;6 2;7 1;8 0" C:/data/final_1 OUTSIDE
I read the description on this page which states this for the polygon parameter:

Polygon that defines the area to be extracted. X,Y coordinates define the vertices of the polygon.

Yes, completely useless. I could not rely on the description, just the random example that was typed up here. Then I get to creating a string with similar content and it all just works:

string strPolygon = String.Format("{0} {1};{2} {3};{4} {5};{6} {7}", left, bottom, left, top, right, top, right, bottom);

I really wish there was a moral to this story. I can't think of a good one here besides the age old developer gripe: "Documentation sucks".

1 comment:

Joseph Armbruster said...

I forgot to add that the description of how polygons should be entered:

"The polygon has a limit of 1,000 vertices. Polygon vertices must be entered in a clockwise order. The first and last vertex must be the same to close the polygon."

And their example, do not match up:

"0 0;1 1;2 2;3 3;4 4;5 3;6 2;7 1;8 0"

And today, I started receiving a random exception:

("esriGeoAnalyst.GridEngine") Error during conversion

Ugh. . . . .