Scrierea noilor Algoritmi de Procesare sub formă de script-uri Python

Puteți crea proprii algoritmi, prin scrierea codului Python corespunzător și prin adăugarea câtorva linii suplimentare, pentru a furniza informațiile suplimentare, necesare pentru a defini semantica algoritmului. Puteți găsi meniul Create new script în grupul Tools din blocul algoritmilor, al barei de instrumente. Faceți dublu-clic pe el, pentru a deschide dialogul de editare a script-ului. Acolo ar trebui să tastați codul. Salvând script-ul de acolo în folderul scripts (implicit, atunci când deschideți dialogul de salvare a fișierului), cu extensia .py, se va crea automat algoritmul corespunzător.

Numele algoritmului (cel pe care îl veți vedea în caseta de instrumente) este generat din numele fișierului, eliminându-i extensia și înlocuind cratimele cu spații albe.

Haideți să folosim următorul cod, care calculează Indicele de Umiditate Topografic (TWI) direct dintr-un 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.

The part of the code where this processing takes place is not difficult to understand if you have read the previous chapter. The first lines, however, need some additional explanation. They provide the information that is needed to turn your code into an algorithm that can be run from any of the GUI components, like the toolbox or the graphical modeler.

Aceste linii încep cu un dublu simbol de comentariu Python (##) și are următoarea structură

[parameter_name]=[parameter_type] [optional_values]

Aici este o listă a tuturor tipurilor de parametri care sunt acceptați în script-urile de procesare, sintaxa acestora și câteva exemple.

  • raster. Un strat raster

  • vector. Un strat vectorial

  • table. O tabelă

  • number. O valoare numerică. Trebuie să fie specificată o valoare implicită. De exemplu, depth=number 2.4

  • string. Un șir care cuprinde text. Ca și în cazul valorilor numerice, trebuie să existe o valoare implicită. De exemplu, name=string Victor

  • longstring. Este similar șirului de caractere, dar se va afișa o casetă de text mai mare, mai potrivită pentru șirurile lungi, cum ar fi un script care așteaptă un mic fragment de cod.

  • boolean. O valoare booleană. Se adaugă True sau False pentru a seta valoarea implicită. De exemplu, verbose=boolean True.

  • multiple raster. Un set de straturi raster de intrare.

  • multiple vector. Un set de straturi vectoriale de intrare.

  • field. A field in the attributes table of a vector layer. The name of the layer has to be added after the field tag. For instance, if you have declared a vector input with mylayer=vector, you could use myfield=field mylayer to add a field from that layer as parameter.

  • folder. Un folder

  • file. Un nume de fișier

  • crs. Un Sistem de Coordonate de Referință

The parameter name is the name that will be shown to the user when executing the algorithm, and also the variable name to use in the script code. The value entered by the user for that parameter will be assigned to a variable with that name.

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

Ieșirile sunt definite într-un mod similar, folosind următoarele etichete:

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

The value assigned to the output variables is always a string with a filepath. It will correspond to a temporary filepath in case the user has not entered any output filename.

In addition to the tags for parameters and outputs, you can also define the group under which the algorithm will be shown, using the group tag.

The last tag that you can use in your script header is ##nomodeler. Use that when you do not want your algorithm to be shown in the modeler window. This should be used for algorithms that do not have a clear syntax (for instance, if the number of layers to be created is not known in advance, at design time), which make them unsuitable for the graphical modeler

Manipularea datelor produse de algoritm

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.

Do not use the load() method in your script algorithms, but just when working with the console line. If a layer is created as output of an algorithm, it should be declared as such. Otherwise, you will not be able to properly use the algorithm in the modeler, since its syntax (as defined by the tags explained above) will not match what the algorithm really creates.

Hidden outputs (numbers and strings) do not have a value. Instead, it is you who has to assign a value to them. To do so, just set the value of a variable with the name you used to declare that output. For instance, if you have used this declaration,

##average=output number

următoarea linie va seta valoarea de ieșire la 5:

average = 5

Comunicarea cu utilizatorul

If your algorithm takes a long time to process, it is a good idea to inform the user. You have a global named progress available, with two available methods: setText(text) and setPercentage(percent) to modify the progress text and the progress bar.

If you have to provide some information to the user, not related to the progress of the algorithm, you can use the setInfo(text) method, also from the progress object.

If your script has some problem, the correct way of propagating it is to raise an exception of type GeoAlgorithmExecutionException(). You can pass a message as argument to the constructor of the exception. Processing will take care of handling it and communicating with the user, depending on where the algorithm is being executed from (toolbox, modeler, Python console...)

Documentarea script-urilor

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.

Exemple de script-uri

Several examples are available in the on-line collection of scripts, which you can access by selecting the Get script from on-line script collection tool under the Scripts/tools entry in the toolbox.

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

Please, check them to see real examples of how to create algorithms using the processing framework classes. You can right-click on any script algorithm and select Edit script to edit its code or just to see it.

Cele mai bune practici pentru scrierea algoritmilor pentru script

Here’s a quick summary of ideas to consider when creating your script algorithms and, especially, if you want to share with other QGIS users. Following these simple rules will ensure consistency across the different Processing elements such as the toolbox, the modeler or the batch processing interface.

  • Do not load resulting layers. Let Processing handle your results and load your layers if needed.
  • Always declare the outputs your algorithm creates. Avoid things such as declaring one output and then using the destination filename set for that output to create a collection of them. That will break the correct semantics of the algorithm and make it impossible to use it safely in the modeler. If you have to write an algorithm like that, make sure you add the ##nomodeler tag.
  • Do not show message boxes or use any GUI element from the script. If you want to communicate with the user, use the setInfo() method or throw an GeoAlgorithmExecutionException
  • As a rule of thumb, do not forget that your algorithm might be executed in a context other than the Processing toolbox.

Script de interceptare a pre- și post-execuției

Scripts can also be used to set pre- and post-execution hooks that are run before and after an algorithm is run. This can be used to automate tasks that should be performed whenever an algorithm is executed.

The syntax is identical to the syntax explained above, but an additional global variable named alg is available, representing the algorithm that has just been (or is about to be) executed.

In the General group of the processing config dialog you will find two entries named Pre-execution script file and Post-execution script file where the filename of the scripts to be run in each case can be entered.