Outdated version of the documentation. Find the latest one here.

.

Processing algoritmen gebruiken vanaf de console

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.

There is not a proccesing console in QGIS, but all processing commands are available instead from the QGIS built-in Python console. That means that you can incorporate those commands into your console work and connect processing algorithms to all the other features (including methods from the QGIS API) available from there.

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 this section, we will see how to use processing algorithms from the QGIS Python console, and also how to write algorithms using Python.

Algoritmen aanroepen van de console van Python

Het eerste dat u moet doen is de functies voor Processing importeren met de volgende regel:

>>> import processing

Wel, er is in de basis slechts één (interessant) ding dat u daarmee kunt doen vanaf de console: een algoritme uitvoeren. Dat wordt gedaan met behulp van de methode runalg(), welke de naam van dat uit te voeren algoritme als zijn eerste parameter opneemt, en dan een variabel aantal aanvullende parameters, afhankelijk van de vereisten van het algoritme. Dus het eerste wat u moet weten is de naam van het uit te voeren algoritme. Dat is niet de naam die u ziet in de Toolbox, maar eerder een unieke naam voor de opdrachtregel. U kunt de methode algslist() gebruiken om de juiste naam voor uw algoritme te zoeken. Type de volgende regel in uw 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 or Table. Simply use a string with the name that identifies the data object to use (the name it has in the QGIS Table of Contents) or a filename (if the corresponding layer is not opened, it will be opened but not added to the map canvas). If you have an instance of a QGIS object representing the layer, you can also pass it as parameter. If the input is optional and you do not want to use any data object, use 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.

Unlike when an algorithm is executed from the toolbox, outputs are not added to the map canvas if you execute that same algorithm from the Python console. If you want to add an output to the map canvas, you have to do it yourself after running the algorithm. To do so, you can use QGIS API commands, or, even easier, use one of the handy methods provided for such tasks.

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().

Aanvullende functies voor het afhandelen van gegevens

Apart from the functions used to call algorithms, importing the processing package will also import some additional functions that make it easier to work with data, particularly vector data. They are just convenience functions that wrap some functionality from the QGIS API, usually with a less complex syntax. These functions should be used when developing new algorithms, as they make it easier to operate with input data.

Below is a list of some of these commands. More information can be found in the classes under the processing/tools package, and also in the example scripts provided with QGIS.

  • getObject(obj): Returns a QGIS object (a layer or table) from the passed object, which can be a filename or the name of the object in the QGIS Table of Contents.
  • 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.

Scripts maken en die uitvoeren vanuit de Toolbox

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

Layers and table values are strings containing the file path of the corresponding object. To turn them into a QGIS object, you can use the processing.getObjectFromUri() function. Multiple inputs also have a string value, which contains the file paths to all selected object, separated by semicolons (;).

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

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.

When you declare an output, the algorithm will try to add it to QGIS once it is finished. That is why, although the runalg() method does not load the layers it produces, the final TWI layer will be loaded (using the case of our previous example), since it is saved to the file entered by the user, which is the value of the corresponding output.

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.

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

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

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.