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 gombra kattintva;

• elemek kiválasztása a ^{Kiválasztás kifejezéssel…} eszközzel;

• attribútumok szerkesztése például a ^{Mezőkalkulátor} eszközzel;

• jelrendszer, címkék, elrendezéselemek paramétereinek manipulálása az ^{Adatvezérelt felülbírálás} eszközzel (lásd Adatvezérelt felülbírálási beállítások);

• szimbólumréteg készítése geometriagenerátorral;

• valamilyen geoprocessing elvégzése.

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:

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:

  • ^{Kifejezésszerkesztő tartalmának törlése}

  • Felhasználói kifejezések szerkesztése és kezelése

• 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 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 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 ^{Kivá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 ^{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 ^{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:

• ^{Az 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á.

• ^{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

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

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

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

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

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

1. Nyomja meg az ^{Ú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 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 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 ^{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ó:

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.