De console stelt gevorderde gebruikers in staat hun productiviteit te vergroten en complexe bewerkingen uit te voeren die niet kunnen worden uitgevoerd met een van de andere elementen van de GUI van het framework Processing. Modellen die verscheidene algoritmen omvatten kunnen worden gedefinieerd met behulp van de interface voor de opdrachtregel, en aanvullende bewerkingen, zoals lussen en voorwaardelijke zinnen, kunnen worden toegevoegd om meer flexibele en meer krachtige werkstromen te maken.
Er is geen console voor Processing in QGIS, maar alle opdrachten voor Processing zijn in plaats daarvan beschikbaar vanuit de in QGIS ingebouwde console voor Python. Dat betekent dat u die opdrachten in uw werk op de console kunt inpassen en algoritmen van Processing kunt verbinden aan alle andere mogelijkheden (inclusief methoden uit de API van QGIS) die van daaruit beschikbaar zijn.
De code die u kunt uitvoeren vanuit de console van Python, zelfs als het geen specifieke methode voor Processing aanroept, kan worden geconverteerd naar een nieuw algoritme dat u later kunt aanroepen vanuit de Toolbox, Grafische modellen bouwen of enige andere component, net zoals u doet met een andere algoritme. In feite zijn enkele algoritmen, die u in de Toolbox aantreft, eenvoudige scripts.
In dit gedeelte zullen we zien hoe we algoritmen van Processing gebruiken vanuit de console voor Python in QGIS, en ook hoe we algoritmen schrijven met behulp van Python.
Het eerste dat u moet doen is de functies voor Processing importeren met de volgende regel:
>>> import processing
Now, there is basically just one (interesting) thing you can do with that from the console: execute an algorithm. That is done using the runalg() method, which takes the name of the algorithm to execute as its first parameter, and then a variable number of additional parameters depending on the requirements of the algorithm. So the first thing you need to know is the name of the algorithm to execute. That is not the name you see in the toolbox, but rather a unique command–line name. To find the right name for your algorithm, you can use the alglist() method. Type the following line in your console:
>>> processing.alglist()
U zult iets zien zoals dit.
Accumulated Cost (Anisotropic)---------------->saga:accumulatedcost(anisotropic)
Accumulated Cost (Isotropic)------------------>saga:accumulatedcost(isotropic)
Add Coordinates to points--------------------->saga:addcoordinatestopoints
Add Grid Values to Points--------------------->saga:addgridvaluestopoints
Add Grid Values to Shapes--------------------->saga:addgridvaluestoshapes
Add Polygon Attributes to Points-------------->saga:addpolygonattributestopoints
Aggregate------------------------------------->saga:aggregate
Aggregate Point Observations------------------>saga:aggregatepointobservations
Aggregation Index----------------------------->saga:aggregationindex
Analytical Hierarchy Process------------------>saga:analyticalhierarchyprocess
Analytical Hillshading------------------------>saga:analyticalhillshading
Average With Mask 1--------------------------->saga:averagewithmask1
Average With Mask 2--------------------------->saga:averagewithmask2
Average With Thereshold 1--------------------->saga:averagewiththereshold1
Average With Thereshold 2--------------------->saga:averagewiththereshold2
Average With Thereshold 3--------------------->saga:averagewiththereshold3
B-Spline Approximation------------------------>saga:b-splineapproximation
...
Dat is een lijst met alle beschikbare algoritmen, alfabetisch gerangschikt, tezamen met hun corresponderende namen voor de opdrachtregel.
U kunt een tekenreeks gebruiken als een parameter voor deze methode. In plaats van de volledige lijst met algoritmen terug te geven, zal het alleen die weergeven waar in de naam die tekenreeks voorkomt. Als u bijvoorbeeld op zoek bent naar een algoritme om de helling van een DEM te berekenen, typ alglist("slope") om het volgende resultaat te verkrijgen:
DTM Filter (slope-based)---------------------->saga:dtmfilter(slope-based)
Downslope Distance Gradient------------------->saga:downslopedistancegradient
Relative Heights and Slope Positions---------->saga:relativeheightsandslopepositions
Slope Length---------------------------------->saga:slopelength
Slope, Aspect, Curvature---------------------->saga:slopeaspectcurvature
Upslope Area---------------------------------->saga:upslopearea
Vegetation Index[slope based]----------------->saga:vegetationindex[slopebased]
Dit resultaat zou kunnen wijzigen, afhankelijk van de algoritmen die u beschikbaar heeft.
Het is nu eenvoudiger om het algoritme te vinden waar u naar zoekt en de naam voor de opdrachtregel ervan, in dit geval saga:slopeaspectcurvature.
Wanneer u eenmaal de naam voor de opdrachtregel weet van het algoritme, is het volgende om te doen de juiste syntaxis te bepalen om het uit te voeren. Dat betekent: weten welke parameters nodig zijn en de volgorde waarin zij moeten worden doorgegeven bij het aanroepen van de methode runalg(). Er bestaat een methode om een algoritme in detail te beschrijven, die kan worden gebruikt om een lijst van de parameters te verkrijgen die een algoritme vereist en de soorten uitvoer die het zal genereren. U kunt de methode alghelp(naam_van_het_algoritme) gebruiken om deze informatie te krijgen. Gebruik de naam voor de opdrachtregel van het algoritme, niet de volledige beschrijvende naam.
De methode aanroepen met als parameter saga:slopeaspectcurvature, geeft u de volgende beschrijving:
>>> processing.alghelp("saga:slopeaspectcurvature")
ALGORITHM: Slope, Aspect, Curvature
ELEVATION <ParameterRaster>
METHOD <ParameterSelection>
SLOPE <OutputRaster>
ASPECT <OutputRaster>
CURV <OutputRaster>
HCURV <OutputRaster>
VCURV <OutputRaster>
Nu heeft u alles wat u nodig heeft om een algoritme uit te voeren. Zoals we al eerder hebben verteld is er slechts één opdracht om algoritmen uit te voeren: runalg(). De syntaxis ervan is als volgt:
>>> processing.runalg(name_of_the_algorithm, param1, param2, ..., paramN,
Output1, Output2, ..., OutputN)
De lijst met parameters en de toe te voegen uitvoer is afhankelijk van het algoritme dat u wilt uitvoeren, en is exact de lijst die de methode alghelp() u geeft, in dezelfde volgorde als weergegeven.
Afhankelijk van het type parameter dienen waarden verschillend te worden ingevoerd. De volgende lijst geeft een snel overzicht van hoe waarden in te voeren voor elk type parameter:
Raster Layer, Vector Layer of Table. Gebruik eenvoudigweg een tekenreeks met de naam die het te gebruiken gegevensobject identificeert (de naam die het heeft in de inhoudsopgave van QGIS) of een bestandsnaam (als de betreffende laag niet is geopend, hij zal worden geopend, maar niet worden toegevoegd aan het kaartvenster). Als u een instantie van een object van QGIS heeft dat de laag vertegenwoordigt, kunt u die ook doorgeven als parameter. Als de invoer optioneel is en u wilt geen gegevensobject gebruiken, gebruik dan None.
Selection. Als een algoritme een parameter voor selectie heeft moet de waarde van die parameter worden ingevuld met behulp van een waarde integer. U kunt de opdracht algoptions() gebruiken om de beschikbare opties te weten te komen, zoals weergegeven in het volgende voorbeeld:
>>> processing.algoptions("saga:slopeaspectcurvature")
METHOD(Method)
0 - [0] Maximum Slope (Travis et al. 1975)
1 - [1] Maximum Triangle Slope (Tarboton 1997)
2 - [2] Least Squares Fitted Plane (Horn 1981, Costa-Cabral & Burgess 1996)
3 - [3] Fit 2.Degree Polynom (Bauer, Rohdenburg, Bork 1985)
4 - [4] Fit 2.Degree Polynom (Heerdegen & Beran 1982)
5 - [5] Fit 2.Degree Polynom (Zevenbergen & Thorne 1987)
6 - [6] Fit 3.Degree Polynom (Haralick 1983)
In dit geval heeft het algoritme één dergelijke parameter, met zeven opties. Onthoud dat de volgorde begint met nul.
Multiple input. De waarde is een tekenreeks met beschrijvingen voor de invoer die zijn gescheiden door puntkomma’s (;). Net als in het geval van enkele lagen of tabellen, kan elke beschrijving voor de invoer de naam van het gegevensobject of het bestandspad zijn.
Table Field from XXX. Gebruik een tekenreeks met de naam van het te gebruiken veld. Deze parameter is hoofdlettergevoelig.
Fixed Table. Type de lijst voor alle waarden voor de tabel, gescheiden door komma’s (,) en omsluit ze met aanhalingstekens ("). Waarden beginnen op de bovenste rij en gaan van rechts naar links. U kunt ook een 2D-array van waarden gebruiken die de tabel vertegenwoordigt.
CRS. Voer het EPSG-codenummer van het gewenste CRS in.
Extent. U dient een tekenreeks te gebruiken met de waarden xmin, xmax, ymin en ymax, gescheiden door komma’s (,).
Booleaanse, bestand, tekenreeks en numerieke parameters behoeven geen aanvullende uitleg.
Parameters voor invoer, zoals tekenreeksen, Booleaanse waarden of numerieke waarden hebben standaard waarden. Specificeer None voor het corresponderende item van de parameter om ze te gebruiken.
Typ, voor gegevensobjecten voor de uitvoer, het te gebruiken bestandspad om ze op te slaan, net zoals wordt gedaan in de Toolbox. Gebruik None als u het resultaat naar een tijdelijk bestand wilt opslaan. De extensie van het bestand bepaalt de indeling van het bestand. Als u een extensie invoert die niet wordt ondersteund door het algoritme, zal de standaard indeling voor het bestand voor dat type uitvoer worden gebruikt en de corresponderende extensie worden toegevoegd aan het opgegeven bestandspad.
Anders dan wanneer een algoritme wordt uitgevoerd vanuit de Toolbox, wordt uitvoer niet toegevoegd aan het kaartvenster als u datzelfde algoritme uitvoert vanaf de console voor Python. Als u een uitvoer wilt toevoegen aan het kaartvenster dient u dat zelf te doen na het uitvoeren van het algoritme. U kunt opdrachten voor de API van QGIS gebruiken om dat te doen, maar, zelfs eenvoudiger, ook een van de handige methoden gebruiken die zijn verschaft voor dergelijke taken.
De methode runalg geeft een woordenboek terug met de namen van de uitvoer (die welke worden weergegeven in de beschrijving van het algoritme) als sleutels en de bestandspaden van die uitvoer als waarden. U kunt deze lagen laden door de corresponderende bestandspaden door te geven aan de methode load().
Naast de functies die worden gebruikt om algoritmen aan te roepen, zal het importeren van het pakket processing ook enkele aanvullende functies importeren die het gemakkelijke maken om met gegevens te werken, in het bijzonder vectorgegevens. Het zijn slechts functies voor het gemak die enige functionaliteit vanuit de API van QGIS binden, gewoonlijk met een minder complexe syntaxis. Deze functies zouden moeten worden gebruikt bij het ontwikkelen van nieuwe algoritmen, omdat zij het eenvoudiger maken om te werken met invoergegevens.
Hieronder staat een lijst van enkele van die opdrachten. Meer informatie kan worden gevonden in de klassen onder het pakket processing/tools, en ook in de voorbeeldscripts die worden verschaft met QGIS.
getObject(obj): Geeft een object van QGIS (een laag of tabel) terug uit het doorgegeven object, wat een bestandsnaam of de naam van een object in de lagenlijst van QGIS kan zijn.
values(layer, fields): Geeft de waarden voor de opgegeven velden in de attributentabel van een vectorlaag terug. Velden kunnen worden opgegeven als veldnamen of als op nul gebaseerde indices van velden. Geeft een woordenboek van lijsten terug, met de opgegeven identificaties van de velden als sleutels. Het is van toepassing op de bestaande selectie.
features(layer): Geeft een herhaalde gang terug over de objecten van een vectorlaag, rekening houdende met de bestaande selectie.
uniqueValues(layer, field): Geeft een lijst unieke waarden terug voor een opgegeven attribuut. Attributen kunnen worden opgegeven als veldnamen of als op nul gebaseerde indices van velden Het is van toepassing op de bestaande selectie.
U kunt uw eigen algoritmen maken door de corresponderende code voor Python te schrijven en een paar extra regels toe te voegen met aanvullende informatie die nodig is om de semantiek van het algoritme te definiëren. U vindt een menu Nieuw script maken onder de groep Gereedschap in het blok met algoritmen Scripts van de Toolbox. Dubbelklik erop om het dialoogvenster voor bewerken van scripts te openen. Daar zou u uw code moeten typen. Sla het script daarvandaan op in de map scripts (de standaard map wanneer u het dialoogvenster Opslaan als... opent) met de extensie .py en het zal automatisch het corresponderende 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
ret_slope = processing.runalg("saga:slopeaspectcurvature", dem, 0, None,
None, None, None, None)
ret_area = processing.runalg("saga:catchmentarea(mass-fluxmethod)", dem,
0, False, False, False, False, None, None, None, None, None)
processing.runalg("saga:topographicwetnessindex(twi), ret_slope['SLOPE'],
ret_area['AREA'], None, 1, 0, twi)
Zoals u kunt zien behelst de berekening drie 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.
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 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.
folder. Een map.
file. Een bestandsnaam.
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:
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.
Wanneer u een uitvoer declareert, zal het algoritme proberen het aan QGIS toe te voegen als het is voltooid. Dat is waarom, hoewel de methode runalg() niet de lagen laadt die het produceert, de uiteindelijke laag TWI zal worden geladen (in het geval van ons vorige voorbeeld), omdat het is opgeslagen in het bestand dat is ingevoerd door de gebruiker, wat de waarde is van de de corresponderende 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
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.
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.
Verscheidene voorbeelden zijn meegeleverd. 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 zien.
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 mee rover 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.
Scripts kunnen ook worden gebruikt om haken in te stellen voor vóór- en na-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 algoritme 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.