Nieuwe algoritmen voor Processing schrijven als scripts voor Python¶

U kunt uw eigen algoritmen maken door de overeenkomstige code voor Python te schrijven en enkele extra regels toe te voegen om aanvullende informatie te geven die nodig is om de semantiek van het algoritme te definiëren. U bindt het menu Nieuw script maken onder de groep Gereedschap in het blok voor algoritmen Script van de Toolbox. Dubbelklik erop om het dialoogvenster Script editor te openen. Dat is waar u uw code zou moeten typen. Opslaan van het script vanaf daar in de map scripts (de standaard wanneer u het dialoogvenster Opslaan opent), met de extensie .py, zal automatisch het overeenkomstige algoritme maken.

De naam van het algoritme (die welke u zult zien in de Toolbox) wordt gemaakt uit de bestandsnaam, waarbij de extensie is verwijderd en de lage streepjes zijn vervangen door spaties.

Laten we eens kijken naar de volgende code, die de Topographic Wetness Index (TWI) berekent, direct uit een DEM.

##dem=raster
##twi=output raster
ret_slope = processing.runalg("saga:slopeaspectcurvature", dem, 0, None,
                None, None, None, None)
ret_area = processing.runalg("saga:catchmentarea", dem,
                0, False, False, False, False, None, None, None, None, None)
processing.runalg("saga:topographicwetnessindextwi, ret_slope['SLOPE'],
                ret_area['AREA'], None, 1, 0, twi)

Zoals u kunt zien omvat het 3 algoritmen, alle drie afkomstig uit SAGA. De laatste berekent de TWI, maar het heeft een laag slope nodig en een laag flow accumulation. We hebben deze lagen niet, maar omdat we de DEM hebben, kunnen we ze berekenen door het aanroepen van de corresponderende algoritmen van SAGA.

Het gedeelte van de code waar dit verwerken plaatsvindt is niet moeilijk te begrijpen als u de eerdere gedeelten in dit hoofdstuk heeft gelezen. De eerste regels behoeven echter enige nadere uitleg. Zij verschaffen de informatie die nodig is om uw code te veranderen in een algoritme dat kan worden uitgevoerd vanuit één van de componenten van de GUI, zoals de Toolbox of Grafische modellen bouwen.

Deze regels beginnen met een dubbel symbool voor een opmerking in Python (##) en hebben de volgende structuur

[parameter_name]=[parameter_type] [optional_values]

Hier is een lijst met alle typen parameter die worden ondersteund in scripts voor Processing, hun syntaxis en enkele voorbeelden.

• raster. Een rasterlaag

• vector. Een vectorlaag

• table. Een tabel

• number. Een numerieke waarde. Een standaard waarde moet worden opgegeven. Bijvoorbeeld: depth=number 2.4.

• string. Een tekst-tekenreeks. Net als in het geval van numerieke waarden moet een standaard waarde worden toegevoegd. Bijvoorbeeld: name=string Victor.

• longstring. hetzelfde als string, maar een groter tekstvak zal worden weergegeven, zodat het beter geschikt is voor langere teksten, zoals voor een script dat een klein gedeelte code verwacht.

• boolean. Een Booleaanse waarde. Voeg True of False erna toe om het in te stellen op de standaard waarde. Bijvoorbeeld: verbose=boolean True.

• multiple raster. Een set van rasterlagen voor invoer.

• multiple vector. Een set van vectorlagen voor invoer.

• field. Een veld in de attributentabel van een vectorlaag. De naam van de laag moet worden toegevoegd na de tag field. Als u bijvoorbeeld een vector als invoer heeft gedeclareerd met mynlaag=vector, zou u mynveld=field mynlaag kunnen gebruiken om een veld uit die laag als parameter toe te voegen.

• extent. Een ruimtelijk bereik gedefinieerd door xmin, xmax, ymin, ymax

• folder. Een map

• file. Een bestandsnaam

• crs. Een Coördinaten ReferentieSysteem

• selection. Een keuzemenu dat de gebruiker in staat stelt uit ene vooraf gevulde lijst te kiezen. Bijvoorbeeld: units=selection sq_km;sq_miles;sq_degrees

• name. Naam van het script. Dit zal worden weergegeven als de naam van het algoritme in de Toolbox van Processing. Bijvoorbeeld: Mijn algoritme Name=naam

• group. Naam van de map waar het script zal verschijnen in de Toolbox van Processing. Bijvoorbeeld: toevoegen van Utils=groups zal het script plaatsen in een map Utils binnen Scripts.

De naam van de parameter is de naam die aan de gebruiker zal worden getoond bij het uitvoeren van het algoritme, en ook de naam van de variabele die moet worden gebruikt in de code van het script. De waarde die door de gebruiker voor die parameter wordt ingevuld zal worden toegewezen aan een variabele met die naam.

Bij het tonen van de naam van de parameter aan de gebruiker, zal de naam worden bewerkt om zijn uiterlijk te verbeteren, waarbij lage streepjes worden vervangen door spaties. Dus, als u bijvoorbeeld wilt dat de gebruiker een parameter genaamd Een numerieke waarde ziet, kunt u als naam voor de variabele Een_numerieke_waarde gebruiken`.

Lagen en tabelwaarden zijn tekenreeksen die het bestandspad van het corresponderende object bevatten. U kunt de functie processing.getObjectFromUri() gebruiken om er een object voor QGIS van te maken. Meerdere invoer is ook een waarde van een tekenreeks, die de bestandspaden naar alle geselecteerde objecten bevat, gescheiden door puntkomma’s (;).

Soorten uitvoer worden op een soortgelijke manier gedefinieerd, met behulp van de volgende tags:

• output raster
• output vector
• output table
• output html
• output file
• output number
• output string
• output extent

De waarde die wordt toegewezen aan de variabelen voor uitvoer is altijd een tekenreeks met een bestandspad. Het zal corresponderen met een tijdelijk bestandspad als de gebruiker geen bestandsnaam voor de uitvoer heeft ingevoerd.

In aanvulling op de tags voor parameters en soorten uitvoer, kunt u ook de groep definiëren waaronder het algoritme zal worden weergegeven, met behulp van de tag group.

De laatste tag die u kunt gebruiken in de kop van uw script is ##nomodeler. Gebruik dat wanneer u niet wilt dat uw algoritme wordt weergegeven in het venster Grafische modellen bouwen. Dit zou moeten worden gebruikt voor algoritmen die geen heldere syntaxis hebben (bijvoorbeeld als het aantal lagen dat moet worden gemaakt niet op voorhand bekend is, op het moment van ontwerpen), wat ze ongeschikt maakt voor Grafische modellen bouwen

Gegevens, geproduceerd door het algoritme, afhandelen¶

Wanneer u een uitvoer declareert die een laag vertegenwoordigt (raster, vector of tabel), zal het algoritme proberen het aan QGIS toe te voegen als het is voltooid. Dat is de reden waarom, hoewel de methode runalg() niet de lagen laadt die het produceert, de uiteindelijke laag TWI zal worden geladen, omdat het is opgeslagen in het bestand dat is ingevoerd door de gebruiker, wat de waarde is van de overeenkomstige uitvoer.

Gebruik niet de methode load() in uw script-algoritmen, wanneer u slechts werkt met de regel voor de console. Als een laag wordt gemaakt als uitvoer van een algoritme, zou het als zodanig moeten worden gedeclareerd. Anders zult u niet in staat zijn het algoritme op de juiste manier te gebruiken in Grafische modellen bouwen, omdat de syntaxis ervan (zoals gedefinieerd door de hierboven uitgelegde tags) niet overeenkomen met wat het algoritme in werkelijkheid maakt.

Verborgen uitvoer (numbers en strings) hebben geen waarde. In plaats daarvan dient u aan hen een waarde toe te kennen. Stel de waarde van een variabele in met de naam die u gebruikte om de uitvoer te declareren om dat te doen. Als u bijvoorbeeld deze declaratie gebruikte,

##average=output number

zal de volgende regel de waarde voor de uitvoer instellen op 5:

average = 5

Communiceren met de gebruiker¶

Als uw algoritme er lang over doet om te worden verwerkt, is het een goed idee om de gebruiker daarover te informeren. U heeft een globale genaamd progress beschikbaar, met twee mogelijke methoden: setText(text) en setPercentage(percent) om de tekst over de voortgang en de voortgangsbalk aan te passen.

Als u enige informatie aan de gebruiker moet verschaffen, niet gerelateerd aan de voortgang van het algoritme, kunt u de methode setInfo(text) gebruiken, ook vanuit het object progress.

Als uw script problemen heeft, is de juiste manier om door te gaan het een uitzondering te laten opkomen van het type GeoAlgorithmExecutionException(). U kunt een bericht doorgeven als argument aan de constructor van de uitzondering. Processing zal zorg dragen voor de afhandeling ervan en communiceren met de gebruiker, afhankelijk van waaruit het algoritme wordt uitgevoerd (Toolbox, Grafische modellen bouwen, console van Python...)

Documenteren van uw scripts¶

Net als in het geval van modellen kunt u aanvullende documentatie voor uw scripts maken, om uit te leggen wat zij doen en hoe ze zijn te gebruiken. In het dialoogvenster Script editor vindt u een knop [Help script bewerken]. Klik er op en het brengt u naar het dialoogvenster Help editor. Bekijk het gedeelte over Grafische modellen bouwen om meer over dit dialoogvenster te weten te komen en hoe het te gebruiken.

Help-bestanden worden in dezelfde map opgeslagen als het script zelf, waarbij de extensie .help aan de bestandsnaam wordt toegevoegd. Onthoud dat u uw Help voor uw script kunt bewerken vóórdat u het script voor de eerste keer opslaat. Als u later het dialoogvenster Script editor sluit zonder het script op te slaan (d.i. u verwerpt het), zal de inhoud voor de Help verloren gaan. Als uw script al was opgeslagen en is geassocieerd aan een bestandsnaam, wordt de inhoud voor de Help automatisch opgeslagen.

Voorbeelden van scripts¶

Verscheidene voorbeelden zijn beschikbaar in de online verzameling van scripts, waar u toegang tot krijgt door het gereedschap Script verkrijgen uit online scriptcollectie te selecteren onder het item Scripts/Gereedschap in de Toolbox.

Bekijk ze om echte voorbeelden te zien van het maken van algoritmen met behulp van de klassen van het framework Processing. U kunt met rechts op elk script voor een algoritme klikken en Edit script selecteren om de code ervan te bewerken of om die slechts te bekijken.

Best practices voor het schrijven van algoritmen als scripts¶

Hier is een snelle samenvatting van ideeën om te overwegen wanneer u uw algoritmen als scripts maakt en, in het bijzonder, als u ze wilt delen met andere gebruikers van QGIS. Volgen van deze eenvoudige regels zal zorgen voor consistentie in de verschillende elementen van Processing, zoals de Toolbox, Grafische modellen bouwen of de interface Batch-processing.

• Laad geen resulterende lagen. Laat Processing uw resultaten afhandelen en lagen laden als dat nodig is.

• Declareer altijd de uitvoer die uw algoritme maakt. Vermijd dingen zoals het declareren van één uitvoer en dan de doelnaam van het bestand gebruiken voor die uitvoer om er een verzameling van te maken. Dat zal de juiste semantiek van het algoritme breken en het onmogelijk maken het veilig te gebruiken in Grafische modellen bouwen. Als u een dergelijk algoritme moet schrijven, zorg er dan voor dat u de tag ##nomodeler toevoegt.

• Geef geen berichtenvensters weer of gebruik een element van de GUI vanuit het script. Als u wilt communiceren met de gebruiker, gebruik dan de methode setInfo() of zorg voor een GeoAlgorithmExecutionException

• Als vuistregel, vergeet niet dat uw algoritme zou kunnen worden uitgevoerd in een andere context dan de Toolbox van Processing.

Haken voor vóór- en na-uitvoering van scripts¶

Scripts kunnen ook worden gebruikt om haken in te stellen voor pre- en post-uitvoering die worden uitgevoerd vóórdat of nadat een algoritme is uitgevoerd. Dit kan worden gebruikt om taken te automatiseren die zouden moeten worden uitgevoerd wanneer een algortime wordt uitgevoerd.

De syntaxis is identiek aan de hierboven uitgelegde syntaxis, maar een aanvullende globale variabele genaamd alg is beschikbaar, die het algoritme vertegenwoordigt dat zojuist is (of op het punt staat te worden) uitgevoerd.

In de groep Algemeen van het dialoogvenster Opties van Processing vindt u twee items genaamd Vóór-uitvoering script en Na-uitvoering script waar de bestandsnaam van de uit te voeren scripts in elk geval kunnen worden ingevoerd.