13.1. Kifejezések

A rétegadatokon és az előre elkészített vagy felhasználó által definiált függvényeken alapuló Kifejezések hatékony módot kínálnak az attribútumértékek, a geometria és a változók manipulálására, a geometria stílusának, a címke tartalmának vagy pozíciójának, a diagram értékének, egy elrendezéselem magasságának dinamikus megváltoztatására, valamint elemek kiválasztására és virtuális mezők létrehozására, és így tovább…

Megjegyzés

A kifejezések írásához használt alapértelmezett függvények és változók listája megtalálható A függvények listája címen, részletes információkkal és példákkal.

13.1.1. A kifejezésszerkesztő

A kifejezések létrehozására szolgáló fő párbeszédablak, a Kifejezésszerkesztő a QGIS számos részéből elérhető, első sorban az alábbi módokon:

A Kifejezésszerkesztő párbeszédablakból elérhető:

  • Kifejezés fül, amely az előre definiált függvényeknek köszönhetően segít megírni és ellenőrizni a kifejezést;

  • Függvényszerkesztő fül, amely segítségével egyéni függvényekkel bővíthető a függvények listája.

13.1.1.1. A felület

A Kifejezés fül biztosítja a fő felületet a függvényeket, rétegek mezőit és értékeit használó kifejezések írásához. A következő részeket tartalmazza:

../../../_images/function_list.png

13.1. ábra A Kifejezés fül

  • Egy kifejezésszerkesztő terület kifejezések megadásához vagy beillesztéséhez. A kifejezések írásának felgyorsítása érdekében automatikus kitöltés áll rendelkezésre:

    • A bevitt szövegnek megfelelő változók, függvénynevek és mezőnevek alatta jelennek meg: a Felfelé és Lefelé nyilakkal válogathat az elemek között, és a Tab gomb megnyomásával vagy a kívánt elemre kattintva beillesztheti a kifejezésbe.

    • A függvényparaméterek kitöltés közben jelennek meg.

    A QGIS ellenőrzi a kifejezés helyességét is, és kiemeli az összes hibát:

    • Aláhúzás: ismeretlen függvények, rossz vagy érvénytelen argumentumok esetén;

    • Jelölő: minden más hiba (pl. hiányzó zárójel, váratlan karakter) esetén egyetlen helyen.

    Javaslat

    Dokumentálja a kifejezéseket megjegyzésekkel

    Ha összetett kifejezések használatakor jó gyakorlat a szöveget emlékeztető jegyzetekkel ellátni, akár többsoros, akár soron belüli megjegyzésként.

    /*
    Labels each region with its highest (in altitude) airport(s)
    and altitude, eg 'AMBLER : 264m' for the 'Northwest Artic' region
    */
    with_variable(
      'airport_alti', -- stores the highest altitude of the region
      aggregate(
        'airports',
        'max',
        "ELEV", -- the field containing the altitude
        -- and limit the airports to the region they are within
        filter := within( $geometry, geometry( @parent ) )
      ),
        aggregate( -- finds airports at the same altitude in the region
          'airports',
          'concatenate',
          "NAME",
          filter := within( $geometry, geometry( @parent ) )
            and "ELEV" = @airport_alti
        )
        || ' : ' || @airport_alti || 'm'
        -- using || allows regions without airports to be skipped
    )
    
  • A kifejezésszerkesztő felett egy eszköztár segít a következőkben:

  • A kifejezésszerkesztő alatt találja:

    • Alapvető műveleti jelek készlete, amelyek segítenek a kifejezés felépítésében

    • A kimenet elvárt formátumának jelzése, amikor adatvezérelt elemtulajdonságokat definiál

    • A kifejezés élő Előnézetét (legfeljebb 60 karakter), mely alapértelmezetten a réteg első eleme alapján lesz kiértékelve. A 60 karaktert meghaladó előnézeti szöveg megtekintéséhez a kurzort a szöveg fölé mozgatva megjelenik egy felugró eszköztipp, amely a teljes kimeneti előnézetet tartalmazza. A kimeneti előnézeti szöveg vágólapra másolásához kattintson a jobb gombbal az előnézeti szövegre, és válassza a editCopy Kifejezésérték másolása lehetőséget.

      A réteg többi elemét az Elem legördülő listából választhatja és értékeltetheti ki (az értékek a réteg megjelenített név tulajdonságából származnak).

      Hiba esetén jelzi azt, és egy hivatkozáson keresztül elérhetővé teszi a részleteket.

  • A függvényválasztó megjeleníti a függvények, változók, mezők… listáját csoportokba rendezve. A lista szűrésére, és egy adott függvény vagy mező gyors megtalálására egy keresőmező áll rendelkezésre. Egy elemre duplán kattintva hozzáadja azt a kifejezésszerkesztőhöz.

  • A súgópanel egy súgót jelenít meg a függvényválasztó kiválasztott eleméhez.

    Javaslat

    A kurzort a kifejezés egy függvényének neve fölött tartva Ctrl+Kattintással megjelenik annak súgója a párbeszédablakban.

    A mezőértékek vezérlő, amely akkor jelenik meg, amikor egy mezőt választ ki a függvényválasztóban, segít az elemek attribútumainak lekérésében:

    • Egy adott mezőérték keresése

    • Az Összes egyedi vagy 10 minta érték megjelenítése. Jobb gombbal is elérhető.

      Ha a mező egy másik réteggel van összekapcsolva vagy értékkészletre leképezve, azaz ha a mezőtípus RelationReference, ValueRelation vagy ValueMap típusú, akkor lehetőség van a társított mező összes értékének felsorolására (a hivatkozott rétegből, táblázatból vagy listából). Ezenkívül szűrheti a listát a checkbox Csak az aktuális mezőben használt értékek megjelenítése bekapcsolásával.

    A vezérlőben lévő mezőértékre való dupla kattintás hozzáadja azt a kifejezésszerkesztőhöz.

    Javaslat

    A jobb oldali panel, amely a függvények súgóját vagy a mezőértékeket jeleníti meg, a párbeszédablakban összecsukható (rejtett). Nyomja meg az Értékek megjelenítése vagy a Súgó megjelenítése gombot, hogy visszakapja.

13.1.1.2. Kifejezés írása

A QGIS-kifejezések az elemek kiválasztására vagy értékek beállítására szolgálnak. QGIS-ben a kifejezések írása követ néhány szabályt:

  1. A párbeszédablak határozza me a kontextust: ha már használt SQL-t, biztosan ismeri a select elemek from réteg where feltétel vagy update réteg set mező = új_érték where feltétel jellegű lekérdezéseket. A QGIS-kifejezésekben ugyanígy szükség van mind ezen információkra, viszont az az eszköz, amiből megnyitotta a kifejezésszerkesztő párbeszédablakot, biztosítja ezek egy részét. Például adott egy (épületek) réteg egy (magasság) mezővel:

    • a expressionSelectKiválasztás kifejezéssel eszköz megnyomása azt jelenti, hogy az „épületek réteg elemeit akarja kiválasztani”. A feltétel az egyetlen olyan információ, melyet a kifejezésszerkesztőben meg kell adnia. Például a "magasság" > 20 megadásával kiválaszthatóak a 20-nál magasabb épületek.

    • ezt a kiválasztást elvégezve nyomja meg a calculateField Mezőkalkulátor gombot, majd a Meglévő mező frissítése alatt a „magasság” mezőt kiválasztva máris készített egy „update épületek set magasság = ??? where magasság > 20” utasítást. Az egyetlen hiányzó láncszem ez esetben az új érték megadása. Például írja be a kifejezésszerkesztő szövegbeviteli mezőjébe, hogy 50, hogy beállítsa a korábban kiválasztott épületek magasságát.

  2. Figyeljen az idézőjelekre: a szimpla idézőjelek szó szerinti értéket adják vissza, így a szimpla idézőjelek közé helyezett szöveg ('145') karakterláncként lesz értelmezve. A dupla idézőjelek a megadott szöveg értékét adják vissza, amit mezőkhöz használhat ("egyik_mezo"). A mezők idézőjelek nélkül is használhatók (egyik_mezo). A számokat nem kell idézőjelek közé helyezni (3.16).

    Megjegyzés

    A függvények argumentumként a mezőnevet általában karakterláncként várják. Vagyis csinálja így:

    attribute( @atlas_feature, 'height' ) -- returns the value stored in the "height" attribute of the current atlas feature
    

    És ne így:

    attribute( @atlas_feature, "height" ) -- fetches the value of the attribute named "height" (e.g. 100), and use that value as a field
                                          -- from which to return the atlas feature value. Probably wrong as a field named "100" may not exist.
    

Javaslat

Tegye olvashatóbbá a kifejezéseket megnevezett paraméterek használatával

Egyes függvények sok paraméter megadását igénylik. A kifejezésmotor támogatja a megnevezett paraméterek használatát. Ez azt jelenti, hogy a rejtélyes clamp( 1, 2, 9) kifejezés helyett használható a clamp( min:=1, value:=2, max:=9) kifejezés. Ez lehetővé teszi az argumentumok felcserélését is, például clamp( value:=2, max:=9, min:=1). A megnevezett paraméterek használata egyértelműbbé teszi, hogy egy kifejezésfüggvény argumentumai mire vonatkoznak, ami hasznos, ha később megpróbálja értelmezni a kifejezést.

13.1.1.3. Pár példa a kifejezések használatára

  • A Mezőkalkulátorban a „pop_density” mező kiszámolása a meglévő „total_pop” és „area_km2” mezők használatával:

    "total_pop" / "area_km2"
    
  • Elemek címkézése vagy kategorizálása a területük alapján:

    CASE WHEN $area > 10 000 THEN 'Larger' ELSE 'Smaller' END
    
  • A „density_level” frissítése a „pop_density” értékének megfelelő kategóriákkal:

    CASE WHEN "pop_density" < 50 THEN 'Low population density'
         WHEN "pop_density" >= 50 and "pop_density" < 150 THEN 'Medium population density'
         WHEN "pop_density" >= 150 THEN 'High population density'
    END
    
  • Kategorizált stílus alkalmazása az összes elemre aszerint, hogy az átlagos négyzetméterenkénti lakásáruk kisebb vagy nagyobb, mint 10000 €:

    "price_m2" > 10000
    
  • A „Kiválasztás kifejezéssel…” eszközzel válassza ki az összes olyan elemet, amely „nagy népsűrűségű” területet képvisel, és amelynek átlagos négyzetméterenkénti lakásárai meghaladják a 10000 eurót:

    "density_level" = 'High population density' and "price_m2" > 10000
    

    Az előző kifejezés arra is használható, hogy meghatározzuk, hogy mely elemek legyenek címkézve vagy megjelenítve a térképen.

  • Hozzon létre egy eltérő szimbólumot (típust) a réteghez a geometriagenerátor segítségével:

    point_on_surface( $geometry )
    
  • Adott egy pontelem, hozzon létre egy zárt vonalat (a make_line segítségével) a geometriája körül:

    make_line(
      -- using an array of points placed around the original
      array_foreach(
        -- list of angles for placing the projected points (every 90°)
        array:=generate_series( 0, 360, 90 ),
        -- translate the point 20 units in the given direction (angle)
        expression:=project( $geometry, distance:=20, azimuth:=radians( @element ) )
      )
    )
    
  • A nyomtatási elrendezés címkéjén jelenítse meg az „airports” elemeinek neveit, amelyek az elrendezés „Térkép 1” elemén belül vannak:

    with_variable( 'extent',
                   map_get( item_variables( 'Map 1' ), 'map_extent' ),
                   aggregate( 'airports', 'concatenate', "NAME",
                              intersects( $geometry, @extent ), ' ,'
                            )
                 )
    

13.1.1.4. Kifejezések mentése

A kifejezésszerkesztő kerete feletti fileSave Az aktuális kifejezés hozzáadása a felhasználói kifejezésekhez gomb segítségével elmentheti azokat a fontos kifejezéseket, amelyekhez gyors hozzáférést szeretne. Ezek a középső panelen található Felhasználói kifejezések csoportból érhetők el. A felhasználói profil (<userprofile>/QGIS/QGIS3.ini fájl) alá kerülnek mentésre, és az aktuális felhasználói profil összes projektjén belül, az összes kifejezés párbeszédablakból elérhetőek.

A kifejezésszerkesztő feletti eszköztár segít a felhasználói kifejezések kezelésében:

  • fileSaveAz aktuális kifejezés hozzáadása a felhasználói kifejezésekhez: eltárolja a kifejezést a felhasználói profilban. A könnyebb azonosítás érdekében címk és súgószöveg adható hozzá.

  • symbologyEdit A felhasználói kifejezésekből kiválasztott kifejezés szerkesztése, valamint a címkéje és súgója módosítása

  • deleteSelected A kiválasztott kifejezés eltávolítása a felhasználói kifejezések közül

  • sharingImport Felhasználói kifejezések importálása egy .json fájlból az aktív felhasználó profilkönyvtárába

  • sharingExport Felhasználói kifejezések exportálása .json fájlba; a QGIS3.ini felhasználói profilban lévő összes felhasználói kifejezés megosztásra kerül a fájlban

13.1.2. Függvényszerkesztő

A Függvényszerkesztő fülön saját függvényeket írhat Python nyelven. Ez egy praktikus és kényelmes módja olyan különleges igények kielégítésének, amelyeket az előre definiált függvények nem fednek le.

../../../_images/function_editor.png

13.2. ábra A Függvényszerkesztő fül

Új függvény készítéséhez:

  1. Nyomja meg az symbologyAdd Új fájl gombot.

  2. Adja meg a használni kívánt nevet a felugró űrlapon, és nyomja meg az OK gombot.

    A Függvényszerkesztő lap bal oldali paneljén egy új elem kerül hozzáadásra az előbb megadott névvel; ez egy Python .py fájl, amely a QGIS-sablonfájlon alapul, és az aktív user profile könyvtár alatti /python/expressions mappában van tárolva.

  3. A jobb oldali panelen megjelenik a fájl tartalma: egy python script sablon. Frissítse a kódot és a súgóját az igényeinek megfelelően.

  4. Nyomja meg a start Függvények mentése és betöltése gombot. Az elkészített függvény hozzáadódik a Kifejezés fül függvényeihez, alapértelmezés szerint az Egyéni csoporthoz.

  5. Most már használhatja az új függvényt!

  6. Ha a függvény további fejlesztésre szorul, váltson a Függvényszerkesztő fülre végezze el a módosításokat, majd kattintson ismét a start Függvények mentése és betöltése gombra, hogy azok bekerüljenek a fájlba, és vele együtt a kifejezések fülre.

Az egyéni Python függvények a felhasználói profil könyvtárában tárolódnak, ami azt jelenti, hogy a QGIS minden egyes indításkor automatikusan betölti az aktuális felhasználói profilhoz megadott összes függvényt. Ne feledje, hogy az új függvények csak a /python/expressions mappába kerülnek elmentésre, a projektfájlba nem. Ha megoszt egy olyan projektet, amely valamelyik egyéni függvényét használja, akkor a .py fájlt is meg kell osztania a /python/expressions mappában.

Egyéni függvény törléséhez:

  1. Váltson a Függvényszerkesztő fülre

  2. Jelölje ki a függvényt a listában

  3. Nyomja meg a symbologyRemove Kiválasztott függvényfájlok eltávolítása gombot. A függvény eltűnik a listából, valamint a hozzá tartozó .py törlődik a felhasználói profilkönyvtárból.

Példa

Íme egy rövid példa arra, hogyan hozhatja létre saját my_sum függvényét, amely két értékkel dolgozik.

from qgis.core import *
from qgis.gui import *

@qgsfunction(args='auto', group='Custom')
def my_sum(value1, value2, feature, parent):
    """
    Calculates the sum of the two parameters value1 and value2.
    <h2>Example usage:</h2>
    <ul>
      <li>my_sum(5, 8) -> 13</li>
      <li>my_sum("field1", "field2") -> 42</li>
    </ul>
    """
    return value1 + value2

A @qgsfunction a következő argumentumokat fogadja el:

  • args: az argumentumok száma. Az args='auto' argumentum használata esetén a szükséges függvényargumentumok száma a Pythonban-függvény definíciójában lévő argumentumok száma alapján lesz kiszámítva (mínusz 2 – feature és parent). args = -1 esetén bármennyi argumentumot elfogad.

  • A group='Custom' argumentum azt a csoportot jelöli, amelyben a függvénynek szerepelnie kell a Kifejezés párbeszédablakban.

  • usesgeometry=True, ha a kifejezésnek szüksége van az elemek geometriájához való hozzáférésre. Alapértelmezés szerint False.

  • handlesnull=True, ha a kifejezés kezeli a NULL értékeket. Ha False (alapértelmezett), akkor az eredmény mindig NULL lesz, amint bármelyik paraméter NULL.

  • referenced_columns=[list]: A függvény számára szükséges attribútumnevek tömbje. Alapértelmezett értéke [QgsFeatureRequest.ALL_ATTRIBUTES].

Maga a függvény a következő argumentumokat várja:

  • tetszőleges számú és típusú, a függvénynek átadni kívánt paraméter, a következő argumentumok előtt.

  • feature: az aktuális elem

  • parent: a QgsExpression objektum

  • context: Ha van megadva az utolsó helyen egy context nevű argumentum, akkor az a QgsExpressionContext objektumot fogja tartalmazni, amely hozzáférést biztosít különböző kiegészítő információkhoz, például a kifejezésváltozókhoz. Pl. context.variable( 'layer_id' )

Az előző példafüggvény ezután kifejezésekben használható:

../../../_images/customFunction.png

13.3. ábra A Kifejezések fülhöz hozzáadott egyéni függvény

Python kód létrehozásával kapcsolatos további információk a PyQGIS fejlesztői szakácskönyv alatt találhatók.