GIS, UNIGIS und andere Kleinigkeiten

Die Bereitstellung von Funktionalität in Form von Geoprocessing-Tools hat einige gewichtige Vorteile:

• Der Programmierer muss für die gesuchte Funktionalität nicht auch noch eine eigene Oberfläche programmieren, sondern kann elegant auf die bestehende Geoprocessing-Umgebung zurückgreifen und sich auf die eigentliche Programmierarbeit konzentrieren.
• Der Benutzer kann die Tools in der gewohnten Geoprocessing anwenden und nahtlos mit anderen Tools vermischen. Auch können die Tools in Model Builder-Modellen oder Python-Skripten verwendet werden.
• Die Validierung der Parameter geschieht automatisch und muss vom Programmierer nicht manuell codiert werden. Dies ist eine grosse Zeitersparnis.

Natürlich sind auch einige Nachteile auszumachen und zwar vorwiegend im Bereich Dokumentation. ESRI hat diesem Thema meiner Meinung nach eher wenig Zeit und Dokumentation gewidmet. Es gibt auf EDN dazu nur gerade einen Artikel ("Building a custom geoprocessing function tool") und ein eher mageres Code-Beispiel ("GPCalculateArea"). Zusätzlich dazu gibt es in den ESRI-Foren einen längeren Thread ("Programmatically Creating Toolboxes") zum Thema. Das Fehlen etwas ausführlicherer Dokumentation macht die Umsetzung dieses eigentlich sehr interessanten Ansatzes recht umständlich. Dies hat wahrscheinlich auch dazu geführt, dass in den ESRI-Foren oder auch sonst im Internet praktisch keine weiterführenden Informationen dazu zu finden sind. Hier würde ich mir von ESRI einen kleinen Dokumentationseffort wünschen (ausführlichere Dokumentation, mehr Beispiele).

Übersicht:
Teil 1 (Einführung)
Teil 2 (Implementierung von IGPFunctionFactory)
Teil 3 (Implementierung von IGPFunction)
Teil 4 (Implementierung von IGPFunction:ParameterInfo)
Teil 5 (Implementierung von IGPFunction:Validate)
Teil 6 (Implementierung von IGPFunction:Execute)
Teil 7 (Fazit)

Hier wird nun das eigentliche Tool ausgeführt. Doch bevor dies möglich ist, müssen aus den eingegebenen Parametern gewöhnliche ArcObjects werden. Als erstes muss dazu noch einmal geprüft werden, ob die vom Benutzer übergebenen Parameter auch gültig sind. Dies geschieht durch einen Aufruf der Validate-Methode. Anschliessend wird für jeden Parameter aus der Eigenschaft Value der eigentlich übergebene Wert geholt. Dieser muss jedoch zuerst entpackt werden:

IGPParameter parameter = (IGPParameter)paramvalues.get_Element(0);
IGPValue parameterValue = GPUtils.UnpackGPValue(parameter);

Danach kann der Parameter je nach Typ in das richtige ArcObject umgewandelt werden. Dazu sind die zahlreichen Funktionen der Hilfsklasse IGPUtilities nützlich. Ist der Parameter z.B. eine Feature Class, dann wird die Methode DecodeFeatureLayer benötigt:

IFeatureClass featureClass;

IQueryFilter queryFilter;

if (gpValue is IGPFeatureLayer) {

    GPUtils.DecodeFeatureLayer(gpValue, out featureClass, out queryFilter);

}

Und schon hat man eine herkömmliche Feature Class sowie den dazugehörigen QueryFilter, der z.B. aus einer Definition Query stammt.

Ein genaues Studium der Methoden des IGPUtilites-Objekts lohnt sich, denn für praktisch jeden Parametertyp gibt es eine passende Funktion.

Hat man die Parameter in herkömmliche ArcObjects umgewandelt, kann die Funktionalität des Tools wie gewohnt programmiert und ausgeführt werden. Hier stehen einem dann alle Möglichkeiten in der riesigen ArcObjects-Welt offen.

Übersicht:
Teil 1 (Einführung)
Teil 2 (Implementierung von IGPFunctionFactory)
Teil 3 (Implementierung von IGPFunction)
Teil 4 (Implementierung von IGPFunction:ParameterInfo)
Teil 5 (Implementierung von IGPFunction:Validate)
Teil 6 (Implementierung von IGPFunction:Execute)
Teil 7 (Fazit)

Die in der ParameterInfo gemachten Parameter-Definitionen sind schön und gut, nützen aber nichts, wenn nicht auch geprüft wird, ob sie eingehalten werden. D.h. ob der Benutzer gültige Parameter angegeben hat. Genau dies geschieht in der Validate-Methode. Glücklicherweise muss nicht jeder Parameter einzeln geprüft werden. In der Hilfsklasse IGPUtilities gibt es die Methode InternalValidate, die genau dies erledigt. Der Aufruf dieser Funktion bewirkt, dass alle vom Benutzer eingegebenen Parameter auf die Definitionen in ParameterInfo hin geprüft werden. Erfüllt ein Parameter diese Definition nicht, wird dem Benutzer automatisch ein Warnhinweis angezeigt. Es wird auch geprüft, ob alle obligatorischen Parameter angegeben wurden und ob die angegebenen Parameter (z.B. Feature Classes) tatsächlich existieren.

Sind nun darüber hinaus spezielle Anforderungen betreffend Validierung nötig, die von InternalValidate nicht abgedeckt werden, können diese zusätzlichen Tests separat in der Validate-Methode durchgeführt werden. Sollte Kommunikation mit dem Benutzer notwendig sein, weil einer der Parameter ungültig ist, sollte dies nicht via MessageBox geschehen, sondern über das IGPMessages-Objekt. Die InternalValidate-Methode macht dies genauso. Damit werden dem Benutzer Fehlermeldungen und Warnhinweise konsistent in der GUI angezeigt.

Desweiteren muss in der Validate-Methode auch der in der ParameterInfo-Beschreibung erwähnte Spezialfall des Derived-Parameters berücksichtigt werden. Fügt ein Tool einer Feature Class ein Feld hinzu, dann ist der Output-Parameter eben vom Typ Derived. Dies dient einzig dem Zweck, dass im Model Builder dieses neue Feld bereits angezeigt wird, ohne dass es in Tat und Wahrheit schon existiert. Damit dies funktioniert muss in der Validate-Methode der Parameter d.h. die Feature Class geklont (mit dem IClone-Objekt) und dieser geklonten Feature Class das Feld hinzugefügt werden. Die geklonte Feature Class existiert nirgends in einer Datenbank oder in einem Verzeichnis sondern ausschliesslich im Speicher. Die geklonte und um das Feld ergänzte Feature Class wird anschliessend dem Parameter als Wert wieder eingespiesen. Nur so funktioniert ein Tool im Model Builder korrekt.

Übersicht:
Teil 1 (Einführung)
Teil 2 (Implementierung von IGPFunctionFactory)
Teil 3 (Implementierung von IGPFunction)
Teil 4 (Implementierung von IGPFunction:ParameterInfo)
Teil 5 (Implementierung von IGPFunction:Validate)
Teil 6 (Implementierung von IGPFunction:Execute)
Teil 7 (Fazit)

Die Eigenschaft ParameterInfo ist von zentraler Bedeutung. Sie beschreibt nämlich die einzelnen Input- und Output-Parameter des GP-Tools. Genauer gesagt enthält die Eigenschaft einen Array von IGPParameter-Objekten. Mit IGPParameter können alle möglichen Parameter von Feature Classes über Zahlen bis zu Mehrfach-Auswahllisten definiert werden.

Der Typ des Parameters wird hauptsächlich durch die Eigenschaft DataType definiert. Eine Liste aller möglichen Parametertypen ist hier zu finden. Eine Besonderheit gilt es anzumerken: Soll der Parameter eine FeatureClass sein, hat man zwei Möglichkeiten: DEFeatureClassType oder GPFeatureLayerType. DEFeatureClassType meint immer die Feature Class so wie sie in der DB oder als Shapefile vorliegt. Mit GPFeatureLayerType ist zwar dieselbe Feature Class gemeint aber zusätzlich auch in Form eines FeatureLayers (in ArcMap). Es ist meistens sinnvoll, den DataType auf GPFeatureLayerType zu setzen, da damit auch eventuelle Definition Queries und Selections, die auf die Feature Class angewendet werden, berücksichtigt werden können. Bei DEFeatureClassType ist dies nicht möglich.

Zusätzlich kann der Parameter mit den Eigenschaften Name und DisplayName so beschrieben werden, dass der Benutzer begreift, was er hier eingeben muss.

Sehr wichtig ist daneben auch noch die Eigenschaft ParameterDependencies. Damit können Beziehungen/Abhängigkeiten zwischen verschiedene Parametern hergestellt werden. Wenn z.B. Parameter1 eine Feature Class ist und Parameter2 ein Feld (Attribut), dann wird durch die Abängigkeit dem Benutzer in der Geoprocessing-GUI für den Parameter2 automatisch eine Liste der Felder der Feature Class aus Parameter1 angezeigt, aus der er auswählen kann.

Ähnlich wichtig ist die Eigenschaft Domain. Damit kann der Parameter innerhalb des oben angegebenen DataTypes weiter eingegrenzt werden. Ist der DataType eine beliebige FeatureClass kann mit der Domain-Eigenschaft bestimmt werden, dass nur Feature Classes vom Typ Polygon akzeptiert werden. Oder: Ist der DataType eine Zahl, kann mit der Domain-Eigenschaft der gültige Wertebereich angegeben werden. Die Domain-Eigenschaft ist sehr wichtig und hilfreich, um falsche Benutzereingaben zu vermeiden.

Mit der Eigenschaft Value kann dem Parameter ein Default-Wert zugewiesen werden.

Da es sowohl Input- als auch Output-Parameter gibt, muss dies in der Parameter-Definition ebenfalls spezifiziert werden. Dies geschieht mit der Direction-Eigenschaft. Ein Input-Parameter ist ein Parameter, den das Tool als Ausgangswert benötigt. Ein Output-Parameter hingegen ist im Prinzip das Resultat des Tools. Entsteht als Ergebnis des Tools z.B. eine neue Feature Class, muss diese neue Feature Class als Output-Parameter definiert werden. Dies ist übrigens auch der Fall, wenn das Tool gar keine neue Feature Class erzeugt, sondern eine bestehende nur verändert (d.h. ein Feld hinzufügt). In diesem speziellen Fall wird der Parameter in der Eigenschaft Direction als Output-Parameter definiert und in der Eigenschaft ParameterType als Derived-Parameter. Dies ist notwendig, damit das Tool auch im Model Builder reibungslos funktioniert. Fügt ein Tool einer Feature Class ein Feld zu, dann muss dieses neue Feld im Model Builder angezeigt werden. Schliesslich ist es ja möglich, dass genau dieses Feld als Input-Parameter in einem weiteren Tool benötigt wird. Nur wenn dieses neue Feld als Derived markiert ist, taucht es im Model Builder auf. Auf den Gebrauch des Tools in der Toolbox oder in der Kommandozeile hat die Derived-Markierung keinen Einfluss.

Über die ParameterType-Eigenschaft wird ausserdem gesteuert, ob der Parameter optional oder obligatorisch ist.

Beispiel für einen Parameter, der eine Feature Class vom Typ SimpleJunction sein soll:

IGPParameterEdit gpParameter0 = new GPParameterClass();

gpParameter0.DataType = new GPFeatureLayerTypeClass();

IGPValue gpValue0 = new GPFeatureLayerClass();

gpParameter0.Value = gpValue0;

gpParameter0.Direction = esriGPParameterDirection.esriGPParameterDirectionInput;

gpParameter0.DisplayName = "Input-Layer";

gpParameter0.Enabled = true;

gpParameter0.Name = "inputLayer";

IGPFeatureClassDomain gpDomain0 = new GPFeatureClassDomainClass();

gpDomain0.AddFeatureType(esriFeatureType.esriFTSimpleJunction);

gpParameter0.Domain = (IGPDomain) gpDomain0;

gpParameter0.ParameterType = esriGPParameterType.esriGPParameterTypeRequired;

Beispiel für einen Parameter vom Typ Feld. Das Feld soll einerseits ein Feld der oben ausgewählten Feature Class sein und andererseits vom Typ Double sein:

IGPParameterEdit gpParameter1 = new GPParameterClass();

gpParameter1.DataType = new FieldTypeClass();

IGPValue gpValue1 = new FieldClass();

gpParameter1.Value = gpValue1;

gpParameter1.Direction = esriGPParameterDirection.esriGPParameterDirectionInput;

gpParameter1.DisplayName = "Feld";

gpParameter1.Enabled = true;

gpParameter1.Name = "inputLayerFeld";

gpParameter1.AddDependency("inputLayer");

IGPFieldDomain gpDomain1 = new GPFieldDomainClass();

gpDomain1.AddType(esriFieldType.esriFieldTypeDouble);

gpParameter1.Domain = (IGPDomain) gpDomain1;

gpParameter1.ParameterType = esriGPParameterType.esriGPParameterTypeRequired;

Übersicht:
Teil 1 (Einführung)
Teil 2 (Implementierung von IGPFunctionFactory)
Teil 3 (Implementierung von IGPFunction)
Teil 4 (Implementierung von IGPFunction:ParameterInfo)
Teil 5 (Implementierung von IGPFunction:Validate)
Teil 6 (Implementierung von IGPFunction:Execute)
Teil 7 (Fazit)

Die Implementierung von IGPFunction ist etwas aufwendiger als die von IGPFunctionFactory. Hier wird nun das eigentliche GP-Tool definiert. Von zentraler Bedeutung sind dabei die Eigenschaft ParameterInfo sowie die Methoden Validate und Execute, die in den anschliessenden drei Beiträgen genauer beschrieben werden. Hier geht es um die übrigen Eigenschaften und Methoden.

Die String-Eigenschaften Name und DisplayName geben dem Tool einen Namen. DisplayName ist derjenige Name, der in der ArcGIS-Umgebung angezeigt wird (in der Toolbox oder auf der Kommandozeile). Eine ausführlichere Beschreibung des Tools erfolgt in der Eigenschaft FullName, die ein IName-Objekt zurückgibt, das u.a. auch eine ausführliche Text-Beschreibung des Tools enthalten kann:

public ESRI.ArcGIS.esriSystem.IName FullName {

    get {

     IGPName gpName = new GPFunctionNameClass() as IGPName;

     gpName.Category = "";

     gpName.Description = "Ausführliche Textbeschreibung des Tools";

     gpName.Name = "Tool-Name";

     gpName.DisplayName = "Tool-DisplayName";

     gpName.Factory = (IGPFunctionFactory) new ToolFunctionFactory();

     return gpName as IName;

    }

}

Es wird ausserdem auch mit der Untereigenschaft Factory die Beziehung zwischen GP-Tool und der dazugehörigen GPFunctionFactory hergestellt. Die Untereigenschaft Category dient dazu, innerhalb der logischen Tools-Gruppe weitere Untergruppierungen vorzunehmen.

Die Eigenschaft DialogCLSID wird nur benötigt, wenn dem Tool eine eigene GUI verpasst werden soll, die nicht der Standard Geoprocessing-GUI von ArcGIS entspricht. Dies ist wahrscheinlich nur sehr selten notwendig, so dass hier meistens NULL zurückgegeben werden kann.

Die Methode GetRenderer soll für einen der Tool-Parameter einen Renderer zurückgeben. Hier bin ich ehrlich gesagt nicht ganz schlau geworden, was diese Methode bringen soll und habe sie ebenfalls auf NULL gesetzt, ohne dass Komplikationen aufgetreten sind.

Mit den Eigenschaften HelpFile, HelpContext und MetadataFile kann dem Tool-Benutzer zusätzliche Hilfestellung gegeben werden. Ich habe mich damit begnügt, die Tools bzw. die benötigten Parameter in der Eigenschaft ParameterInfo ausführlich zu beschreiben. Der Benutzer kann die Tools auch anhand dieser Beschreibungen benutzen, ohne dass ich noch irgendwelche Helpfile schreiben muss. Wenn aber Helpfiles gewünscht werden, dann ist hier der richtige Ort.

Die IsLicensed-Methode prüft, ob dem Tool das richtige Lizenz-Level zur Verfügung steht. Ist dies nicht der Fall, wird das Tool gar nicht erst ausgeführt. In diesem Beispiel wird geprüft, ob eine ArcInfo-Lizenz vorhanden ist:

public bool IsLicensed()

{

	IESRILicenseInfo licInfo = new ESRILicenseInfoClass();

	return licInfo.IsLicensed(esriProductCode.esriProductCodeProfessional);

}

Übersicht:
Teil 1 (Einführung)
Teil 2 (Implementierung von IGPFunctionFactory)
Teil 3 (Implementierung von IGPFunction)
Teil 4 (Implementierung von IGPFunction:ParameterInfo)
Teil 5 (Implementierung von IGPFunction:Validate)
Teil 6 (Implementierung von IGPFunction:Execute)
Teil 7 (Fazit)

Die Implementierung von IGPFunctionFactory ist recht einfach zu bewerkstelligen. Es geht im Prinzip nur darum, dass man alle die GP-Tools auflistet, die zu der logischen Tools-Gruppe gehören.

Die String-Eigenschaften Name und Alias stehen für die Namen, die man der logischen Gruppe von GP-Tools geben will und können natürlich frei gewählt werden. Die CLSID-Eigenschaft nimmt die CLSID der Tools-Gruppe auf, z.B. so:

public ESRI.ArcGIS.esriSystem.UID CLSID {

    get {

     UID theUID = new UIDClass();

     theUID.Value = "ToolGruppenName";

     return theUID;

    }

}

Die GetFunction-Methode nimmt den Namen eines GP-Tools entgegen und gibt das dazugehörige GPFunction-Objekt zurück:

public IGPFunction GetFunction(string Name)

{

    IGPFunction gpFunction = null;

    switch(Name)

    {

    case "GP-Tool1":

        gpFunction = new Tool1GPFunction();

        break;

    case "GP-Tool2":

        gpFunction = new Tool2GPFunction();

        break;

    }

    return gpFunction;

}

Die Methode GetFunctionName nimmt den Namen (String) eines GP-Tools entgegen und gibt das dazugehörige Name-Objekt zurück:

public ESRI.ArcGIS.Geodatabase.IGPName GetFunctionName(string Name)

{

	IGPFunction gpFunction = this.GetFunction(Name);

	return gpFunction.FullName as IGPName;

}

Die Methode GetFunctionNames liefert eine Aufzählung mit allen Funktionsnamen der logischen Tools-Gruppe zurück:

public ESRI.ArcGIS.Geodatabase.IEnumGPName GetFunctionNames()

{

	IArray functionNamesArray = new EnumGPNameClass();

	functionNamesArray.Add(this.GetFunctionName("GP-Tool1"));

	functionNamesArray.Add(this.GetFunctionName("GP-Tool2"));

	return (EnumGPNameClass) functionNamesArray;

}

Die Methode GetFunctionEnvironments liefert eine Aufzählung aller GP-Environments zurück, die von dieser Gruppe kontrolliert werden. Diese Methode habe ich jedoch nicht weiter implementiert, so dass sie einfach null zurückgibt. Bisher habe ich damit keine negativen Erfahrungen gemacht. Sie ist in der ESRI-Dokumentation auch als optional angegeben.

Übersicht:
Teil 1 (Einführung)
Teil 2 (Implementierung von IGPFunctionFactory)
Teil 3 (Implementierung von IGPFunction)
Teil 4 (Implementierung von IGPFunction:ParameterInfo)
Teil 5 (Implementierung von IGPFunction:Validate)
Teil 6 (Implementierung von IGPFunction:Execute)
Teil 7 (Fazit)

Vor einem knappen Jahr habe anlässlich eines Vortrages im Rahmen des Schweizer esriuserforums ein paar Folien zum Thema Eigene Geoprocessing-Tools mit ArcObjects gepostet. Seitdem habe ich weiter an den Tools gearbeitet und möchte die gesammelten Erfahrungen und Erkenntnisse auf mehrere Postings verteilt zusammenfassen.

In ArcGIS Desktop gibt es seit der Version 9.0 eine neu gestaltete Geoprocessing-Umgebung, die eine grosse Menge an Funktionalität zur Verfügung stellt. Die Grundeinheit in dieser Umgebung sind sogenannte Geoprocessing-Tools, die einzeln oder miteinander kombiniert verwendet werden können. Benötigt man aber Funktionalität, die nicht als GP-Tool zur Verfügung steht, kann man dies entweder im Model Builder oder als Python-Skript nachbauen oder - und darum geht es in dieser Beitragsreihe - man kann eigene GP-Tools entwickeln.
In meinem konkreten Fall habe ich Funktionalität in Zusammenhang mit geometrischen Netzwerken (Gewässernetzwerk) benötigt, die nicht als GP-Tool vorliegt.

Um eigene GP-Tools zu erstellen, müssen eigentlich nur zwei ArcObjects-Interfaces implementiert werden: IGPFunctionFactory und IGPFunction. IGPFunctionFactory ist dabei eine logische Gruppierung von Tools, die den Zugang zu den eigentlichen Tools ermöglicht. Die Klasse, die IGPFunctionFactory implementiert, muss daneben auch in der Komponenten-Kategorie ("component category") ESRI Geoprocessor Function Factory (GUID: {FD939A4A-955D-4094-B440-77083E410F41}) registriert werden. Die Tools selber werden mit der Implementierung des IGPFunction-Interfaces erstellt.

Übersicht:
Teil 1 (Einführung)
Teil 2 (Implementierung von IGPFunctionFactory)
Teil 3 (Implementierung von IGPFunction)
Teil 4 (Implementierung von IGPFunction:ParameterInfo)
Teil 5 (Implementierung von IGPFunction:Validate)
Teil 6 (Implementierung von IGPFunction:Execute)
Teil 7 (Fazit)

Gestern hatte ich die Gelegenheit, anlässlich des Treffens der Fachgruppe ArcObjects des esriuserforum.ch eine Präsentation einiger Entwicklungen aus den letzten Wochen zu halten. Thema war die Programmierung von eigenen Geoprocessing-Tools mit ArcObjects. Da ich keine Geoprocessing-Tools für den Umgang mit geometrischen Netzwerken auffinden konnte, musste ich mir diese selber herstellen. Das ganze war wegen einer in diesem Bereich relativ spärlichen Dokumentation keine ganz einfache Sache. Die Präsentation fasst meine bis jetzt gemachten Erfahrungen sowie die gefundenen Ressourcen zusammen. Damit vielleicht noch jemand anderes davon profitieren kann, lege ich die Präsentation hier zum Download bereit:

Vortrag esriuserforum.ch (Fachgruppe ArcObjects) vom 19.09.2006