12.1. 표현식

레이어 데이터 및 사전 생성된 또는 사용자가 정의한 함수를 기반으로, 표현식 은 도형 스타일, 라벨의 내용 또는 위치, 도표의 값, 조판기 항목의 높이 등을 동적으로 변경하고, 피처를 선택하고, 가상 필드 등을 생성하기 위해 속성값, 도형 및 변수를 처리할 수 있는 강력한 방법을 제공합니다.

참고

함수 목록 에서 표현식 작성을 위한 기본 함수와 변수 목록을 자세한 정보 및 예시와 함께 찾아볼 수 있습니다.

12.1.1. 표현식 문자열 작성기

Expression string builder 는 표현식을 생성하기 위한 주 대화창으로, QGIS의 여러 부분에서 이용할 수 있는데 특히 다음과 같은 경우에 접근할 수 있습니다:

표현식 작성기 대화창에서 다음 탭들을 선택할 수 있습니다:

  • 표현식 탭: 사전 정의 함수 목록을 이용해서 사용할 표현식을 작성하고 확인할 수 있습니다.

  • 함수 편집기 탭: 사용자 지정 함수를 생성해서 함수 목록을 확장할 수 있습니다.

12.1.1.1. 인터페이스

Expression 탭은 함수, 레이어 필드 및 값을 이용해서 표현식을 작성할 수 있는 주 인터페이스를 제공합니다. 이 탭에 다음 작업을 할 수 있는 위젯들이 있습니다:

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

그림 12.1 표현식 탭

  • 표현식을 입력하거나 붙여넣을 수 있는 표현식 편집기 영역이 있습니다. 표현식 작성 속도를 향상시키기 위해 자동완성 기능을 사용할 수 있습니다:

    • 입력 텍스트에 대응하는 변수, 함수명 및 필드명을 아래쪽에 표시합니다. Up 및 Down 화살표를 사용해서 항목을 탐색한 다음 Tab 을 누르거나 원하는 항목을 클릭하기만 해도 표현식에 삽입할 수 있습니다.

    • 파라미터 입력 시 함수 파라미터가 표시됩니다.

    또한 QGIS는 표현식이 올바른지 점검하고 다음을 사용해서 모든 오류를 강조합니다:

    • 밑줄(Underline): 알 수 없는 함수, 틀렸거나 유효하지 않은 인수(argument)를 표시합니다.

    • 마커(Marker): 단일 위치에 있는 다른 모든 오류를 (예를 들어 빠진 괄호, 예상 밖의 문자 등을) 표시합니다.

    팁

    사용자 표현식을 코멘트로 문서화

    복잡 표현식을 사용할 때, 사용자가 기억하기 쉽도록 텍스트를 여러 줄 또는 인라인(inline) 코멘트 가운데 하나로 추가하는 편이 좋습니다.

    /*
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
)

  • 표현식 편집기 위에 있는 도구 모음을 사용할 수 있습니다:

    • fileNewClear the expression editor: 표현식 편집기 초기화

    • 사용자 표현식 생성 및 관리

  • 표현식 편집기 아래에는:

    • 표현식 작성에 도움이 되는 기본 연산자 모음이 있습니다.

    • 피처 속성을 데이터로 정의하는 경우 산출물의 예상 포맷을 알려줍니다.

    • 표현식의 실시간 Output preview 를 볼 수 있습니다. 기본적으로 레이어의 첫 번째 피처를 대상으로 미리보기를 구합니다. Feature 콤보박스를 이용하면 레이어의 다른 피처를 탐색해서 미리보기를 구할 수 있습니다. (콤보박스에 표시되는 값은 레이어의 표시명 속성에서 가져옵니다.)

      오류가 발생하는 경우, 이를 알려주는 하이퍼링크를 통해 오류의 자세한 내용을 볼 수 있습니다.

  • 함수 선택키는 그룹으로 정리된 함수, 변수, 필드 등등의 목록을 표시합니다. 목록을 필터링하는 검색란을 통해 특정 함수 또는 필드를 빨리 찾을 수 있습니다. 항목을 더블클릭하면 표현식 편집기에 해당 항목을 추가합니다.

  • 도움말 패널이 함수 선택기에서 선택한 함수 별로 도움말을 표시합니다.

    팁

    표현식에 있는 함수명을 Ctrl+Click 하면 자동적으로 대화창에 도움말을 표시합니다.

    함수 선택기에서 필드를 선택하면 나타나는 필드의 값 위젯을 통해 다음과 같은 피처 속성을 가져올 수 있습니다:

    • 특정 필드 값 탐색

    • All Unique 또는 10 Samples 값 목록을 표시. 오른쪽 클릭으로도 표시할 수 있습니다.

      필드가 또다른 레이어나 값 모음과 매핑된 경우, 예를 들어 필드 위젯 이 RelationReference, ValueRelation 또는 ValueMap 유형인 경우 (참조된 레이어, 테이블 또는 목록으로부터) 매핑된 필드의 모든 값을 목록화할 수 있습니다. 여기에 더해, checkbox Only show values in use 옵션을 체크하면 이 목록을 현재 필드에서 사용중인 값만 표시하도록 필터링할 수 있습니다.

    위젯에 있는 필드 값을 더블 클릭하면 표현식 편집기에 해당 값을 추가합니다.

    팁

    대화창에서 함수 도움말이나 필드값을 표시하는 오른쪽 패널을 접을 수 (보이지 않게 할 수) 있습니다. 이 패널을 다시 펼치려면 Show Values 또는 Show Help 버튼을 클릭하세요.

12.1.1.2. 표현식 작성하기

QGIS 표현식은 피처를 선택하거나 값을 설정하는 데 쓰입니다. QGIS에서 표현식을 작성하려면 몇몇 규칙을 따라야 합니다:

  1. 대화창이 맥락을 정의한다: 사용자가 SQL에 익숙하다면, select features from layer where condition 또는 update layer set field = new_value where condition 유형의 쿼리를 알고 있을 것입니다. QGIS 표현식도 이런 모든 정보를 필요로 하지만 사용자가 표현식 작성기 대화창을 열기 위해 사용하는 도구가 이 정보의 일부를 제공합니다. 예를 들어, height 필드를 가진 buildings 레이어를 지정한다고 할 때:

    • expressionSelectSelect by expression 도구를 클릭한다는 것은 “건물 레이어에서 피처를 선택” 하려 한다는 뜻입니다. 사용자가 표현식 텍스트 위젯에 입력해야 하는 정보는 조건 뿐입니다. 예를 들면 높이가 20을 초과하는 건물을 선택하려면 "height" > 20 이라고 입력하면 됩니다.

    • 이렇게 선택 집합을 만든 다음, calculateField Field calculator 버튼을 누르고 Update existing field 에 “height”를 선택하면 이미 “update buildings set height = ??? where height > 20” 명령어를 지정한 것입니다. 이 경우 사용자가 지정해야 하는 나머지 부분은 new value 뿐입니다. 예를 들어 표현식 편집기 텍스트란에 50 을 입력해서 이전에 선택했던 건물의 높이를 설정하십시오.

  2. 따옴표에 주의하라: 작은따옴표는 문자 그대로 반환하기 때문에, 작은따옴표 사이에 있는 텍스트는 문자열로 ('145') 해석됩니다. 큰따옴표는 해당 텍스트의 값을 반환하므로 필드 용으로 ("myfield") 사용하십시오. 필드는 따옴표 없이도 (myfield) 사용할 수 있습니다. 숫자는 따옴표를 사용하지 않습니다(3.16).

    참고

    필드명으로 보통 문자열을 인자로 받는 함수에서는 다음과 같이 입력하고:

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

    다음처럼 입력하면 안 됩니다:

    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.

팁

표현식을 읽기 쉽게 하려면 명명된 파라미터를 이용

어떤 함수들은 설정하는 데 여러 파라미터가 필요합니다. 표현식 엔진은 명명 파라미터를 지원하고 있습니다. 즉 암호 같은 표현식 clamp(1, 2, 9) 을 작성하는 대신, clamp(min:=1, value:=2, max:=9) 같은 표현식을 사용할 수 있다는 뜻입니다. 이렇게 하면 인자들도 clamp(value:=2, max:=9, min:=1) 처럼 위치를 바꿀 수 있습니다. 명명 파라미터를 이용하면 표현식 함수의 인자들이 어떤 의미인지 명확해집니다. 시간이 지난 뒤에 표현식을 해석하려 할 때 유용하겠죠!

12.1.1.3. 몇몇 표현식 용례

  • 필드 계산기에서 기존 “total_pop”과 “area_km2” 필드를 이용, “pop_density” 필드를 계산합니다:

    "total_pop" / "area_km2"

  • 피처의 면적에 따라 피처에 라벨을 추가하거나 범주화합니다:

    CASE WHEN $area > 10 000 THEN 'Larger' ELSE 'Smaller' END

  • “pop_density” 값에 따른 범주로 “density_level” 필드를 업데이트합니다:

    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

  • 평균 집값이 제곱미터 당 1만 유로 이하인지 초과인지를 기준으로 모든 피처에 범주 스타일을 적용합니다:

    "price_m2" > 10000

  • Select By Expression… 도구를 통해 “High population density” 지역인 동시에 평균 집값이 제곱미터 당 1만 유로를 초과하는 지역을 나타내는 모든 피처를 선택합니다:

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

    이런 표현식을 이용해서 어떤 피처에 라벨을 적용할지 또는 맵에 표시할지 정의할 수도 있습니다.

  • 도형 생성기를 통해 레이어 별로 서로 다른 (유형의) 심볼을 생성합니다:

    point_on_surface( $geometry )

  • 포인트 피처를 지정, 포인트 도형 주위에 닫힌 라인을 (make_line 을 이용해서) 생성합니다:

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

  • 인쇄 조판기 라벨에, 조판 “Map 1” 항목 안에 있는 “airports” 피처들의 명칭을 표시합니다:

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

12.1.1.4. 표현식 저장하기

표현식 편집기 프레임 위에 있는 fileSave Add current expression to user expressions 버튼을 사용해서 사용자가 자주 사용하는 중요한 표현식을 저장할 수 있습니다. 가운데 패널에 있는 사용자 표현식 그룹에서 사용할 수 있습니다. 이 사용자 표현식은 사용자 프로파일 (<userprofile>/QGIS/QGIS3.ini 파일)에 저장되며 현재 사용자 프로파일의 모든 프로젝트 안에서의 모든 표현식 대화창에서 사용할 수 있습니다.

표현식 편집기 프레임 위에 있는 도구 모음을 통해 사용자 표현식을 관리할 수 있습니다:

  • fileSaveAdd the current expression to user expressions: 사용자 프로파일에 표현식을 저장합니다. 더 쉽게 식별하기 위한 라벨과 도움말 텍스트도 추가할 수 있습니다.

  • symbologyEdit Edit selected expression from user expressions: 사용자 표현식에서 선택한 표현식은 물론 그 라벨과 도움말을 편집합니다.

  • deleteSelected Remove selected expression from user expressions: 사용자 표현식에서 선택한 표현식을 제거합니다.

  • sharingImport Import user expressions: .json 파일에서 현재 사용자 프로파일 폴더로 사용자 표현식을 가져옵니다.

  • sharingExport Export user expressions: 사용자 프로파일 QGIS3.ini 파일에 있는 모든 사용자 표현식을 .json 파일로 공유합니다.

12.1.2. 함수 편집기

Function Editor 탭에서 사용자 고유의 함수를 파이썬 언어로 작성할 수 있습니다. 이 탭은 미리 정의된 함수로는 커버할 수 없는 특별한 요구 사항을 쉽고 편하게 처리할 수 있는 방법을 제공합니다.

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

그림 12.2 함수 편집기 탭

새 함수를 생성하려면:

  1. symbologyAdd New File 버튼을 누르십시오.

  2. 팝업 양식에 사용할 명칭을 입력하고 OK 를 누르십시오.

    사용자가 지정한 명칭을 가진 새 항목이 Function Editor 탭의 왼쪽 패널에 추가됩니다. 이 항목은 QGIS 템플릿 파일 기반 파이썬 .py 파일로, 활성화된 사용자 프로파일 디렉터리 아래 있는 /python/expressions 폴더에 저장됩니다.

  3. 파일의 내용 ─ 파이썬 스크립트 템플릿 ─ 은 오른쪽 패널에 표시됩니다. 사용자의 필요에 따라 코드 및 도움말을 업데이트하십시오.

  4. start Save and Load Functions 버튼을 누르십시오. Expression 탭의 함수 트리에 사용자가 작성한 함수를 추가합니다. 기본적으로 Custom 그룹 아래 추가될 것입니다.

  5. 사용자의 새 함수를 즐겨보세요.

  6. 함수를 향상시켜야 할 경우, Function Editor 탭을 선택해서 수정한 다음 start Save and Load Functions 을 다시 누르면 파일에서 수정 사항을 사용할 수 있게 됩니다. 즉 어떤 표현식 탭에서도 사용할 수 있게 됩니다.

사용자 지정 파이썬 함수는 사용자 프로파일 디렉터리 아래 저장됩니다. 즉 QGIS를 시작할 때마다, 현재 사용자 프로파일에서 정의된 모든 함수를 자동적으로 불러올 것입니다. /python/expressions 폴더에만 새 함수를 저장하고 프로젝트 파일에는 저장하지 않는다는 사실을 알아두십시오. 사용자 지정 함수를 이용하는 프로젝트를 공유하는 경우, /python/expressions 폴더에 있는 .py 파일도 함께 공유해야 합니다.

사용자 지정 함수를 삭제하려면:

  1. Function Editor 탭을 활성화하고

  2. 목록에서 함수를 선택한 다음

  3. symbologyRemove Remove selected function 버튼을 누르십시오. 목록에서 선택한 함수를 제거하고, 사용자 프로파일 폴더에서 해당 함수에 대응하는 .py 파일도 삭제합니다.

예시

다음은 값 2개를 받아 실행되는 사용자만의 my_sum 함수를 생성하는 방법에 대한 간단한 예시입니다.

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

args='auto' 함수 인자를 사용하는 경우 필수 함수 인자의 개수는 파이썬으로 정의된 함수의 인자 개수(에서 feature 와 parent 2를 뺀 개수)로 계산될 것입니다. group='Custom' 인자는 표현식 대화창에서 이 함수가 포함될 목록을 나타냅니다.

다음과 같은 키워드 인자를 추가할 수도 있습니다:

  • 표현식이 피처 도형에 접근해야 하는 경우 usesgeometry=True 인자를 추가하면 됩니다. 기본값은 False 입니다.

  • 표현식이 NULL 값에 대해 사용자가 정의한 처리를 하는 경우 handlesnull=True 인자를 추가하면 됩니다. 기본값인 False 를 사용한다면, 파라미터 가운데 하나라도 NULL인 경우 항상 NULL을 산출할 것입니다.

  • referenced_columns=[list]: 함수가 요구하는 속성명 배열입니다. 기본값은 [QgsFeatureRequest.ALL_ATTRIBUTES] 입니다.

이제 이렇게 정의한 예시 함수를 표현식 탭에서 사용할 수 있습니다:

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

그림 12.3 표현식 탭에 추가된 사용자 지정 함수

PyQGIS 개발자 쿡북 에서 파이썬 코드 생성 관련 심화 정보를 찾아볼 수 있습니다.