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.

The name of the algorithm (the one you will see in the toolbox) is created from the filename, removing its extension and replacing low hyphens with blank spaces.

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)

As you can see, it involves 3 algorithms, all of them coming from SAGA. The last one of them calculates the TWI, but it needs a slope layer and a flow accumulation layer. We do not have these ones, but since we have the DEM, we can calculate them calling the corresponding SAGA algorithms.

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]

Here is a list of all the parameter types that are supported in processign scripts, their syntax and some examples.

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

  • folder. Een map

  • file. Een bestandsnaam

  • crs. Een Coördinaten ReferentieSysteem

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.

When showing the name of the parameter to the user, the name will be edited it to improve its appearance, replacing low hyphens with spaces. So, for instance, if you want the user to see a parameter named A numerical value, you can use the variable name A_numerical_value.

Layers and tables values are strings containing the filepath 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 filepaths to all selected objects, 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
  • 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

When you declare an output representing a layer (raster, vector or table), the algorithm will try to add it to QGIS once it is finished. That is the reason why, although the runalg() method does not load the layers it produces, the final TWI layer will be loaded, 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

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

As in the case of models, you can create additional documentation for your script, to explain what they do and how to use them. In the script editing dialog you will find a [Edit script help] button. Click on it and it will take you to the help editing dialog. Check the chapter about the graphical modeler to know more about this dialog and how to use it.

Help files are saved in the same folder as the script itself, adding the .help extension to the filename. Notice that you can edit your script’s help before saving it for the first time. If you later close the script editing dialog without saving the script (i.e. you discard it), the help content you wrote will be lost. If your script was already saved and is associated to a filename, saving is done automatically.

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.

../../../_images/script_online.png

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.