소개

이 문서는 예제와 참조용 안내서를 겸하고 있습니다. 모든 사용방법을 목록에 포함시킬 수는 없지만 이 문서는 주요 기능들에 대한 훌륭한 개요를 제공할 것입니다.

QGIS는 0.9 릴리즈 버전부터 파이썬 언어를 이용하는 스크립트 작업을 지원합니다. 파이썬이 스크립트 작업에 가장 인기 있는 언어 중 하나이기 때문에 파이썬으로 결정했습니다. PyQGIS 바인딩은 SIP와 PyQt4를 따르고 있습니다. 보다 일반적으로 사용되는 SWIG 대신 SIP을 선택한 이유는 QGIS 코드가 Qt 라이브러리에 의존적이기 때문입니다. Qt(PyQt)를 위한 파이썬 바인딩도 SIP를 사용하고 있어, PyQGIS를 PyQt와 완벽하게 통합시키고 있습니다.

TODO:
Getting PyQGIS to work (Manual compilation, Troubleshooting)

There are several ways how to use QGIS python bindings, they are covered in detail in the following sections:

  • QGIS 실행 시 자동으로 파이썬 코드 실행

  • QGIS에 포함된 파이썬 콘솔의 명령어 소개

  • 파이썬 기반의 플러그인 제작 및 사용

  • QGIS API 기반의 사용자 정의 응용 프로그램 생성

QGIS 라이브러리의 클래스는 complete QGIS API 참조 자료로 문서화되어 있습니다. 파이썬 QGIS API는 C++의 API와 거의 동일합니다.

There are some resources about programming with PyQGIS on QGIS blog. See QGIS tutorial ported to Python for some examples of simple 3rd party apps. A good resource when dealing with plugins is to download some plugins from plugin repository and examine their code. Also, the python/plugins/ folder in your QGIS installation contains some plugin that you can use to learn how to develop such plugin and how to perform some of the most common tasks

QGIS 실행 시 파이썬 코드 실행

QGIS를 실행할 때마다 파이썬 코드를 실행시킬 수 있는 방법은 두 가지로 구분됩니다.

PYQGIS_STARTUP 환경 변수

기존 파이썬 파일의 경로에 PYQGIS_STARTUP 환경 변수를 설정해서 QGIS 초기화가 완료되기 직전에 파이썬 코드를 실행시킬 수 있습니다.

이 방법을 사용할 일은 거의 없겠지만, QGIS 안에서 파이썬 코드를 실행시킬 수 있는 몇 가지 방법 가운데 하나이고, QGIS 초기화가 완료되기 전에 이 코드가 실행될 것이기 때문에 알아둘 필요가 있습니다. 부적절한 경로를 담고 있을 수도 있는 sys.path를 소거하거나, Mac에 설치되는 homebrew나 MacPorts 프로그램처럼 가상 환경을 불러올 필요없이 초기 환경을 분리/불러오기하는 데 이 방법이 매우 유용합니다.

startup.py 파일

QGIS를 실행할 때마다, 사용자의 파이썬 홈 디렉터리(일반적으로 .qgis2/python)에서 startup.py 라는 파일을 검색해서 해당 파일이 있으면 내장 파이썬 인터프리터가 그 파일을 실행하는 방법입니다.

파이썬 콘솔

스크립트 작업 시 통합된 파이썬 콘솔을 이용하면 많은 이점을 얻을 수 있습니다. Plugins ‣ Python Console 메뉴에서 파이썬 콘솔을 실행할 수 있습니다. 콘솔은 다음과 같은 모달리스(non-modal) 유틸리티 창으로 열립니다.

../../_images/console.png

QGIS 파이썬 콘솔

이 스크린샷은 레이어 목록에서 현재 선택된 레이어를 어떻게 가져오고 레이어의 ID를 어떻게 표출하는지 보여줍니다. 또 레이어가 벡터 레이어일 경우 피처의 개수를 보여줄지 결정할 수 있습니다. QGIS 환경과 상호작용하기 위한 QgsInterface 인스턴스인 iface 변수도 있습니다. 이 인터페이스를 통해 맵 캔버스, 메뉴, 툴바 그리고 QGIS 응용 프로그램의 다른 부분들에 접근할 수 있습니다.

사용자 편의를 위해, 콘솔이 시작되면 아래의 명령어가 실행됩니다. (향후 초기화 명령어를 상세히 설정할 수 있게 될 것입니다.)

from qgis.core import *
import qgis.utils

이 콘솔을 자주 이용하는 사용자의 경우 콘솔을 호출하는 단축키를 설정하는 것이 편리할 것입니다. (Settings ‣ Configure shortcuts... 메뉴에서 설정할 수 있습니다.)

파이썬 플러그인

플러그인을 이용하여 QGIS의 기능을 확장할 수 있습니다. 원래는 C++ 언어로만 가능했지만, QGIS가 파이썬을 추가적으로 지원하면서 파이썬으로 작성된 플러그인을 이용할 수 있게 되었습니다. C++ 플러그인과 비교해서 파이썬 플러그인의 중요한 장점은 (플랫폼 별 컴파일 없이) 쉽게 개발할 수 있고 간단하게 배포할 수 있다는 점입니다.

파이썬을 지원하기 시작한 이후 다양한 기능을 커버하는 많은 플러그인이 작성되었습니다. 플러그인 인스톨러는 사용자가 수월하게 파이썬 플러그인을 다운로드, 업그레이드, 삭제할 수 있도록 해줍니다. 다양한 플러그인 소스를 파이썬 플러그인 저장소 페이지에서 찾을 수 있습니다.

파이썬으로 플러그인을 생성하는 일은 매우 간단합니다. 자세한 내용은 파이썬 플러그인 개발 강의를 참조하십시오.

파이썬 응용 프로그램

어떤 GIS 데이터를 공간 처리할 때, 같은 작업을 반복해서 수행하는 대신 작업 과정을 자동화하는 약간의 스크립트를 작성하면 편리할 경우가 많습니다. PyQGIS를 이용하여 이 작업을 완벽하게 수행할 수 있습니다. qgis.core 모듈을 임포트해서 초기화하면 공간 처리 준비가 완료됩니다.

또는 일부 GIS 기능 – 데이터의 측정, PDF로 지도 내보내기 또는 다른 기능 등 – 을 사용하는 대화형 응용 프로그램을 만들고 싶을 수도 있습니다. qgis.gui 모듈을 통해 다양한 GUI 컴포넌트를 추가로 사용할 수 있는데, 확대/축소, 이동 또는 좀더 사용자화 된 맵 도구 등을 지원하는 응용 프로그램의 일부로 매우 쉽게 통합할 수 있는, 맵 캔버스 위젯이 특히 주목할만 합니다.

Using PyQGIS in custom application

주의: qgis.py 를 테스트용 스크립트의 명칭으로 사용하지 마십시오. 스크립트의 명칭이 파이썬 바인딩의 명칭과 겹치기 때문에 파이썬이 바인딩을 임포트할 수 없게 됩니다.

First of all you have to import qgis module, set QGIS path where to search for resources — database of projections, providers etc. When you set prefix path with second argument set as True, QGIS will initialize all paths with standard dir under the prefix directory. Calling initQgis() function is important to let QGIS search for the available providers.

from qgis.core import *

# supply path to where is your qgis installed
QgsApplication.setPrefixPath("/path/to/qgis/installation", True)

# load providers
QgsApplication.initQgis()

이제 QGIS API를 이용해 작업할 수 있습니다. 레이어를 불러와서 공간 처리를 하거나 맵 캔버스에서 GUI를 작동시키는 등, 가능성은 무궁무진합니다. :-)

When you are done with using QGIS library, call exitQgis() to make sure that everything is cleaned up (e.g. clear map layer registry and delete layers):

QgsApplication.exitQgis()

사용자 정의 응용 프로그램 실행

QGIS 라이브러리 및 적절한 파이썬 모듈을 기본 위치에서 찾을 수 없을 경우 사용자 시스템의 어디에서 탐색해야 하는지 설정해줘야 합니다. 그렇지 않으면 파이썬이 오류 메시지를 표출할 것입니다.

>>> import qgis.core
ImportError: No module named qgis.core

환경 변수 PYTHONPATH 를 설정하면 이 문제를 해결할 수 있습니다. 다음 명령어에서 사용자의 실제 QGIS 설치 경로를 qgispath 자리에 입력해야 합니다.

  • 리눅스에서는: export PYTHONPATH=/qgispath/share/qgis/python

  • 윈도우에서는: set PYTHONPATH=c:\qgispath\python

PyQGIS 모듈의 경로를 설정했지만, 이 모듈들은 qgis_core 및 qgis_gui 라이브러리에 종속되어 있습니다. (파이썬 모듈은 래퍼wrapper로만 동작합니다.) 일반적으로 OS가 이 라이브러리들의 경로를 모르고 있으므로, 다시 임포트 오류 메시지가 표출될 겁니다. (이 메시지는 시스템에 따라 달라질 수 있습니다.)

>>> import qgis.core
ImportError: libqgis_core.so.1.5.0: cannot open shared object file: No such file or directory

이 문제를 해결하려면 QGIS 라이브러리가 있는 디렉터리를 동적 링커의 탐색 경로에 추가하십시오.

  • 리눅스에서는: export LD_LIBRARY_PATH=/qgispath/lib

  • 윈도우에서는: set PATH=C:\qgispath;%PATH%

이러한 명령어를 시동과정을 처리하는 부트스트랩 스크립트에 넣어 둘 수 있습니다. PyQGIS를 이용하는 사용자 정의 응용 프로그램을 배포할 경우 보통 다음 두 가지 방법을 쓸 수 있습니다.

  • 응용 프로그램을 설치하기 전에 사용자에게 플랫폼에 맞는 QGIS 설치를 요구하는 방법입니다. 응용 프로그램 인스톨러가 QGIS 라이브러리의 기본 위치를 찾을 테지만, 만약 기본 위치에 없다면 사용자가 경로를 설정할 수 있도록 해줍니다. 이 방법은 간단하다는 장점이 있지만, 사용자가 더 많은 과정을 수행해야 합니다.

  • QGIS를 응용 프로그램과 함께 패키지하는 방법입니다. 응용 프로그램을 배포하는 데 더 많은 노력이 필요하고 용량이 더 커지게 되지만, 사용자가 추가로 다른 소프트웨어를 다운로드해 설치해야 하는 부담이 줄어들게 됩니다.

이 두 배포 방식을 혼합할 수도 있습니다. 윈도우와 Mac OS X에서는 독립 설치형 응용 프로그램으로 배포하고, 리눅스에서는 QGIS 설치를 사용자와 패키지 관리자에게 맡기는 방식입니다.