PostGIS 3.1.0dev マニュアル

DEV (Wed 13 Jan 2021 10:02:08 PM UTC rev. 0bf0122 )

PostGIS開発グループ

Abstract

PostGISは、オブジェクトRDBであるPostgreSQLの拡張で、GIS (地理情報システム)オブジェクトを格納することができます。PostGISは、GiSTベースのR木空間インデクスをサポートし、GISオブジェクトの解析および処理を行う機能を持ちます。

本マニュアルは、3.1.0dev版のマニュアルです。

この作品はクリエイティブ・コモンズ 表示 - 継承 3.0 非移植 ライセンスの下に提供されています。好きなようにこの材料を使うことができますが、PostGIS Project のクレジット提示を求めます。また可能な限りhttp://postgis.netへのリンクを求めます。


Table of Contents
1. 導入
1.1. プロジェクト運営委員会
1.2. 現在の中核貢献者
1.3. 過去の中核貢献者
1.4. 他の貢献者
2. PostGISインストール
2.1. 簡略版
2.2. ソースからのコンパイルとインストール: 詳細
2.2.1. ソースの取得
2.2.2. インストール要件
2.2.3. コンフィギュレーション
2.2.4. ビルド
2.2.5. PostGISエクステンションのビルドとデプロイ
2.2.6. テスト
2.2.7. インストール
2.3. PAGC住所標準化ツールのインストールと使用
2.3.1. Regex::Assembleのインストール
2.4. Tigerジオコーダのインストールとアップグレードとデータロード
2.4.1. TigerジオコーダをPostGISデータベースで有効にする: エクステンションを使用
2.4.2. TigerジオコーダをPostGISデータベースで有効にする: エクステンション不使用
2.4.3. TigerジオコーダをPostGISデータベースで有効にする: エクステンションを使用
2.4.4. Tigerデータのロード
2.4.5. Tigerジオコーダのアップグレード
2.5. 共通の問題
3. PostGIS Administration
3.1. Tuning your configuration for performance
3.1.1. Startup
3.1.2. Runtime
3.2. Configuring raster support
3.3. Creating spatial databases
3.3.1. Spatially enable database using EXTENSION
3.3.2. Spatially enable database without using EXTENSION (discouraged)
3.3.3. Create a spatially-enabled database from a template
3.4. Upgrading spatial databases
3.4.1. Soft upgrade
3.4.2. Hard upgrade
4. PostGIS Usage
4.1. PostGISを使う: データ管理とクエリ
4.1.1. GISオブジェクト
4.1.2. PostGISジオグラフィ型
4.1.3. OpenGIS標準を使う
4.1.4. GIS (ベクタ)データをロードする
4.1.5. GISデータを検索する
4.1.6. インデックスを構築する
4.1.7. 複雑なクエリ
4.2. PostGISを使う: アプリケーションを構築する
4.2.1. MapServerを使う
4.2.2. Javaクライアント (JDBC)
4.2.3. Cクライアント (libpq)
4.3. ラスタデータの管理、クエリ、アプリケーション
4.3.1. ラスタのロードと生成
4.3.2. ラスタカタログ
4.3.3. PostGISラスタを使ったカスタムアプリケーションの構築
4.4. トポロジ
4.4.1. トポロジ型
4.4.2. トポロジドメイン
4.4.3. トポロジ管理とTopoGeometry管理
4.4.4. トポロジ管理とTopoGeometry管理
4.4.5. トポロジコンストラクタ
4.4.6. トポロジエディタ
4.4.7. トポロジアクセサ
4.4.8. トポロジ処理
4.4.9. TopoGeometryコンストラクタ
4.4.10. TopoGeometryエディタ
4.4.11. TopoGeometryアクセサ
4.4.12. TopoGeometry出力
4.4.13. トポロジ空間関係関数
4.5. 住所標準化
4.5.1. パーサの動作
4.5.2. 住所標準化の型
4.5.3. 住所標準化テーブル
4.5.4. 住所標準化関数
4.6. PostGIS追加機能
4.6.1. Tigerジオコーダ
4.7. 性能向上に関する技法
4.7.1. 大きなジオメトリを持つ小さなテーブル
4.7.2. ジオメトリインデクスでCLUSTERを実行する
4.7.3. 次元変換の回避
5. PostGISリファレンス
5.1. PostgreSQL PostGIS Geometry/Geography/Box型
5.2. PostGIS GUC (Grand Unified Custom)変数
5.3. 管理関数
5.4. ジオメトリ コンストラクタ
5.5. ジオメトリアクセサ
5.6. ジオメトリエディタ
5.7. ジオメトリ出力
5.7.1. Well-Known Text (WKT)
5.7.2. Well-Known Binary (WKB)
5.7.3. Other Formats
5.8. 演算子
5.8.1. Bounding Box Operators
5.8.2. 演算子
5.9. Measurement Functions
5.10. SFCGAL関数
5.11. ジオメトリ処理関数
5.12. 線型参照
5.13. ロングトランザクション機能
6. ラスタ リファレンス
6.1. ラスタサポートデータ型
6.2. ラスタ管理
6.3. ラスタコンストラクタ
6.4. ラスタアクセサ
6.5. ラスタバンドアクセサ
6.6. ラスタピクセルアクセサとセッター
6.7. ラスタエディタ
6.8. ラスタバンドエディタ
6.9. ラスタバンド統計情報と解析
6.10. ラスタ入力
6.11. 出力
6.12. ラスタ処理
6.12.1. 地図代数
6.12.2. 組み込み地図代数コールバック関数
6.12.3. DEM (標高)
6.12.4. ラスタからジオメトリ
6.13. ラスタ演算子
6.14. ラスタとラスタバンドの空間関係関数
6.15. ラスタに関する技法
6.15.1. データベース外ラスタ
7. PostGIS よくある質問
8. PostGISラスタ よくある質問
9. PostGIS Special Functions Index
9.1. PostGIS Aggregate Functions
9.2. PostGIS Window Functions
9.3. PostGIS SQL-MM Compliant Functions
9.4. PostGIS Geography Support Functions
9.5. PostGIS Raster Support Functions
9.6. PostGIS Geometry / Geography / Raster Dump Functions
9.7. PostGIS Box Functions
9.8. PostGIS Functions that support 3D
9.9. PostGIS Curved Geometry Support Functions
9.10. PostGIS Polyhedral Surface Support Functions
9.11. PostGIS Function Support Matrix
9.12. New, Enhanced or changed PostGIS Functions
9.12.1. PostGIS Functions new or enhanced in 3.1
9.12.2. PostGIS Functions new or enhanced in 3.0
9.12.3. PostGIS Functions new or enhanced in 2.5
9.12.4. PostGIS Functions new or enhanced in 2.4
9.12.5. PostGIS Functions new or enhanced in 2.3
9.12.6. PostGIS Functions new or enhanced in 2.2
9.12.7. PostGIS functions breaking changes in 2.2
9.12.8. PostGIS Functions new or enhanced in 2.1
9.12.9. PostGIS functions breaking changes in 2.1
9.12.10. PostGIS Functions new, behavior changed, or enhanced in 2.0
9.12.11. PostGIS Functions changed behavior in 2.0
9.12.12. PostGIS Functions new, behavior changed, or enhanced in 1.5
9.12.13. PostGIS Functions new, behavior changed, or enhanced in 1.4
9.12.14. PostGIS Functions new in 1.3
10. 問題を報告する
10.1. ソフトウェアのバグを報告する
10.2. 文書の問題を報告する
A. 付録
A.1. Release 3.1.0alpha2
A.2. Release 3.1.0alpha1
A.3. リリース 3.0.0
A.4. リリース3.0.0rc1
A.5. リリース3.0.0rc1
A.6. リリース 3.0.0beta1
A.7. リリース 3.0.0alpha4
A.8. リリース 3.0.0alpha3
A.9. リリース 3.0.0alpha2
A.10. リリース 3.0.0alpha1
A.11. リリース 2.5.0
A.12. リリース 2.4.5
A.13. リリース 2.4.4
A.14. リリース 2.4.3
A.15. リリース 2.4.2
A.16. リリース 2.4.1
A.17. リリース 2.4.0
A.18. リリース 2.3.3
A.19. リリース 2.3.2
A.20. リリース 2.3.1
A.21. リリース 2.3.0
A.22. リリース 2.2.2
A.23. リリース 2.2.1
A.24. リリース 2.2.0
A.25. リリース 2.1.8
A.26. リリース 2.1.7
A.27. リリース 2.1.6
A.28. リリース 2.1.5
A.29. リリース 2.1.4
A.30. リリース 2.1.3
A.31. リリース 2.1.2
A.32. リリース 2.1.1
A.33. リリース 2.1.0
A.34. リリース 2.0.5
A.35. リリース 2.0.4
A.36. リリース 2.0.3
A.37. リリース 2.0.2
A.38. リリース 2.0.1
A.39. リリース 2.0.0
A.40. リリース 1.5.4
A.41. リリース 1.5.3
A.42. リリース 1.5.2
A.43. リリース 1.5.1
A.44. リリース 1.5.0
A.45. リリース 1.4.0
A.46. リリース 1.3.6
A.47. リリース 1.3.5
A.48. リリース 1.3.4
A.49. リリース 1.3.3
A.50. リリース 1.3.2
A.51. リリース 1.3.1
A.52. リリース 1.3.0
A.53. リリース 1.2.1
A.54. リリース 1.2.0
A.55. リリース 1.1.6
A.56. リリース 1.1.5
A.57. リリース 1.1.4
A.58. リリース 1.1.3
A.59. リリース 1.1.2
A.60. リリース 1.1.1
A.61. リリース 1.1.0
A.62. リリース 1.0.6
A.63. リリース 1.0.5
A.64. リリース 1.0.4
A.65. リリース 1.0.3
A.66. リリース 1.0.2
A.67. リリース 1.0.1
A.68. リリース 1.0.0
A.69. リリース 1.0.0RC6
A.70. リリース 1.0.0RC5
A.71. リリース 1.0.0RC4
A.72. リリース 1.0.0RC3
A.73. リリース 1.0.0RC2
A.74. リリース 1.0.0RC1

Chapter 1. 導入

PostGISは、PostgreSQLリレーショナルデータベースに空間拡張を施すものです。Refractions Research Incが、空間データベース技術の研究プロジェクトとして開発しました。Refractionsはカナダ・ブリティッシュコロンビア州・ビクトリアにある、データインテグレーションとカスタムソフトウェア開発に特化した、GISとデータベースのコンサルティング会社です。

PostGISはOSGeo財団のプロジェクトです。PostGISは、多数のFOSS4G開発者と、PostGISの機能と多彩さから大きな利益を得る世界中の企業によって継続的に改善され、資金を得ています。

PostGISプロジェクトの開発グループは、PostGISが、OpenGISとSQL/MM空間標準の領域における重要なGIS機能、高度なトポロジ構築 (カバレッジ、サーフェス、ネットワーク)、GISデータの表示と編集を行うデスクトップユーザインタフェースツール、およびウェブベースのアクセスツールのためのデータソースに、より良く対応するよう、サポートと機能強化を行う予定です。

1.1. プロジェクト運営委員会

PostGISプロジェクト運営委員会 (PostGIS Project Steering Committee, PSC)は、総合的な指示、リリースサイクル、ドキュメンテーション、支援活動に関する調整を行っています。また、委員会は、全体的なユーザサポート、PostGISコミュニティからのパッチの受け付けと適用、 開発者のコミットのアクセス、新しい委員、APIの重要な変更といった、PostGISを含む雑多な問題に関する投票を行っています。

Raúl Marín Rodríguez

MVT support, Bug fixing, Performance and stability improvements, GitHub curation, alignment of PostGIS with PostgreSQL releases

Regina Obe

Buildbotのメンテナンス、Windows版と試験版のビルド、ドキュメンテーション、PostgreSQLとの調整、PostGISニュースグループの一般的なユーザサポート、X3D対応、Tiger Geocoder機能、関数管理、新機能と大きなコード変更のスモークテスト。

Bborie Park

ラスタ開発、GDALとの統合、ラスタローダ、ユーザサポート、一般的なバグフィクス、様々なOS (Slackware, Mac, Windows他)での試験。

Darafei Praliaskouski

インデクス改善、誤り修正とジオメトリ/ジオグラフィ関数の改善、GitHub担当、Travis Botのメンテナンス。

Paul Ramsey (委員長)

PostGISプロジェクトの副創始者。総合的なバグフィクス、ジオグラフィ機能、ジオグラフィとジオメトリのインデクス機能 (2次元,、3次元、n次元インデクスとあらゆる空間インデクス)、ジオメトリ内部構造、PointCloud (開発中)、GEOS機能の統合とGEOSリリースとの調整、PostgreSQLのリリースとの調整、ローダ/ダンパ、シェープファイルGUIローダ。

Sandro Santilli

誤り修正とメンテナンス、gitミラーの管理、新しいGEOS機能のメンテナンス、GEOSリリースとの調整、トポロジ機能、ラスタフレームワークと低水準API関数。

1.2. 現在の中核貢献者

Jorge Arévalo

ラスタ開発、GDALドライバ機能、ローダ。

Nicklas Avén

距離関数の強化 (3次元距離、関係関数を含む)と追加、Tiny WKB出力書式(TWKB, 開発中)と一般的なユーザサポート。

Dan Baston

ジオメトリクラスタリング関数の追加、他のジオメトリアルゴリズムの強化、GEOSの強化、および全体のユーザ対応

Olivier Courtin

XML (KML, GML)/GeoJSON入出力関数と3次元サポートとバグフィクス。

Martin Davis

GEOS enhancements and documentation

Björn Harrtell

MapBox Vector Tile関数とGeoBuf関数、Gogsの試験とGitLabの実験。

Mateusz Loskot

PostGISのCMakeサポート。オリジナルのPython版ラスタローダ低水準ラスタAPI関数の以前の開発。

Pierre Racine

ラスタ全体のアーキテクチャ、プロトタイピング、プログラミング支援。

1.3. 過去の中核貢献者

Mark Cave-Ayland

誤り修正とメンテナンスの調整、空間インデクスの選択とバインディング、ローダ/ダンパ、シェープファイルGUIローダ、新機能の統合と強化。

Chris Hodgson

以前のPSCメンバ。一般的な開発、サイトとBuildbotのメンテナンス、OSGeoインキュベーション管理。

Kevin Neufeld

以前のPSCメンバ。文書と文書補助ツール、Buildbotのメンテナンス、PostGISニュースグループでの高度なユーザサポート、PostGISメンテナンス機能の強化。

Dave Blasby

PostGISのオリジナルの開発/副創始者。サーバサイドのオブジェクト、インデクスのバインディングや多数のサーバサイドの解析機能を記述。

Jeff Lounsbury

シェープファイルのローダ/ダンパのオリジナルの開発者。現在のPostGISプロジェクトオーナーの代表。

Mark Leslie

中核機能の、継続的なメンテナンスと開発。曲線機能の強化。シェープファイルGUIローダ。

David Zwarg

ラスタ開発 (ほとんど地図代数解析関数)。

1.4. 他の貢献者

個人

Alex BodnaruGerald FenoyMaxime Guillaud
Alex MayrhoferGino LucreziMaxime van Noppen
Andrea PeriGreg TroxelMichael Fuhr
Andreas Forø TollefsenGuillaume LelargeMike Toews
Andreas NeumannHaribabu KommiNathan Wagner
Anne GhislaHavard TveiteNathaniel Clay
Antoine BajoletIIDA TetsushiNikita Shulga
Artur ZakirovIngvild NystuenNorman Vine
Barbara PhillipotJackie LengPatricia Tozer
Ben JubbJames MarcaRafal Magda
Bernhard ReiterJason SmithRalph Mason
Björn EsserJeff AdamsRémi Cura
Brian HamlinJonne SavolainenRichard Greenwood
Bruce RindahlJose Carlos Martinez LlariRoger Crew
Bruno Wolff IIIJörg HabenichtRon Mayer
Bryce L. NordgrenJulien RouhaudSebastiaan Couwenberg
Carl AndersonKashif RasulSergey Fedoseev
Charlie SavageKlaus FoersterShinichi Sugiyama
Christoph BergKris JurkaShoaib Burq
Christoph Moench-TegederLaurenz AlbeSilvio Grosso
Dane SpringmeyerLars RoessigerSteffen Macke
Dave FuhryLeo HsuStepan Kuzmin
David ZwargLoic DacharyStephen Frost
David ZwargLuca S. PercichTalha Rizwan
David ZwargMaria Arias de ReynaTom Glancy
Dmitry VasilyevMarc DucobuTom van Tilburg
Eduin CarrilloMark SondheimVincent Mora
Eugene AntimirovMarkus SchaberVincent Picavet
Even RouaultMarkus WannerVolf Tomáš
Frank WarmerdamMatt Amos 
George SilvaMatthias Bay 

企業

PostGISプロジェクトへの開発時間、ホスティング、直接的な金銭提供の貢献を行った企業です。

クラウドファンディングキャンペーン

クラウドファンディングキャンペーンは、PostGIS開発チームが走らせているキャンペーンです。欲しくて仕方ない機能に資金を与えて、多数の人々にサービスを提供できるようにするためのものです。それぞれのキャンペーンでは、特定の機能または機能の集合に焦点があてられます。それぞれのスポンサーは、必要な資金提供のうち少しだけを提供し、十分な人/組織の寄付で、たくさんの助けになる作業に支払う基金を持ちます。他の多くの人が寄付に協力してくれそうな機能に関するアイデアがありましたら、PostGIS newsgroupに、その考えを投稿して下さい。一緒に実現できます。

PostGIS 2.0.0はこの戦略を実施する最初のリリースです。PledgeBankを使い、2件のキャンペーンが成功しました。

postgistopology - 10以上のスポンサーがTopoGeometry機能の構築と2.0.0でのトポロジ対応強化とのために、それぞれ250米ドルを寄付しました。

postgis64windows - 20のスポンサーが, Windows上でのPostGIS 64ビット版に必要な作業のために、それぞれ100米ドルを寄付しました。64ビット用PostGIS 2.0.1ができ、PostgreSQLスタックビルダで使用可能なリリースを予定している最終版ができました。

重要なサポートライブラリ

The GEOS geometry operations library

地理空間データ抽出ライブラリGDALはFrank Warmerdamらによります。PostGIS 2.0.0で導入されたラスタ機能で、非常によく使われています。 同じように、PostGISサポートに関するGDALの必要な改善でGDALプロジェクトに貢献しています。

The PROJ cartographic projection library

最後ですがおろそかにできないのがPostgreSQL DBMSです。PostGISはこの巨人の肩に乗っています。PostGISの速度と柔軟性はPostgreSQLが提供する拡張性、偉大なクエリプランナ、GiSTインデクス、多数のSQL機能がないと成り立ちません。

Chapter 2. PostGISインストール

本章では、PostGISのインストールに必要な手順について説明します。

2.1. 簡略版

全ての依存がパスに入っているとする場合、次のようにコンパイルします。

tar xvfz postgis-3.1.0dev.tar.gz
cd postgis-3.1.0dev
./configure
make
make install

PostGISをインストールした後は、利用したいデータベース個々内で利用可能にする必要があります。

2.2. ソースからのコンパイルとインストール: 詳細

[Note]

多くのOSで、ビルドされたPostgreSQL/PostGISパッケージがあります。多くの場合、コンパイルが必要なのは、最もひどい最先端の版が欲しい場合やパッケージメンテナンスを行う人ぐらいです。

本節では、一般的なコンパイル手順を示します。Windows用や他のOS用等にコンパイルするなら、PostGIS User contributed compile guidesPostGIS Dev Wikiで、より詳細な助けが見つかるかも知れません。

多くのOS用のビルド済みパッケージの一覧はPostGIS Pre-built Packagesにあります。

Windowsユーザの場合は、スタックビルダか、PostGIS Windows download siteから安定版を得ることができます。また、週に1回か2回、刺激的なことがあれば随時ビルドを行っているvery bleeding-edge windows experimental buildsもあります。これらはPostGISの進行中のリリースでの試験に使用します。

PostGISモジュールは、PostgreSQLバックエンドサーバの拡張です。PostGIS 3.1.0devでは、コンパイルのために、完全なPostgreSQLサーバヘッダが必要です。PostgreSQL 3.1.0dev以上でビルドできます。古い版のPostgreSQLはサポートされません

PostgreSQLをインストールしていないならPostgreSQLインストールガイドを参照して下さい。http://www.postgresql.org/にあります。

[Note]

GEOS機能を有効にするために、PostgreSQLをインストール時に明示的に標準C++ライブラリに対する明示的なリンクが必要になる場合があります。

LDFLAGS=-lstdc++ ./configure [コンフィギュアオプション]

これは、古い開発ツールとインチキC++例外との対話のための応急処置です。怪しい問題 (望んでいないのにバックエンドが閉じたりそれに近い挙動を起こす)を経験したなら、このトリックを試してみて下さい。もちろん、これを行うにはPostgreSQLをはじめからコンパイルし直す必要があります。

次のステップでは、PostGISソースのコンフィギュレーションとコンパイルに概要を記述します。これらは、Linuxユーザ用に書いてありますので、WindowsやMacでは動作しません。

2.2.1. ソースの取得

ダウンロードサイトhttp://postgis.net/stuff/postgis-3.1.0dev.tar.gzからソースのアーカイブを入手します。

wget http://postgis.net/stuff/postgis-3.1.0dev.tar.gz
tar -xvzf postgis-3.1.0dev.tar.gz

これで、カレントディレクトリの下にpostgis-3.1.0devができます。

もしくはsvnレポジトリhttp://svn.osgeo.org/postgis/trunk/からチェックアウトします。

git clone https://git.osgeo.org/gitea/postgis/postgis.git postgis

新しく作られたpostgis-3.1.0devディレクトトリに移動して、インストールを続けます。

2.2.2. インストール要件

PostGISのビルドと利用のために、次のものが必要です。

必須

  • PostgreSQL 9.6以上。PostgreSQLの完全なインストール (サーバヘッダを含む)が必要です。PostgreSQLは http://www.postgresql.org/にあります。

    完全なPosgreSQL/PostGIS対応表とPostGIS/GEOS対応表についてはhttp://trac.osgeo.org/postgis/wiki/UsersWikiPostgreSQLPostGISをご覧ください。

  • GNU Cコンパイラ (gcc)。ANSI Cコンパイラの中には、PostGISをコンパイルできるものもありますが、gccでコンパイルするのが最も問題が少ないと見ています。

  • GNU Make (gmakeまたはmake)。多くのシステムで、GNU makeがデフォルトのmakeになっています。make -vを実行して版を確認して下さい。他版のmakeでは、PostGISのMakefileを完全に処理しきれないかもしれません。

  • 投影変換ライブラリ Proj4 の 4.9.0版以上。地理座標系の改善の利点を得るには、Proj4 4.9以上が必要です。Proj4ライブラリは、PostGISの座標系投影変換機能に使われます。Proj4は、http://trac.osgeo.org/proj/からダウンロードできます。

  • 投影変換ライブラリ Proj4 の 4.9.0版以上。地理座標系の改善の利点を得るには、Proj4 4.9以上が必要です。Proj4ライブラリは、PostGISの座標系投影変換機能に使われます。Proj4は、http://trac.osgeo.org/proj/からダウンロードできます。

  • LibXML2の2.5.x以上。LibXML2は現在取り込み関数 (ST_GeomFromGMLとST_GeomFromKML)で使っています。LibXML2はhttp://xmlsoft.org/downloads.htmlからダウンロード可能です。

  • JSON-C 0.9以上。JSON-Cは現在、ST_GeomFromGeoJsonによるGeoJSONの取り込みに使われます。JSON-Cはhttps://github.com/json-c/json-c/releases/からダウンロード可能です。

  • GDAL 1.8以上 (古い版では一部機能が働かなかったり挙動が異なるので1.9以上を強く推奨します)。ラスタ機能に必要で、CREATE EXTENSION postgisでのインストールに必要となります。このため、PostgreSQL 9.1以上での使用では非常に推奨されますhttp://trac.osgeo.org/gdal/wiki/DownloadSource/からダウンロード可能です。

  • このパラメータは現在のところ壊れていて、PostgreSQLのインストール先にしかインストールされません。このバグのトラックについてはhttp://trac.osgeo.org/postgis/ticket/635をご覧ください。

オプション

  • ドライバを有効にするにはSection 2.1, “簡略版”を参照してください。

  • GTK (GTK+2.0, 2.8+が必要)。シェープファイルのローダであるshp2pgsql-guiのコンパイル用です。http://www.gtk.org/にあります。

  • SFCGAL 1.1版以上。追加的な2次元や3次元の高度な解析関数をPostGISで使うために使用するものです。Section 5.10, “SFCGAL関数”をご覧下さい。また、GEOSを使う2次元関数のうちいくつか (たとえばST_IntersectionやST_Area)は、GEOSでなくSFCGALを使用することができます。PostgreSQLコンフィギュレーション変数postgis.backendによって、SFCGALがインストールされている場合にはエンドユーザがバックエンドを制御することができます (デフォルトではGEOS)。SFCGAL 1.2は少なくともCGAL 4.3とBoost 1.54 (http://oslandia.github.io/SFCGAL/installation.htmlをご覧下さい)が必要ですのでご注意下さい。https://github.com/Oslandia/SFCGALにあります。

  • Section 4.5, “住所標準化”をビルドするには、PCRE http://www.pcre.org (Unix系システムには通常はインストール済みです)も必要です。parseaddress-stcities.h内のエンコードしたデータを再構築したい場合には、Perl CPANのRegex::Assembleパッケージのみ必要です。Section 4.5, “住所標準化”は、PCREライブラリを検出するか、コンフィギュレーションで適切に--with-pcre-dir=/path/to/pcreを指定すると、自動的にビルドされます。

  • ST_AsMVTを有効にするには、protobuf-cライブラリ (実行時)とprotoc-cコンパイラ (ビルド時)が必要です。protobuf-cの正しい最小版を確認するには、pkg-configが必要です。protobuf-cをご覧下さい。

  • CUnit (CUnit)。レグレッションテストに必要です。http://cunit.sourceforge.net/にあります。

  • DocBook (xsltproc)。文書のビルドに必要です。http://www.docbook.org/にあります。

  • DBLatex (dblatex)。文書をPDFでビルドするのに必要です。http://dblatex.sourcforge.net/にあります。

  • ImageMagick (convert)。文書で使う画像を生成するのに必要です。http://www.imagemagick.org/にあります。

2.2.3. コンフィギュレーション

ほとんどのLinuxのインストールと同様に、最初のステップでは、ソースコードのビルドに使われるMakefileを生成します。これは、シェルスクリプトが行います。

./configure

パラメータを付けない場合には、このコマンドは自動で、PostGISのソースコードのビルドを行うのに必要なコンポーネントやライブラリをシステム上で探します。./configureとするのが一般的な使い方ですが、標準的でない位置に必要なライブラリやプログラムを置いてある場合のために、いくつかのパラメータを受け付けます。

次のリストで、共通して使われるパラメータを示します。 完全なリストについては、--helpまたは--help=shortパラメータを使って下さい。

--with-library-minor-version

Starting with PostGIS 3.0, the library files generated by default will no longer have the minor version as part of the file name. This means all PostGIS 3 libs will end in postgis-3. This was done to make pg_upgrade easier, with downside that you can only install one version PostGIS 3 series in your server. To get the old behavior of file including the minor version: e.g. postgis-3.0 add this switch to your configure statement.

--prefix=PREFIX

PostGISライブラリとSQLスクリプトのインストール先を指定します。デフォルトでは、検出されたPostgreSQLのインストール先と同じになります。

[Caution]

このパラメータは現在のところ壊れていて、PostgreSQLのインストール先にしかインストールされません。このバグのトラックについてはhttp://trac.osgeo.org/postgis/ticket/635をご覧ください。

--with-pgconfig=FILE

PostgreSQLは、PostGISなどの拡張に対してPostgreSQLのインストール先ディレクトリを伝えるpg_configというユーティリティを持っています。PostGISの対象とする特定のPostgreSQLのインストール先を手動で指定する場合に、このパラメータ(--with-pgconfig=/path/to/pg_config)を使います。

--with-gdalconfig=FILE

必須ライブラリであるGDALは、ラスタ機能に必要な機能を提供します。GDALには、インストール先ディレクトリをインストールスクリプトに伝えるgdal-configがあります。PostGISのビルドに使う特定のGDALを手動で指定する場合に、このパラメータ (--with-gdalconfig=/path/to/gdal-config)を使います。

--with-geosconfig=FILE

必須のジオメトリライブラリであるGEOSには、ソフトウェアのインストール時にGEOSのインストール先ディレクトリを伝えるgeos-configというユーティリティがあります。PostGISのビルドに使う特定のGEOSを手動で指定する場合に、このパラメータ (--with-geosconfig=/path/to/geos-config)を使います。

--with-xml2config=FILE

LibXMLはGeomFromKML/GML処理を行うのに必須のライブラリです。通常はlibxmlをインストールしているなら発見されますが、発見できない場合や特定の版を使用したい場合は、xml2-configを指定してインストールスクリプトにLibXMLのインストール先ディレクトリを伝えます。PostGISのビルドに使う特定のLibXMLを手動で指定する場合に、このパラメータ ( >--with-xml2config=/path/to/xml2-config)を使います。

--with-projdir=DIR

Proj4はPostGISに必須の投影変換ライブラリです。PostGISのビルドに使う特定のProj4のディレクトリを手動で指定する場合は、このパラメータ (--with-projdir=/path/to/projdir)を使います。

--with-libiconv=DIR

iconvのインストール先ディレクトリを指定します。

--with-jsondir=DIR

JSON-Cは、MITライセンスのJSONライブラリで、PostGISのST_GeomFromJSONに必須です。PostGISのビルドに使う特定のJSON-Cを手動で指定する場合に、このパラメータ (--with-jsondir=/path/to/jsondir)を使います。

--with-pcredir=DIR

PCREは、BSDライセンスのPerl互換正規表現ライブラリです。住所標準化エクステンションに必須です。PostGISのビルド対象としている特定のPCREを手動で指定する場合に、このパラメータ (--with-pcredir=/path/to/pcredir)を使います。

--with-gui

データインポートGUI (GTK+2.0が必要)をコンパイルします。このパラメータによって、shp2pgsql-guiという、shp2pgsqlのグラフィカルユーザインタフェースが作成されます。

--without-raster

ラスタ機能をインストールします。

--without-topology

トポロジ対応を無くしてコンパイルします。トポロジに必要なロジックは全てpostgis-3.1.0devライブラリ内に作られるので、関連ライブラリはありません。

--with-gettext=no

デフォルトでは、gettextの検出とこれを用いたコンパイルを試みますが、ローダ破損を引き起こす非互換性問題のもとで実行する場合には、このコマンドで無効にできます。これを使ったコンフィギュレーションによって解決する問題の例はhttp://trac.osgeo.org/postgis/ticket/748にあります。ご注意: これを切ることで多くの機能がなくなるわけではありません。まだ文書化されていなくて試験段階であるGUIローダにおける内部のヘルプ/ラベル機能に使われています。

--with-sfcgal=PATH

デフォルトでは、このスイッチなしではSFCGAL対応でインストールされません。PATHは、sfcgal-configへのパスを指定することができる追加的な引数です。

--without-wagyu

When building with MVT support, Postgis will use Wagyu to clip and validate MVT polygons. Wagyu is the fastest alternative and guarantees producing correct values for this specific case, but it requires a C++-11 compiler. With this optional argument you can disable using this library; GEOS will be used instead.

--without-phony-revision

Disable updating postgis_revision.h to match current HEAD of the git repository.

[Note]

PostGISをSVNレポジトリから得る場合には、はじめに次のスクリプトを実行します。

./autogen.sh

このスクリプトによってconfigureスクリプトが生成されます。これはPostGISのインストールに関するカスタマイズに使われます。

PostGISをアーカイブファイルで入手する場合には、configureが既に生成されているので./autogen.shは不要です。

2.2.4. ビルド

Makefileが生成されたら、PostGISのビルドは、次のコマンドを実行するだけです。

make

出力の最後の行に"PostGIS was built successfully. Ready to install."と出れば終わりです。

PostGIS 1.4.0版からは、全ての関数に文書から生成されるコメントが付きます。これらのコメントを後からインストールするには、次のコマンドを実行しますが、docbookが必要です。アーカイブファイルからインストールする場合は、postgis_comments.sql, raster_comments.sql, topology_comments.sqlは、docフォルダにあるので、コメントを作成する必要はありません。コメントはCREATE EXTENSIONによるインストールの一部として取り込まれます。

make comments

PostGIS 2.0で導入されました。早見表に、または学習中の方のハンドアウトに適しているHTMLチートシートを生成します。xsltprocが必要で、topology_cheatsheet.html, tiger_geocoder_cheatsheet.html, raster_cheatsheet.html, postgis_cheatsheet.htmlの4ファイルが生成されます。

HTMLとPDFのビルド済みのものはPostGIS / PostgreSQL Study Guidesにあります。

make cheatsheets

2.2.5. PostGISエクステンションのビルドとデプロイ

PostgreSQL 9.1以上を使用している場合は、PostGISエクステンションが自動的にビルド、インストールされます。

ソースレポジトリからビルドしている場合は、関数の記述を最初にビルドする必要があります。これらは、docbookがインストールされている時にビルドされます。手動でインストールするには次のようにします。

make comments

アーカイブファイルからのビルドの場合は、ビルド済みのものがあるので、コメントのビルドは必須ではありません。

PostgreSQL 9.1を対象にビルドしている場合は、extensionsは自動的にmake install処理の一部としてビルドするべきです。必要ならextensionsフォルダからビルドできますし、他のサーバで必要ならファイルの複製ができます。

cd extensions
cd postgis
make clean
make
export PGUSER=postgres #overwrite psql variables
make check #to test before install
make install
# to test extensions
make check RUNTESTFLAGS=--extension
[Note]

make check uses psql to run tests and as such can use psql environment variables. Common ones useful to override are PGUSER,PGPORT, and PGHOST. Refer to psql environment variables

エクステンションファイルは、OSに関係なく、常に同じ版のPostGISと同じです。PostGISバイナリを既にインストールしている限りは、エクステンションファイルをあるOSから別のものに複写して大丈夫です。

開発用と異なる別のサーバでエクステンションを手動でインストールしたい場合は、サーバにない時に必要となる通常のPostGISのバイナリだけでなく、次のファイルをextensionsフォルダからPostgreSQLインストール先のPostgreSQL / share / extensionフォルダに複写します。

  • 指定されていない場合のインストールするエクステンションの版等の情報を示す制御ファイpostgis.control, postgis_topology.control

  • エクステンションごとの/sqlフォルダにあるファイル全て。extensions/postgis/sql/*.sql, extensions/postgis_topology/sql/*.sqlはPostgreSQL share/extensionフォルダの最上位に複写する必要があることに注意して下さい。

以上を実行すると、PgAdmin -> extensionでpostgis, postgis_topologyが有効なエクステンションとして見えます。

psqlを使う場合は、次のクエリを実行してエクステンションがインストールされていることを確認できます。

SELECT name, default_version,installed_version
FROM pg_available_extensions WHERE name LIKE 'postgis%' or name LIKE 'address%';

             name             | default_version | installed_version
------------------------------+-----------------+-------------------
 address_standardizer         | 3.1.0dev         | 3.1.0dev
 address_standardizer_data_us | 3.1.0dev         | 3.1.0dev
 postgis                      | 3.1.0dev         | 3.1.0dev
 postgis_sfcgal               | 3.1.0dev         |
 postgis_tiger_geocoder       | 3.1.0dev         | 3.1.0dev
 postgis_topology             | 3.1.0dev         |
(6 rows)

クエリを行ったデータベースにエクステンションがインストールされている場合は、installed_versionカラムに記載が見えます。レコードが返ってこない場合は、PostGIS EXTENSIONがインストールされていないことになります。PgAdmin III 1.14以上では、データベースブラウザツリーのextensionsセクションで提供されていて、右クリックでアップグレードまたアンインストールできます。

有効なエクステンションがある場合、pgAdminエクステンションインタフェースまたは次のSQLの実行によって、選択したデータベースにPostGISエクステンションをインストールできます。

CREATE EXTENSION postgis;
CREATE EXTENSION postgis_sfcgal;
CREATE EXTENSION fuzzystrmatch; -- postgis_tiger_geocoderに必要
-- postgis_tiger_geocoderで使用されるか単独で使われます
CREATE EXTENSION address_standardizer;
CREATE EXTENSION address_standardizer_data_us;
CREATE EXTENSION postgis_tiger_geocoder;
CREATE EXTENSION postgis_topology;

psqlでは、どの版が、どのスキーマにインストールされているかを見ることができます。

\connect mygisdb
\x
\dx postgis*
List of installed extensions
-[ RECORD 1 ]-------------------------------------------------
-
Name        | postgis
Version     | 3.1.0dev
Schema      | public
Description | PostGIS geometry, geography, and raster spat..
-[ RECORD 2 ]-------------------------------------------------
-
Name        | postgis_tiger_geocoder
Version     | 3.1.0dev
Schema      | tiger
Description | PostGIS tiger geocoder and reverse geocoder
-[ RECORD 3 ]-------------------------------------------------
-
Name        | postgis_topology
Version     | 3.1.0dev
Schema      | topology
Description | PostGIS topology spatial types and functions
[Warning]

エクステンションのテーブルspatial_ref_sys, layer, topologyは、明示的にバックアップできません。それぞれのpostgisまたはpostgis_topologyエクステンションがバックアップされる時のみバックアップできます。これは、データベース全体のバックアップの時のみ行われます。PostGIS 2.0.1の時点では、データベースがバックアップされる際に、PostGISでパッケージ化されていないsridレコードのみバックアップされます。パッケージに入っているsridの変更は巡回せず、変更はそこにあるものと期待されます。PostGIS 2.0.1の時点では、データベースがバックアップされるときにPostGISに入っていないsridのレコードだけがバックアップされます。PostGISに入っていて後に変更されたsridの変更については巡回しません。問題が見られたら、チケットを発行して下さい。エクステンションテーブルの構造はCREATE EXTENSIONで生成されるので、バックアップを行いません。エクステンションの与えられた版と同じものであると仮定されます。この挙動は現在のPostgreSQL エクステンションモデルに組み込まれているため、これについては何もできません。

この素晴らしいエクステンション機能を使わずに3.1.0devをインストールした場合でもエクステンションベースに変更することができます。まずpostgis_upgrade_22_minor.sql,raster_upgrade_22_minor.sql,topology_upgrade_22_minor.sqlのアップグレードスクリプトを実行して最新版にアップグレードします

CREATE EXTENSION postgis FROM unpackaged;
CREATE EXTENSION postgis_topology FROM unpackaged;
CREATE EXTENSION postgis_tiger_geocoder FROM unpackaged;

2.2.6. テスト

PostGISのテストを行うには、次のコマンドを実行します。

make check

このコマンドで、実際のPostgreSQLデータベースに対して生成したライブラリを使用した、様々なチェックとレグレッションテストを行います。

[Note]

PostgreSQL, GEOS または Proj4 を標準の位置にインストールしていない場合には、環境変数LD_LIBRARY_PATHに、ライブラリの位置を追加する必要があるかも知れません。

[Caution]

現在のところmake checkは、チェックを行う際に 環境変数PATHPGPORTによっています。コンフィギュレーションパラメータ--with-pgconfigを使って特定したPostgreSQLではありません。PATHを編集して、コンフィギュレーションの際に検出したPostgreSQLと一致するようにして下さい。もしくは、間もなく襲ってくる頭痛の準備をしておいて下さい。

成功した場合は、テストの出力は次のようなかんじになります。

CUnit - A unit testing framework for C - Version 2.1-2
     http://cunit.sourceforge.net/


Suite: computational_geometry
  Test: test_lw_segment_side ...passed
  Test: test_lw_segment_intersects ...passed
  Test: test_lwline_crossing_short_lines ...passed
  Test: test_lwline_crossing_long_lines ...passed
  Test: test_lwline_crossing_bugs ...passed
  Test: test_lwpoint_set_ordinate ...passed
  Test: test_lwpoint_get_ordinate ...passed
  Test: test_point_interpolate ...passed
  Test: test_lwline_clip ...passed
  Test: test_lwline_clip_big ...passed
  Test: test_lwmline_clip ...passed
  Test: test_geohash_point ...passed
  Test: test_geohash_precision ...passed
  Test: test_geohash ...passed
  Test: test_geohash_point_as_int ...passed
  Test: test_isclosed ...passed
  Test: test_lwgeom_simplify ...passed
Suite: buildarea
  Test: buildarea1 ...passed
  Test: buildarea2 ...passed
  Test: buildarea3 ...passed
  Test: buildarea4 ...passed
  Test: buildarea4b ...passed
  Test: buildarea5 ...passed
  Test: buildarea6 ...passed
  Test: buildarea7 ...passed
Suite: geometry_clean
  Test: test_lwgeom_make_valid ...passed
Suite: clip_by_rectangle
  Test: test_lwgeom_clip_by_rect ...passed
Suite: force_sfs
  Test: test_sfs_11 ...passed
  Test: test_sfs_12 ...passed
  Test: test_sqlmm ...passed
Suite: geodetic
  Test: test_sphere_direction ...passed
  Test: test_sphere_project ...passed
  Test: test_lwgeom_area_sphere ...passed
  Test: test_signum ...passed
  Test: test_gbox_from_spherical_coordinates ...passed
  Test: test_gserialized_get_gbox_geocentric ...passed
  Test: test_clairaut ...passed
  Test: test_edge_intersection ...passed
  Test: test_edge_intersects ...passed
  Test: test_edge_distance_to_point ...passed
  Test: test_edge_distance_to_edge ...passed
  Test: test_lwgeom_distance_sphere ...passed
  Test: test_lwgeom_check_geodetic ...passed
  Test: test_gserialized_from_lwgeom ...passed
  Test: test_spheroid_distance ...passed
  Test: test_spheroid_area ...passed
  Test: test_lwpoly_covers_point2d ...passed
  Test: test_gbox_utils ...passed
  Test: test_vector_angle ...passed
  Test: test_vector_rotate ...passed
  Test: test_lwgeom_segmentize_sphere ...passed
  Test: test_ptarray_contains_point_sphere ...passed
  Test: test_ptarray_contains_point_sphere_iowa ...passed
Suite: GEOS
  Test: test_geos_noop ...passed
  Test: test_geos_subdivide ...passed
  Test: test_geos_linemerge ...passed
Suite: Clustering
  Test: basic_test ...passed
  Test: nonsequential_test ...passed
  Test: basic_distance_test ...passed
  Test: single_input_test ...passed
  Test: empty_inputs_test ...passed
Suite: Clustering Union-Find
  Test: test_unionfind_create ...passed
  Test: test_unionfind_union ...passed
  Test: test_unionfind_ordered_by_cluster ...passed
Suite: homogenize
  Test: test_coll_point ...passed
  Test: test_coll_line ...passed
  Test: test_coll_poly ...passed
  Test: test_coll_coll ...passed
  Test: test_geom ...passed
  Test: test_coll_curve ...passed
Suite: encoded_polyline_input
  Test: in_encoded_polyline_test_geoms ...passed
  Test: in_encoded_polyline_test_precision ...passed
Suite: geojson_input
  Test: in_geojson_test_srid ...passed
  Test: in_geojson_test_bbox ...passed
  Test: in_geojson_test_geoms ...passed
Suite: twkb_input
  Test: test_twkb_in_point ...passed
  Test: test_twkb_in_linestring ...passed
  Test: test_twkb_in_polygon ...passed
  Test: test_twkb_in_multipoint ...passed
  Test: test_twkb_in_multilinestring ...passed
  Test: test_twkb_in_multipolygon ...passed
  Test: test_twkb_in_collection ...passed
  Test: test_twkb_in_precision ...passed
Suite: serialization/deserialization
  Test: test_typmod_macros ...passed
  Test: test_flags_macros ...passed
  Test: test_serialized_srid ...passed
  Test: test_gserialized_from_lwgeom_size ...passed
  Test: test_gbox_serialized_size ...passed
  Test: test_lwgeom_from_gserialized ...passed
  Test: test_lwgeom_count_vertices ...passed
  Test: test_on_gser_lwgeom_count_vertices ...passed
  Test: test_geometry_type_from_string ...passed
  Test: test_lwcollection_extract ...passed
  Test: test_lwgeom_free ...passed
  Test: test_lwgeom_flip_coordinates ...passed
  Test: test_f2d ...passed
  Test: test_lwgeom_clone ...passed
  Test: test_lwgeom_force_clockwise ...passed
  Test: test_lwgeom_calculate_gbox ...passed
  Test: test_lwgeom_is_empty ...passed
  Test: test_lwgeom_same ...passed
  Test: test_lwline_from_lwmpoint ...passed
  Test: test_lwgeom_as_curve ...passed
  Test: test_lwgeom_scale ...passed
  Test: test_gserialized_is_empty ...passed
  Test: test_gbox_same_2d ...passed
Suite: measures
  Test: test_mindistance2d_tolerance ...passed
  Test: test_rect_tree_contains_point ...passed
  Test: test_rect_tree_intersects_tree ...passed
  Test: test_lwgeom_segmentize2d ...passed
  Test: test_lwgeom_locate_along ...passed
  Test: test_lw_dist2d_pt_arc ...passed
  Test: test_lw_dist2d_seg_arc ...passed
  Test: test_lw_dist2d_arc_arc ...passed
  Test: test_lw_arc_length ...passed
  Test: test_lw_dist2d_pt_ptarrayarc ...passed
  Test: test_lw_dist2d_ptarray_ptarrayarc ...passed
  Test: test_lwgeom_tcpa ...passed
  Test: test_lwgeom_is_trajectory ...passed
Suite: effectivearea
  Test: do_test_lwgeom_effectivearea_lines ...passed
  Test: do_test_lwgeom_effectivearea_polys ...passed
Suite: miscellaneous
  Test: test_misc_force_2d ...passed
  Test: test_misc_simplify ...passed
  Test: test_misc_count_vertices ...passed
  Test: test_misc_area ...passed
  Test: test_misc_wkb ...passed
  Test: test_grid ...passed
Suite: noding
  Test: test_lwgeom_node ...passed
Suite: encoded_polyline_output
  Test: out_encoded_polyline_test_geoms ...passed
  Test: out_encoded_polyline_test_srid ...passed
  Test: out_encoded_polyline_test_precision ...passed
Suite: geojson_output
  Test: out_geojson_test_precision ...passed
  Test: out_geojson_test_dims ...passed
  Test: out_geojson_test_srid ...passed
  Test: out_geojson_test_bbox ...passed
  Test: out_geojson_test_geoms ...passed
Suite: gml_output
  Test: out_gml_test_precision ...passed
  Test: out_gml_test_srid ...passed
  Test: out_gml_test_dims ...passed
  Test: out_gml_test_geodetic ...passed
  Test: out_gml_test_geoms ...passed
  Test: out_gml_test_geoms_prefix ...passed
  Test: out_gml_test_geoms_nodims ...passed
  Test: out_gml2_extent ...passed
  Test: out_gml3_extent ...passed
Suite: kml_output
  Test: out_kml_test_precision ...passed
  Test: out_kml_test_dims ...passed
  Test: out_kml_test_geoms ...passed
  Test: out_kml_test_prefix ...passed
Suite: svg_output
  Test: out_svg_test_precision ...passed
  Test: out_svg_test_dims ...passed
  Test: out_svg_test_relative ...passed
  Test: out_svg_test_geoms ...passed
  Test: out_svg_test_srid ...passed
Suite: x3d_output
  Test: out_x3d3_test_precision ...passed
  Test: out_x3d3_test_geoms ...passed
  Test: out_x3d3_test_option ...passed
Suite: ptarray
  Test: test_ptarray_append_point ...passed
  Test: test_ptarray_append_ptarray ...passed
  Test: test_ptarray_locate_point ...passed
  Test: test_ptarray_isccw ...passed
  Test: test_ptarray_signed_area ...passed
  Test: test_ptarray_unstroke ...passed
  Test: test_ptarray_insert_point ...passed
  Test: test_ptarray_contains_point ...passed
  Test: test_ptarrayarc_contains_point ...passed
  Test: test_ptarray_scale ...passed
Suite: printing
  Test: test_lwprint_default_format ...passed
  Test: test_lwprint_format_orders ...passed
  Test: test_lwprint_optional_format ...passed
  Test: test_lwprint_oddball_formats ...passed
  Test: test_lwprint_bad_formats ...passed
Suite: SFCGAL
  Test: test_sfcgal_noop ...passed
Suite: split
  Test: test_lwline_split_by_point_to ...passed
  Test: test_lwgeom_split ...passed
Suite: stringbuffer
  Test: test_stringbuffer_append ...passed
  Test: test_stringbuffer_aprintf ...passed
Suite: surface
  Test: triangle_parse ...passed
  Test: tin_parse ...passed
  Test: polyhedralsurface_parse ...passed
  Test: surface_dimension ...passed
Suite: Internal Spatial Trees
  Test: test_tree_circ_create ...passed
  Test: test_tree_circ_pip ...passed
  Test: test_tree_circ_pip2 ...passed
  Test: test_tree_circ_distance ...passed
  Test: test_tree_circ_distance_threshold ...passed
Suite: triangulate
  Test: test_lwgeom_delaunay_triangulation ...passed
Suite: twkb_output
  Test: test_twkb_out_point ...passed
  Test: test_twkb_out_linestring ...passed
  Test: test_twkb_out_polygon ...passed
  Test: test_twkb_out_multipoint ...passed
  Test: test_twkb_out_multilinestring ...passed
  Test: test_twkb_out_multipolygon ...passed
  Test: test_twkb_out_collection ...passed
  Test: test_twkb_out_idlist ...passed
Suite: varint
  Test: test_zigzag ...passed
  Test: test_varint ...passed
  Test: test_varint_roundtrip ...passed
Suite: wkb_input
  Test: test_wkb_in_point ...passed
  Test: test_wkb_in_linestring ...passed
  Test: test_wkb_in_polygon ...passed
  Test: test_wkb_in_multipoint ...passed
  Test: test_wkb_in_multilinestring ...passed
  Test: test_wkb_in_multipolygon ...passed
  Test: test_wkb_in_collection ...passed
  Test: test_wkb_in_circularstring ...passed
  Test: test_wkb_in_compoundcurve ...passed
  Test: test_wkb_in_curvpolygon ...passed
  Test: test_wkb_in_multicurve ...passed
  Test: test_wkb_in_multisurface ...passed
  Test: test_wkb_in_malformed ...passed
Suite: wkb_output
  Test: test_wkb_out_point ...passed
  Test: test_wkb_out_linestring ...passed
  Test: test_wkb_out_polygon ...passed
  Test: test_wkb_out_multipoint ...passed
  Test: test_wkb_out_multilinestring ...passed
  Test: test_wkb_out_multipolygon ...passed
  Test: test_wkb_out_collection ...passed
  Test: test_wkb_out_circularstring ...passed
  Test: test_wkb_out_compoundcurve ...passed
  Test: test_wkb_out_curvpolygon ...passed
  Test: test_wkb_out_multicurve ...passed
  Test: test_wkb_out_multisurface ...passed
  Test: test_wkb_out_polyhedralsurface ...passed
Suite: wkt_input
  Test: test_wkt_in_point ...passed
  Test: test_wkt_in_linestring ...passed
  Test: test_wkt_in_polygon ...passed
  Test: test_wkt_in_multipoint ...passed
  Test: test_wkt_in_multilinestring ...passed
  Test: test_wkt_in_multipolygon ...passed
  Test: test_wkt_in_collection ...passed
  Test: test_wkt_in_circularstring ...passed
  Test: test_wkt_in_compoundcurve ...passed
  Test: test_wkt_in_curvpolygon ...passed
  Test: test_wkt_in_multicurve ...passed
  Test: test_wkt_in_multisurface ...passed
  Test: test_wkt_in_tin ...passed
  Test: test_wkt_in_polyhedralsurface ...passed
  Test: test_wkt_in_errlocation ...passed
Suite: wkt_output
  Test: test_wkt_out_point ...passed
  Test: test_wkt_out_linestring ...passed
  Test: test_wkt_out_polygon ...passed
  Test: test_wkt_out_multipoint ...passed
  Test: test_wkt_out_multilinestring ...passed
  Test: test_wkt_out_multipolygon ...passed
  Test: test_wkt_out_collection ...passed
  Test: test_wkt_out_circularstring ...passed
  Test: test_wkt_out_compoundcurve ...passed
  Test: test_wkt_out_curvpolygon ...passed
  Test: test_wkt_out_multicurve ...passed
  Test: test_wkt_out_multisurface ...passed

Run Summary:    Type  Total    Ran Passed Failed Inactive
              suites     38     38    n/a      0        0
               tests    251    251    251      0        0
             asserts   2468   2468   2468      0      n/a

Elapsed time =    0.298 seconds

Creating database 'postgis_reg'
Loading PostGIS into 'postgis_reg'
  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/postgis.sql
  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/postgis_comments.sql
Loading SFCGAL into 'postgis_reg'
  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/sfcgal.sql
  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/sfcgal_comments.sql
PostgreSQL 9.4.4, compiled by Visual C++ build 1800, 32-bit
  Postgis 2.2.0dev - r13980 - 2015-08-23 06:13:07
  scripts 2.2.0dev r13980
  GEOS: 3.5.0-CAPI-1.9.0 r4088
  PROJ: Rel. 4.9.1, 04 March 2015
  SFCGAL: 1.1.0

Running tests

 loader/Point .............. ok
 loader/PointM .............. ok
 loader/PointZ .............. ok
 loader/MultiPoint .............. ok
 loader/MultiPointM .............. ok
 loader/MultiPointZ .............. ok
 loader/Arc .............. ok
 loader/ArcM .............. ok
 loader/ArcZ .............. ok
 loader/Polygon .............. ok
 loader/PolygonM .............. ok
 loader/PolygonZ .............. ok
 loader/TSTPolygon ......... ok
 loader/TSIPolygon ......... ok
 loader/TSTIPolygon ......... ok
 loader/PointWithSchema ..... ok
 loader/NoTransPoint ......... ok
 loader/NotReallyMultiPoint ......... ok
 loader/MultiToSinglePoint ......... ok
 loader/ReprojectPts ........ ok
 loader/ReprojectPtsGeog ........ ok
 loader/Latin1 .... ok
 loader/Latin1-implicit .... ok
 loader/mfile .... ok
 dumper/literalsrid ....... ok
 dumper/realtable ....... ok
 affine .. ok
 bestsrid .. ok
 binary .. ok
 boundary .. ok
 cluster .. ok
 concave_hull .. ok
 ctors .. ok
 dump .. ok
 dumppoints .. ok
 empty .. ok
 forcecurve .. ok
 geography .. ok
 in_geohash .. ok
 in_gml .. ok
 in_kml .. ok
 in_encodedpolyline .. ok
 iscollection .. ok
 legacy .. ok
 long_xact .. ok
 lwgeom_regress .. ok
 measures .. ok
 operators .. ok
 out_geometry .. ok
 out_geography .. ok
 polygonize .. ok
 polyhedralsurface .. ok
 postgis_type_name .. ok
 regress .. ok
 regress_bdpoly .. ok
 regress_index .. ok
 regress_index_nulls .. ok
 regress_management .. ok
 regress_selectivity .. ok
 regress_lrs .. ok
 regress_ogc .. ok
 regress_ogc_cover .. ok
 regress_ogc_prep .. ok
 regress_proj .. ok
 relate .. ok
 remove_repeated_points .. ok
 removepoint .. ok
 setpoint .. ok
 simplify .. ok
 simplifyvw .. ok
 size .. ok
 snaptogrid .. ok
 split .. ok
 sql-mm-serialize .. ok
 sql-mm-circularstring .. ok
 sql-mm-compoundcurve .. ok
 sql-mm-curvepoly .. ok
 sql-mm-general .. ok
 sql-mm-multicurve .. ok
 sql-mm-multisurface .. ok
 swapordinates .. ok
 summary .. ok
 temporal .. ok
 tickets .. ok
 twkb .. ok
 typmod .. ok
 wkb .. ok
 wkt .. ok
 wmsservers .. ok
 knn .. ok
 hausdorff .. ok
 regress_buffer_params .. ok
 offsetcurve .. ok
 relatematch .. ok
 isvaliddetail .. ok
 sharedpaths .. ok
 snap .. ok
 node .. ok
 unaryunion .. ok
 clean .. ok
 relate_bnr .. ok
 delaunaytriangles .. ok
 clipbybox2d .. ok
 subdivide .. ok
 in_geojson .. ok
 regress_sfcgal .. ok
 sfcgal/empty .. ok
 sfcgal/geography .. ok
 sfcgal/legacy .. ok
 sfcgal/measures .. ok
 sfcgal/regress_ogc_prep .. ok
 sfcgal/regress_ogc .. ok
 sfcgal/regress .. ok
 sfcgal/tickets .. ok
 sfcgal/concave_hull .. ok
 sfcgal/wmsservers .. ok
 sfcgal/approximatemedialaxis .. ok
 uninstall .  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/uninstall_sfcgal.sql
  /projects/postgis/branches/2.2/regress/00-regress-install/share/contrib/postgis/uninstall_postgis.sql
. ok (4336)

Run tests: 118
Failed: 0

-- if you built --with-gui, you should see this too

     CUnit - A unit testing framework for C - Version 2.1-2
     http://cunit.sourceforge.net/


Suite: Shapefile Loader File shp2pgsql Test
  Test: test_ShpLoaderCreate() ...passed
  Test: test_ShpLoaderDestroy() ...passed
Suite: Shapefile Loader File pgsql2shp Test
  Test: test_ShpDumperCreate() ...passed
  Test: test_ShpDumperDestroy() ...passed

Run Summary:    Type  Total    Ran Passed Failed Inactive
              suites      2      2    n/a      0        0
               tests      4      4      4      0        0
             asserts      4      4      4      0      n/a

postgis_tiger_geocoderaddress_standardizerは、現在は、標準的なPostgreSQLインストールチェックにのみ対応しています。これらをテストするには、次のようにします。ご注意: PostGISコードフォルダのルートでmake installを既に行っている場合には、make installは重要ではありません。

address_standardizer用:

cd extensions/address_standardizer
make install
make installcheck
          

出力は次のようなかんじになります。

============== dropping database "contrib_regression" ==============
DROP DATABASE
============== creating database "contrib_regression" ==============
CREATE DATABASE
ALTER DATABASE
============== running regression test queries        ==============
test test-init-extensions     ... ok
test test-parseaddress        ... ok
test test-standardize_address_1 ... ok
test test-standardize_address_2 ... ok

=====================
 All 4 tests passed.
=====================

Tiger Geocodeを使う場合には、使用するPostgreSQLインスタンス内にPostGISとfuzzystrmatchのエクステンションが必要です。PostGISをaddress_standardizer機能付きでビルドした場合は、address_standardizerのテストも行います。

cd extensions/postgis_tiger_geocoder
make install
make installcheck
          

出力は次のようなかんじになります。

============== dropping database "contrib_regression" ==============
DROP DATABASE
============== creating database "contrib_regression" ==============
CREATE DATABASE
ALTER DATABASE
============== installing fuzzystrmatch               ==============
CREATE EXTENSION
============== installing postgis                     ==============
CREATE EXTENSION
============== installing postgis_tiger_geocoder      ==============
CREATE EXTENSION
============== installing address_standardizer        ==============
CREATE EXTENSION
============== running regression test queries        ==============
test test-normalize_address   ... ok
test test-pagc_normalize_address ... ok

=====================
All 2 tests passed.
=====================

2.2.7. インストール

PostGISをインストールするには、次のコマンドを実行します。

make install

これにより、PostGISのインストールファイルが、--prefixパラメータで指定した、適切なサブディレクトリに複写されます。次に特筆すべきサブディレクトリを示します。

  • ローダとダンパのバイナリのインストール先は[prefix]/binです。

  • postgis.sqlなどのSQLファイルのインストール先は[prefix]/share/contribです。

  • PostGISライブラリのインストール先は[prefix]/libです。

先にmake commentsを実行してpostgis_comments.sql, raster_comments.sqlを生成していた場合は、次のコマンドを実行すると、これらのSQLファイルがインストールされます。

make comments-install

[Note]

postgis_comments.sql, raster_comments.sql, topology_comments.sqlは、xsltprocの外部依存ができたので、通常のビルドとインストールから切り離されました。

2.3. PAGC住所標準化ツールのインストールと使用

address_standardizerエクステンションは、別途ダウンロードする必要がある別パッケージとしていました。PostGIS 2.2からは同梱されています。address_standardizeの追加情報、できること、および、コンフィギュレーション方法については、Section 4.5, “住所標準化”をご覧下さい。

標準化エクステンションは、Normalize_Addressの後継で、PostGISに入っているTigerジオコーダエクステンションに使うことができます。この場合の使い方についてはSection 2.4.3, “TigerジオコーダをPostGISデータベースで有効にする: エクステンションを使用”を参照して下さい。また、ユーザ自身がつくるジオコーダの要素として使用したり、住所の比較を簡単にするために住所を標準化するために使うことができます。

住所標準化エクステンションはPCREに依存しています。PCREは多くのUNIX系システムにインストールされていますが、http://www.pcre.orgから最新版をダウンロードできます。Section 2.2.3, “コンフィギュレーション”の際にPCREを発見すると、住所標準化エクステンションが自動的にビルドされます。使用したいPCREのインストールが独自なものである場合は、configureに--with-pcredir=/path/to/pcreを渡します。/path/to/pcreは、PCREのincludeとlibのあるルートフォルダです。

Windowsでは、PostGIS 2.1以上に住所標準化エクステンションが同梱されているので、コンパイルを行わずに、すぐにCREATE EXTENSIONに行くことができます。

インストールしたら、対象データベースに接続して次のSQLが実行できます。

CREATE EXTENSION address_standardizer;

次のテストでは、rules, gaz, lexテーブルは必要ありません。

SELECT num, street, city, state, zip
 FROM parse_address('1 Devonshire Place PH301, Boston, MA 02109');

出力は次のようになります。

num |         street         |  city  | state |  zip
-----+------------------------+--------+-------+-------
 1   | Devonshire Place PH301 | Boston | MA    | 02109

2.3.1. Regex::Assembleのインストール

PerlのRegex::Assembleは、ソースツリーの一部がこれで作られていますが、住所標準化エクステンションではもはや不要です。ただし、usps-st-city-orig.txtまたはusps-st-city-orig.txt usps-st-city-adds.txを編集する必要がある場合は、parseaddress-stcities.hのリビルドでRegex:Assembleが必要です。

cpan Regexp::Assemble

Ubuntu / Degianの場合には、次のようにしなければならないかも知れません。

sudo perl -MCPAN -e "install Regexp::Assemble"

2.4. Tigerジオコーダのインストールとアップグレードとデータロード

Tigerジオコーダのような拡張機能はPostGISディストリビューションに同梱されていません。Tigerジオコーダエクステンションが無かったり、インストールしているものより新しい版のものが欲しい場合には、Windows Unreleased Versions節でPostgreSQLの版に合ったパッケージにあるshare/extension/postgis_tiger_geocoder.*ファイルを使います。これらのパッケージはWindows用ですが、postgis_tige_geocoderエクステンションファイルは、SQLとPL/pgSQLだけですので、他のOSでも動作します。

2.4.1. TigerジオコーダをPostGISデータベースで有効にする: エクステンションを使用

PostgreSQL 9.1以上とPostGIS 2.1.0を使用している場合は、Tigerジオコーダのインストールで、新しいエクステンションモデルの利点を得ることができます。次のようにします。

  1. まず、通常の方法で、PostGIS 2.1.0のバイナリを取得するか、コンパイルしてインストールします。これにより重要なエクステンションファイルとTigerジオコーダのファイルがインストールされます。

  2. psql、pgAdminまたは他のツールでデータベースに接続して、次のSQLコマンドを実行します。既にPostGISを持っているデータベースにインストールする場合は、一つ目の手順は不要です。fuzzystrmatchエクステンションが既にインストールされている場合は、二つ目の手順は不要です。

    CREATE EXTENSION postgis;
    CREATE EXTENSION fuzzystrmatch;
    CREATE EXTENSION postgis_tiger_geocoder;
    -- 規則を基にした住所標準化 (pagc_normalize_address)を使いたい場合の任意実行
    CREATE EXTENSION address_standardizer;

    既にpostgis_tiger_geocoderエクステンションをインストールしていて、最新版に更新するだけの場合には、次を実行します。

    ALTER EXTENSION postgis UPDATE;
    ALTER EXTENSION postgis_tiger_geocoder UPDATE;

    独自のエントリを生成した場合や、tiger.loader_platformtiger.loader_variablesに変更を加えた場合には、これらをアップデートしなければならないことがあります。

  3. 正しくインストールされたかを確認するために、インストール対象データベース内で次のSQLを実行します。

    SELECT na.address, na.streetname,na.streettypeabbrev, na.zip
            FROM normalize_address('1 Devonshire Place, Boston, MA 02109') AS na;

    出力は次のようになります。

    address | streetname | streettypeabbrev |  zip
    ---------+------------+------------------+-------
               1 | Devonshire | Pl               | 02109
  4. tiger.loader_platformテーブルの、実行ファイルやサーバのパスを持つ新しいレコードを生成します。

    shコンベンションのあとにdebbieというプロファイルを生成する例として、次のコマンドを実行します。

    INSERT INTO tiger.loader_platform(os, declare_sect, pgbin, wget, unzip_command, psql, path_sep,
                       loader, environ_set_command, county_process_command)
    SELECT 'debbie', declare_sect, pgbin, wget, unzip_command, psql, path_sep,
               loader, environ_set_command, county_process_command
      FROM tiger.loader_platform
      WHERE os = 'sh';

    それから、declare_sectカラム内のパスを編集して、Debbieのpg, unzip, shp2pgsql, psql他のパス位置に適応するようにします。

    loader_platformテーブルを編集しない場合は、一般的なアイテムの位置を持っているので、スクリプトが生成された後で、スクリプトを編集しなければなりません。

  5. PostGIS 2.4.1からは、ZTCA5 (Zip Code 5 digit Tabulation Area)のロード手順が変更され、有効になった時にLoader_Generate_Nation_Scriptの一部として現在のZCTA5データをロードするようになりました。デフォルトでは切られています。ロードにかなりの時間 (20から60分)が取られ、かなりのディスクスペースを占有するのに、そんなに頻繁には使わないためです。

    有効にするには、次のようにします。

    UPDATE tiger.loader_lookuptables SET load = true WHERE table_name = 'zcta510';

    境界のフィルタが追加され、ちょうど境界内のZIPに制限された場合に、Geocode関数は、ZCTA5が存在するなら使います。Reverse_Geocode関数は、返された住所にZIPコードが無い場合に (しばしば高速道路での逆ジオコーディングで発生します)、これを使います。

  6. サーバまたはローカル (サーバへのネットワーク接続が早い場合)のルートにgisdataというフォルダを作成します。このフォルダはTigerファイルがダウンロードされ、処理される場所です。サーバのルートにフォルダを作ると不幸になる場合や、単に他のフォルダに移したい場合には、tiger.loader_variablesテーブルのstaging_foldフィールドを編集します。

  7. gisdataフォルダ内にtempというフォルダを作成します。もしくは、staging_foldで示されたフォルダを作成します。ローダがダウンロードしたTigerデータを展開する場所です。

  8. そして、SQL関数Loader_Generate_Nation_Scriptを実行して、独自のプロファイルの名前を使うか確認し、.shまたは.batファイルにスクリプトを複写します。たとえば、新しいプロファイルで国のロードを行う場合には、次のようにします。

    psql -c "SELECT Loader_Generate_Nation_Script('debbie')" -d geocoder -tA 
    > /gisdata/nation_script_load.sh
  9. 生成された国データをロードするコマンドラインスクリプトを実行します。

    cd /gisdata
    sh nation_script_load.sh
  10. 国スクリプトを実行した後、tiger_dataスキーマに三つのテーブルが作られ、データが格納されています。次のクエリをpsqlかpgAdminから実行して、確認します。

    SELECT count(*) FROM tiger_data.county_all;
    count
    -------
      3233
    (1 row)
    SELECT count(*) FROM tiger_data.state_all;
    count
    -------
        56
    (1 row)
    
  11. デフォルトではbg, tract, tabblockに対応するテーブルはロードされません。ジオコーダはこれらのテーブルを使いませんが、一般に、人口統計に使います。州データのロードの一部としてロードするには、次の手続きを実行して有効にします。

    UPDATE tiger.loader_lookuptables SET load = true WHERE load = false AND lookup_name IN('tract', 'bg', 'tabblock');

    もしくは、Loader_Generate_Census_Scriptを使って州のデータをロードした後に、これらのテーブルだけをロードできます。

  12. データをロードしたい州ごとに、Loader_Generate_Scriptで州スクリプトを作ります。

    [Warning]

    国データのロードを完了する前に*州スクリプトを作ってはなりません*。州スクリプトは国スクリプトでロードされる国リストを利用するためです。

  13. psql -c "SELECT Loader_Generate_Script(ARRAY['MA'], 'debbie')" -d geocoder -tA 
    > /gisdata/ma_load.sh
  14. 生成されたコマンドラインスクリプトを実行します。

    cd /gisdata
    sh ma_load.sh
  15. 全てのデータのロードが完了するか中断ポイントに達した後に、全てのtigerテーブルに対してanalyzeを実行して、(継承されたものも含めて)状態を更新するのは良いことです。

    SELECT install_missing_indexes();
    vacuum analyze verbose tiger.addr;
    vacuum analyze verbose tiger.edges;
    vacuum analyze verbose tiger.faces;
    vacuum analyze verbose tiger.featnames;
    vacuum analyze verbose tiger.place;
    vacuum analyze verbose tiger.cousub;
    vacuum analyze verbose tiger.county;
    vacuum analyze verbose tiger.state;
    vacuum analyze verbose tiger.zip_lookup_base;
    vacuum analyze verbose tiger.zip_state;
    vacuum analyze verbose tiger.zip_state_loc;

2.4.1.1. Tigerジオコーダ通常インストールのエクステンションモデルへの変換

エクステンションモデルを使わずにTigerジオコーダをインストールしている場合に、次のようにして、エクステンションモデルに変換できます。

  1. Section 2.4.5, “Tigerジオコーダのアップグレード”の指示に従って非エクステンションモデルのアップグレードを行います。

  2. psqlまたはpgAdminでデータベースに接続して、次のコマンドを実行します。

    CREATE EXTENSION postgis_tiger_geocoder FROM unpackaged;

2.4.2. TigerジオコーダをPostGISデータベースで有効にする: エクステンション不使用

まず、上述の手順でPostGISをインストールします。

extrasフォルダが無い場合、http://postgis.net/stuff/postgis-3.1.0dev.tar.gzをダウンロードします。

tar xvfz postgis-3.1.0dev.tar.gz

cd postgis-3.1.0dev/extras/tiger_geocoder

tiger_loader_2015.sql (違う年のものをロードしたくないならば最新のローダファイル)をあなたの実行サーバ等のパスに編集します。もしくはloader_platformがインストールされた後に一度これを更新します。このファイルもloader_platformも編集しない場合には、一般的なアイテムの位置を持っているだけなので、Loader_Generate_Nation_ScriptLoader_Generate_Scriptを実行した後に、生成されたスクリプトを編集しなければなりません。

初めてTigerジオコーダをインストールする場合は、Windowsではcreate_geocode.batを、またLinux/Unix/Mac OSXではcreate_geocode.shを、使用するPostgreSQLにとって独自の設定に変更したうえで、コマンドラインから対応するスクリプトを実行します。

データベースにtigerスキーマがあることを確認します。もし無い場合は、次の行を参考に、コマンドを実行します。

ALTER DATABASE geocoder SET search_path=public, tiger;

住所正規化機能は、トリッキーな住所を除いて、大体データなしで動作します。テストを実行して次のように見えることを確認して下さい。

SELECT pprint_addy(normalize_address('202 East Fremont Street, Las Vegas, Nevada 89101')) As pretty_address;
pretty_address
---------------------------------------
202 E Fremont St, Las Vegas, NV 89101
                        

2.4.3. TigerジオコーダをPostGISデータベースで有効にする: エクステンションを使用

皆さんが問題と思われるの多くのことのひとつに、ジオコーディング前の準備に住所を正規化する関数Normalize_Addressがあります。住所正規化は万全と言うにはほど遠く、パッチをあてようとすると膨大な資源を費やします。よって、より良い住所標準化エンジンを持つ他のプロジェクトに統合しました。この新しい住所標準化を使うには、Section 2.3, “PAGC住所標準化ツールのインストールと使用”で記述するようにエクステンションをコンパイルし、使用するデータベースにインストールします。

このエクステンションをpostgis_tiger_geocoderをインストールしているデータベースにインストールすると、Pagc_Normalize_Address文字列のストリート住所を与えると、道路後置辞、前置辞、標準タイプ、番地、ストリート名等を複数フィールドに分解して持つnorm_addy複合型を返します。この関数は、tiger_geocoder同梱のルックアップテーブルだけを使います (Tigerデータは不要です)。住所標準化エクステンションが必要です。を、Normalize_Addressの代わりに使うことができます。このエクステンションはTigerジオコーダからは見えないので、国際的な住所といった他のデータソースでも使えます。Tigerジオコーダエクステンションは、その版の規則テーブル (tiger.pagc_rules), gaz table (tiger.pagc_gaz), lexテーブル (tiger.pagc_lex)を同梱しています。これらは、必要に応じて標準化の改善のために追加や更新ができます。

2.4.4. Tigerデータのロード

データロードの説明の詳細はextras/tiger_geocoder/tiger_2011/READMEにあります。これは一般的な手順を示しています。

ロードプロセスによって、米センサスウェブサイトから個々の国ファイル、リクエストされた州のデータをダウンロードし、ファイルを展開し、個別の州をそれぞれの州テーブルの集合にロードします。各州のテーブルは、tigerスキーマで定義されたテーブルを継承しているので、これらのテーブルに対して全てのデータにアクセスするためのクエリを出すことができますし、州の再読み込みが必要となったり、州が必要ない場合には、Drop_State_Tables_Generate_Scriptで、いつでも州テーブルの集合を削除するクエリを出すことができます。

データのロードを可能にするためには次のツールが必要です。

  • センサスウェブサイトから取得するZIPファイルを展開するツール。

    Unix系システムでは、unzip実行ファイルです。通常は、ほとんどのUnix系プラットフォームで既にインストールされています。

    Windowsでは7-zipです。http://www.7-zip.org/からダウンロードできる無償の圧縮解答ツールです。

  • shp2pgsqlコマンド。PostGISインストール時にデフォルトでインストールされます。

  • wgetコマンド。通常はほとんどのUnix/Linuxシステムにインストールされている、ウェブ取得ツールです。

    Windows用については、コンパイル済みのバイナリをhttp://gnuwin32.sourceforge.net/packages/wget.htmから取得できます。

tiger_2010からアップグレードする場合には、最初にDrop_Nation_Tables_Generate_Scriptを生成、実行する必要があります。州データをロードする前に、Loader_Generate_Nation_Scriptで国データをロードする必要があります。これによって、環境に合ったローダスクリプトが生成されます。Loader_Generate_Nation_Scriptは、一度の操作で、(2010からの)アップグレードと、新しいインストールが行われます。

州データをロードするには、Loader_Generate_Scriptを参照して、手持ちのプラットフォームで動作する、求める州データをロードするデータロードスクリプトを生成します。州データはひとつずつダウンロードできることに注意して下さい。一度に必要な州の全てについてデータをロードする必要はありません。必要なだけダウンロードできます。

求める州データをロードした後は、Install_Missing_Indexesに示すように、

SELECT install_missing_indexes();

を実行するようにして下さい。

行うべきことができたかをテストするために、Geocodeを使用する州の中の住所についてジオコーダを実行してみます。

2.4.5. Tigerジオコーダのアップグレード

2.0以上に含まれるTigerジオコーダがインストールされている場合には、どうしても必要な訂正があるときは、いつでも臨時のアーカイブファイルからでも機能のアップグレードができます。 これは、エクステンションでインストールされていないTigerジオコーダで動作します。

extrasフォルダが無い場合、http://postgis.net/stuff/postgis-3.1.0dev.tar.gzをダウンロードします。

tar xvfz postgis-3.1.0dev.tar.gz

cd postgis-3.1.0dev/extras/tiger_geocoder/tiger_2011

Windowsの場合はupgrade_geocoder.batスクリプト、Linux/Unix/MacOS Xの場合はupgrade_geocoder.shスクリプトの位置を特定します。 PostGISデータベースの資格情報を持つように編集します。

2010または2011からアップグレードする場合には、確実にローダスクリプトのコメントアウトを消すと、2012データのロードのための最新のスクリプトを得ます。

対応するスクリプトをコマンドラインから実行します。

次に、全ての国テーブルを削除し、新しい国テーブルをロードします。Drop_Nation_Tables_Generate_Scriptに詳細がある通り、このSQLステートメントを使った削除スクリプトを生成します。

SELECT drop_nation_tables_generate_script();

生成した削除SQLステートメントを実行します。

Loader_Generate_Nation_Scriptに詳細がある通り、このSELECTステートメントを使った削除スクリプトを生成します。

Windows向け

SELECT loader_generate_nation_script('windows'); 

Unix/Linux向け

SELECT loader_generate_nation_script('sh');

生成したスクリプトの実行方法に関する説明は、Section 2.4.4, “Tigerデータのロード”を参照して下さい。これは一度だけ実行する必要があります。

[Note]

2010/2011州テーブルを混在させることができ、それぞれの州について個別にアップグレードできます。2011にアップグレードする前に、まず、Drop_State_Tables_Generate_Scriptを使って、2010州テーブルを削除します。

2.5. 共通の問題

インストールやアップグレードが思うようにいかない時にチェックすることがいくつかあります。

  1. PostgreSQL 9.6以上をインストールしているか、実行中のPostgreSQLと同じ版のソースでコンパイルしているか、をチェックします。(Linuxの)ディストリビューションによって既にPostgreSQLがインストールされている時や、 PostgreSQLを以前にインストールして忘れた場合に、 混乱が発生することがあります。PostGISはPostgreSQL 9.6以上で動作します。古い版のものを使った場合には、おかしな予想外のエラーメッセージが表示されます。実行中のPostgreSQLの版をチェックするには、psqlを使ってデータベースを接続して、次のクエリを実行して下さい。

    SELECT version();

    RPMベースのディストリビューションを実行している場合、 プリインストールされたパッケージが存在するかのチェックは、rpm コマンドを使ってrpm -qa | grep postgresqlでチェックできます。

  2. アップグレードに失敗する場合、既にPostGISがインストールされているデータベースにリストアしているか確認して下さい。

    SELECT postgis_full_version();

また、コンフィギュアが正しくPostgreSQL、Proj4ライブラリ、GEOSライブラリのインストール先を検出したかチェックして下さい。

  1. コンフィギュアからの出力でpostgis_config.hファイルが作られます。POSTGIS_PGSQL_VERSIONPOSTGIS_PROJ_VERSIONおよびPOSTGIS_GEOS_VERSION変数が正しくセットされたかをチェックして下さい。

Chapter 3. PostGIS Administration

3.1. Tuning your configuration for performance

Tuning for PostGIS is much like tuning for any PostgreSQL workload. The only additional note to keep in mind is that geometries and rasters are heavy so memory related optimizations generally have more of an impact on PostGIS than other types of PostgreSQL queries.

For general details about optimizing PostgreSQL, refer to Tuning your PostgreSQL Server.

For PostgreSQL 9.4+ all these can be set at the server level without touching postgresql.conf or postgresql.auto.conf by using the ALTER SYSTEM.. command.

ALTER SYSTEM SET work_mem = '256MB';
-- this will force, non-startup configs to take effect for new connections
SELECT pg_reload_conf();
-- show current setting value
-- use SHOW ALL to see all settings
SHOW work_mem;

In addition to these settings, PostGIS also has some custom settings which you can find listed in Section 5.2, “PostGIS GUC (Grand Unified Custom)変数”.

3.1.1. Startup

These settings are configured in postgresql.conf:

constraint_exclusion

  • Default: partition

  • This is generally used for table partitioning. The default for this is set to "partition" which is ideal for PostgreSQL 8.4 and above since it will force the planner to only analyze tables for constraint consideration if they are in an inherited hierarchy and not pay the planner penalty otherwise.

shared_buffers

  • Default: ~128MB in PostgreSQL 9.6

  • Set to about 25% to 40% of available RAM. On windows you may not be able to set as high.

max_worker_processes This setting is only available for PostgreSQL 9.4+. For PostgreSQL 9.6+ this setting has additional importance in that it controls the max number of processes you can have for parallel queries.

  • Default: 8

  • Sets the maximum number of background processes that the system can support. This parameter can only be set at server start.

3.1.2. Runtime

work_mem (the memory used for sort operations and complex queries)

  • Default: 1-4MB

  • Adjust up for large dbs, complex queries, lots of RAM

  • Adjust down for many concurrent users or low RAM.

  • If you have lots of RAM and few developers:

    SET work_mem TO '256MB';

maintenance_work_mem (used for VACUUM, CREATE INDEX, etc.)

  • Default: 16-64MB

  • Generally too low - ties up I/O, locks objects while swapping memory

  • Recommend 32MB to 1GB on production servers w/lots of RAM, but depends on the # of concurrent users. If you have lots of RAM and few developers:

    SET maintenance_work_mem TO '1GB';

max_parallel_workers_per_gather

This setting is only available for PostgreSQL 9.6+ and will only affect PostGIS 2.3+, since only PostGIS 2.3+ supports parallel queries. If set to higher than 0, then some queries such as those involving relation functions like ST_Intersects can use multiple processes and can run more than twice as fast when doing so. If you have a lot of processors to spare, you should change the value of this to as many processors as you have. Also make sure to bump up max_worker_processes to at least as high as this number.

  • Default: 0

  • Sets the maximum number of workers that can be started by a single Gather node. Parallel workers are taken from the pool of processes established by max_worker_processes. Note that the requested number of workers may not actually be available at run time. If this occurs, the plan will run with fewer workers than expected, which may be inefficient. Setting this value to 0, which is the default, disables parallel query execution.

3.2. Configuring raster support

If you enabled raster support you may want to read below how to properly configure it.

As of PostGIS 2.1.3, out-of-db rasters and all raster drivers are disabled by default. In order to re-enable these, you need to set the following environment variables POSTGIS_GDAL_ENABLED_DRIVERS and POSTGIS_ENABLE_OUTDB_RASTERS in the server environment. For PostGIS 2.2, you can use the more cross-platform approach of setting the corresponding Section 5.2, “PostGIS GUC (Grand Unified Custom)変数”.

If you want to enable offline raster:

POSTGIS_ENABLE_OUTDB_RASTERS=1

Any other setting or no setting at all will disable out of db rasters.

In order to enable all GDAL drivers available in your GDAL install, set this environment variable as follows

POSTGIS_GDAL_ENABLED_DRIVERS=ENABLE_ALL

If you want to only enable specific drivers, set your environment variable as follows:

POSTGIS_GDAL_ENABLED_DRIVERS="GTiff PNG JPEG GIF XYZ"
[Note]

If you are on windows, do not quote the driver list

Setting environment variables varies depending on OS. For PostgreSQL installed on Ubuntu or Debian via apt-postgresql, the preferred way is to edit /etc/postgresql/10/main/environment where 10 refers to version of PostgreSQL and main refers to the cluster.

On windows, if you are running as a service, you can set via System variables which for Windows 7 you can get to by right-clicking on Computer->Properties Advanced System Settings or in explorer navigating to Control Panel\All Control Panel Items\System. Then clicking Advanced System Settings ->Advanced->Environment Variables and adding new system variables.

After you set the environment variables, you'll need to restart your PostgreSQL service for the changes to take effect.

3.3. Creating spatial databases

3.3.1. Spatially enable database using EXTENSION

If you are using PostgreSQL 9.1+ and have compiled and installed the extensions/postgis modules, you can turn a database into a spatial one using the EXTENSION mechanism.

Core postgis extension includes geometry, geography, spatial_ref_sys and all the functions and comments. Raster and topology are packaged as a separate extension.

Run the following SQL snippet in the database you want to enable spatially:

CREATE EXTENSION IF NOT EXISTS plpgsql;
      CREATE EXTENSION postgis;
      CREATE EXTENSION postgis_raster; -- OPTIONAL
      CREATE EXTENSION postgis_topology; -- OPTIONAL

3.3.2. Spatially enable database without using EXTENSION (discouraged)

[Note]

This is generally only needed if you cannot or don't want to get PostGIS installed in the PostgreSQL extension directory (for example during testing, development or in a restricted environment).

Adding PostGIS objects and function definitions into your database is done by loading the various sql files located in [prefix]/share/contrib as specified during the build phase.

The core PostGIS objects (geometry and geography types, and their support functions) are in the postgis.sql script. Raster objects are in the rtpostgis.sql script. Topology objects are in the topology.sql script.

For a complete set of EPSG coordinate system definition identifiers, you can also load the spatial_ref_sys.sql definitions file and populate the spatial_ref_sys table. This will permit you to perform ST_Transform() operations on geometries.

If you wish to add comments to the PostGIS functions, you can find them in the postgis_comments.sql script. Comments can be viewed by simply typing \dd [function_name] from a psql terminal window.

Run the following Shell commands in your terminal:

DB=[yourdatabase]
    SCRIPTSDIR=`pg_config --sharedir`/contrib/postgis-3.1/

    # Core objects
    psql -d ${DB} -f ${SCRIPTSDIR}/postgis.sql
    psql -d ${DB} -f ${SCRIPTSDIR}/spatial_ref_sys.sql
    psql -d ${DB} -f ${SCRIPTSDIR}/postgis_comments.sql # OPTIONAL

    # Raster support (OPTIONAL)
    psql -d ${DB} -f ${SCRIPTSDIR}/rtpostgis.sql
    psql -d ${DB} -f ${SCRIPTSDIR}/raster_comments.sql # OPTIONAL

    # Topology support (OPTIONAL)
    psql -d ${DB} -f ${SCRIPTSDIR}/topology.sql
    psql -d ${DB} -f ${SCRIPTSDIR}/topology_comments.sql # OPTIONAL

3.3.3. Create a spatially-enabled database from a template

Some packaged distributions of PostGIS (in particular the Win32 installers for PostGIS >= 1.1.5) load the PostGIS functions into a template database called template_postgis. If the template_postgis database exists in your PostgreSQL installation then it is possible for users and/or applications to create spatially-enabled databases using a single command. Note that in both cases, the database user must have been granted the privilege to create new databases.

From the shell:

# createdb -T template_postgis my_spatial_db

From SQL:

postgres=# CREATE DATABASE my_spatial_db TEMPLATE=template_postgis

3.4. Upgrading spatial databases

Upgrading existing spatial databases can be tricky as it requires replacement or introduction of new PostGIS object definitions.

Unfortunately not all definitions can be easily replaced in a live database, so sometimes your best bet is a dump/reload process.

PostGIS provides a SOFT UPGRADE procedure for minor or bugfix releases, and a HARD UPGRADE procedure for major releases.

Before attempting to upgrade PostGIS, it is always worth to backup your data. If you use the -Fc flag to pg_dump you will always be able to restore the dump with a HARD UPGRADE.

3.4.1. Soft upgrade

If you installed your database using extensions, you'll need to upgrade using the extension model as well. If you installed using the old sql script way, then you should upgrade using the sql script way. Please refer to the appropriate.

3.4.1.1. Soft Upgrade Pre 9.1+ or without extensions

This section applies only to those who installed PostGIS not using extensions. If you have extensions and try to upgrade with this approach you'll get messages like:

can't drop ... because postgis extension depends on it

NOTE: if you are moving from PostGIS 1.* to PostGIS 2.* or from PostGIS 2.* prior to r7409, you cannot use this procedure but would rather need to do a HARD UPGRADE.

After compiling and installing (make install) you should find a set of *_upgrade.sql files in the installation folders. You can list them all with:

ls `pg_config --sharedir`/contrib/postgis-3.1.0dev/*_upgrade.sql

Load them all in turn, starting from postgis_upgrade.sql.

psql -f postgis_upgrade.sql -d your_spatial_database

The same procedure applies to raster, topology and sfcgal extensions, with upgrade files named rtpostgis_upgrade.sql, topology_upgrade.sql and sfcgal_upgrade.sql respectively. If you need them:

psql -f rtpostgis_upgrade.sql -d your_spatial_database
psql -f topology_upgrade.sql -d your_spatial_database
psql -f sfcgal_upgrade.sql -d your_spatial_database
[Note]

If you can't find the postgis_upgrade.sql specific for upgrading your version you are using a version too early for a soft upgrade and need to do a HARD UPGRADE.

The ??? function should inform you about the need to run this kind of upgrade using a "procs need upgrade" message.

3.4.1.2. Soft Upgrade 9.1+ using extensions

If you originally installed PostGIS with extensions, then you need to upgrade using extensions as well. Doing a minor upgrade with extensions, is fairly painless.

ALTER EXTENSION postgis UPDATE TO "3.1.0dev";
ALTER EXTENSION postgis_topology UPDATE TO "3.1.0dev";

If you get an error notice something like:

No migration path defined for ... to 3.1.0dev

Then you'll need to backup your database, create a fresh one as described in Section 3.3.1, “Spatially enable database using EXTENSION” and then restore your backup ontop of this new database.

If you get a notice message like:

Version "3.1.0dev" of extension "postgis" is already installed

Then everything is already up to date and you can safely ignore it. UNLESS you're attempting to upgrade from an development version to the next (which doesn't get a new version number); in that case you can append "next" to the version string, and next time you'll need to drop the "next" suffix again:

ALTER EXTENSION postgis UPDATE TO "3.1.0devnext";
ALTER EXTENSION postgis_topology UPDATE TO "3.1.0devnext";
[Note]

If you installed PostGIS originally without a version specified, you can often skip the reinstallation of postgis extension before restoring since the backup just has CREATE EXTENSION postgis and thus picks up the newest latest version during restore.

[Note]

If you are upgrading PostGIS extension from a version prior to 3.0.0 you'll end up with an unpackaged PostGIS Raster support. You can repackage the raster support using:

    CREATE EXTENSION postgis_raster FROM unpackaged;
    

And then, if you don't need it, drop it with:

DROP EXTENSION postgis_raster;
    

3.4.2. Hard upgrade

By HARD UPGRADE we mean full dump/reload of postgis-enabled databases. You need a HARD UPGRADE when PostGIS objects' internal storage changes or when SOFT UPGRADE is not possible. The Release Notes appendix reports for each version whether you need a dump/reload (HARD UPGRADE) to upgrade.

The dump/reload process is assisted by the postgis_restore.pl script which takes care of skipping from the dump all definitions which belong to PostGIS (including old ones), allowing you to restore your schemas and data into a database with PostGIS installed without getting duplicate symbol errors or bringing forward deprecated objects.

Supplementary instructions for windows users are available at Windows Hard upgrade.

The Procedure is as follows:

  1. Create a "custom-format" dump of the database you want to upgrade (let's call it olddb) include binary blobs (-b) and verbose (-v) output. The user can be the owner of the db, need not be postgres super account.

    pg_dump -h localhost -p 5432 -U postgres -Fc -b -v -f "/somepath/olddb.backup" olddb
  2. Do a fresh install of PostGIS in a new database -- we'll refer to this database as newdb. Please refer to Section 3.3.2, “Spatially enable database without using EXTENSION (discouraged)” and Section 3.3.1, “Spatially enable database using EXTENSION” for instructions on how to do this.

    The spatial_ref_sys entries found in your dump will be restored, but they will not override existing ones in spatial_ref_sys. This is to ensure that fixes in the official set will be properly propagated to restored databases. If for any reason you really want your own overrides of standard entries just don't load the spatial_ref_sys.sql file when creating the new db.

    If your database is really old or you know you've been using long deprecated functions in your views and functions, you might need to load legacy.sql for all your functions and views etc. to properly come back. Only do this if _really_ needed. Consider upgrading your views and functions before dumping instead, if possible. The deprecated functions can be later removed by loading uninstall_legacy.sql.

  3. Restore your backup into your fresh newdb database using postgis_restore.pl. Unexpected errors, if any, will be printed to the standard error stream by psql. Keep a log of those.

    perl utils/postgis_restore.pl "/somepath/olddb.backup" | psql -h localhost -p 5432 -U postgres newdb 2> errors.txt

Errors may arise in the following cases:

  1. Some of your views or functions make use of deprecated PostGIS objects. In order to fix this you may try loading legacy.sql script prior to restore or you'll have to restore to a version of PostGIS which still contains those objects and try a migration again after porting your code. If the legacy.sql way works for you, don't forget to fix your code to stop using deprecated functions and drop them loading uninstall_legacy.sql.

  2. Some custom records of spatial_ref_sys in dump file have an invalid SRID value. Valid SRID values are bigger than 0 and smaller than 999000. Values in the 999000.999999 range are reserved for internal use while values > 999999 can't be used at all. All your custom records with invalid SRIDs will be retained, with those > 999999 moved into the reserved range, but the spatial_ref_sys table would lose a check constraint guarding for that invariant to hold and possibly also its primary key ( when multiple invalid SRIDS get converted to the same reserved SRID value ).

    In order to fix this you should copy your custom SRS to a SRID with a valid value (maybe in the 910000..910999 range), convert all your tables to the new srid (see UpdateGeometrySRID), delete the invalid entry from spatial_ref_sys and re-construct the check(s) with:

    ALTER TABLE spatial_ref_sys ADD CONSTRAINT spatial_ref_sys_srid_check check (srid > 0 AND srid < 999000 );

    ALTER TABLE spatial_ref_sys ADD PRIMARY KEY(srid));

    If you are upgrading an old database containing french IGN cartography, you will have probably SRIDs out of range and you will see, when importing your database, issues like this :

     WARNING: SRID 310642222 converted to 999175 (in reserved zone)

    In this case, you can try following steps : first throw out completely the IGN from the sql which is resulting from postgis_restore.pl. So, after having run :

    perl utils/postgis_restore.pl "/somepath/olddb.backup" > olddb.sql

    run this command :

    grep -v IGNF olddb.sql > olddb-without-IGN.sql

    Create then your newdb, activate the required Postgis extensions, and insert properly the french system IGN with : this script After these operations, import your data :

    psql -h localhost -p 5432 -U postgres -d newdb -f olddb-without-IGN.sql  2> errors.txt

Chapter 4. PostGIS Usage

Table of Contents
4.1. PostGISを使う: データ管理とクエリ
4.1.1. GISオブジェクト
4.1.2. PostGISジオグラフィ型
4.1.3. OpenGIS標準を使う
4.1.4. GIS (ベクタ)データをロードする
4.1.5. GISデータを検索する
4.1.6. インデックスを構築する
4.1.7. 複雑なクエリ
4.2. PostGISを使う: アプリケーションを構築する
4.2.1. MapServerを使う
4.2.2. Javaクライアント (JDBC)
4.2.3. Cクライアント (libpq)
4.3. ラスタデータの管理、クエリ、アプリケーション
4.3.1. ラスタのロードと生成
4.3.2. ラスタカタログ
4.3.3. PostGISラスタを使ったカスタムアプリケーションの構築
4.4. トポロジ
4.4.1. トポロジ型
4.4.2. トポロジドメイン
4.4.3. トポロジ管理とTopoGeometry管理
4.4.4. トポロジ管理とTopoGeometry管理
4.4.5. トポロジコンストラクタ
4.4.6. トポロジエディタ
4.4.7. トポロジアクセサ
4.4.8. トポロジ処理
4.4.9. TopoGeometryコンストラクタ
4.4.10. TopoGeometryエディタ
4.4.11. TopoGeometryアクセサ
4.4.12. TopoGeometry出力
4.4.13. トポロジ空間関係関数
4.5. 住所標準化
4.5.1. パーサの動作
4.5.2. 住所標準化の型
4.5.3. 住所標準化テーブル
4.5.4. 住所標準化関数
4.6. PostGIS追加機能
4.6.1. Tigerジオコーダ
4.7. 性能向上に関する技法
4.7.1. 大きなジオメトリを持つ小さなテーブル
4.7.2. ジオメトリインデクスでCLUSTERを実行する
4.7.3. 次元変換の回避

4.1. PostGISを使う: データ管理とクエリ

4.1.1. GISオブジェクト

PostGISでサポートされるGISオブジェクトは、OpenGIS Consortium (OGC)が定義する"Simple Features" のスーパーセットです。 PostGISはOGCの"Simple Features for SQL"仕様で定められた全てのオブジェクトと関数に対応しています。

PostGISは標準から拡張して 3DZ, 3DM, 4次元 (訳注: それぞれXYZ, XYM, XYZM)座標に対応しています。

4.1.1.1. OpenGIS WKBとWKT

OpenGIS仕様は空間オブジェクトの表現について二つの標準を定義しています。Well-Knownテキスト (WKT)形式とWell-Knownバイナリ (WKB)形式です。WKTもWKBも、オブジェクトの型とオブジェクトを形成する座標に関する情報を持っています。

フィーチャーの空間オブジェクトのテキスト表現 (WKT)の例は、次の通りです。

  • POINT(0 0)

  • POINT(0 0)

  • POINT(0 0)

  • LINESTRING(0 0,1 1,1 2)

  • POLYGON((0 0,4 0,4 4,0 4,0 0),(1 1, 2 1, 2 2, 1 2,1 1))

  • MULTIPOINT((0 0),(1 2))

  • MULTIPOINT((0 0),(1 2))

  • MULTILINESTRING((0 0,1 1,1 2),(2 3,3 2,5 4))

  • MULTIPOLYGON(((0 0,4 0,4 4,0 4,0 0),(1 1,2 1,2 2,1 2,1 1)), ((-1 -1,-1 -2,-2 -2,-2 -1,-1 -1)))

  • GEOMETRYCOLLECTION(POINT(2 3),LINESTRING(2 3,3 4))

OpenGIS仕様では、空間オブジェクトの内部保存書式は空間参照系識別子 (Spatial Referencing System IDentifier, SRID)を含むことも求められます。SRIDはデータベースへの挿入のために空間オブジェクトが生成される時に求められます。

これらの書式の入出力は次のインタフェースを用いて実現できます。

バイト配列 WKB = ST_AsBinary(geometry);
テキスト WKT = ST_AsText(geometry);
ジオメトリ = ST_GeomFromWKB (bytea WKB、SRID);
ジオメトリ = ST_GeometryFromText (テキスト WKT、SRID);

たとえば、OGC空間オブジェクトを生成して挿入する妥当なINSERTステートメントは次の通りです。

INSERT INTO geotable ( the_geom, the_name )
  VALUES ( ST_GeomFromText('POINT(-126.4 45.32)', 312), 'A Place');

4.1.1.2. PostGIS EWKB, EWKTと標準形式

OGC書式は2次元ジオメトリしかサポートされておらず、また、入出力の表現においてSRIDは*決して*埋め込まれません。

Even though the last OpenGIS specification 1.2.1 supports 3DM and 3DZ coordinates specifing ZM qualifiers, it does not include yet the associated SRID in the input/output representations.

PostGIS EWKB/EWKT では 3DM, 3DZ, 4D の座標サポートが追加され、SRID情報が埋め込まれます。

  • For 3DZ geometries they will drop the Z qualifier:

    OpenGIS: POINT Z (1 2 3)

    EWKB/EWKT: POINT(1 2 3)

  • For 3DM geometries they will keep the M qualifier:

    OpenGIS: POINT M (1 2 3)

    EWKB/EWKT: POINTM(1 2 3)

  • For 4D geometries they will drop the ZM qualifiers:

    OpenGIS: POINT ZM (1 2 3 4)

    EWKB/EWKT: POINT(1 2 3 4)

By doing this, PostGIS EWKB/EWKT avoids over-specifying dimensionality and a whole categories of potential errors that ISO admits, e.g.:

  • POINT(0 0)

  • POINT(0 0)

  • POINT(0 0)

[Caution]

PostGIS拡張書式は現在のところOGC書式のスーパーセットとなっています (全ての妥当なWKB/WKTは妥当なEWKB/EWKTです)。しかし、特にもしOGCがPostGIS拡張と矛盾する新しい書式を出すことがあるなら、これは将来変更されるかも知れません。ゆえにこの機能に頼るべきではありません。

拡張された空間オブジェクトのテキスト表現 (EWKT)の例は、次の通りです。

  • POINT(0 0 0) -- XYZ

  • SRID=32632;POINT(0 0) -- SRID付きXY

  • POINTM(0 0 0) -- XYM

  • POINT(0 0 0 0) -- XYZM

  • SRID=4326;MULTIPOINTM(0 0 0,1 2 1) -- SRID付きXYM

  • MULTILINESTRING((0 0 0,1 1 0,1 2 1),(2 3 1,3 2 1,5 4 1))

  • POLYGON((0 0 0,4 0 0,4 4 0,0 4 0,0 0 0),(1 1 0,2 1 0,2 2 0,1 2 0,1 1 0))

  • MULTIPOLYGON(((0 0 0,4 0 0,4 4 0,0 4 0,0 0 0),(1 1 0,2 1 0,2 2 0,1 2 0,1 1 0)),((-1 -1 0,-1 -2 0,-2 -2 0,-2 -1 0,-1 -1 0)))

  • GEOMETRYCOLLECTIONM( POINTM(2 3 9), LINESTRINGM(2 3 4, 3 4 5) )

  • MULTICURVE( (0 0, 5 5), CIRCULARSTRING(4 0, 4 4, 8 4) )

  • POLYHEDRALSURFACE( ((0 0 0, 0 0 1, 0 1 1, 0 1 0, 0 0 0)), ((0 0 0, 0 1 0, 1 1 0, 1 0 0, 0 0 0)), ((0 0 0, 1 0 0, 1 0 1, 0 0 1, 0 0 0)), ((1 1 0, 1 1 1, 1 0 1, 1 0 0, 1 1 0)), ((0 1 0, 0 1 1, 1 1 1, 1 1 0, 0 1 0)), ((0 0 1, 1 0 1, 1 1 1, 0 1 1, 0 0 1)) )

  • TRIANGLE ((0 0, 0 9, 9 0, 0 0))

  • TIN( ((0 0 0, 0 0 1, 0 1 0, 0 0 0)), ((0 0 0, 0 1 0, 1 1 0, 0 0 0)) )

これらの書式の変換は次のインタフェースを用いて実現できます。

バイト配列 EWKB = ST_AsEWKB(geometry);
テキスト EWKT = ST_AsEWKT(geometry);
ジオメトリ = ST_GeomFromEWKB(bytea EWKB);
ジオメトリ = ST_GeomFromEWKT(text EWKT);

たとえば、PostGISの空間オブジェクトを作成し挿入する妥当なINSERTステートメントは次の通りです。

INSERT INTO geotable ( the_geom, the_name )
  VALUES ( ST_GeomFromEWKT('SRID=312;POINTM(-126.4 45.32 15)'), 'A Place' )

PostgreSQLの「標準的な形式」は単純なクエリ (全く関数呼び出しが無い)で得る表現であり、単純なINSERT, UPDATE, COPYで受け付けられることが保障されるものです。PostGISの"geometory"型の場合は次の通りです。

- 出力
  - バイナリ: EWKB
        ascii: HEXEWKB (EWKBのHEX表現)
- 入力
  - バイナリ: EWKB
        ascii: HEXEWKB|EWKT 

たとえば、次のステートメントは、標準的なASCII文字列による入出力の処理でEWKTを読み、HEXEWKBを返すものです。

=# SELECT 'SRID=4;POINT(0 0)'::geometry;

geometry
----------------------------------------------------
01010000200400000000000000000000000000000000000000
(1 row)

4.1.1.3. SQL-MM第3部

SQLマルチメディア・アプリケーション空間仕様は、円弧補完曲線を定義したSQL仕様の拡張です。

SQL-MMの定義では、3DM、3DZと4Dの座標を含みますが、SRID情報の埋め込みはできません。

Well-Known Text拡張はまだ完全にはサポートされていません。単純な曲線ジオメトリの例を次に示します。

  • CIRCULARSTRING(0 0, 1 1, 1 0)

    CIRCULARSTRING(0 0, 4 0, 4 4, 0 4, 0 0)

    CIRCULARSTRINGは基本的な曲線型で、線型のLINESTRINGに似ています。一つの辺で、始点、終点 (一つめと三つめ)と弧上の任意の点、の3点が必要です。例外として、始点と終点が同じとなる閉曲線があります。閉曲線では二つ目の点が弧の中心、すなわち円の反対側にならなければなりません。弧の連結では、LINESTRINGと同じように、前の弧の最後の点が次の弧の最初の点となります。よって、妥当なCIRCULARSTRINGは1以上の奇数になります。

  • COMPOUNDCURVE(CIRCULARSTRING(0 0, 1 1, 1 0),(1 0, 0 1))

    複合曲線は、曲線 (円弧)セグメントと線型セグメントの両方を持つ、単一の連続した曲線です。 よって、要素が的確である必要があることに加え、各要素 (最終要素は除く)の終点は次の要素の始点と同じになる必要があります。

  • CURVEPOLYGON(CIRCULARSTRING(0 0, 4 0, 4 4, 0 4, 0 0),(1 1, 3 3, 3 1, 1 1))

    曲線ポリゴンの中に複合ポリゴンがある例は次の通りです。 CURVEPOLYGON(COMPOUNDCURVE(CIRCULARSTRING(0 0,2 0, 2 1, 2 3, 4 3),(4 3, 4 5, 1 4, 0 0)), CIRCULARSTRING(1.7 1, 1.4 0.4, 1.6 0.4, 1.6 0.5, 1.7 1) )

    CURVEPOLYGONは外環と0以上の内環とを持つ点でPOLYGONと似ています。 異なる点は、環に曲線ストリング、線型ストリング、複合ストリングのいずれも取れる点です。

    PostGIS 1.4から、PostGISで曲線ポリゴンで複合曲線をサポートするようになりました。

  • MULTICURVE((0 0, 5 5),CIRCULARSTRING(4 0, 4 4, 8 4))

    MULTICURVEは曲線のコレクションで、線型ストリング、曲線ストリング、複合ストリングを取れます。

  • MULTISURFACE(CURVEPOLYGON(CIRCULARSTRING(0 0, 4 0, 4 4, 0 4, 0 0),(1 1, 3 3, 3 1, 1 1)),((10 10, 14 12, 11 10, 10 10),(11 11, 11.5 11, 11 11.5, 11 11)))

    サーフェスのコレクションです。(線型)ポリゴンか曲線ポリゴンを取れます。

[Note]

SQL-MM実装での全ての浮動小数点数の比較では、所定の丸め誤差があります。現在は1E-8です。

4.1.2. PostGISジオグラフィ型

ジオグラフィ型は、「地理」座標 (しばしば「測地」座標、"lat/lon"、"lon/lat"、緯度経度, 経度緯度などとも呼ばれます)上で表現された空間フィーチャーのネイティブサポートするためのものです。地理座標は角度の単位 (度)で表現される球面座標です。

PostGISジオメトリ型の基礎は平面です。平面上の二点間の最短コースは直線になります。よって、ジオメトリ上の計算 (面積、距離、長さ、インタセクション等)は、デカルト座標と線型ベクトルを使用することができます。

PostGISのジオグラフィ型の基礎は球面です。球面上での二点間の最短距離は大圏の弧です。よって、ジオグラフィ上の計算 (面積、距離、長さ、インタセクション等)は、球面上で計算しなければならず、複雑な計算が必要となります。より正確な計測のためには、世界の実際の回転楕円体の形を考慮に入れなければならず、非常に複雑です。

基礎となる数学が大変に複雑なので、ジオグラフィ型用に定義された関数は、ジオメトリ型よりも少ないです。時間とともに、新しいアルゴリズムが追加されて、ジオグラフィ型の能力は拡大していくでしょう。

geographyと呼ばれるデータ型を使用します。GEOS関数はgeography型に対応していません。回避策として、ジオメトリとジオグラフィの型変換を行うことができます。

PostGIS 2.2より前は、ジオグラフィ型はWGS84経度緯度 (SRID:4326)だけに対応していました。PostGIS 2.2以降は、spatial_ref_sysで定義されている経度緯度ベースの空間参照系の全てが使えます。geography type is not limited to earthの記述にある通り、独自の回転楕円体の空間参照系を追加することもできます。

どの空間参照系を使用しても、計測関数 (ST_Distance, ST_Length, ST_Perimeter, ST_Area)の返り値の単位と、???の入力の単位はメートルです。

ジオグラフィ型はPostgreSQLのtypmod定義書式を使います。ジオグラフィカラムを持つテーブルに1ステップで追加できます。標準OGC書式は曲線を除いてサポートします。

4.1.2.1. ジオグラフィ基礎

ジオグラフィ型はシンプルフィーチャーの最も簡単なもののみサポートします。標準的なジオメトリ型データで、SRIDが4326の場合は、ジオグラフィに自動でキャストされます。またデータ挿入においてEWKTとEWKBの取り決めを使うこともできます。

  • POINT: SRID指定なしでの2次元ポイントジオグラフィのテーブル生成は次の通りです。デフォルトは4326 WGS84経度緯度となります。

    CREATE TABLE ptgeogwgs(gid serial PRIMARY KEY, geog geography(POINT) );

    POINT: NAD83経度緯度での2次元ポイントジオグラフィのテーブル生成は次の通りです。

    CREATE TABLE ptgeognad83(gid serial PRIMARY KEY, geog geography(POINT,4269) );

    Z値を持ち、明示的にSRIDを指定したポイントのテーブル生成は次の通りです。

    CREATE TABLE ptzgeogwgs84(gid serial PRIMARY KEY, geog geography(POINTZ,4326) );
  • LINESTRING

    CREATE TABLE lgeog(gid serial PRIMARY KEY, geog geography(LINESTRING) );
  • POLYGON

    -- ポリゴン NAD 1927経度緯度
    CREATE TABLE lgeognad27(gid serial PRIMARY KEY, geog geography(POLYGON,4267) );
  • MULTIPOINT

  • MULTILINESTRING

  • MULTIPOLYGON

  • GEOMETRYCOLLECTION

ジオグラフィ型のフィールドはgeography_columnsシステムビューに登録されます。

"geography_columns"ビューをチェックして、テーブルが一覧にあるか見て下さい。

CREATE TABLEの文法でジオグラフィカラムを持つテーブルを新規に生成できます。

CREATE TABLE global_points (
    id SERIAL PRIMARY KEY,
    name VARCHAR(64),
    location GEOGRAPHY(POINT,4326)
  );

locationカラムはジオグラフィ型で、二つの任意修飾子に対応していることにご注意ください。一つは、そのカラムで使用できる形状と次元を限定する型修飾子です。もう一つは、座標参照IDを特定の数に限定するSRID修飾子です。

型修飾子として受け付ける値は、POINT, LINESTRING, POLYGON, MULTIPOINT, MULTILINESTRING, MULTIPOLYGONです。型修飾子は、Z, M, ZMの後置子を付けることで次元制限にも対応します。たとえば、'LINESTRINGM'という型修飾子で、三つ目の次元をMとする3次元のラインストリングのみ受け付けることになります。同じように'POINTZM'で、4次元データを期待します。

SRIDを指定していない場合には、SRIDは4326 WGS84経度緯度が使われ、全ての計算はWGS 84を使って行われます。

テーブルを作ったら、次のようにしてGEOGRAPHY_COLUMNSを見ることができます。

-- メタデータビューの中身を見る
SELECT * FROM geography_columns;

ジオメトリカラムを使うのと同じようにテーブルへのデータの挿入ができます。

-- testテーブルにデータを追加する
INSERT INTO global_points (name, location) VALUES ('Town', 'SRID=4326;POINT(-110 30)');
INSERT INTO global_points (name, location) VALUES ('Forest', 'SRID=4326;POINT(-109 29)');
INSERT INTO global_points (name, location) VALUES ('London', 'SRID=4326;POINT(0 49)');

ジオメトリと同じ操作でインデックスを作成します。PostGISは、カラム型がジオグラフィであるかを見て、ジオメトリで使われる平面用インデックスの代わりに球面ベースのインデックスを作成します。

-- testテーブルに球面インデックスを作成
  CREATE INDEX global_points_gix ON global_points USING GIST ( location );

クエリと計測関数はメートル単位となります。そのため距離パラメータはメートル (面積の場合は平方メートル)単位となります。

-- 距離クエリの表示。ロンドンは1000km範囲外です
  SELECT name FROM global_points WHERE ST_DWithin(location, 'SRID=4326;POINT(-110 29)'::geography, 1000000);

ジオグラフィの威力については、シアトルからロンドンまで (LINESTRING(-122.33 47.606, 0.0 51.5))の飛行機がレイキャビク (POINT(-21.96 64.15))に最も近くなるときの距離を求めてみると分かります。

-- ジオグラフィを使った距離計算 (122.2km)
  SELECT ST_Distance('LINESTRING(-122.33 47.606, 0.0 51.5)'::geography, 'POINT(-21.96 64.15)'::geography);

-- ジオメトリを使った計算 (13.3 "度")
  SELECT ST_Distance('LINESTRING(-122.33 47.606, 0.0 51.5)'::geometry, 'POINT(-21.96 64.15)'::geometry);

異なる経度緯度座標系を試します。spatial_ref_sysテーブルで挙げられている経度緯度の空間参照系なら全て可能です。

-- NAD83経度緯度
SELECT 'SRID=4269;POINT(-123 34)'::geography;
                    geography
----------------------------------------------------
 0101000020AD1000000000000000C05EC00000000000004140
(1 row)

-- NAD27経度緯度
SELECT 'SRID=4267;POINT(-123 34)'::geography;

                    geography
----------------------------------------------------
 0101000020AB1000000000000000C05EC00000000000004140
(1 row)

-- メートル単位のNAD83 UTM、メートル単位の投影法ですのでエラーが出ます
SELECT 'SRID=26910;POINT(-123 34)'::geography;

ERROR:  Only lon/lat coordinate systems are supported in geography.
LINE 1: SELECT 'SRID=26910;POINT(-123 34)'::geography;

ジオグラフィ型は、レイキャビクとシアトル-ロンドン間の飛行機の大圏コースとの間の、球面上での本当に最も近い距離を計算します。

大圏コースマップ ジオメトリ型は、平面の世界地図上にプロットされたレイキャビクとシアトル-ロンドン間の直線とのデカルト距離という意味のない値を出します。結果の名目上の単位は「度」ですが、点間の本当の角度差にあっていませんので、「度」と言うこと自体不正確です。

4.1.2.2. ジオグラフィ型をジオメトリ型にして使用すべき時

ジオグラフィ型によって、経度緯度座標でデータを格納できるようになりましたが、ジオグラフィで定義されている関数が、ジオメトリより少ないのと、実行にCPU時間がかかる、というところが犠牲になっています。

選択した型が、期待する領域から出ないことを、ジオメトリ型にして使用する条件とすべきです。使用するデータは地球全体か、大陸か、州か、自治体か?

  • データが小さいエリア内におさまるなら、適切な投影を選択してジオメトリを使うのが、効率面でも機能面でも最も良い方法です。

  • データが地球全体か大陸なら、ジオグラフィで投影法の細かい問題を気にせずにシステムを構築できるでしょう。経度/緯度のデータを保存して、ジオグラフィで定義された関数使います。

  • 投影法を理解していなくて、学習したくもなくて、かつ、ジオグラフィで使える関数が限られていることを受け入れるのなら、ジオグラフィを使った方が簡単です。単純にデータを経度/緯度でロードして、そこから進めて下さい。

ジオグラフィとジオメトリ間のサポート状況の比較についてはSection 9.11, “PostGIS Function Support Matrix”をご覧下さい。ジオグラフィ関数の簡潔なリストと説明についてはSection 9.4, “PostGIS Geography Support Functions”をご覧下さい。

4.1.2.3. ジオグラフィに関する高度なよくある質問

4.1.2.3.1. 球または回転楕円体のどちらで計算するのでしょうか?
4.1.2.3.2. 日付変更線や極に関してはどうなっていますか?
4.1.2.3.3. 処理できる最も長い弧はどうなりますか?
4.1.2.3.4. なぜヨーロッパやロシアといった大きな範囲の面積計算はとても遅いのですか?

4.1.2.3.1.

球または回転楕円体のどちらで計算するのでしょうか?

デフォルトでは、全ての距離と面積の計算は回転楕円体で行います。局所的なエリアでの計算結果と良好な投影を施した平面での結果と比較して下さい。大きなエリアの場合は、回転楕円体計算は、投影平面上でのどの計算よりも精度が高くなります。

全てのジオグラフィ関数には、最後の真偽パラメータを'FALSE'にすると球面を使った計算を行うというオプションがあります。これは、特にジオメトリが非常に単純である場合に計算を速くするためのものです。

4.1.2.3.2.

日付変更線や極に関してはどうなっていますか?

全ての計算に日付変更線や極の概念がありません。座標は球 (経度/緯度)であるので、日付変更線とクロスする形状は、計算の観点からは、他のものと変わりありません。

4.1.2.3.3.

処理できる最も長い弧はどうなりますか?

大圏の弧を2点の「補完線」として使用しています。任意の2点は、実際には2方向につながっていて、どちらの方向に行くかに依存します。PostGISの全てのコードは、大圏コースの2コースのうち*短い*方でつながっていると仮定しています。結果として、180度以上の弧を持つ形状は正しくモデル化されません。

4.1.2.3.4.

なぜヨーロッパやロシアといった大きな範囲の面積計算はとても遅いのですか?

ポリゴンがとんでもなく大きいからです。二つの理由から、大きなエリアは悪いです。一つは、バウンダリボックスが大きいため、どのようなクエリを走らせても、インデックスがフィーチャーを引っ張ってくる傾向にあるためです。もう一つは、頂点数が巨大で、テスト (距離、包含)関数では、少なくとも1回、通常はN (Nは、もう一方のフィーチャーの頂点数)回、頂点を横断しなければならないためです。

ジオメトリでは、大きなポリゴンを持っているけれども小さな範囲のクエリを実行する時、ジオメトリデータ情報を小片に「非正規化」します。これにより、インデックスが効果的にオブジェクトの一部を問い合わせるようになり、またクエリが常にオブジェクト全体を引っ張りこむようなことがないようになります。ST_Subdivideを参照して下さい。ヨーロッパ全体を一つのポリゴンに*格納できる*からといって、*そうすべき*だというわけではありません。

4.1.3. OpenGIS標準を使う

OpenGISの「SQL用シンプルフィーチャー仕様」では、標準GISオブジェクト型とこれらを操作するために必要な関数、メタデータテーブルのセットが定義されています。メタデータが一貫性を維持していることを保証するために、空間カラムの生成、消去といった操作はOpenGISで定義されている空間プロシージャを通して実行されます。

OpenGISメタデータテーブルにはSPATIAL_REF_SYSGEOMETRY_COLUMNSの二つがあります。SPATIAL_REF_SYSテーブルは空間データベースで用いられる座標系の、数字によるIDと文字による説明を持っています。

4.1.3.1. SPATIAL_REF_SYSテーブルと空間参照系

spatial_ref_sysテーブルは、PostGISに含まれるもので、3000以上の空間参照系と、座標変換/投影変換を行うのに必要な詳細情報との一覧を持つ、OGC準拠のデータベーステーブルです。

PostGISのspatial_ref_sysテーブルには、projライブラリで使われる3000以上の一般に使われる空間参照系定義がありますが、全てを持っているわけではなく、proj4の構築に慣れているならカスタム投影を定義することができます。ほとんどの空間参照系は地域限定のもので、想定されている範囲の外で使うと意味が無いことに注意して下さい。

PostGISのコアセットに入っていない空間参照系を探すための素晴らしい資料がhttp://spatialreference.org/にあります。

よく共通的に使われる空間参照系は次の通りです (訳注: 日本では状況が異なります)。4326 - WGS 84 経度緯度4269 - NAD 83 経度緯度3395 - WGS 84 メルカトル図法2163 - 米国ナショナルアトラス正積図法、NAD83とWGS84のUTM空間参照系 - UTMゾーンは計測に最も理想的なものの一つですが6度 (訳注: 経度)の領域しかカバーしません。

まざまな米国の州の平面空間参照系 (メートルまたはフィート単位) - 通常は州ごとに一つか二つあります。メートル単位のもののほとんどがPostGISのコアセットに入っていますが、多数のフィート単位のものやESRIが作ったものについてはspatialreference.orgから取得して下さい。

対象領域がどのUTMゾーンになるかを決めるには、utmzone PostGIS plpgsql helper functionを参照して下さい。

SPATIAL_REF_SYSテーブル定義は次の通りです。

CREATE TABLE spatial_ref_sys (
  srid       INTEGER NOT NULL PRIMARY KEY,
  auth_name  VARCHAR(256),
  auth_srid  INTEGER,
  srtext     VARCHAR(2048),
  proj4text  VARCHAR(2048)
)

SPATIAL_REF_SYSのカラムは次の通りです。

SRID

一意に定められた整数値で、データベースで空間参照系 (SRS)を識別するものです。

AUTH_NAME

その参照系の引用元である標準の名前です。たとえば「EPSG」は妥当なAUTH_NAMEです。

AUTH_SRID

AUTH_NAMEで引用される団体によって定義された空間参照系のIDです。EPSGの場合、EPSG投影コードが入ります。

SRTEXT

空間参照系のWell-Knownテキスト表現です。たとえば、WKT SRSの表現は、次のようになります。

PROJCS["NAD83 / UTM Zone 10N",
  GEOGCS["NAD83",
        DATUM["North_American_Datum_1983",
          SPHEROID["GRS 1980",6378137,298.257222101]
        ],
        PRIMEM["Greenwich",0],
        UNIT["degree",0.0174532925199433]
  ],
  PROJECTION["Transverse_Mercator"],
  PARAMETER["latitude_of_origin",0],
  PARAMETER["central_meridian",-123],
  PARAMETER["scale_factor",0.9996],
  PARAMETER["false_easting",500000],
  PARAMETER["false_northing",0],
  UNIT["metre",1]
]

EPSG投影コードと対応するWKT表現の一覧については、http://www.opengeospatial.org/をご覧下さい。WKTの一般的な議論については、OpenGISのhttp://www.opengeospatial.org/standardsにある「座標変換サービス実装仕様」をご覧下さい。欧州石油調査グループ(European Petroleum Survey Group, EPSG)とEPSG空間参照系のデータベースに関する情報は、http://www.epsg.org/をご覧下さい。

PROJ4TEXT

PostGISは座標変換機能を提供するためにProj4ライブラリを用いています。 PROJ4TEXTカラムには、特定のSRIDを示すProj4座標定義文字列が入ります。たとえば次のようになります。

+proj=utm +zone=10 +ellps=clrk66 +datum=NAD27 +units=m

詳細情報については、Proj4ウェブサイトhttp://trac.osgeo.org/proj/をご覧下さい。spatial_ref_sys.sqlは、全てのEPSG投影法のためのSRTEXTPROJ4TEXTとを持っています。

4.1.3.2. GEOMETRY_COLUMNSビュー

GEOMETRY_COLUMNSは、データベースのシステムカタログから読み取るビューです。構造は次の通りです。

\d geometry_columns
View "public.geometry_columns"
      Column       |          Type          | Modifiers
-------------------+------------------------+-----------
 f_table_catalog   | character varying(256) |
 f_table_schema    | character varying(256) |
 f_table_name      | character varying(256) |
 f_geometry_column | character varying(256) |
 coord_dimension   | integer                |
 srid              | integer                |
 type              | character varying(30)  |

カラムの意味は次の通りです。

F_TABLE_CATALOG, F_TABLE_SCHEMA, F_TABLE_NAME

ジオメトリカラムを持つフィーチャーテーブルの完全修飾名。"catalog"および"schema"の語はOracle風であることに注意して下さい。"catalog"に類似するものはPostgreSQLになく、このカラムは空白にされます。"schema"についてはPostgreSQLスキーマ名が使われています (publicがデフォルトです)。

F_GEOMETRY_COLUMN

フィーチャーテーブル内のジオメトリカラムの名前。

COORD_DIMENSION

そのカラムの空間の次元 (2, 3 または 4)。

SRID

このテーブルの座標ジオメトリのために使われる空間参照系のID。SPATIAL_REF_SYSへの外部キーになっています。

TYPE

空間オブジェクトの型。空間カラムを単一型に制限するには、POINT、LINESTRING、POLYGON、MULTIPOINT、MULTILINESTRING、MULTIPOLYGON、GEOMETRYCOLLECTIONのうちのいずれかを、また、XYMで使う場合には、LINESTRINGM、POLYGONM、MULTIPOINTM、MULTILINESTRINGM、MULTIPOLYGONM、GEOMETRYCOLLECTIONMのうちのいずれかを使います。複数の型が混合するコレクションの場合は"GEOMETRY"を型とすることができます。

[Note]

この属性は (おそらく)OpenGIS仕様に入っていませんが、型の同一性を保証するために必要です。

4.1.3.3. 空間テーブルを作る

空間データを持つテーブルの生成は、1段階でできます。2次元ラインストリングでWGS84経度緯度のジオメトリカラムを持つroadsテーブルの生成の例を次に示します。

CREATE TABLE ROADS (ID serial, ROAD_NAME text, geom geometry(LINESTRING,4326) );

次の、3次元ラインストリングを追加する例で示す通り、標準的なALTER TABLEコマンドを使ってカラムを追加できます。

ALTER TABLE roads ADD COLUMN geom2 geometry(LINESTRINGZ,4326);

4.1.3.4. 手動でジオメトリカラムをgeometry_columnsに登録する

これが必要になる事例に、SQLビューとバルクインサートの二つがあります。バルクインサートの場合には、カラムに制約を与えるか、ALTER TABLEを実行することで、geometry_columnsテーブル内の登録を訂正することができます。ビューの場合には、CAST演算を使用します。カラムが型修飾子に基づく場合には、生成処理によって正しく登録されるので、何も行う必要がありません。ジオメトリに適用する空間関数を持たないビューも、基礎となるテーブルのジオメトリカラムと同じように登録されます。

-- 次のようなビューがあるとします
CREATE VIEW public.vwmytablemercator AS
        SELECT gid, ST_Transform(geom, 3395) As geom, f_name
        FROM public.mytable;

-- 正しく登録するには、
-- ジオメトリをキャストします。
--
DROP VIEW public.vwmytablemercator;
CREATE VIEW  public.vwmytablemercator AS
        SELECT gid, ST_Transform(geom, 3395)::geometry(Geometry, 3395) As geom, f_name
        FROM public.mytable;

-- ジオメトリタイプが確実に2次元ポリゴンだと知っているなら
-- 次のようにできます。
DROP VIEW public.vwmytablemercator;
CREATE VIEW  public.vwmytablemercator AS
        SELECT gid, ST_Transform(geom,3395)::geometry(Polygon, 3395) As geom, f_name
        FROM public.mytable;
-- 次のように、バルクインサートで派生テーブルを生成したとしましょう
SELECT poi.gid, poi.geom, citybounds.city_name
INTO myschema.my_special_pois
FROM poi INNER JOIN citybounds ON ST_Intersects(citybounds.geom, poi.geom);

-- 新しいテーブルに2次元インデックスを作ります
CREATE INDEX idx_myschema_myspecialpois_geom_gist
  ON myschema.my_special_pois USING gist(geom);

-- ポイントが3次元ポイントであったり、XYMポイントであったりした場合には、
-- 次のように、2次元インデックスでなくN次元インデックスを作ることになるかも
-- 知れません。
CREATE INDEX my_special_pois_geom_gist_nd
        ON my_special_pois USING gist(geom gist_geometry_ops_nd);

-- 新しいテーブルのジオメトリカラムをgeometry_columnsに手動登録するには、
-- 次のようにします。
-- カラムを型修飾子ベースにするために、基礎となるテーブル構造も変更することに
-- 注意して下さい。
SELECT populate_geometry_columns('myschema.my_special_pois'::regclass);

-- PostGIS 2.0を使っていて、何らかの理由で古い制約をもとにした定義を行う
-- (派生テーブルが同じタイプやSRIDを持たないといった場合)ことが必要な場合には、
-- 新しい任意変数use_typemodをfalseにします。
SELECT populate_geometry_columns('myschema.my_special_pois'::regclass, false); 

古い制約を基にした手法は現在も対応していますが、制約を基にしたジオメトリカラムで直接的にビューで使われている場合は、型修飾子のようには正しくgeometry_columnsに登録されません。次の例では、型修飾子を使ったカラム定義と、制約に基づくカラムの定義とを行っています。

CREATE TABLE pois_ny(gid SERIAL PRIMARY KEY, poi_name text, cat text, geom geometry(POINT,4326));
SELECT AddGeometryColumn('pois_ny', 'geom_2160', 2160, 'POINT', 2, false);

psqlで次を実行します。

\d pois_ny;

型修飾子と制約に基づくのとでは異なった定義になっているのが見えます。

Table "public.pois_ny"
  Column   |         Type          |                       Modifiers

-----------+-----------------------+------------------------------------------------------
 gid       | integer               | not null default nextval('pois_ny_gid_seq'::regclass)
 poi_name  | text                  |
 cat       | character varying(20) |
 geom      | geometry(Point,4326)  |
 geom_2160 | geometry              |
Indexes:
    "pois_ny_pkey" PRIMARY KEY, btree (gid)
Check constraints:
    "enforce_dims_geom_2160" CHECK (st_ndims(geom_2160) = 2)
    "enforce_geotype_geom_2160" CHECK (geometrytype(geom_2160) = 'POINT'::text
        OR geom_2160 IS NULL)
    "enforce_srid_geom_2160" CHECK (st_srid(geom_2160) = 2160)

geometry_columnsでは、両方とも正しく登録されています。

SELECT f_table_name, f_geometry_column, srid, type
        FROM geometry_columns
        WHERE f_table_name = 'pois_ny';
f_table_name | f_geometry_column | srid | type
-------------+-------------------+------+-------
pois_ny      | geom              | 4326 | POINT
pois_ny      | geom_2160         | 2160 | POINT

しかし、次のようにビューを作ろうとします。

CREATE VIEW vw_pois_ny_parks AS
SELECT *
  FROM pois_ny
  WHERE cat='park';

SELECT f_table_name, f_geometry_column, srid, type
        FROM geometry_columns
        WHERE f_table_name = 'vw_pois_ny_parks';

型修飾子によるgeomのビューカラムは正しく登録されますが、制約に基づくものは正しく登録されません。

f_table_name   | f_geometry_column | srid |   type
------------------+-------------------+------+----------
 vw_pois_ny_parks | geom              | 4326 | POINT
 vw_pois_ny_parks | geom_2160         |    0 | GEOMETRY

これは、将来的にPostGISの版で変更されるかもしれませんが、今のところは、制約に基づくビューカラムを正しく登録させるには、次のようにします。

DROP VIEW vw_pois_ny_parks;
CREATE VIEW vw_pois_ny_parks AS
SELECT gid, poi_name, cat,
  geom,
  geom_2160::geometry(POINT,2160) As geom_2160
  FROM pois_ny
  WHERE cat = 'park';
SELECT f_table_name, f_geometry_column, srid, type
        FROM geometry_columns
        WHERE f_table_name = 'vw_pois_ny_parks';
f_table_name   | f_geometry_column | srid | type
------------------+-------------------+------+-------
 vw_pois_ny_parks | geom              | 4326 | POINT
 vw_pois_ny_parks | geom_2160         | 2160 | POINT

4.1.3.5. ジオメトリのOpenGIS準拠を確実にする

PostGISはOpen Geospatial Consortium (OGC)のOpenGIS仕様に準拠しています。多くのPostGISメソッドは、操作対象のジオメトリが単純かつ妥当であることが求められます (正確に言うとそう仮定します)。たとえば、ポリゴンの外に穴があるようなものの面積を計算したり、単純でない境界線を持つポリゴンを作ったりするのは、意味がありません。

OGS仕様に沿うと、単純なジオメトリとは、自己インタセクトや自己接触のような、異常な幾何点を持たないことです。主に0次元または1次元のジオメトリ ([MULTI]POINT, [MULTI]LINESTRING))に適用します。 他方、ジオメトリの妥当性は、主に2次元ジオメトリ ([MULTI]POLYGON)に適用し、妥当なポリゴンを特徴づける位置指定子の集合を定義します。個々のジオメトリクラスには、単純性と妥当性をさらに詳細に述べる特定の条件があります。

POINTは0次元ジオメトリオブジェクトとして常に単純です。

MULTIPOINTは、二つの座標値 (POINT)が同じでないなら単純です。

LINESTRINGは、2度同じPOINTを通らない (終点は除きます。この場合は線型環と呼ばれ、さらに言うと閉じていると思われます)なら単純です。

(a)

(b)

(c)

(d)

(a)(c)は単純なLINESTRINGです。(b)(d)は単純ではありません。

MULTILINESTRINGは、 全ての要素が単純で、かつ任意の2要素のインタセクトが要素の境界であるPOINTでだけ発生する場合に限って単純です。

(e)

(f)

(g)

(e)(f)は単純なMULTILINESTRINGです。(g)は単純ではありません。

定義からPOLYGONは常に単純です。バウンダリ内の環 (外環と内環からなる)のうち二つがクロスしていないなら妥当です。POLYGONの境界は、POINTとインタセクトするかも知れませんが、接点にしかなりません (すなわち線上にない)。POLYGONはカットラインまたはスパイクを持たなくても良く、内環は外環の中に完全に含まれていなければなりません。

(h)

(i)

(j)

(k)

(l)

(m)

(h)(i)は妥当なPOLYGONです。(jからm)は単一のPOLYGONとしては表現できませんが、(j)(m)は妥当なMULTIPOLYGONとして表現できます。

MULTIPOLYGONは、全ての要素が妥当で、二つのポリゴン要素について内側がインタセクトしていない場合は妥当です。ポリゴン要素の任意の二つの境界は接触してもよいですが、有限な数のPOINTでなければなりません。

(n)

(o)

(p)

(n)(o)は妥当でないMULTIPOLYGONです。(p)は妥当です。

GEOSライブラリを使って実装されている関数のほとんどは、ジオメトリがOpenGISシンプルフィーチャー仕様で定義されているように妥当であると仮定しています。ジオメトリが単純であるか、また妥当であるか、のチェックとしてST_IsSimple()ST_IsValid()が使えます。

-- 一般的に、線フィーチャーの妥当性のチェックは
-- 常にTRUEを返すので意味がありません
-- しかし、この例では、PostGISがOGCのIsValidの定義を拡張して
-- *一意な頂点*が2より少ないラインストリングについてFALSEを
-- 返すようにしています
gisdb=# SELECT
   ST_IsValid('LINESTRING(0 0, 1 1)'),
   ST_IsValid('LINESTRING(0 0, 0 0, 0 0)');

 st_isvalid | st_isvalid
------------+-----------
      t     |     f

デフォルトでは、PostGISはジオメトリ入力に関するこの妥当性チェックを適用しません。複雑なジオメトリの妥当性のチェックはCPU時間を多く必要とするためです。データソースが信用できない場合は、手動でこのチェックを強制するための制約を付けることができます。

ALTER TABLE mytable
  ADD CONSTRAINT geometry_valid_check
        CHECK (ST_IsValid(the_geom));

妥当な入力ジオメトリでPostGIS関数を呼んだのに「GEOS Intersection()がエラーを投げました!」というようなエラーメッセージに遭遇したなら、PostGISまたは使用しているライブラリの中のエラーを発見しました。PostGIS開発者に連絡するべきです。PostGIS関数が妥当である入力ジオメトリから妥当でないジオメトリが返る場合も同じです。

[Note]

厳格にOGCジオメトリに準拠すると、Z値やM値を持てません。ST_IsValid()は高次を考慮に入れません。AddGeometryColumn()を実行するとジオメトリの次元をチェックする制約が加わるので、そこで2を指定すれば十分です。

4.1.3.6. ここで、Dimensionally Extended 9 Intersection Modelまたは略してDE-9IMを見てみましょう。

代表的な空間述語 (???, ???, ???, ???, ...)は、求められる空間フィルタを適切に提供するには十分でないことが時々あります。

たとえば、道路網を表現する線型のデータセットがあるとします。ビジネスルールを無視しているかも知れませんが、点で交差するだけでなく線上で交差する道路区間を全て判別することがGIS解析者の仕事となるかも知れません。この場合、 ???では重要な空間フィルタとして十分ではありません。線型のフィーチャーでは、点でクロス (訳注: インタセクトより厳しい条件です)している場合のみtrueが返ります。

空間的にインタセクトしている (???)と判別された二つの区間の組み合わせについて、実際のインタセクト (ST_Intersection)を取り、 インタセクトのST_GeometryTypeが''LINESTRING'であるかを見る ([MULTI]POINT[MULTI]LINESTRING等からなるGEOMETRYCOLLECTIONが帰ってくる場合にしっかり対応するため)、という2段階の方法で解くことはできます。

よりエレガントかつ速い解法が本当に望ましいでしょう。

二つ目の[理論的な]例として、GIS解析者が全ての湖の境界に線でインタセクトする波止場やドックの全ての位置を特定しようとするとします。ここで、波止場の一端だけ陸にあるとします。言いかえると、波止場が湖の中にあるが完全に中に入りきってはいなくて、湖と線でインタセクトして、波止場の一方の端が完全に湖に入っていて、かつもう一方の端点が境界線上にあります。解析者は空間述語の組み合わせで、非常に望まれるフィーチャーを引き出す必要があるかも知れません。

ここで、Dimensionally Extended 9 Intersection Mode、略してDE-9IMを見てみましょう。

4.1.3.6.1. 理論

OpenGIS Simple Features Implementation Specification for SQLによると「二つのジオメトリの比較の基本的なアプローチは、二つのジオメトリの内部、境界、外部のインタセクションの比較と、『インタセクション行列』の要素に基づく2ジオメトリの関係の分類です」。

境界 (Boundary)

ジオメトリの境界は一つ低い次元のジオメトリの集合です。0次元のPOINTの境界は空集合です。LINESTRINGの境界は二つの端点です。 POLYGONの境界は外環と内環を形成する線です。

内部 (Interior)

ジオメトリの内部は境界を取り去った際に残るジオメトリです。POINTの内部はPOINT自身です。LINESTRINGの内部は二つの端点の間の実際の点の集合です。POLYGONの内部はポリゴンの内側の範囲であるサーフェスです。

外部 (Exterior)

ジオメトリの外部は、内部と境界を除いた全領域のサーフェスです。

ジオメトリaがあり、aの内部、境界、外部をそれぞれI(a)B(a)E(a)とします。数学的な行列表現は次のようになります。

 内部 (Interior)境界 (Boundary)外部 (Exterior)
内部 (Interior)dim( I(a) ∩ I(b) )dim( I(a) ∩ B(b) )dim( I(a) ∩ E(b) )
境界 (Boundary)dim( B(a) ∩ I(b) )dim( B(a) ∩ B(b) )dim( B(a) ∩ E(b) )
外部 (Exterior)dim( E(a) ∩ I(b) )dim( E(a) ∩ B(b) )dim( E(a) ∩ E(b) )

ここで、dim(a)aの次元で、ST_Dimensionで規定されますが、{0,1,2,T,F,*}の値域を持ちます。

  • 0 => 点

  • 1 => 線

  • 2 => 面

  • T => {0,1,2}

  • F => 空集合

  • * => 何でも良い

二つのオーバラップするポリゴンについて可視化すると、次のようになります。

 

 内部 (Interior)境界 (Boundary)外部 (Exterior)
内部 (Interior)

dim(...) = 2

dim(...) = 1

dim(...) = 2

境界 (Boundary)

dim(...) = 1

dim(...) = 0

dim(...) = 1

外部 (Exterior)

dim(...) = 2

dim(...) = 1

dim(...) = 2

左から右、上から下に読むと、次元行列は'212101212'と表現されます。

一つ目の例である、2線が線上でインタセクトする場合の関係行列は'1*1***1**'となります。

-- 線上でクロスする道路区間の判別
SELECT a.id
FROM roads a, roads b
WHERE a.id != b.id
AND a.geom && b.geom
AND ST_Relate(a.geom, b.geom, '1*1***1**');

二つ目の例である、一部が湖の水涯線上にある波止場についての関係行列は'102101FF2'となります。

-- 一部が湖の水涯線上にある波止場の判別
SELECT a.lake_id, b.wharf_id
FROM lakes a, wharfs b
WHERE a.geom && b.geom
AND ST_Relate(a.geom, b.geom, '102101FF2');

詳細情報ついては、次のページをご覧ください。

4.1.4. GIS (ベクタ)データをロードする

空間テーブルを作成したら、これでGISデータをデータベースにアップロードする準備ができたことになります。現在、PostGIS/PostgreSQLデータベースにデータをロードするには、SQLステートメントを使う、またはシェープファイルのローダ/ダンパを使う、二つの方法があります。

4.1.4.1. SQLを使ってロードする

データをテキスト表現に変換できるなら、フォーマットされたSQLを使うのがデータをPostGISに入れる最も簡単な方法です。Oracleや他のSQLデータベースを使うように、SQL端末モニタにSQLの"INSERT"ステートメントで一杯になった大きなテキストファイルをパイプで送ることで、大量のデータをロードできます。

データアップロードファイル (たとえばroads.sql)は次のようになるでしょう。

BEGIN;
INSERT INTO roads (road_id, roads_geom, road_name)
  VALUES (1,'LINESTRING(191232 243118,191108 243242)','Jeff Rd');
INSERT INTO roads (road_id, roads_geom, road_name)
  VALUES (2,'LINESTRING(189141 244158,189265 244817)','Geordie Rd');
INSERT INTO roads (road_id, roads_geom, road_name)
  VALUES (3,'LINESTRING(192783 228138,192612 229814)','Paul St');
INSERT INTO roads (road_id, roads_geom, road_name)
  VALUES (4,'LINESTRING(189412 252431,189631 259122)','Graeme Ave');
INSERT INTO roads (road_id, roads_geom, road_name)
  VALUES (5,'LINESTRING(190131 224148,190871 228134)','Phil Tce');
INSERT INTO roads (road_id, roads_geom, road_name)
  VALUES (6,'LINESTRING(198231 263418,198213 268322)','Dave Cres');
COMMIT;

データファイルは、次に示す"psql"というSQL端末モニタを使って、簡単にPostgreSQLにパイプで送ることができます。

psql -d [データベース名] -f roads.sql

4.1.4.2. shp2pgsql: ESRIシェープファイルローダを使う

shp2pgsqlデータローダは、ESRIシェープファイルをPostGIS/PostgreSQLデータベースに、ジオメトリまたはジオグラフィとして挿入するための適切なSQLに変換します。ローダには、次に示すコマンドラインフラグによって区別される、いくつかの操作モードがあります。

また、コマンドラインローダのほとんどのオプションに対応するshp2pgsql-guiグラフィカルユーザインタフェースがあります。一度限りのロードしか行わずスクリプト化しない場合やPostGISに不慣れな方にとって便利になるかもしれません。これはpgAdminIIIのプラグインとして構築することもできます。

(c|a|d|p) 相互に排他的なオプションです

-c

新しいテーブルの作成とシェープファイルからのデータの読み込みを行います。これがデフォルトモードです

-a

シェープファイルからデータベーステーブルにデータを追加します。複数のファイルをロードするためにこのオプションを使う場合は、これらのファイルは同じ属性と同じデータ型を持つ必要があります。

-d

シェープファイルにあるデータを持つ新しいテーブルを作成する前にデータベーステーブルを削除します。

-p

テーブル作成のSQLコードを生成するだけで、実際のデータは追加しません。このモードは、テーブル作成とデータロードとを完全に分けたい場合に使用します。

-?

ヘルプ画面を表示します。

-D

出力データにPostgreSQLのダンプ書式を用います。このモードは-a, -c, -dと組み合わせて利用します。デフォルトの"insert"によるSQL書式よりも、大変早くロードできます。大きなデータセットではこちらを使用して下さい。

-s [<FROM_SRID>:]<SRID>

指定したSRIDでジオメトリデーブルの作成とデータの読み込みを行います。 入力シェープファイルが使っているFROM_SRIDの指定が可能で、この場合は対象SRIDに投影変換を行います。FROM_SRIDは-Dと一緒には指定できません。

-k

識別子 (カラム、スキーマおよび属性)の大文字小文字を保持します。シェープファイルの属性は全て大文字であることに注意して下さい。

-i

全ての整数を標準の32ビット整数に強制します。DBFヘッダではそれが正当であったとしても、64ビットのbigintを生成しません。

-I

ジオメトリカラムにGiSTインデックスを生成します。

-m

-m a_file_nameで、長いカラム名を10文字のDBFカラム名に対応付けるファイルを指定します。ファイルは、1以上の行を持ちます。各行は空白区切りで二つの名前を持ち、行頭行末に空白を入れません。例を次に示します。

COLUMNNAME DBFFIELD1
AVERYLONGCOLUMNNAME DBFFIELD2

-S

マルチ系ジオメトリの替りに単一ジオメトリを生成します。全てのジオメトリが実際に単一である (たとえば単一の外環でなるMULTIPOLYGONや単一の頂点でなるMULTIPOINT)場合にのみ成功します。

-t <次元>

出力ジオメトリが特定の次元を持つよう強制します。次元は、2D, 3DZ, 3DM, 4Dの文字列を使います。

入力の次元が出力より小さい場合には、出力では0が入ります。入力の次元が大きい場合には、外されます。

-w

出力書式をWKBでなくWKTにします。精度が低下して、座標変動が発生しうることに注意が必要です。

-e

トランザクションを使わずに、ステートメントごとに実行するようにします。エラーの元となる不良なジオメトリがいくつか含んでいる時に、大半の良好なデータのロードが可能にするものです。ダンプ書式ではトランザクションを常に使うので、-Dフラグを指定している場合には使えません。

-W <エンコーディング>

入力データ (dbfファイル)のエンコーディングを指定します。全てのdbfの属性は指定されたエンコーディングからUTF8に変換されます。SQL出力結果には SET CLIENT_ENCODING to UTF8が含まれるようになり、バックエンドはUTF-8からデータベースが内部利用のために設定したエンコーディングに再変換できます。

-N <方針>

NULLジオメトリ操作方針(insert*=挿入, skip=スキップ, abort=強制終了)を選択します。

-n

DBFファイルのみインポートします。対応するシェープファイルを持っていない場合、 自動的にこのモードになり、DBFファイルのみロードします。 このフラグは、完全なシェープファイル群を持っていて、属性データだけが欲しくてジオメトリが欲しくない時のみ使用します。

-G

ジオメトリ型のかわりに、ジオグラフィ型で、WGS84経度緯度 (SRID=4326)を使用します (経度緯度データが必要です)。

-T <tablespace>

新しいテーブルのテーブル空間を指定します。 -Xパラメータが使われない場合には、インデックスはデフォルトのテーブル空間を使用します。PostgreSQL文書には、テーブル空間を用いるべき時に関する良い文書があります。

-X <tablespace>

新しいテーブルのインデックスで使われるテーブル空間を指定します。 主キーインデックスに適用され、-Iが合わせて使われている場合にはGiST空間インデックスにも適用されます。

ローダを使って入力ファイルを生成してアップロードするセッション例は次の通りです。

# shp2pgsql -c -D -s 4269 -i -I shaperoads.shp myschema.roadstable > roads.sql
# psql -d roadsdb -f roads.sql

変換とアップロードはUNIXのパイプを使うと一回で実行できます。

# shp2pgsql shaperoads.shp myschema.roadstable | psql -d roadsdb

4.1.5. GISデータを検索する

データは、SQLまたはシェープファイルローダ/ダンパを使ってデータベースから抜き出すことができます。SQLに関する節において、空間テーブルでの比較とクエリを行うために用いることができる演算子のいくつかを議論します。

4.1.5.1. SQLを使ってデータを検索する

データベースからデータを引き出す最も直接的な手段は、次のように、SQLのSELECTクエリを使って返ってくるレコードとカラムの数を減らし、結果のカラムを可読テキストファイルにダンプするやり方です。

db=# SELECT road_id, ST_AsText(road_geom) AS geom, road_name FROM roads;

road_id | geom                                    | road_name
--------+-----------------------------------------+-----------
          1 | LINESTRING(191232 243118,191108 243242) | Jeff Rd
          2 | LINESTRING(189141 244158,189265 244817) | Geordie Rd
          3 | LINESTRING(192783 228138,192612 229814) | Paul St
          4 | LINESTRING(189412 252431,189631 259122) | Graeme Ave
          5 | LINESTRING(190131 224148,190871 228134) | Phil Tce
          6 | LINESTRING(198231 263418,198213 268322) | Dave Cres
          7 | LINESTRING(218421 284121,224123 241231) | Chris Way
(6 rows)

しかし、返ってくる結果の数を削るために、なんらかの制限をかけることが重要となるときがあるでしょう。属性ベースの制限の場合、非空間テーブルで使う通常の文法と同じSQLを使うだけです。空間ベースの制限の場合、次の演算子が使用可能であり、便利です。

ST_Intersects

この関数は、二つのジオメトリが空間を共有しているかどうかをテストします。

=

この関数で、二つのジオメトリが幾何的に同一であるかを見ることができます。たとえば、'POLYGON((0 0,1 1,1 0,0 0))' は 'POLYGON((0 0,1 1,1 0,0 0))' と同じかを見ることができます (これは同じとなります)。

ご注意: PostGIS 2.4より前では、これはジオメトリのボックスでの比較でした。

次に、これらの演算子をクエリで使うことができます。SQLコマンドラインからジオメトリとボックスの指定を行うときは、明示的に文字列表現をジオメトリに変換しなければならないことに注意して下さい。たとえば、次のようになります。ただし312は架空の空間参照系番号で、ここでのデータに合致しています。

SELECT road_id, road_name
  FROM roads
  WHERE roads_geom='SRID=312;LINESTRING(191232 243118,191108 243242)'::geometry;

上のクエリは"ROADS_GEOM"テーブルから、その値と等価である単一のレコードを返します。

道路がポリゴンで定義した面を通過するかどうかをチェックするには次のようにします。

SELECT road_id, road_name
FROM roads
WHERE ST_Intersects(roads_geom, 'SRID=312;POLYGON((...))');

最も一般的な空間クエリは「フレームベース」のクエリでしょう。これは、表示するためのデータの価値のある「マップフレーム」を取得するために、データブラウザやウェブマッパのようなクライアントソフトウェアに使われます。

"&&"演算子を使うとき、比較フィーチャーをBOX3DかGEOMETRYかに指定することができます。ただし、GEOMETRYを指定すると、それのバウンディングボックスが比較に使われます。

次に示すクエリのように、フレームにBOX3Dオブジェクトを使います。

SELECT ST_AsText(roads_geom) AS geom
FROM roads
WHERE
  roads_geom && ST_MakeEnvelope(191232, 243117,191232, 243119,312);

エンベロープの投影を指定するためにSRID 312を使っていることに注意して下さい。

4.1.5.2. ダンパを使う

pgsql2shpテーブルダンパは、データベースに直接接続して、テーブル (あるいはクエリによって定義されたもの)をシェープファイルに変換するものです。基本的な文法は次の通りです。

pgsql2shp [<オプション>] <database> [<スキーマ>.]<table>
pgsql2shp [<オプション>] <データベース> <クエリ>

コマンドラインオプションは次の通りです。

-f <ファイル名>

特定のファイル名に出力を書きこみます。

-h <ホスト>

接続先データベースのホスト名。

-p <ポート>

接続先データベースのポート。

-P <パスワード>

データベースに接続するためのパスワード。

-u <ユーザ名>

データベースに接続する際のユーザ名。

-g <ジオメトリカラム>

複数のジオメトリカラムを持つテーブルの場合の、シェープファイルの出力に使用するジオメトリカラム。

-b

バイナリカーソルを使います。これは、実行時間を短くしますが、テーブルの非ジオメトリ属性がテキストへのキャストを持っていない場合には、動作しません。

-r

Rawモード。gidフィールドを落としたり、カラム名をエスケープしてはいけません。

-m ファイル名

識別名を10文字名に再割り当てします。 ファイルの中身は、一つの空白で区切られ、前と後に空白が無い二つのシンボルの行からなります。VERYLONGSYMBOL SHORTONE ANOTHERVERYLONGSYMBOL SHORTER等となります。

4.1.6. インデックスを構築する

インデックスは大きなデータセットを持つ空間データベースの利用を可能にするものです。インデックスなしでは、地物の検索でデータベースの全レコードを「シーケンシャルスキャン」する必要があります。インデックスをつけることで、データを検索木に組織化して、特定のレコードを発見するための検索をより早くすることができます。 PostgreSQLは、B木、SP-GiST、GiSTの3種類のインデックスにデフォルトで対応しています。

  • B木は、数字、文字、日付といった、一つの軸に沿ってソートできるデータに使用します。 空間データは空間充填曲線、Z階数曲線またはヒルベルト曲線に沿ってソートされます。しかし、この表現は一般的な演算子の速度向上を許しません。

  • GiST (Generalized Search Trees)インデックスはデータを「一方へのもの」 (訳注: 「左側にあるもの」「上側にあるもの」など)、「オーバラップするもの」、「中にあるもの」に分割して、GISデータを含む幅広いデータ型で使えるようにしたものです。PostGISではGISデータにインデックスを付けるためにGiSTの上でR木インデックス実装を使用しています。

4.1.6.1. GiSTインデックス

GiSTは「汎用的な検索木 (Generalized Search Tree)」の意味で、インデックスの一般化された形式です。GISインデックスに加えて、GiSTは通常のB木インデックスに従わない全ての種類の不規則なデータ構造 (整数配列, スペクトラルデータ等)の検索速度を向上させるために使います。

ひとたびGISデータテーブルが数千行を超えたら、空間検索の速度向上のためインデックスを構築したくなるでしょう (これは属性検索でない場合です。属性でしたら通常のインデックスを属性フィールドに追加します)。

GiSTインデックスをジオメトリカラムに追加するための文は次の通りです。

CREATE INDEX [インデックス名] ON [テーブル名] USING GIST ( [ジオメトリカラム名] ); 

上の文では常に2次元インデックスを構築します。n次元インデックスをジオメトリ型で使うには、次の文でインデックスを生成できます。

CREATE INDEX [インデックス名] ON [テーブル名] USING GIST ( [ジオメトリカラム名] gist_geometry_ops_nd);

空間インデックスの構築は、計算量を集中させて行われます。また、この時には、テーブルへの書き込みアクセスがブロックされます。そのため、本番システムではより遅いCONCURRENTLYを選択するかも知れません。次のようにします。

CREATE INDEX CONCURRENTLY [インデックス名] ON [テーブル名] USING GIST ( [ジオメトリカラム名] ); 

インデックス構築後に、時々PostgreSQLにテーブルの統計情報を集めさせると助かります。クエリプランの最適化に使われます。

VACUUM ANALYZE [テーブル名] [(カラム名)];

4.1.6.2. BRINインデックス

BRINは"Block Range Index"のことで、PostgreSQL 9.5で導入された一般性のあるインデックスの形式です。BRINは不可逆インデックスで、主に読み取り効率と書き込み効率とを妥協させるために使われます。主要な目標は、非常に大きなテーブルの取り扱いで、そのテーブルのために、テーブル内の物理的な位置との自然な相関があるカラムを一部に持ちます。GISインデックスだけでなく、BRINは規則的だったりそうでない多種多様なデータ構造 (整数、配列等)における検索速度の向上のために使われます。

ひとたびGISデータテーブルが数千行を超えたら、空間検索の速度向上のためインデックスを構築したくなるでしょう (これは属性検索でない場合です。属性でしたら通常のインデックスを属性フィールドに追加します)。GiSTインデックスは、サイズがデータベースに割り当てられているRAM容量を超えずに、ストレージサイズが十分であり、かつ書き込みワークロードのペナルティに余裕がある限りは、本当に高性能です。その他の場合にはBRINインデックスが他の選択肢として考えられます。

BRINインデックスの原理は、テーブルブロックの集合の全ての行に含まれる全てのジオメトリを余すところなく取り込んだバウンディングボックスだけを格納することです。明らかに、このインデックス手法は、ブロックレンジの結果バウンディングボックスが相互に排他的になるように、データが物理的に並ぶ場合にだけ効率が良くなります。結果インデックスは本当に小さいのですが、多くの場合で、GiSTインデックスより効率が落ちます。

BRINインデックスの構築はGiSTインデックスの構築より少ない資源集約で済みます。BRINインデックスがGiSTインデックスが求めるよりも十分の一以下であるのが本当に一般的です。BRINインデックスは、多数のテーブルブロックに対して一つのバウンディングボックスを格納するだけなので、この手の他のインデックスよりもディスク使用量が数千分の一程度で済むのが一般的です。

レンジ内で要約するブロック数を選択できます。この数字を減らすと、インデックスは大きくなりますが、効率向上の助けになる可能性があります。

BRINインデックスを「ジオメトリ」カラムに追加するための文は次の通りです。

CREATE INDEX [インデックス名] ON [テーブル名] USING BRIN ( [ジオメトリカラム名] ); 

上の文では常に2次元インデックスを構築します。3次元インデックスは次の文で生成できます。

CREATE INDEX [インデックス名] ON [テーブル名] USING BRIN ( [ジオメトリカラム名] brin_geometry_inclusion_ops_3d);

また、4次元演算子クラスを使う4次元インデックスを使うこともできます。

CREATE INDEX [インデックス名] ON [テーブル名] USING BRIN ( [ジオメトリカラム名] brin_geometry_inclusion_ops_4d);

上の書式では、デフォルトの数値やレンジ内ブロック数を使っていますが、値は128です。ブロック数を指定するには、レンジ内の要約をすることになります。次の文のようにして作ります。

CREATE INDEX [インデックス名] ON [テーブル名] USING BRIN ( [ジオメトリカラム名] ) WITH (pages_per_range = [数字]); 

また、BRINインデックスは、多数の行で一つのインデックス値を格納することを心に留めておいて下さい。テーブルに違う次元のジオメトリを格納する場合には、インデックスの効率が悪くなります。この効率欠落を回避するには、格納したジオメトリの次元数の最小値となる演算子クラスを選択します。

「ジオグラフィ」型もまたBRINインデックスに対応しています。BRINインデックスを「ジオグラフィ」カラムに構築するための文は次の通りです。

CREATE INDEX [インデックス名] ON [テーブル名] USING BRIN ( [ジオグラフィカラム名] ); 

上の書式では常に回転楕円対面上の地理空間オブジェクトの2次元インデックスを構築します。

現在のところは「包括対応」だけをここで考えています。これは、&&~@演算子だけが2次元の場合に使われることを意味します (「ジオメトリ」「ジオグラフィ」の両方)。&&&演算子は3次元ジオメトリで使えます。しばらくはKNN検索に対応しません。

4.1.6.3. SP-GiSTインデックス

SP-GiSTは、「空間分割された一般探索木」を表します。四分木、k次元木、基数木 (トライ木)のような分割探索木に対応するインデックスの総称的な形式です。このデータ構造の一般的な機能は、検索空間を反復して分割することですが、分割は等しいサイズである必要はありません。SP-GiSTは、GISインデックスだけでなく、電話回線のルーティングや、IPルーティング、部分文字列検索等といった、様々な種類のデータを探索する速度の向上に使われます。

GiSTインデックスのためのケースですので、空間オブジェクトを覆うバウンディングボックスを保存するという意味で、SP-GiSTインデックスは不可逆です。SP-GiSTインデックスは、GiSTインデックスの選択肢の一つとして考えることができます。能率試験によって、SP-GiSTインデックスは,、多数のオーバラップするオブジェクトがある「スパゲッティデータ」と呼ばれる状態のときに、特に有利であることが分かりました。

一度GISデータテーブルが数千行を超えると、データの空間探索の速度向上にSP-GiSTインデックスを使うと良いかも知れません。「ジオメトリ」カラムにSP-GiSTインデックスを構築するための文は次の通りです。

CREATE INDEX [インデックス名] ON [テーブル名] USING SPGIST ( [ジオメトリカラム] ); 

上の文では、2次元インデックスを構築します。ジオメトリ型の3次元インデックスは、次のように、3次元演算子クラスを使用して生成します。

CREATE INDEX [インデックス名] ON [テーブル名] USING SPGIST ([ジオメトリカラム] spgist_geometry_ops_3d);

空間インデックスの構築は、計算量を集中させて行われます。また、この時には、テーブルへの書き込みアクセスがブロックされます。そのため、本番システムでは、より遅いCONCURRENTLYを選択するかも知れません。次のようにします。

CREATE INDEX CONCURRENTLY [インデックス名] ON [テーブル名] USING SPGIST ( [ジオメトリカラム] ); 

インデックス構築後に、時々PostgreSQLにテーブルの統計情報を集めさせると助かります。クエリプランの最適化に使われます。

VACUUM ANALYZE [テーブル名] [(カラム名)];

SP-GiSTインデックスは次の演算子を含むクエリの実行速度を向上させられます。

  • 2次元インデックスについては <<, &<, &>, >>, <<|, &<|, |&>, |>>, &&, @>, <@, and ~= 。

  • 3次元インデックスについては &/&, ~==, @>>, and <<@ 。

現時点ではkNN探索に対応していません。

4.1.6.4. インデックスを使う

通常、インデックスは見えないところでデータアクセスの速度向上を行います。すなわち、ひとたびインデックスが構築されたら、クエリプランナは透過的に、クエリプランの速度を向上させるためにインデックス情報を使うべき時を判断します。残念なことに、PostgreSQLクエリプランナは、GiSTインデックスの使用について十分に最適化できず、時々、検索で空間インデックスを使用すべきなのに、テーブル全体を順に走査することがあります。

空間インデックスが使用されていない (または属性インデックスがその問題のために使用されていない)場合、次の二つのことができます。

  • まず、クエリプランを読んで、クエリが実際に必要な計算をしようとしているか確認します。JOIN条件を忘れていたり、間違ったテーブルに付けていたりすることで、暴走することがあり、予期せずに何度もテーブル全体を得ることになります。クエリプランを取得するには、クエリの前にEXPLAINキーワードを追加します。

  • 次に、テーブル内の値の数量と分布に関する統計情報を収集するとともに、クエリプランナにインデックス使用にかかる意思決定のための、より良い情報を与えるようにします。VACUUM ANALYZEは両方を計算します。

    データベースに対する定期的なvacuumは常に実行するべきです。多くのPostgreSQLデータベースエージェントは、閑散時のcronジョブとして定期的にVACUUMを実行します。

  • vacuumが働かないなら、set enable_seqscan to off;コマンドで、一時的にプランナに対してインデックス情報の使用を強制することができます。この方法で、プランナがインデックスを使用するプランを生成できるかどうか確認できます。このコマンドはデバッグにのみ使用すべきです。一般的に言うと、プランナはあなたよりインデックスを使うべき時を知っています。クエリを実行したら、ENABLE_SEQSCAN設定を戻して、他のクエリでは通常通りプランナを使用します。

  • もし、set enable_seqscan to off;がクエリの実行に役立っているなら、お使いのPostgreSQLはハードウェアにあわせた調整をしていないようです。順に走査する際のコストとインデックスを使う際のコストとを比較してプランナが間違っていることに気付いたら、postgresql.confでrandom_page_costの値を減らしてみるか、set random_page_cost to 1.1;を使ってみてください。このパラメータのデフォルト値は4ですが、それを1 (SSDの場合)または2 (高速磁気ディスクの場合)にして下さい。値を減らすことで、プランナがよりインデックススキャンを行う傾向になります。

  • set enable_seqscan to off;がクエリの役に立たない場合には、PostgreSQLがまだ解決できない構文を使ってしまっているのかもしれません。インラインSELECTのサブクエリが一つの例です。プランナが最適化できるように書き直す必要があります。LATERAL JOINと呼びます。

4.1.7. 複雑なクエリ

空間データベース機能のレゾンデートルは、通常はデスクトップGISに求める機能を、データベース内部のクエリで実現してすることです。PostGISを効果的に使用するには、どの空間関数が有効かを知り、また、良好なパフォーマンスを提供する所に適切にインデックスがあることが保証されていることが求められます。なお、本例ではSRID 312を使っていますが、これは純粋に例として出しているだけです。spatial_ref_sysテーブルにあり、データの投影法に合致している、本当のSRIDを使ってください。空間参照系を持たないデータについては、なぜ持っていないのか、持つべきなのかも知れないのか、をじっくり*考えてください*。 たとえば分子内部や火星旅行の到達位置といった、定義された空間参照系を持たない場合には、単にSRIDを無視するか、一つ作成してspatial_ref_sysテーブルに追加して下さい。

分子の内部構造や開発前の遊園地の間取り図といった、空間参照系を持たないものを扱うためだったら、問題ありません。ただし、遊園地の位置が決まっている場合だと、遊園地が既存構造の上に入り込まないようにするためだけでも、その位置に適切な平面座標系を使うようにします。

核戦争時に人類を輸送するための火星遠征を計画し、火星居住用の地図を作成する場合であったとしても、Mars 2000といった地球以外の座標系を作成し、spatial_ref_sysに挿入して使うことができます。この火星座標系は非平面 (回転楕円体面の度)ですが、ジオグラフィ型で長さや、計測近似値を、度単位でなくメートル単位で得ることができます。

4.1.7.1. インデックスの利点を使う

クエリを作成するとき、&&のようなバウンディングボックスを基準とした演算子によってのみGiST空間インデックスの利点が出てくることだけは覚えておくことが重要です。ST_Distance()のような関数では演算の最適化を行うためにインデックスを使うことができません。たとえば、次のクエリでは、大きなテーブルでは本当に遅くなります。

SELECT the_geom
FROM geom_table
WHERE ST_Distance(the_geom, 'SRID=312;POINT(100000 200000)') < 100

このクエリは、geom_tableにおける (100000, 200000)の点から距離が100単位以内にある全てのジオメトリを選択します。このクエリは、テーブル内にあるそれぞれの点と指定した点との距離を計算する、すなわち、それぞれの行で一つのST_Distance()計算を行うため、遅くなります。1ステップでインデックスを利用するST_DWithin関数を使って、求められる距離計算の量を減らすことで回避できます。次のようにします。

SELECT the_geom
FROM geom_table
WHERE ST_DWithin(the_geom, 'SRID=312;POINT(100000 200000)', 100)

このクエリは、同じジオメトリを選択しますが、より効果的な方法で行われます。the_geomにGiSTインデックスがあると仮定すると、クエリプランナはST_Distance()関数の結果を計算する前にインデックスを使って行を減らせると認識します。 &&演算子で使われるST_MakeEnvelopeジオメトリは、元のポイントに中央寄せした200単位の正方形です。これは「クエリボックス」です。&&演算子は、結果セットを「クエリボックス」にオーバラップするバウンディングボックスを持つジオメトリだけに素早く減らすためにインデックスを使います。「クエリボックス」がジオメトリテーブル全体の範囲より十分に小さいと仮定すると、行われなければならない距離計算の量は劇的に減少します。

4.1.7.2. 空間SQLの例

本節の例では、線型の道、ポリゴンの自治体境界、の二つのテーブルを使います。テーブルの定義をしまします。bc_roadsについては次の通りです。

Column      | Type              | Description
------------+-------------------+-------------------
gid         | integer           | Unique ID
name        | character varying | Road Name
the_geom    | geometry          | Location Geometry (Linestring)

bc_municipalityテーブルの定義については次の通りです。

Column     | Type              | Description
-----------+-------------------+-------------------
gid        | integer           | Unique ID
code       | integer           | Unique ID
name       | character varying | City / Town Name
the_geom   | geometry          | Location Geometry (Polygon)
4.1.7.2.1. 道路の総延長はkm表記でいくらになるでしょう?
4.1.7.2.2. プリンスジョージ市の大きさはha表記でいくらになるでしょう?
4.1.7.2.3. 県内で最も大きな面積となる自治体はどこでしょう?
4.1.7.2.4. 各自治体内に含まれる道路の総延長はいくらでしょう?
4.1.7.2.5. プリンスジョージ市内の全ての道路からなるテーブルを作る
4.1.7.2.6. ビクトリア州の「ダグラス通り」の長さはkm表記でいくらになるでしょう?
4.1.7.2.7. 穴を持つ自治体ポリゴンのうち最も大きいのはどれでしょう?

4.1.7.2.1.

道路の総延長はkm表記でいくらになるでしょう?

この問題は、次のようなとても単純なSQLで答えを得ることができます。

SELECT sum(ST_Length(the_geom))/1000 AS km_roads FROM bc_roads;

km_roads
------------------
70842.1243039643
(1 row)

4.1.7.2.2.

プリンスジョージ市の大きさはha表記でいくらになるでしょう?

このクエリでは、属性条件 (municipality name, 自治体名)に空間計算 (面積)を併用しています。

SELECT
  ST_Area(the_geom)/10000 AS hectares
FROM bc_municipality
WHERE name = 'PRINCE GEORGE';

hectares
------------------
32657.9103824927
(1 row)

4.1.7.2.3.

県内で最も大きな面積となる自治体はどこでしょう?

このクエリは、空間計測をクエリ条件に持ってきています。この問題へのアプローチの方法はいくつかありますが、最も効率的なのは次の通りです。

SELECT
  name,
  ST_Area(the_geom)/10000 AS hectares
FROM
  bc_municipality
ORDER BY hectares DESC
LIMIT 1;

name           | hectares
---------------+-----------------
TUMBLER RIDGE  | 155020.02556131
(1 row)

このクエリの答えを出すためには、全てのポリゴンの面積を求める必要があることに注意して下さい。このクエリを多く実行する場合、性能向上のためにテーブルにareaカラムを追加して、別のインデックスを追加することができるようにするのは、意義のあることです。結果を距離について降順に並べ替え、PostgreSQLの"LIMIT"コマンドを用いることで、max()のような集約関数を使わずに、簡単に最も大きい値を集約関数を得ることができます。

4.1.7.2.4.

各自治体内に含まれる道路の総延長はいくらでしょう?

これは、二つのテーブルからデータを持ち込んで (結合して)いるので「空間結合」の例です。しかし、結合の条件として共通キーの上で接続するという普通のリレーションのやり方でなく空間インタラクション条件 (「含む」)を使っています。

SELECT
  m.name,
  sum(ST_Length(r.the_geom))/1000 as roads_km
FROM
  bc_roads AS r,
  bc_municipality AS m
WHERE
  ST_Contains(m.the_geom, r.the_geom)
GROUP BY m.name
ORDER BY roads_km;

name                        | roads_km
----------------------------+------------------
SURREY                      | 1539.47553551242
VANCOUVER                   | 1450.33093486576
LANGLEY DISTRICT            | 833.793392535662
BURNABY                     | 773.769091404338
PRINCE GEORGE               | 694.37554369147
...

このクエリは、テーブル内の全ての道路の合計を最終結果 (この例での話ですが約250Kmの道です)にまとめられるので、少し時間がかかります。より小さいオーバレイ (数百の道路で数千のレコード)の場合、応答はもっと早くなりえます。

4.1.7.2.5.

プリンスジョージ市内の全ての道路からなるテーブルを作る

これは「オーバレイ」の例です。つまり、二つのテーブルを取得して、空間的に切り取られた結果からなる新しいテーブルを出力します。上で示した「空間結合」と違い、このクエリは実際に新しいジオメトリを生成します。生成されたオーバレイはターボのかかった空間結合みたいなもので、より確かな解析作業に便利です。

CREATE TABLE pg_roads as
SELECT
  ST_Intersection(r.the_geom, m.the_geom) AS intersection_geom,
  ST_Length(r.the_geom) AS rd_orig_length,
  r.*
FROM
  bc_roads AS r,
  bc_municipality AS m
WHERE
  m.name = 'PRINCE GEORGE'
        AND ST_Intersects(r.the_geom, m.the_geom);

4.1.7.2.6.

ビクトリア州の「ダグラス通り」の長さはkm表記でいくらになるでしょう?

SELECT
  sum(ST_Length(r.the_geom))/1000 AS kilometers
FROM
  bc_roads r,
  bc_municipality m
WHERE
        r.name = 'Douglas St'
        AND m.name = 'VICTORIA'
        AND ST_Intersects(m.the_geom, r.the_geom);

kilometers
------------------
4.89151904172838
(1 row)

4.1.7.2.7.

穴を持つ自治体ポリゴンのうち最も大きいのはどれでしょう?

SELECT gid, name, ST_Area(the_geom) AS area
FROM bc_municipality
WHERE ST_NRings(the_geom) > 1
ORDER BY area DESC LIMIT 1;

gid  | name         | area
-----+--------------+------------------
12   | SPALLUMCHEEN | 257374619.430216
(1 row)

4.2. PostGISを使う: アプリケーションを構築する

4.2.1. MapServerを使う

Minnesota MapServerはOpenGIS Web Mapping Server仕様を満たすウェブマッピングサーバです。

4.2.1.1. 基本的な使い方

MapServerでPostGISを使うには、MapServerのコンフィギュレーション方法についての知識が必要ですが、この文書の範囲外です。この節では、PostGIS特有の問題とコンフィギュレーション詳細について記載します。

PostGISをMapServerで使うには、次のものが必要です。

  • PostGIS 0.6以上

  • MapServer 3.5以上

MapServerは、他のクライアントのように、libpqインタフェースを使って、PostGIS/PostgreSQLデータにアクセスします。よってMapServerはPostGISサーバにアクセスするネットワークを持つ計算機にインストールでき、PostGISをデータソースとして使用することができます。システム間の接続は速いほど良いです。

  1. "--with-postgis"と好きなconfigureオプションを付けてMpaServerのコンパイルとインストールを行います。

  2. Mapserverのmapファイルの中に、PostGISレイヤを追加します。たとえば次のようになります。

    LAYER
      CONNECTIONTYPE postgis
      NAME "widehighways"
      # リモートの空間データベースに接続します
      CONNECTION "user=dbuser dbname=gisdatabase host=bigserver"
      PROCESSING "CLOSE_CONNECTION=DEFER"
      # 'roads'テーブルの'geom'カラムからラインを取得します
      DATA "geom from roads using srid=4326 using unique gid"
      STATUS ON
      TYPE LINE
      # 範囲内のラインである広い高速道路のみ描画します
      FILTER "type = 'highway' and numlanes >= 4"
      CLASS
        # 非常に広い高速道路はより明るい色かつ2ピクセル幅にします
        EXPRESSION ([numlanes] >= 6)
        STYLE
          COLOR 255 22 22
          WIDTH 2
        END
      END
      CLASS
         # 残りは、暗い色かつ1ピクセル幅です
        EXPRESSION ([numlanes] < 6)
        STYLE
          COLOR 205 92 82
        END
      END
    END

    上の例におけるPostGIS特有のディレクティブは次の通りです。

    CONNECTIONTYPE

    PostGISレイヤでは常に"postgis"とします。

    CONNECTION

    データベース接続は「接続文字列」によって制御されます。接続文字列は、次に示すような標準的なキーと値からなります(<>内はデフォルト値)。

    user=<ユーザ名> password=<パスワード> dbname=<ユーザ名> hostname=<サーバ> port=<5432>

    空の接続文字列も妥当とされますし、あらゆるキーと値のペアは省略できます。接続するためには一般的にはdbnameとusernameとが最少で与えるものとなります。

    DATA

    このパラメータの形式は "<カラム名> from <テーブル名> using srid=<SRID> using unique <主キー>"となります。ここで、カラム名は地図に描画したい空間カラムを指し、SRIDはそのカラムで使われるSRIDで、主キーはそのテーブルの主キー (またはインデックスを伴う一意の値を持つカラム)です。

    "using srid"と"using unique"節は省略できます。MapServerは可能なら自動的に正しい値を判断しますが、地図を描画するサーバ上で余分なクエリを若干実行するコストがかかります。

    PROCESSING

    接続を閉じずに複数のレイヤで再利用する場合にCLOSE_CONNECTION=DEFERとします。速度が改善します。詳細な説明についてはMapServer PostGIS Performance Tipsを参照して下さい。

    FILTER

    フィルタは、妥当なSQL文字列でなければなりません。この文字列は、通常はSQLクエリにおける"WHERE"に続く論理式に対応します。たとえば、6レーン以上の道路だけを描画する場合には、"num_lanes >= 6"というフィルタを使います。

  3. 空間データベースにおいては、空間 (GiST)インデックスを、マップに描かれるレイヤ全てに構築していることを保証して下さい。

    CREATE INDEX [インデックス名] ON [テーブル名] USING GIST ( [ジオメトリカラム] );
  4. MapServerを使用するレイヤのクエリを実行する場合には、"using unique"節もDATAステートメントに追加しなければなりません。

    MapServerでは、クエリ実行の際には、それぞれの空間レコードを識別するための一意な識別子が必要です。MapServerのPostGISモジュールは、一意な識別子を提供するために、ユーザ指定の一意な値を使います。テーブルの主キーを使うのが最も良い方法です。

4.2.1.2. よくある質問

4.2.1.2.1. EXPRESSIONをマップファイルで使う時に、値がテーブルにあるのを確認しているのに条件がtrueになりません。
4.2.1.2.2. シェープファイルで使っているFILTERが、同じデータを持つPostGISテーブルでは動作しません。
4.2.1.2.3. PostGISレイヤの描画がシェープファイルより遅くなりますが、これが普通なのでしょうか?
4.2.1.2.4. PostGISレイヤはちゃんと描けましたが、クエリが本当に遅いです。何が問題なのですか?
4.2.1.2.5. ジオグラフィカラム (PostGIS 1.5で機能追加)をMapServerのレイヤのソースとして使用できますか?

4.2.1.2.1.

EXPRESSIONをマップファイルで使う時に、値がテーブルにあるのを確認しているのに条件がtrueになりません。

EXPRESIONで使うフィールド名は、シェープファイルと違ってPostGISの場合小文字になります。

EXPRESSION ([numlanes] >= 6)

4.2.1.2.2.

シェープファイルで使っているFILTERが、同じデータを持つPostGISテーブルでは動作しません。

シェープファイルと違い、PostGISレイヤのフィルタはSQL構文を使います (PostGISコネクタがMapServerでレイヤを描画するために生成するSQLステートメントに追加されます)。

FILTER "type = 'highway' and numlanes >= 4"

4.2.1.2.3.

PostGISレイヤの描画がシェープファイルより遅くなりますが、これが普通なのでしょうか?

一般的に、地図に描画されるフィーチャーが多くなると、PostGISはシェープファイルより遅くなります。比較的少ないフィーチャー (100件台)ではPostGISの方が早く、フィーチャー密度が高くなる (1000件台)と、PostGISの方が遅くなります。

重大な描画性能の問題があるようでしたら、テーブルにある空間インデックスを構築していないというのがありそうです。

postgis# CREATE INDEX geotable_gix ON geotable USING GIST ( geocolumn );
postgis# VACUUM ANALYZE;

4.2.1.2.4.

PostGISレイヤはちゃんと描けましたが、クエリが本当に遅いです。何が問題なのですか?

クエリを早くするには、空間テーブルに一意なキーを持たせ、そのキーにインデックスを持たせなければなりません。

DATA行のUSING UNIQUE節で、MapServerで使用する一意なキーをどれにするか指定することができます。

DATA "geom FROM geotable USING UNIQUE gid"

4.2.1.2.5.

ジオグラフィカラム (PostGIS 1.5で機能追加)をMapServerのレイヤのソースとして使用できますか?

できます!MapServerはジオグラフィカラムをジオメトリカラムと同じに認識します。しかし、常にSRIDを4326とします。"using srid=4326"節をDATAステートメントに入れて下さい。他の部分はジオメトリの場合と同じです。

DATA "geog FROM geogtable USING SRID=4326 USING UNIQUE gid"

4.2.1.3. 踏み込んだ使用法

USING疑似SQL節を使ってMapServerがより複雑なクエリの結果を理解できるようにするための情報を追加します。より詳しく言うと、ビューまたは副問い合わせが元テーブル (DATA定義で"FROM"の右にあるもの)として使われる時、MapServerが自動的に一意な識別子がそれぞれの行にあるか、また、SRIDがテーブルにあるかを判別するのは困難です。USING節によって、MapServerがこれらの情報を得ることができます。例を次に挙げます。

DATA "geom FROM (
  SELECT
    table1.geom AS geom,
    table1.gid AS gid,
    table2.data AS data
  FROM table1
  LEFT JOIN table2
  ON table1.id = table2.id
) AS new_table USING UNIQUE gid USING SRID=4326"
USING UNIQUE <uniqueid>

MapServerは、マップクエリを実行する際、行識別のために、それぞれの行に一意な識別子を求めます。通常ならシステムテーブルから主キーを識別しますが、ビューや副問い合わせでは、一意性のあるカラムを自動的に知ることができません。MapServerのクエリ機能を使いたいなら、一意性のあるカラムをビューまたは副問い合わせに追加する必要があり、USING UNIQUE宣言を付ける必要があります。たとえば、この目的のための主キー値のテーブルでのカラム名や、結果セットで一意性が保障されたカラムを明示的にSELECTに入れることができます。

[Note]

「マップクエリ」はマップ上でクリックして、その場所におけるフィーチャーに関する情報を問い合わせる動作です。「マップクエリ」とDATA定義におけるSQLクエリと混同しないで下さい。

USING SRID=<srid>

PostGISは、MapServerに正しいデータを返すために、ジオメトリがどの空間参照系を使っているかを知る必要があります。通常は、この情報はPostGISデータベースの"geometry_columns"テーブルから得ることができます。しかし、副問い合わせやビューのような一時テーブルでは、この方法は不可能です。そこで、 USING SRID=オプションを使って、正しいSRIDがDATA定義で使われるように指定します。

4.2.1.4. 例

簡単な例から始めて、ステップアップしていきましょう。次のMapServerレイヤ定義を考えて下さい。

LAYER
  CONNECTIONTYPE postgis
  NAME "roads"
  CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
  DATA "geom from roads"
  STATUS ON
  TYPE LINE
  CLASS
    STYLE
      COLOR 0 0 0
    END
  END
END

このレイヤは"roads"テーブルにある道路ジオメトリの全部を黒線で表示するものです。

では、少なくとも1:100000にズームするまでは高速道路だけを表示したい、としましょう。次の二つのレイヤで、その効果が実現できます。

LAYER
  CONNECTIONTYPE postgis
  CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
  PROCESSING "CLOSE_CONNECTION=DEFER"
  DATA "geom from roads"
  MINSCALE 100000
  STATUS ON
  TYPE LINE
  FILTER "road_type = 'highway'"
  CLASS
    COLOR 0 0 0
  END
END
LAYER
  CONNECTIONTYPE postgis
  CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
  PROCESSING "CLOSE_CONNECTION=DEFER"
  DATA "geom from roads"
  MAXSCALE 100000
  STATUS ON
  TYPE LINE
  CLASSITEM road_type
  CLASS
    EXPRESSION "highway"
    STYLE
      WIDTH 2
      COLOR 255 0 0
    END
  END
  CLASS
    STYLE
      COLOR 0 0 0
    END
  END
END

一つ目のレイヤはスケールが1:100000以上であるときに使われ、道路タイプが"highway"である道路のみ黒線で表示されます。FILTERオプションによって、道路タイプが"highway"の場合のみ表示することになります。

二つ目のレイヤはスケールが1:100000未満である時に使われ、"highway"は赤い二重細線で表示され、他の道路は黒線で表示されます。

さて、MapServerの機能を使うだけで、二つのおもしろいことを実行しました。しかし、DATAのSQLステートメントは、単純なままです。道路名が (どういう理由かは知りませんが)他のテーブルに収められていて、それのデータを取得するためにテーブルを連結して、道路のラベルを取る必要がある、とします。

LAYER
  CONNECTIONTYPE postgis
  CONNECTION "user=theuser password=thepass dbname=thedb host=theserver"
  DATA "geom FROM (SELECT roads.gid AS gid, roads.geom AS geom,
        road_names.name as name FROM roads LEFT JOIN road_names ON
        roads.road_name_id = road_names.road_name_id)
        AS named_roads USING UNIQUE gid USING SRID=4326"
  MAXSCALE 20000
  STATUS ON
  TYPE ANNOTATION
  LABELITEM name
  CLASS
    LABEL
      ANGLE auto
      SIZE 8
      COLOR 0 192 0
      TYPE truetype
      FONT arial
    END
  END
END

このANNOTAIONレイヤでは、縮尺が1:20000以下のときに、全ての道路に緑色のラベルを表示します。また、この例は、 DATA定義で、SQLのJOINを使用する方法も示しています。

4.2.2. Javaクライアント (JDBC)

Javaクライアントは、直接的にテキスト表現として、またはPostGISに同梱されているJDBC拡張オブジェクトを使用して、PostgreSQLデータベース内にある、PostGISの"geometry"オブジェクトにアクセスできます。JDBC拡張オブジェクトを使うためには、"postgis.jar"ファイルを、JDBCドライバパッケージの"postgresql.jar"とともに、 CLASSPATHに置く必要があります。

import java.sql.*;
import java.util.*;
import java.lang.*;
import org.postgis.*;

public class JavaGIS {

public static void main(String[] args) {

  java.sql.Connection conn;

  try {
    /*
    * JDBCドライバをロードして接続を確立します。
    */
    Class.forName("org.postgresql.Driver");
    String url = "jdbc:postgresql://localhost:5432/database";
    conn = DriverManager.getConnection(url, "postgres", "");
    /*
    * ジオメトリ型を接続に追加します。
    * ご注意 : addDateType()を呼ぶ前に
    *   接続をpgsql特有の接続実装にキャストしなければなりません。
    */
    ((org.postgresql.PGConnection)conn).addDataType("geometry",Class.forName("org.postgis.PGgeometry"));
    ((org.postgresql.PGConnection)conn).addDataType("box3d",Class.forName("org.postgis.PGbox3d"));
    /*
    * ステートメントの生成とSELECTクエリの実行を行います。
    */
    Statement s = conn.createStatement();
    ResultSet r = s.executeQuery("select geom,id from geomtable");
    while( r.next() ) {
      /*
      * ジオメトリをオブジェクトとして検索してジオメトリ型にキャストします。
      * オブジェクトを印字します
      */
      PGgeometry geom = (PGgeometry)r.getObject(1);
      int id = r.getInt(2);
      System.out.println("Row " + id + ":");
      System.out.println(geom.toString());
    }
    s.close();
    conn.close();
  }
catch( Exception e ) {
  e.printStackTrace();
  }
}
}

"PGeometry"オブジェクトは、Point、LineString、Polygon、MultiPoint、MultiLineString、MultiPolygonの各型に依存する、特定のトポロジカルジオメトリオブジェクト ("Geometory"抽象クラスの子クラス)を持つラッパオブジェクトです。

PGgeometry geom = (PGgeometry)r.getObject(1);
if( geom.getType() == Geometry.POLYGON ) {
  Polygon pl = (Polygon)geom.getGeometry();
  for( int r = 0; r < pl.numRings(); r++) {
    LinearRing rng = pl.getRing(r);
    System.out.println("Ring: " + r);
    for( int p = 0; p < rng.numPoints(); p++ ) {
      Point pt = rng.getPoint(p);
      System.out.println("Point: " + p);
      System.out.println(pt.toString());
    }
  }
}

幾何オブジェクトのさまざまなデータアクセサ関数に関する参照情報については、拡張オブジェクトのJavaDocをご覧下さい。

4.2.3. Cクライアント (libpq)

...

4.2.3.1. テキストカーソル

...

4.2.3.2. バイナリカーソル

...

4.3. ラスタデータの管理、クエリ、アプリケーション

4.3.1. ラスタのロードと生成

raster2pgsqlラスタローダを使ってPostGISラスタを既存のラスタファイルからロードするのは、最もよく行われます。

4.3.1.1. raster2pgsqlを使ってラスタをロードする

raster2pgsqlは、GDALがサポートするラスタ書式をPostGISラスタテーブルにロードするのに適切なSQLにするバイナリファイルです。ラスタのオーバビューの生成だけでなく、ラスタファイルのフォルダのロードも可能です。

raster2pgsqlは、ほとんどの場合、PostGISの一部としてコンパイルされます (GDALライブラリをコンパイルしている場合)が、バイナリファイルによってサポートされるラスタタイプは、GDALでコンパイルされたのと同じです。raster2pgsqlがサポートするラスタタイプの一覧を得るには、-Gスイッチを使います。この一覧は、インストールした PostGIS が提供するST_GDALDriversと同じになるはずです。

[Note]

このツールの古い版では、Pythonスクリプトでした。実行ファイルに置き換えられています。Pythonスクリプトが必要な場合は、 GDAL PostGIS Raster Driver Usageに、Pythonの例があります。raster2pgsqlのPythonスクリプトは、今後のPostGIS rasterでは動作しないかも知れませんし、サポートされませんので、ご注意ください。

[Note]

同じアラインメントを持つラスタの集合から特定の要素のオーバビューを生成する時、オーバビューが同じアラインメントを持たないことがあります。オーバビューが同じアラインメントを持たない例についてはhttp://trac.osgeo.org/postgis/ticket/1764をご覧下さい。

使用例:

raster2pgsql raster_options_go_here raster_file someschema.sometable > out.sql

-?

ヘルプを表示します。引数を全く指定しない場合にも表示されます。

-G

サポートされているラスタ書式を印字します。

(c|a|d|p) 相互に排他的なオプションです

-c

新しいテーブルを生成し、ラスタを入れます。これがデフォルトモードです

-a

既存のテーブルにラスタを追加します。

-d

テーブルを削除し、新しいテーブルを生成し、ラスタを入れます。

-p

準備モード、テーブルを作るだけです。

ラスタ処理: ラスタカタログに適切に登録するための制約の適用

-C

SRIDやピクセルサイズ等のラスタ制約を適用して、raster_columnsビューで適切な登録ができるようにします。

-x

制約の最大範囲を無効にします。-Cフラグが使われている場合のみ適用されます。

-r

正規ブロック制約 (空間的に一意で網羅タイル)を適用します。-Cフラグが使用されている場合のみ適用されます。

ラスタ処理: 入力ラスタデータセットの操作に使われる追加的なパラメータ

-s <SRID>

出力ラスタを指定されたSRIDにします。 指定しないか0を指定した場合、ラスタのメタデータに対して、適切なSRIDを決定するためのチェックを行います。

-b BAND

ラスタから抽出するバンドのインデクス (1始まり)。1より多いバンドを抽出するには、コンマ(,)で区切ります。指定しない場合、全てのバンドが抽出されます。

-t TILE_SIZE

行毎に挿入するラスタを切断します。TILE_SIZEは、「幅x高さ」で表現しますが、"auto"を指定すると、最初のラスタを使って適切なタイルサイズが計算され、全てのラスタに適用されます。

-P

全てのタイルが同じ幅と高さを持つことを保証するために、右端、下端のタイルに詰め物を施します。

-R, --register

ファイルシステム (データベース外)ラスタとして、ラスタを登録します。

データベースには、ラスタのメタデータとラスタのファイルパスのみ格納されます (ピクセルは格納されません)。

-l OVERVIEW_FACTOR

ラスタのオーバビューを生成します。一つより多い係数を用いる場合は、コンマ (,) で区切ります。オーバビューのテーブル名はo_overview factor_tableとなります。overview factorにはオーバビュー係数が入り、tableには基底テーブル名が入ります。生成されるオーバビューはデータベースに格納され、-Rは無視されます。生成されたSQLファイルは元データのテーブルとオーバビューテーブルの両方を含むことに注意して下さい。

-N NODATA

NODATA値を持たないバンドで使用するNODATA値を設定します。

テータベースオブジェクトの操作に使われる追加的なパラメータ

-f COLUMN

出力先ラスタカラムの名前を指定します。デフォルトは'rast'です。

-F

ファイル名でカラムを追加します。

-n COLUMN

ファイル名カラムの名前を指定します。-Fを暗に含みます。

-q

PostgreSQL識別子に引用符を付けます。

-I

ラスタカラムにGiSTインデクスを生成します。

-M

ラスタテーブルにvacuum analyzeを行います。

-k

バンドごとのNODATA値のチェックを省略します。

-T tablespace

生成されるテーブルのテーブルスペースを指定します。-Xフラグを併用しない場合には、インデクス (主キーを含む)はデフォルトのテーブルスペースを使用することにご注意ください。

-X tablespace

テーブルの新しいインデクスに使うテーブル空間を指定します。主キーに適用され、-Iフラグがある場合においては空間インデクスにも適用されます。

-Y

INSERTステートメントでなくCOPYステートメントを使います。

-e

ステートメント毎に実行して、トランザクションを使用しないようにします。

-E ENDIAN

生成されるラスタのバイナリ出力のエンディアンを制御します。XDR (訳注: ビッグエンディアン)の場合は0を、NDR (訳注:リトルエンディアン)の場合は1を、それぞれ指定します。デフォルトは1です。現時点ではNDR出力のみサポートします。

-V version

出力書式の版を指定します。デフォルトは0です。現時点では0のみサポートします。

ローダを用いて入力ファイルを100x100のタイルで生成して、データベースにアップロードする例は、次の通りです。

[Note]

public.demelevationでなくdemelevation というようにスキーマ名を外すことができます。この場合、ラスタテーブルはデータベースまたユーザの指定するデフォルトのスキーマに生成されます。

raster2pgsql -s 4326 -I -C -M *.tif -F -t 100x100 public.demelevation 
> elev.sql
psql -d gisdb -f elev.sql

変換とアップロードはUNIXのパイプを使うと一回で実行できます。

raster2pgsql -s 4326 -I -C -M *.tif -F -t 100x100 public.demelevation | psql -d gisdb

マサチューセッツ州平面のメートル単位の空中写真タイルをaerialという名前のスキーマにロードします。 元の画像と2, 4レベルのオーバビューのテーブルとを生成します。 データ格納にCOPYを使用し (データベースに仲介ファイルなくまっすぐ入ります)、-eでトランザクションを指定しないようにします (待たずにテーブルのデータを見たい場合には良いです)。ラスタを128x128ピクセルのタイルに分解してラスタ制約を適用します。INSERTモードでなくCOPYモードを使用します。-Fで、カラム名をタイル切り出し元ファイルのファイル名にします。

raster2pgsql -I -C -e -Y -F -s 26986 -t 128x128  -l 2,4 bostonaerials2008/*.jpg aerials.boston | psql -U postgres -d gisdb -h localhost -p 5432
-- サポートされているラスタタイプの一覧:
raster2pgsql -G

-Gコマンドの出力は次のようになります。

Available GDAL raster formats:
  Virtual Raster
  GeoTIFF
  National Imagery Transmission Format
  Raster Product Format TOC format
  ECRG TOC format
  Erdas Imagine Images (.img)
  CEOS SAR Image
  CEOS Image
  JAXA PALSAR Product Reader (Level 1.1/1.5)
  Ground-based SAR Applications Testbed File Format (.gff)
  ELAS
  Arc/Info Binary Grid
  Arc/Info ASCII Grid
  GRASS ASCII Grid
  SDTS Raster
  DTED Elevation Raster
  Portable Network Graphics
  JPEG JFIF
  In Memory Raster
  Japanese DEM (.mem)
  Graphics Interchange Format (.gif)
  Graphics Interchange Format (.gif)
  Envisat Image Format
  Maptech BSB Nautical Charts
  X11 PixMap Format
  MS Windows Device Independent Bitmap
  SPOT DIMAP
  AirSAR Polarimetric Image
  RadarSat 2 XML Product
  PCIDSK Database File
  PCRaster Raster File
  ILWIS Raster Map
  SGI Image File Format 1.0
  SRTMHGT File Format
  Leveller heightfield
  Terragen heightfield
  USGS Astrogeology ISIS cube (Version 3)
  USGS Astrogeology ISIS cube (Version 2)
  NASA Planetary Data System
  EarthWatch .TIL
  ERMapper .ers Labelled
  NOAA Polar Orbiter Level 1b Data Set
  FIT Image
  GRIdded Binary (.grb)
  Raster Matrix Format
  EUMETSAT Archive native (.nat)
  Idrisi Raster A.1
  Intergraph Raster
  Golden Software ASCII Grid (.grd)
  Golden Software Binary Grid (.grd)
  Golden Software 7 Binary Grid (.grd)
  COSAR Annotated Binary Matrix (TerraSAR-X)
  TerraSAR-X Product
  DRDC COASP SAR Processor Raster
  R Object Data Store
  Portable Pixmap Format (netpbm)
  USGS DOQ (Old Style)
  USGS DOQ (New Style)
  ENVI .hdr Labelled
  ESRI .hdr Labelled
  Generic Binary (.hdr Labelled)
  PCI .aux Labelled
  Vexcel MFF Raster
  Vexcel MFF2 (HKV) Raster
  Fuji BAS Scanner Image
  GSC Geogrid
  EOSAT FAST Format
  VTP .bt (Binary Terrain) 1.3 Format
  Erdas .LAN/.GIS
  Convair PolGASP
  Image Data and Analysis
  NLAPS Data Format
  Erdas Imagine Raw
  DIPEx
  FARSITE v.4 Landscape File (.lcp)
  NOAA Vertical Datum .GTX
  NADCON .los/.las Datum Grid Shift
  NTv2 Datum Grid Shift
  ACE2
  Snow Data Assimilation System
  Swedish Grid RIK (.rik)
  USGS Optional ASCII DEM (and CDED)
  GeoSoft Grid Exchange Format
  Northwood Numeric Grid Format .grd/.tab
  Northwood Classified Grid Format .grc/.tab
  ARC Digitized Raster Graphics
  Standard Raster Product (ASRP/USRP)
  Magellan topo (.blx)
  SAGA GIS Binary Grid (.sdat)
  Kml Super Overlay
  ASCII Gridded XYZ
  HF2/HFZ heightfield raster
  OziExplorer Image File
  USGS LULC Composite Theme Grid
  Arc/Info Export E00 GRID
  ZMap Plus Grid
  NOAA NGS Geoid Height Grids

4.3.1.2. PostGISラスタ関数を用いたラスタの生成

データベース内でラスタやラスタテーブルを生成したい場合が多くあります。これを行うための関数が多数あります。一般的な手順は次の通りです。

  1. 新しいラスタ行を保持するためのラスタカラムを持つテーブルを生成します。次を実行します。

    CREATE TABLE myrasters(rid serial primary key, rast raster);
  2. この目標で助けとなる関数は多数あります。他のラスタの派生でないラスタを生成する場合、ST_MakeEmptyRasterST_AddBandを順次実行して作業を開始します。

    ジオメトリからラスタを生成することもできます。ST_AsRasterを使います。ST_UnionST_MapAlgebraFctや、地図解析関数群等といった、他の関数を組み合わせる場合もあります。

    既存テーブルから新しいラスタテーブルを生成するための多数の選択肢があります。たとえば、ST_Transformを使って、既存テーブルから異なる投影法のラスタテーブルを生成します。

  3. はじめにテーブルにデータを入れたら、ラスタカラムに空間インデクスを生成したくなるでしょう。次のようにします。

    CREATE INDEX myrasters_rast_st_convexhull_idx ON myrasters USING gist( ST_ConvexHull(rast) );

    ST_ConvexHullを使用していることに注意して下さい。多くのラスタ演算子はラスタの凸包を元にしています。

    [Note]

    2.0より前の PostGIS ラスタは、エンベロープを基本にして、凸包ではありませんでした。空間インデクスを適切に働かせるには、エンベロープを基本にしたインデクスを削除して、凸包を元にしたインデクスに置き換えます。

  4. AddRasterConstraintsを用いてラスタ制約を適用します。

4.3.2. ラスタカタログ

PostGISが生成する、二つのラスタカタログのビューがあります。両方ともラスタテーブルの制約の中に埋め込まれる情報を用いています。結果として、カタログビューは、テーブル内のラスタデータに制約が働くため、常にラスタデータとの矛盾がありません。

  1. raster_columns ラスタタイプのデータベースにおける全てのラスタテーブルカラムのカタログです。

  2. raster_overviews データベース内の、より詳細なテーブルのためのオーバビューを提供するラスタテーブルのカラム全てのカタログです。この種のテーブルは、ロード時に-lを指定した時に生成されます。

4.3.2.1. ラスタカラムカタログ

raster_columnsは、ラスタタイプのデータベースにおける全てのラスタテーブルカラムのカタログです。テーブルの制約を使ったビューなので、他のデータベースのバックアップからラスタテーブルをリストアしたとしても、情報は常に矛盾がありません。raster_columnsカタログには次のカラムがあります。

ローダを使わずにテーブルを生成したり、ロード時に-C フラグを忘れたりした場合には、事後にAddRasterConstraintsで制約を強制でき、raster_columnsカタログは、ラスタタイルの共通の情報を登録します。

  • r_table_catalog テーブルが存在するデータベースです。これは常に現在のデータベースを読みます。

  • r_table_schema ラスタテーブルが属するデータベーススキーマです。

  • r_table_name ラスタテーブルです。

  • r_raster_column ラスタタイプであるr_table_nameテーブルのカラムです。PostGISには、一つのテーブルに複数のラスタカラムを持つことを妨げません。異なるラスタカラムを持つラスタテーブルが、ラスタカラム毎に複数回出現するテーブルを持つことができます。

  • srid ラスタの空間参照系識別番号です。Section 4.1.3.1, “SPATIAL_REF_SYSテーブルと空間参照系”にあるエントリであるべきです。

  • scale_x 地理空間座標とピクセルの間の拡大縮小係数です。これは、ラスタカラムのすべてのタイルが同じscale_xを持ち、制約が適用されている場合のみ出現します。詳細情報についてはST_ScaleXを参照してください。

  • scale_y 地理空間座標とピクセルの間の拡大縮小係数です。これは、ラスタカラムのすべてのタイルが同じscale_yを持ち、制約が適用されている場合のみ出現します。詳細情報についてはST_ScaleYを参照してください。

  • blocksize_x ラスタタイルごとの幅 (横方向のピクセル数)です。詳細情報についてはST_Widthを参照してください。

  • blocksize_y ラスタタイルごとの高さ (縦方向のピクセル数)です。詳細情報についてはST_Heightを参照してください。

  • same_alignment 全てのラスタタイルが同じアラインメントを持っているかを示す真偽値です。詳細情報についてはST_SameAlignmentを参照してください。

  • regular_blocking ラスタカラムが空間的に一意かつカバレッジタイルの制約を持つなら、TRUEとなります。その他の場合はFALSEになります。。

  • num_bands ラスタ集合のタイルごとのバンド数。 ST_NumBands

  • pixel_types バンドごとのピクセルタイプを定義する配列です。この配列の要素数はバンド数と同じです。pixel_typesは、ST_BandPixelTypeで定義されるピクセルタイプの一つを取ります。

  • nodata_values バンド毎のnodata_valueを示す倍精度浮動小数点数の配列です。バンド数と同じ配列数となります。これらの値は、バンド毎のほとんどの処理で無視されるべきピクセル値の定義です。これはST_BandNoDataValueで得られる情報と似ています。

  • out_db ラスタバンドデータがデータベース外で維持されているかを示す真偽値の配列です。この配列の添え字はバンド番号と同じです。

  • extent ラスタ集合における全てのラスタ行の範囲です。集合の範囲を変更するデータを別途ロードする予定である場合、ロード前にDropRasterConstraints関数を実行して、ロード後にAddRasterConstraintsで制約を再適用します。

  • spatial_index 空間インデクスを持っているかどうかを示す真偽値です。

4.3.2.2. ラスタオーバビュー

raster_overviewsは、オーバビューで使われるラスタテーブルカラムに関する情報のカタログで、オーバビューを用いる際に知っておくと便利な情報も持ちます。オーバビューテーブルはraster_columnsraster_overviewsの両方のカタログに入れられます。オーバビューもラスタの一つであるのは確かですが、より高い解像度テーブルの解像度を落としたカリカチュアになるという特殊な目的を満たすためでもあるからです。ラスタをロードする際に-lスイッチを使うと、オーバビューが主ラスタテーブルと一緒に生成されます。もしくは、AddOverviewConstraintsを使うと手動で生成できます。

オーバビューテーブルには、他のラスタテーブルと同じ制約と、オーバビュー特有の制約となる追加情報があります。

[Note]

raster_overviewsの情報はraster_columnsとは重複しません。raster_columnsにあるオーバビューテーブルに関する情報が必要な場合は、raster_overviewsraster_columnsとを結合すると、必要な情報の集合を完全に取得することができます。

オーバビューの主たる理由は次の二つです。

  1. ズームアウトした際の地図表示を早くするために、元のテーブルの低解像度表現が一般的に使われます。

  2. レコード数が少なく、ピクセル毎の適用範囲が広いため、高解像度の元テーブルより計算が一般的に早くなります。計算は高解像度テーブルより精度は落ちますが、大まかな計算には十分でありえます。

raster_overviewsカタログには、次の情報のカラムがあります。

  • o_table_catalog オーバビューテーブルが存在するデータベースです。常に現在のデータベースを読みます。

  • o_table_schema オーバビューラスタテーブルが属するデータベーススキーマです。

  • o_table_name ラスタオーバビューテーブル名です。

  • o_raster_column オーバビューテーブル内のラスタカラムです。

  • r_table_catalog このオーバビューの元となるラスタテーブルのデータベースです。常に現在のデータベースを読みます。

  • r_table_schema このオーバビューの元となるラスタテーブルが属するデータベーススキーマです。

  • r_table_name このオーバビューの元となるラスタテーブルです。

  • r_raster_column このオーバビューの元となるラスタカラムです。

  • overview_factor - オーバビューテーブルのピラミッドレベルです。高い数字ほど解像度が低くなります。raster2pgsqlは、画像のフォルダを渡された場合は、分割して、イメージファイルのオーバビューの計算とロードを行います。レベル1は元ファイルと同じです。レベル2は、元ファイルの4分の1になります。たとえば、5000x5000ピクセルの画像ファイルのフォルダがあるとして、125x125に分ける場合、画像ファイルごとに(5000*5000)/(125*125) = 1600行のレコードを持ち、o_2テーブル (レベル2)はceiling(1600/Power(2,2)) = 400行、o_3(レベル3)ではceiling(1600/Power(2,3) ) = 200行のレコードを持ちます。ピクセルがタイルサイズで割り切れない場合、スクラップタイル (完全には値が入っていない)が得られます。raster2pgsqlによって生成される個々のオーバビュータイルは、元となるラスタと同じピクセル数を持ち、個々のピクセルの表現範囲 (オリジナルの Power(2,overview_factor)ピクセル分)が低い解像度になっている点に注意して下さい。

4.3.3. PostGISラスタを使ったカスタムアプリケーションの構築

PostGISラスタには、対応イメージ書式のラスタをレンダリングするSQL関数があり、レンダリングを行うための多数の選択肢があります。たとえば、Rendering PostGIS Raster graphics with LibreOffice Base Reportsで例を挙げている通り、OpenOffice/LibreOfficeを使うことができます。さらに、ここで示すように、幅広い言語で使うことができます。

4.3.3.1. ST_AsPNG を他の関数とあわせて使った PHP 出力例

本節では、PHPのPostgreSQLドライバとST_AsGDALRaster等の関数を使って、HTML imgタグに埋め込むことができるPHPリクエストストリームにラスタの1、2、3バンドを出力する方法を示します。

サンプルクエリでは、 指定したWGS84バウンディングボックスにインタセクトするタイルを取って、 ST_Unionでインタセクトしたタイルを結合して全てのバンドを返し、ST_Transformでユーザ指定投影法に変換し、ST_AsPNGを使ってPNGで結果を出力するためのラスタ関数群全体をまとめる方法を示します。

次で示すスクリプトは、

http://mywebserver/test_raster.php?srid=2249

で、マサチューセッツ州平面 (フィート単位)のラスタ画像を取得するものです。

<?php
/** test_raster.phpのコンテンツ **/
$conn_str ='dbname=mydb host=localhost port=5432 user=myuser password=mypwd';
$dbconn = pg_connect($conn_str);
header('Content-Type: image/png');
/** 特定の投影法が要求された場合にはそれを使い、それ以外ではメートル単位マサチューセッツ州平面を使います **/
if (!empty( $_REQUEST['srid'] ) && is_numeric( $_REQUEST['srid']) ){
                $input_srid = intval($_REQUEST['srid']);
}
else { $input_srid = 26986; }
/** set bytea_outputは、PostgreSQL 9.0以上で必要になるかも知れませんが、8.4では不要です **/
$sql = "set bytea_output='escape';
SELECT ST_AsPNG(ST_Transform(
                        ST_AddBand(ST_Union(rast,1), ARRAY[ST_Union(rast,2),ST_Union(rast,3)])
                                ,$input_srid) ) As new_rast
 FROM aerials.boston
        WHERE
         ST_Intersects(rast, ST_Transform(ST_MakeEnvelope(-71.1217, 42.227, -71.1210, 42.218,4326),26986) )";
$result = pg_query($sql);
$row = pg_fetch_row($result);
pg_free_result($result);
if ($row === false) return;
echo pg_unescape_bytea($row[0]);
?>

4.3.3.2. ST_AsPNGを他の関数とあわせて使ったASP.NET C#出力例

本節では、Npgsql PostgreSQL .NETドライバとST_AsGDALRaster等の関数を使って、HTML imgタグに埋め込むことができるように、ラスタの1、2、3バンドを出力する方法を示します。

この例ではNpgsql .NET PostgreSQLドライバが必要です。最新版はhttp://npgsql.projects.postgresql.org/にあります。最新版をダウンロードして、ASP.NET の binフォルダに入れるだけでうまくいきます。

サンプルクエリでは、 指定したWGS84バウンディングボックスにインタセクトするタイルを取って、 ST_Unionでインタセクトしたタイルを結合して全てのバンドを返し、ST_Transformでユーザ指定投影法に変換し、ST_AsPNGを使ってPNGで結果を出力するためのラスタ関数群全体をまとめる方法を示します。

この例はC#で実装している点を除いてはSection 4.3.3.1, “ST_AsPNG を他の関数とあわせて使った PHP 出力例”と同じです。

次で示すスクリプトは、

http://mywebserver/TestRaster.ashx?srid=2249

で、マサチューセッツ州平面 (フィート単位)のラスタ画像を取得します。

-- web.config 接続文字列部 --
<connectionStrings>
    <add name="DSN"
        connectionString="server=localhost;database=mydb;Port=5432;User Id=myuser;password=mypwd"/>
</connectionStrings
>
// TestRaster.ashxのコード
<%@ WebHandler Language="C#" Class="TestRaster" %>
using System;
using System.Data;
using System.Web;
using Npgsql;

public class TestRaster : IHttpHandler
{
        public void ProcessRequest(HttpContext context)
        {

                context.Response.ContentType = "image/png";
                context.Response.BinaryWrite(GetResults(context));

        }

        public bool IsReusable {
                get { return false; }
        }

        public byte[] GetResults(HttpContext context)
        {
                byte[] result = null;
                NpgsqlCommand command;
                string sql = null;
                int input_srid = 26986;
        try {
                    using (NpgsqlConnection conn = new NpgsqlConnection(System.Configuration.ConfigurationManager.ConnectionStrings["DSN"].ConnectionString)) {
                            conn.Open();

                if (context.Request["srid"] != null)
                {
                    input_srid = Convert.ToInt32(context.Request["srid"]);
                }
                sql = @"SELECT ST_AsPNG(
                            ST_Transform(
                                        ST_AddBand(
                                ST_Union(rast,1), ARRAY[ST_Union(rast,2),ST_Union(rast,3)])
                                                    ,:input_srid) ) As new_rast
                        FROM aerials.boston
                                WHERE
                                    ST_Intersects(rast,
                                    ST_Transform(ST_MakeEnvelope(-71.1217, 42.227, -71.1210, 42.218,4326),26986) )";
                            command = new NpgsqlCommand(sql, conn);
                command.Parameters.Add(new NpgsqlParameter("input_srid", input_srid));


                            result = (byte[]) command.ExecuteScalar();
                conn.Close();
                        }

                }
        catch (Exception ex)
        {
            result = null;
            context.Response.Write(ex.Message.Trim());
        }
                return result;
        }
}

4.3.3.3. rasterクエリを画像ファイルで出力するJavaコンソールアプリケーション

これは、一つの画像を返すクエリを取り、指定したファイルに出力する、簡単なJavaコンソールアプリケーションです。

最新のPostgreSQL JDBCドライバはhttp://jdbc.postgresql.org/download.htmlからダウンロードできます。

あとで示すコードをコンパイルします。コマンドは次の通りです。

set env CLASSPATH .:..\postgresql-9.0-801.jdbc4.jar
javac SaveQueryImage.java
jar cfm SaveQueryImage.jar Manifest.txt *.class

次のようにコマンドラインから呼び出します。

java -jar SaveQueryImage.jar "SELECT ST_AsPNG(ST_AsRaster(ST_Buffer(ST_Point(1,5),10, 'quad_segs=2'),150, 150, '8BUI',100));" "test.png" 
-- Manifest.txt --
Class-Path: postgresql-9.0-801.jdbc4.jar
Main-Class: SaveQueryImage
// SaveQueryImage.javaのコード
import java.sql.Connection;
import java.sql.SQLException;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.io.*;

public class SaveQueryImage {
  public static void main(String[] argv) {
      System.out.println("Checking if Driver is registered with DriverManager.");

      try {
        //java.sql.DriverManager.registerDriver (new org.postgresql.Driver());
        Class.forName("org.postgresql.Driver");
      }
      catch (ClassNotFoundException cnfe) {
        System.out.println("Couldn't find the driver!");
        cnfe.printStackTrace();
        System.exit(1);
      }

      Connection conn = null;

      try {
        conn = DriverManager.getConnection("jdbc:postgresql://localhost:5432/mydb","myuser", "mypwd");
        conn.setAutoCommit(false);

        PreparedStatement sGetImg = conn.prepareStatement(argv[0]);

        ResultSet rs = sGetImg.executeQuery();

                FileOutputStream fout;
                try
                {
                        rs.next();
                        /** Output to file name requested by user **/
                        fout = new FileOutputStream(new File(argv[1]) );
                        fout.write(rs.getBytes(1));
                        fout.close();
                }
                catch(Exception e)
                {
                        System.out.println("Can't create file");
                        e.printStackTrace();
                }

        rs.close();
                sGetImg.close();
        conn.close();
      }
      catch (SQLException se) {
        System.out.println("Couldn't connect: print out a stack trace and exit.");
        se.printStackTrace();
        System.exit(1);
      }
  }
}

4.3.3.4. PLPython を使って SQL を介して画像をダンプする

これは、サーバディレクトリ内でレコードごとにファイルを生成するPythonストアド関数です。plpythonが必要です。plpythonuとplpython3uの両方が正しく動作します。

CREATE OR REPLACE FUNCTION write_file (param_bytes bytea, param_filepath text)
RETURNS text
AS $$
f = open(param_filepath, 'wb+')
f.write(param_bytes)
return param_filepath
$$ LANGUAGE plpythonu;
-- 5つの画像をPostgreSQLサーバに可変サイズで描きます。
-- PostgreSQLデーモンのアカウントにフォルダへの書き込み権限が必要ですので
-- ご注意ください。
-- 生成されたファイル名をエコーバックします。
 SELECT write_file(ST_AsPNG(
        ST_AsRaster(ST_Buffer(ST_Point(1,5),j*5, 'quad_segs=2'),150*j, 150*j, '8BUI',100)),
         'C:/temp/slices'|| j || '.png')
         FROM generate_series(1,5) As j;

     write_file
---------------------
 C:/temp/slices1.png
 C:/temp/slices2.png
 C:/temp/slices3.png
 C:/temp/slices4.png
 C:/temp/slices5.png

4.3.3.5. PSQLでラスタを出力する

PSQLから組み込み機能を用いてバイナリを出力するのは簡単ではありません。ここで紹介する方法は、レガシーなラージオブジェクトをサポートするPostgreSQL上に乗っかる、ちょっとしたハックです。まずは、psqlを起動して、データベースに接続します。

この方法はPythonの場合と違い、ローカル機にファイルが生成されます

SELECT oid, lowrite(lo_open(oid, 131072), png) As num_bytes
 FROM
 ( VALUES (lo_create(0),
   ST_AsPNG( (SELECT rast FROM aerials.boston WHERE rid=1) )
  ) ) As v(oid,png);
-- 次のような出力が得られます --
   oid   | num_bytes
---------+-----------
 2630819 |     74860

-- 続いて、oidを書き留めて、'C:/temp/aerial_smap.png'を
-- ローカルのコンピュータ上のファイルパスに置き換えたうえで、
-- 次を実行します。
 \lo_export 2630819 'C:/temp/aerial_samp.png'

-- db上のラージオブジェクトストレージからファイルを削除します
SELECT lo_unlink(2630819);
                        

4.4. トポロジ

PostGISトポロジ型と関数は、フェイス、エッジ、ノード等のトロポジオブジェクトを管理するために使います。

PostGIS Day Paris 2011におけるSandro Santilliさんの講演が、PostGISトポロジの概略説明として良いです。Topology with PostGIS 2.0 slide deckにあります。

Vincent Picavetさんはトポロジとは何か、どのように使われるか、および、対応するFOSS4Gツールに関する良い概略説明をPostGIS Topology PGConf EU 2012で出しています。

トポロジベースのGISデータベースの例としてUS Census Topologically Integrated Geographic Encoding and Referencing System (TIGER)があります。PostGISトポロジの試験がしたくて、何らかのデータが必要ならTopology_Load_Tigerをご覧下さい

PostGISトポロジモジュールは前の版にもありましたが、正式なPostGIS文書の中には入れていませんでした。PostGIS 2.0.0 では、全ての非推奨関数を無くし、知られていた使いやすさの問題を解決し、機能と関数の文書をより良くし、新しい関数を追加し、SQL-MM標準により準拠させるために、大整理を行っています。

このプロジェクトの詳細情報はPostGIS Topology Wikiにあります。

このモジュールに関する全ての関数とテーブルは、topologyスキーマにインストールされます。

SQL/MM標準で定義される関数はST_プリフィクスを持ち、PostGIS特有の関数はこのプリフィクスを持ちません。

PostGIS 2.0から、トポロジ対応はデフォルトでビルドされます。Chapter 2, PostGISインストールに書かれている通り、ビルド時のコンフィギュアオプションで、--without-topology を指定すると無効化できます。

4.4.1. トポロジ型

Abstract

本節では、PostGISトポロジでインストールされるPostgreSQLデータ型の一覧を挙げます。独自に関数をデザインする際に特に重要となる、キャストでの挙動を記述していることにご注意ください。

getfaceedges_returntype — 順列番号とエッジ番号の複合型です。ST_GetFaceEdgesが返す型です。
TopoGeometry — トポロジとして定義されたジオメトリを表現する型です。
validatetopology_returntype — エラーメッセージとエラーの場所を示す、id1とid2からなる複合型です。これはValidateTopologyが返す型です。

Name

getfaceedges_returntype — 順列番号とエッジ番号の複合型です。ST_GetFaceEdgesが返す型です。

説明

順列番号とエッジ番号の複合型ですST_GetFaceEdges関数が返す型です。

  1. sequence (整数): トポロジスキーマとSRIDを定義するtopology.topologyテーブルで定義されるトポロジへの参照です。

  2. edge (整数): エッジの識別番号です。


Name

TopoGeometry — トポロジとして定義されたジオメトリを表現する型です。

説明

特定のトポロジレイヤ内のトポロジジオメトリを参照する複合型で、特定のタイプと特定のIDを持ちます。TopoGeometryの要素はtopology_id, layer_id, id integer, type integerの各属性です。

  1. topology_id (整数): トポロジスキーマとSRIDを定義するtopology.topologyテーブルで定義されているトポロジへの参照です。

  2. layer_id (整数): TopoGeometryが属するlayersテーブルにおけるlayer_idです。topology_idとlayer_idとの組み合わせで、topology.layersテーブルを一意に参照できます。

  3. id (整数): それぞれのトポロジでTopoGeometryを一意にするための順序整数で、自動生成されます。

  4. type (1から4の整数でジオメトリタイプを定義): 1:[multi]point, 2:[multi]line, 3:[multi]poly, 4:collectionとなります。

キャストの挙動

本節では、このデータ型で許容される明示的なキャストと自動キャストの一覧を挙げます。

キャスト先挙動
geometry自動

関連情報

CreateTopoGeom


Name

validatetopology_returntype — エラーメッセージとエラーの場所を示す、id1とid2からなる複合型です。これはValidateTopologyが返す型です。

説明

エラーメッセージと二つの整数からなる複合型です。ValidateTopology関数は、これの集合を返します。評価エラーを示し、id1とid2でエラーを含むトポロジオブジェクトの識別番号を示します。

  1. error (varchar): エラーのタイプを示します。

    現在のエラー記述: coincident nodes (訳注: ノード重複), edge crosses node (訳注: エッジとノードのクロス), edge not simple (訳注: 単純でないエッジ), edge end node geometry mis-match (訳注: 終了ノードジオメトリの不整合), edge start node geometry mismatch (訳注: 開始ノードジオメトリの不整合), face overlaps face (訳注: フェイス同士のオーバラップ), face within face (訳注: フェイス間の包含)

  2. id1 (整数): エラーを持つエッジ/フェイス/ノードの識別番号を示します。

  3. id2 (整数): 2オブジェクトでのエラーにおける二つ目のエッジ/ノードの識別番号を示します。

関連情報

ValidateTopology

4.4.2. トポロジドメイン

Abstract

本節では、PostGISトポロジでインストールされるPostgreSQLドメインの一覧を挙げます。ドメインは、オブジェクト型のように扱え、関数やテーブルカラムのオブジェクトを返します。ドメインは存在するチェック制約を持つ既存の型である点で、型とは違います。

TopoElement — 二つの整数の配列で、通常TopoGeometry要素を識別するために使われます。
TopoElementArray — TopoElementオブジェクトの配列

Name

TopoElement — 二つの整数の配列で、通常TopoGeometry要素を識別するために使われます。

説明

二つの整数の配列で、単純または階層を持つTopoGeometryの一つのコンポーネントを表現するために使われます。

単純なTopoGeometryの場合は、配列の最初の要素がトポロジのプリミティブの識別を表現し、二つ目の要素がタイプ (1:ノード 2:エッジ, 3:フェイス)を表現します。階層的なTopoGeometryの場合は、一つ目の要素が子のTopoGeometryの識別子を表現し、二つ目の要素はレイヤ識別子を表現します。

[Note]

階層的なTopoGeometryについては、全ての子のTopoGeometry要素は同じ子レイヤから来ます。子レイヤは、定義されたTopoGeometryのレイヤのtopology.layerレコード内で指定されます。

SELECT te[1] AS id, te[2] AS type FROM
( SELECT ARRAY[1,2]::topology.topoelement AS te ) f;
 id | type
----+------
  1 |    2
                 
SELECT ARRAY[1,2]::topology.topoelement;
  te
-------
 {1,2}
                 
-- 3要素配列をtopoelementに使った際に発生するエラーの例
-- ご注意: topoelementは、必ず2要素を持ちます。次元チェックにひっかかります。
SELECT ARRAY[1,2,3]::topology.topoelement;
ERROR:  value for domain topology.topoelement violates check constraint "dimensions"
                 

Name

TopoElementArray — TopoElementオブジェクトの配列

説明

1以上のTopoElementオブジェクトの配列で、通常はTopoGeometryオブジェクトのコンポーネントを分配するために使われます。

SELECT '{{1,2},{4,3}}'::topology.topoelementarray As tea;
  tea
-------
{{1,2},{4,3}}

-- より長く書いた等価なもの --
SELECT ARRAY[ARRAY[1,2], ARRAY[4,3]]::topology.topoelementarray As tea;

  tea
-------
{{1,2},{4,3}}

-- トポロジに同梱されている配列集約関数 --
SELECT topology.TopoElementArray_Agg(ARRAY[e,t]) As tea
  FROM generate_series(1,4) As e CROSS JOIN generate_series(1,3) As t;
  tea
--------------------------------------------------------------------------
{{1,1},{1,2},{1,3},{2,1},{2,2},{2,3},{3,1},{3,2},{3,3},{4,1},{4,2},{4,3}}
                 
SELECT '{{1,2,4},{3,4,5}}'::topology.topoelementarray As tea;
ERROR:  value for domain topology.topoelementarray violates check constraint "dimensions"
                 

4.4.3. トポロジ管理とTopoGeometry管理

Abstract

本節では、新しいトポロジスキーマの構築、トポロジの評価、TopoGeometryカラムの管理のためのトポロジ関数の一覧を挙げます。

AddTopoGeometryColumn — 既存のテーブルにTopoGeometryカラムを追加し、topology.layer内に新しいレイヤとして新しいカラムを登録して、新しい layer_id を返します。
DropTopology — 使用上の注意: この関数によって、トポロジスキーマが削除され、topology.topologyテーブルからの参照が削除され、geometry_columnsテーブルから削除対象スキーマ内のテーブルへの参照が削除されます。
DropTopoGeometryColumnschema_nameで指定されたスキーマ内にあるtable_nameで指定されたテーブルからTopoGeometryカラムを削除し、topology.layerテーブルにある登録を解除します。
Populate_Topology_Layer — テーブルからメタデータを読み、topology.layerテーブルに不足しているものを追加します。
TopologySummary — Tトポロジ名を取り、トポロジ内のオブジェクトの型に関する概要の全体を提供します。
ValidateTopology — トポロジの問題についての詳細を示すvalidatetopology_returntypeの集合を返します。

Name

AddTopoGeometryColumn — 既存のテーブルにTopoGeometryカラムを追加し、topology.layer内に新しいレイヤとして新しいカラムを登録して、新しい layer_id を返します。

Synopsis

integer AddTopoGeometryColumn(varchar topology_name, varchar schema_name, varchar table_name, varchar column_name, varchar feature_type);

integer AddTopoGeometryColumn(varchar topology_name, varchar schema_name, varchar table_name, varchar column_name, varchar feature_type, integer child_layer);

説明

それぞれのTopoGeometryオブジェクトは、特定のトポロジの特定のレイヤに属します。TopoGeometryオブジェクト生成の前に、トポロジレイヤの生成が必要です。トポロジレイヤは地物テーブルとトポロジとで組織されます。また、タイプと階層の情報を持ちます。レイヤの生成にはAddTopoGeometryColumn()を使います。

この関数は、リクエストされたカラムをテーブルに追加し、topology.layerテーブルに、与えられた全ての情報のレコードを追加します。

[child_layer]を指定しない (またはNULLを指定する)場合、このレイヤは、基本的なTopoGeometry (プリミティブなトポロジ要素で構成)を含みます。指定する場合、このレイヤは階層的なTopoGeometry (child_layerからのTopoGeometryで構成)を持ちます。

レイヤが生成される (これの識別番号は、AddTopoGeometryColumn関数が返します)と、TopoGeometryオブジェクトをこの中に構築する準備ができます。

妥当なfeature_typeは、POINT, LINE, POLYGON, COLLECTIONです。

Availability: 1.?

-- この例では、topology_nameとshecma_nameが異なる場合には、
-- 異なるスキーマに作ることができましたが、
-- ma_topoスキーマに新しいテーブルを作ったことに注意して下さい。

CREATE SCHEMA ma;
CREATE TABLE ma.parcels(gid serial, parcel_id varchar(20) PRIMARY KEY, address text);
SELECT topology.AddTopoGeometryColumn('ma_topo', 'ma', 'parcels', 'topo', 'POLYGON');
CREATE SCHEMA ri;
CREATE TABLE ri.roads(gid serial PRIMARY KEY, road_name text);
SELECT topology.AddTopoGeometryColumn('ri_topo', 'ri', 'roads', 'topo', 'LINE');

Name

DropTopology — 使用上の注意: この関数によって、トポロジスキーマが削除され、topology.topologyテーブルからの参照が削除され、geometry_columnsテーブルから削除対象スキーマ内のテーブルへの参照が削除されます。

Synopsis

integer DropTopology(varchar topology_schema_name);

説明

トポロジスキーマを削除し、topology.topologyテーブルからの参照を削除し、geometry_columnsテーブルから削除対象スキーマ内のテーブルへの参照を削除します。この関数は *十分に注意してご使用下さい*。残しておきたかったデータが破壊される可能性があります。スキーマが存在しない場合、スキーマへの参照に関するエントリの削除だけを行います。

Availability: 1.?

ma_topoスキーマをカスケード削除し、topology.topologyにある参照のうち関係するものを全て削除します。

SELECT topology.DropTopology('ma_topo');

Name

DropTopoGeometryColumn — schema_nameで指定されたスキーマ内にあるtable_nameで指定されたテーブルからTopoGeometryカラムを削除し、topology.layerテーブルにある登録を解除します。

Synopsis

text DropTopoGeometryColumn(varchar schema_name, varchar table_name, varchar column_name);

説明

schema_nameで指定されたスキーマ内にあるtable_nameで指定されたテーブルからTopoGeometryカラムを削除し、topology.layerテーブルにある登録を解除します。削除の概要報告を返します。ご注意: この関数は、参照整合性チェックをすり抜けるために、まずNULL値に上書きしてから削除します。

Availability: 1.?

SELECT topology.DropTopoGeometryColumn('ma_topo', 'parcel_topo', 'topo');

Name

Populate_Topology_Layer — テーブルからメタデータを読み、topology.layerテーブルに不足しているものを追加します。

Synopsis

setof record Populate_Topology_Layer();

説明

テーブルの制約を読み、topology.layerテーブルに不足しているものを追加します。トポロジデータをスキーマに格納した後に、トポロジカタログで抜けているものを訂正するのに使います。

生成されたもののリストを返します。返されるカラムは schema_name, table_name, feature_columnです。

Availability: 2.3.0

SELECT CreateTopology('strk_topo');
CREATE SCHEMA strk;
CREATE TABLE strk.parcels(gid serial, parcel_id varchar(20) PRIMARY KEY, address text);
SELECT topology.AddTopoGeometryColumn('strk_topo', 'strk', 'parcels', 'topo', 'POLYGON');
-- この地物はすでに登録されているので返されるレコードはありません
SELECT *
  FROM topology.Populate_Topology_Layer();

-- 再構築してみます
TRUNCATE TABLE topology.layer;

SELECT *
  FROM topology.Populate_Topology_Layer();

SELECT topology_id,layer_id, schema_name As sn, table_name As tn, feature_column As fc
FROM topology.layer;

                                
schema_name | table_name | feature_column
-------------+------------+----------------
 strk        | parcels    | topo
(1 row)

 topology_id | layer_id |  sn  |   tn    |  fc
-------------+----------+------+---------+------
           2 |        2 | strk | parcels | topo
(1 row)

Name

TopologySummary — Tトポロジ名を取り、トポロジ内のオブジェクトの型に関する概要の全体を提供します。

Synopsis

text TopologySummary(varchar topology_schema_name);

説明

トポロジ名を取り、トポロジ内のオブジェクトの型に関する概要の全体を提供します。

Availability: 2.0.0

SELECT topology.topologysummary('city_data');
                    topologysummary
--------------------------------------------------------
 Topology city_data (329), SRID 4326, precision: 0
 22 nodes, 24 edges, 10 faces, 29 topogeoms in 5 layers
 Layer 1, type Polygonal (3), 9 topogeoms
  Deploy: features.land_parcels.feature
 Layer 2, type Puntal (1), 8 topogeoms
  Deploy: features.traffic_signs.feature
 Layer 3, type Lineal (2), 8 topogeoms
  Deploy: features.city_streets.feature
 Layer 4, type Polygonal (3), 3 topogeoms
  Hierarchy level 1, child layer 1
  Deploy: features.big_parcels.feature
 Layer 5, type Puntal (1), 1 topogeoms
  Hierarchy level 1, child layer 2
  Deploy: features.big_signs.feature

Name

ValidateTopology — トポロジの問題についての詳細を示すvalidatetopology_returntypeの集合を返します。

Synopsis

setof validatetopology_returntype ValidateTopology(varchar topology_schema_name);

説明

トポロジの問題についての詳細を示すvalidatetopology_returntypeの集合を返します。ありえるエラーと返されたIDが表現するものの一覧は次のとおりです。

Errorid1id2
edge crosses node (訳注: エッジとノードのクロス)edge_idnode_id
invalid edge (訳注: 不正なエッジ)edge_idnull
edge not simple (訳注: 単純でないエッジ)edge_idnull
edge crosses edge (訳注: エッジとエッジのクロス)edge_idedge_id
edge start node geometry mis-match (訳注: 開始ノードジオメトリの不整合)edge_idnode_id
edge end node geometry mis-match (訳注: 終了ノードジオメトリの不整合)edge_idnode_id
face without edges (訳注: エッジのないフェイス)face_idnull
face has no rings (訳注: 環のないフェイス)face_idnull
face overlaps face (訳注: フェイス同士のオーバラップ)face_idface_id
face within face (訳注: フェイス間の包含) 内側のface_id外側のface_id

Availability: 1.0.0

Enhanced: 2.0.0では、より効果的なエッジ交差検出が可能になり、以前の版で残っていた偽陽性を解決しています。

Changed: 2.2.0 エラーの記述と矛盾しないように'edge crosses node'のid1とid2の値が入れ替わっています。

SELECT * FROM  topology.ValidateTopology('ma_topo');
      error        | id1 | id2
-------------------+-----+-----
face without edges |   0 |
                                

4.4.4. トポロジ管理とTopoGeometry管理

Abstract

This section discusses management of database statistics during topology building.

Adding elements to a topology triggers many database queries for finding existing edges that will be split, adding nodes and updating edges that will node with the new linework. For this reason it is useful that statistics about the data in the topology tables are up-to-date.

PostGIS Topology population and editing functions do not automatically update the statistics because a updating stats after each and every change in a topology would be overkill, so it is the caller's duty to take care of that.

[Note]

That the statistics updated by autovacuum will NOT be visible to transactions which started before autovacuum process completed, so long-running transactions will need to run ANALYZE themeselves, to use updated statistics.

4.4.5. トポロジコンストラクタ

Abstract

本節では、新しいトポロジを生成するトポロジ関数を挙げます。

CreateTopology — 新しいトポロジスキーマを生成し、新しいスキーマをtopology.topologyテーブルに登録します。
CopyTopology — トポロジ構造 (ノード、エッジ、フェイス、レイヤ、TopoGeometry)を複写します。
ST_InitTopoGeo — 新しいトポロジスキーマを生成し、topology.topologyテーブルに新しいスキーマを登録し、処理の概要を表示します。
ST_CreateTopoGeo — 空のトポロジにジオメトリのコレクションを追加し、成否を示すメッセージを返します。
TopoGeo_AddPoint — 許容差を使って既存のトポロジにポイントを追加し、可能ならエッジを分割します。
TopoGeo_AddLineString — 許容差を使って既存のトポロジにラインストリングを追加し、可能ならエッジ/フェイスを分割します。
TopoGeo_AddPolygon — 許容差を使って既存のトポロジにラインストリングを追加し、可能ならエッジ/フェイスを分割します。

Name

CreateTopology — 新しいトポロジスキーマを生成し、新しいスキーマをtopology.topologyテーブルに登録します。

Synopsis

integer CreateTopology(varchar topology_schema_name);

integer CreateTopology(varchar topology_schema_name, integer srid);

integer CreateTopology(varchar topology_schema_name, integer srid, double precision prec);

integer CreateTopology(varchar topology_schema_name, integer srid, double precision prec, boolean hasz);

説明

topology_nameで指定したスキーマを生成し、テーブル (edge_data, face, node, relation)を生成し、topology.topologyテーブルに新しいトポロジを登録します。トポロジテーブルにおけるトポロジのIDを返します。sridは、spatial_ref_sysテーブルで定義されている空間参照系識別番号です。トポロジの名称は一意でなければなりません。許容差は、空間参照系で規定される単位です。precで許容差を指定しない場合は 0 とされます。

SQL/MMのST_InitTopoGeoに似ていますが、少しだけこちらの方が機能追加されています。haszは、指定されていない場合はfalseとされます。

Availability: 1.?

本例ではメートル単位マサチューセッツ州平面のエッジ、フェイスとリレーションを保存するための、ma_topoという新しいスキーマを生成します。空間参照系はメートルを単位としているので、許容差は0.5メートルとなります。

SELECT topology.CreateTopology('ma_topo',26986, 0.5);

ロードアイランド州トポロジをフィート単位州平面で生成

SELECT topology.CreateTopology('ri_topo',3438) As topoid;
topoid
------
2

Name

CopyTopology — トポロジ構造 (ノード、エッジ、フェイス、レイヤ、TopoGeometry)を複写します。

Synopsis

integer CopyTopology(varchar existing_topology_name, varchar new_name);

説明

new_topology_nameで指定した名前のトポロジを生成し、existing_topology_nameから取得されるSRIDと精度にして、ノード、エッジ、フェイス、レイヤ、TopoGeometryを複製します。

[Note]

topology.layerの新しい行には、schema_name, table_name, feature_columnの統合された値が入ります。TopoGeometryが定義には存在しても、どのユーザレベルのテーブルにも存在しないためです。

Availability: 2.0.0

本例では、ma_topoという名前のトポロジにバックアップをとっています。

SELECT topology.CopyTopology('ma_topo', 'ma_topo_bakup');

Name

ST_InitTopoGeo — 新しいトポロジスキーマを生成し、topology.topologyテーブルに新しいスキーマを登録し、処理の概要を表示します。

Synopsis

text ST_InitTopoGeo(varchar topology_schema_name);

説明

これはCreateTopologyのSQL-MM互換ですが、CreateTopologyにある空間参照系とtoleranceオプションがありません。また、トポロジIDを返すのではなく、生成に関する記述を出力します。

Availability: 1.?

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.17

SELECT topology.ST_InitTopoGeo('topo_schema_to_create') AS topocreation;
                      astopocreation
------------------------------------------------------------
 Topology-Geometry 'topo_schema_to_create' (id:7) created.
                                

関連情報

CreateTopology


Name

ST_CreateTopoGeo — 空のトポロジにジオメトリのコレクションを追加し、成否を示すメッセージを返します。

Synopsis

text ST_CreateTopoGeo(varchar atopology, geometry acollection);

説明

空のトポロジにジオメトリのコレクションを追加し、成否を示すメッセージを返します。

空トポロジの追加に使えます。

Availability: 2.0

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.18

-- トポロジの投入 --
SELECT topology.ST_CreateTopoGeo('ri_topo',
 ST_GeomFromText('MULTILINESTRING((384744 236928,384750 236923,384769 236911,384799 236895,384811 236890,384833 236884,
  384844 236882,384866 236881,384879 236883,384954 236898,385087 236932,385117 236938,
  385167 236938,385203 236941,385224 236946,385233 236950,385241 236956,385254 236971,
  385260 236979,385268 236999,385273 237018,385273 237037,385271 237047,385267 237057,
  385225 237125,385210 237144,385192 237161,385167 237192,385162 237202,385159 237214,
  385159 237227,385162 237241,385166 237256,385196 237324,385209 237345,385234 237375,
  385237 237383,385238 237399,385236 237407,385227 237419,385213 237430,385193 237439,
  385174 237451,385170 237455,385169 237460,385171 237475,385181 237503,385190 237521,
  385200 237533,385206 237538,385213 237541,385221 237542,385235 237540,385242 237541,
  385249 237544,385260 237555,385270 237570,385289 237584,385292 237589,385291 237596,385284 237630))',3438)
  );

      st_createtopogeo
----------------------------
 Topology ri_topo populated


-- テーブルとTopoGeometryの生成--
CREATE TABLE ri.roads(gid serial PRIMARY KEY, road_name text);

SELECT topology.AddTopoGeometryColumn('ri_topo', 'ri', 'roads', 'topo', 'LINE');
                                

Name

TopoGeo_AddPoint — 許容差を使って既存のトポロジにポイントを追加し、可能ならエッジを分割します。

Synopsis

integer TopoGeo_AddPoint(varchar toponame, geometry apoint, float8 tolerance);

説明

既存のトポロジにポイントを追加し、その識別番号を返します。指定されたポイントは、許容差の範囲内で既存のノードまたはエッジにスナップします。既存のエッジはスナップされたポイントで分割されることがあります。

Availability: 2.0.0


Name

TopoGeo_AddLineString — 許容差を使って既存のトポロジにラインストリングを追加し、可能ならエッジ/フェイスを分割します。

Synopsis

SETOF integer TopoGeo_AddLineString(varchar toponame, geometry aline, float8 tolerance);

説明

既存のトポロジにラインストリングを追加し、これを構成するエッジの識別番号の集合を返します。指定されたラインは、許容差の範囲内で既存のノードまたはエッジにスナップします。既存のエッジとフェイスはラインで分割されることがあります。

[Note]

Updating statistics about topologies being loaded via this function is up to caller, see maintaining statistics during topology editing and population.

Availability: 2.0.0


Name

TopoGeo_AddPolygon — 許容差を使って既存のトポロジにラインストリングを追加し、可能ならエッジ/フェイスを分割します。

Synopsis

integer TopoGeo_AddPolygon(varchar atopology, geometry apoly, float8 atolerance);

説明

既存のトポロジにポリゴンを追加し、これを構成するフェイスの識別番号の集合を返します。指定されたポリゴンの境界線は、許容差の範囲内で既存のノードまたはエッジにスナップします。既存のエッジとフェイスはポリゴンの境界線で分割されることがあります。

[Note]

Updating statistics about topologies being loaded via this function is up to caller, see maintaining statistics during topology editing and population.

Availability: 2.0.0

4.4.6. トポロジエディタ

Abstract

本節では、エッジ、フェイス、ノードの追加、移動、削除、分割に関する関数を挙げます。本節の関数はすべてISO SQL/MMで定義されています。

ST_AddIsoNode — フェイスに孤立ノードを追加し、新しいノードの識別番号を返します。フェイスがNULLの場合でもノードは生成されます。
ST_AddIsoEdgeanodeanothernodeで指定される二つの既存孤立ノードを接続するトポロジに、ジオメトリalinestringで定義される孤立エッジを追加し、新しいエッジの識別番号を返します。
ST_AddEdgeNewFaces — 新しいエッジを追加します。新しいエッジがフェイスを分割する場合には、もとのフェイスを削除して、分割した二つのフェイスに置き換えます。
ST_AddEdgeModFace — 新しいエッジを追加します。新しいエッジがフェイスを分割する場合には、もとのフェイスを編集し、一つのフェイスを追加します。
ST_RemEdgeNewFace — エッジを削除し、消去対象エッジでフェイスが二つに分割されているなら元の二つのフェイスを削除し、一つの新しいフェイスに置き換えます。
ST_RemEdgeModFace — エッジを削除し、削除対象エッジでフェイスが二つに分割されているなら、両方の空間をとるため、一つを削除して、もう一つを編集します。
ST_ChangeEdgeGeom — トポロジ構造に影響を与えることなくエッジの形状を変更します。
ST_ModEdgeSplit — 既存のエッジに沿って新しいノードを生成してエッジを分割します。もとのエッジは変更され、新しいエッジが一つ追加されます。
ST_ModEdgeHeal — 二つのエッジについて、接続しているノードを削除して修復します。1番目のエッジを編集して、2番目のエッジを削除します。削除されたノードの識別番号を返します。
ST_NewEdgeHeal — 二つのエッジについて、接続しているノードを削除して修復します。両方のエッジを削除し、1番目のエッジと同じ方向のエッジに置き換えます。
ST_MoveIsoNode — トポロジ内の孤立ノードを別の位置に移動させます。新しいapointジオメトリがノードとして存在しているなら、エラーが投げられます。移動に関する説明を返します。
ST_NewEdgesSplit — 新しいノードを既存のエッジに沿って作成して、エッジを分割します。もとのエッジは削除され、二つのエッジに置き換えられます。二つの新しいエッジに接続する新しいノードの識別番号を返します。
ST_RemoveIsoNode — 孤立ノードを削除し、実行結果が返されます。ノードが孤立していない (エッジの始端または終端である)場合には、例外が投げられます。
ST_RemoveIsoEdge — 孤立エッジを削除し、実行結果の記述を返します。エッジが孤立していない場合には、例外が投げられます。

Name

ST_AddIsoNode — フェイスに孤立ノードを追加し、新しいノードの識別番号を返します。フェイスがNULLの場合でもノードは生成されます。

Synopsis

integer ST_AddIsoNode(varchar atopology, integer aface, geometry apoint);

説明

atopologyで指定されたトポロジのafaceの識別番号で示された既存のフェイスに対して、apointで示された位置に孤立ノードを追加します。

ポイントジオメトリの空間参照系 (SRID)がトポロジと同じでない場合、apointがポイントジオメトリでない場合、ポイントがNULLである場合、または、ポイントが既存のエッジ (境界も含む)とインタセクトする場合には、例外が投げられます。また、ポイントが既にノードとして存在する場合、例外が投げられます。

afaceがNULLでなく、かつapointがフェイス内に無い場合には、例外が投げられます。

Availability: 1.?

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X 3.1


Name

ST_AddIsoEdge — anodeanothernodeで指定される二つの既存孤立ノードを接続するトポロジに、ジオメトリalinestringで定義される孤立エッジを追加し、新しいエッジの識別番号を返します。

Synopsis

integer ST_AddIsoEdge(varchar atopology, integer anode, integer anothernode, geometry alinestring);

説明

anodeanothernodeで指定される二つの既存孤立ノードを接続するトポロジに、ジオメトリalinestringで定義される孤立エッジを追加し、新しいエッジの識別番号を返します。

alinestringジオメトリとトポロジとで空間参照系 (SRID)が異なる場合、引数がNULLである場合、ノードが一つ以上のフェイスに含まれている場合には、二つのノードが既存エッジの始端または終端である場合には、例外が投げられます。

alinestringanodeanothernodeに属するフェイス内に無い場合には、例外が投げられます。

anodeanothernodeが、alinestringの始端と終端でない場合には、例外が投げられます。

Availability: 1.?

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.4


Name

ST_AddEdgeNewFaces — 新しいエッジを追加します。新しいエッジがフェイスを分割する場合には、もとのフェイスを削除して、分割した二つのフェイスに置き換えます。

Synopsis

integer ST_AddEdgeNewFaces(varchar atopology, integer anode, integer anothernode, geometry acurve);

説明

新しいエッジを追加します。新しいエッジがフェイスを分割する場合には、もとのフェイスを削除して、分割した二つのフェイスに置き換えます。新しいエッジの識別番号を返します。

この関数によって、既存の接続されているエッジとリレーションシップが更新されます。

引数がNULLの場合、与えられたノードが不明な場合(トポロジスキーマのnodeテーブル内に既に存在していなければなりません)、acurveLINESTRINGでない場合、anodeanothernodeが始端、終端でない場合には、例外が投げられます。

acurveジオメトリの空間参照系 (SRID) がトポロジと同じでない場合、例外が投げられます。

Availability: 2.0

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.12


Name

ST_AddEdgeModFace — 新しいエッジを追加します。新しいエッジがフェイスを分割する場合には、もとのフェイスを編集し、一つのフェイスを追加します。

Synopsis

integer ST_AddEdgeModFace(varchar atopology, integer anode, integer anothernode, geometry acurve);

説明

新しいエッジを追加します。新しいエッジがフェイスを分割する場合には、もとのフェイスを編集し、一つのフェイスを追加します。

[Note]

可能なら、新しいフェイスは新しいエッジの左側に作られます。左側のフェイスがユニバースフェイス (境界がない)でなければならない場合には、可能ではありません。

新しく追加されたエッジの識別番号を返します。

この関数によって、既存の接続されているエッジとリレーションシップが更新されます。

引数がNULLの場合、与えられたノードが不明な場合(トポロジスキーマのnodeテーブル内に既に存在していなければなりません)、acurveLINESTRINGでない場合、anodeanothernodeが始端、終端でない場合には、例外が投げられます。

acurveジオメトリの空間参照系 (SRID) がトポロジと同じでない場合、例外が投げられます。

Availability: 2.0

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.13


Name

ST_RemEdgeNewFace — エッジを削除し、消去対象エッジでフェイスが二つに分割されているなら元の二つのフェイスを削除し、一つの新しいフェイスに置き換えます。

Synopsis

integer ST_RemEdgeNewFace(varchar atopology, integer anedge);

説明

エッジを削除し、消去対象エッジでフェイスが二つに分割されているなら元の二つのフェイスを削除し、一つの新しいフェイスに置き換えます。

新しく作成されたフェイスの識別番号を返します。新しいフェイスが生成されない場合にはNULLを返します。削除対象エッジがダングルである (訳注: 「ぶらさがる」状態、すなわち一方の端が孤立ノードでなく、かつもう一方が孤立ノード)場合か、孤立している場合か、 ユニバースフェイスとの境界になっている (おそらく反対側のフェイスにユニバースが侵入します)場合には、フェイスは生成されません。

この関数によって、既存の接続されているエッジとリレーションシップが更新されます。

既存のTopoGeometryの定義に入り込んでいるエッジは削除を拒絶されます。TopoGeometryが二つのフェイスのうちひとつだけで定義されている (かつ他方は定義に使われていない)場合、二つのフェイスの修復は拒絶されます。

引数がNULLである場合、与えられたエッジが不明である場合 (トポロジスキーマのedgeテーブル内に既に存在していなければなりません)、トポロジ名が不正である場合、例外が投げられます。

Availability: 2.0

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.14


Name

ST_RemEdgeModFace — エッジを削除し、削除対象エッジでフェイスが二つに分割されているなら、両方の空間をとるため、一つを削除して、もう一つを編集します。

Synopsis

integer ST_RemEdgeModFace(varchar atopology, integer anedge);

説明

エッジを削除し、削除対象エッジでフェイスが二つに分割されているなら、両方の空間をとるため、一つを削除して、もう一つを編集します。ST_AddEdgeModFaceと対称となるよう、右側のフェイスを優先して保持します。削除対象エッジの代わりに残存するフェイスの識別番号を返します。

この関数によって、既存の接続されているエッジとリレーションシップが更新されます。

既存のTopoGeometryの定義に入り込んでいるエッジは削除を拒絶されます。TopoGeometryが二つのフェイスのうちひとつだけで定義されている (かつ他方は定義に使われていない)場合、二つのフェイスの修復は拒絶されます。

引数がNULLである場合、与えられたエッジが不明である場合 (トポロジスキーマのedgeテーブル内に既に存在していなければなりません)、トポロジ名が不正である場合、例外が投げられます。

Availability: 2.0

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.15


Name

ST_ChangeEdgeGeom — トポロジ構造に影響を与えることなくエッジの形状を変更します。

Synopsis

integer ST_ChangeEdgeGeom(varchar atopology, integer anedge, geometry acurve);

説明

トポロジ構造に影響を与えることなくエッジの形状を変更します。

NULLの引数があった場合、与えられたエッジがtopologyスキーマのedgeテーブルに存在しない場合、acurveLINESTRINGでない場合、anodeanothernodeacurveの開始点と終了点でない場合、または、変更によってトポロジが変わる場合には、エラーが投げられます。

acurveジオメトリの空間参照系 (SRID) がトポロジと同じでない場合、例外が投げられます。

新しいacurveが単純でない場合には、エラーが投げられます。

古い位置から新しい位置へのエッジ移動で障害物にあたった場合はエラーが投げられます。

Availability: 1.1.0

Enhanced: 2.0.0版で、トポロジ整合性の強制を追加しました。

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.6

SELECT topology.ST_ChangeEdgeGeom('ma_topo', 1,
                ST_GeomFromText('LINESTRING(227591.9 893900.4,227622.6 893844.3,227641.6 893816.6, 227704.5 893778.5)', 26986) );
 ----
 Edge 1 changed

Name

ST_ModEdgeSplit — 既存のエッジに沿って新しいノードを生成してエッジを分割します。もとのエッジは変更され、新しいエッジが一つ追加されます。

Synopsis

integer ST_ModEdgeSplit(varchar atopology, integer anedge, geometry apoint);

説明

既存のエッジに沿って新しいノードを生成してエッジを分割します。もとのエッジは変更され、新しいエッジが一つ追加されます。この関数によって、既存の接続されているエッジとリレーションシップが更新されます。新しく追加されたノードの識別番号が返ります。

Availability: 1.?

Changed: 2.0 - 以前の版では名前を間違えてST_ModEdgesSplitになっていました。

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.9

-- エッジの追加 --
 SELECT topology.AddEdge('ma_topo', ST_GeomFromText('LINESTRING(227592 893910, 227600 893910)', 26986) ) As edgeid;

-- edgeid --
3


-- エッジの分割 --
SELECT topology.ST_ModEdgeSplit('ma_topo',  3, ST_SetSRID(ST_Point(227594,893910),26986)  ) As node_id;
        node_id
-------------------------
7

Name

ST_ModEdgeHeal — 二つのエッジについて、接続しているノードを削除して修復します。1番目のエッジを編集して、2番目のエッジを削除します。削除されたノードの識別番号を返します。

Synopsis

int ST_ModEdgeHeal(varchar atopology, integer anedge, integer anotheredge);

説明

二つのエッジについて、接続しているノードを削除して修復します。1番目のエッジを編集して、2番目のエッジを削除します。削除されたノードの識別番号を返します。この関数によって、既存の接続されているエッジとリレーションシップが更新されます。

Availability: 2.0

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.9


Name

ST_NewEdgeHeal — 二つのエッジについて、接続しているノードを削除して修復します。両方のエッジを削除し、1番目のエッジと同じ方向のエッジに置き換えます。

Synopsis

int ST_NewEdgeHeal(varchar atopology, integer anedge, integer anotheredge);

説明

二つのエッジについて、接続しているノードを削除して修復します。両方のエッジを削除し、1番目のエッジと同じ方向のエッジに置き換えます。 修復されたエッジに置き換えられた新しいエッジの識別番号を返します。 この関数によって、既存の接続されているエッジとリレーションシップが更新されます。

Availability: 2.0

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.9


Name

ST_MoveIsoNode — トポロジ内の孤立ノードを別の位置に移動させます。新しいapointジオメトリがノードとして存在しているなら、エラーが投げられます。移動に関する説明を返します。

Synopsis

text ST_MoveIsoNode(varchar atopology, integer anedge, geometry apoint);

説明

トポロジ内の孤立ノードを別の位置に移動させます。新しいapointジオメトリがノードとして存在しているなら、エラーが投げられます。

引数がNULLである場合、apointがポイントでない場合、既存のノードが孤立していない (既存エッジの始端または終端)場合、 新しいノード位置が既存のエッジとインタセクトする (終端も含む)場合、例外が投げられます。

ポイントジオメトリの空間参照系 (SRID)がトポロジと異なる場合には、例外が投げられます。

Availability: 1.?

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.2

-- フェイスの無い孤立ノードの追加 --
SELECT topology.ST_AddIsoNode('ma_topo',  NULL, ST_GeomFromText('POINT(227579 893916)', 26986) ) As nodeid;
 nodeid
--------
      7
-- 新しいノードの移動 --
SELECT topology.ST_MoveIsoNode('ma_topo', 7,  ST_GeomFromText('POINT(227579.5 893916.5)', 26986) ) As descrip;
                      descrip
----------------------------------------------------
Isolated Node 7 moved to location 227579.5,893916.5

関連情報

ST_AddIsoNode


Name

ST_NewEdgesSplit — 新しいノードを既存のエッジに沿って作成して、エッジを分割します。もとのエッジは削除され、二つのエッジに置き換えられます。二つの新しいエッジに接続する新しいノードの識別番号を返します。

Synopsis

integer ST_NewEdgesSplit(varchar atopology, integer anedge, geometry apoint);

説明

anedgeで指定される既存のエッジに沿ったapointの位置に新しいノードを作成して、エッジを分割します。もとのエッジは削除され、二つつのエッジに置き換えられます。二つの新しいエッジに接続する新しいノードの識別番号を返します。この関数によって、既存の接続されているエッジとリレーションシップが更新されます。

ポイントジオメトリの空間参照系 (SRID)がトポロジと異なる場合、apointがポイントジオメトリでない場合、ポイントがNULLの場合、ポイントが既にノードとして存在する場合、エッジが既存のエッジと一致しない場合、ポイントがエッジ内にない場合、例外が投げられます。

Availability: 1.?

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.8

-- エッジの追加  --
SELECT topology.AddEdge('ma_topo', ST_GeomFromText('LINESTRING(227575 893917,227592 893900)', 26986) ) As edgeid;
-- 結果 --
edgeid
------
        2
-- 新しいエッジの分割 --
SELECT topology.ST_NewEdgesSplit('ma_topo', 2,  ST_GeomFromText('POINT(227578.5 893913.5)', 26986) ) As newnodeid;
 newnodeid
---------
       6

Name

ST_RemoveIsoNode — 孤立ノードを削除し、実行結果が返されます。ノードが孤立していない (エッジの始端または終端である)場合には、例外が投げられます。

Synopsis

text ST_RemoveIsoNode(varchar atopology, integer anode);

説明

孤立ノードを削除し、実行結果が返されます。ノードが孤立していない (エッジの始端または終端である)場合には、例外が投げられます。

Availability: 1.?

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.3

-- フェイスの無い孤立ノードの削除 --
SELECT topology.ST_RemoveIsoNode('ma_topo',  7 ) As result;
         result
-------------------------
 Isolated node 7 removed

関連情報

ST_AddIsoNode


Name

ST_RemoveIsoEdge — 孤立エッジを削除し、実行結果の記述を返します。エッジが孤立していない場合には、例外が投げられます。

Synopsis

text ST_RemoveIsoEdge(varchar atopology, integer anedge);

説明

孤立エッジを削除し、実行結果の記述を返します。エッジが孤立していない場合には、例外が投げられます。

Availability: 1.?

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.3

-- フェイスの無い孤立ノードの削除 --
SELECT topology.ST_RemoveIsoNode('ma_topo',  7 ) As result;
         result
-------------------------
 Isolated node 7 removed

関連情報

ST_AddIsoNode

4.4.7. トポロジアクセサ

GetEdgeByPoint — 与えられたポイントにインタセクトするエッジの識別番号を探索します。
GetFaceByPoint — 与えられたポイントにインタセクトするフェイスの識別番号を探索します。
GetNodeByPoint — ポイント位置にあるノードの識別番号を探索します。
GetTopologyID — トポロジ名からtopology.topologyテーブル内にあるトポロジの識別番号を返します。
GetTopologySRID — トポロジ名からtopology.topologyテーブル内にあるトポロジのSRIDを返します。
GetTopologyName — 識別番号からトポロジ (スキーマ)の名前を返します。
ST_GetFaceEdges — 順序番号を含む、afaceの境界となる、整列したエッジの集合を返します。
ST_GetFaceGeometry — 指定されたトポロジの中の、フェイス識別番号で指定されたポリゴンを返します。
GetRingEdges — 与えられた側を歩いて得られた、正負符号付きエッジ識別番号の集合を、順序通りに返します。
GetNodeEdges — 与えられたノードに付随するエッジの集合を整列して返します。

Name

GetEdgeByPoint — 与えられたポイントにインタセクトするエッジの識別番号を探索します。

Synopsis

integer GetEdgeByPoint(varchar atopology, geometry apoint, float8 tol);

説明

与えられたポイントにインタセクトするエッジの識別番号を探索します。

この関数は、トポロジ、ポイント、許容差を引数にして、整数 (エッジの識別番号)を返します。許容差が0の場合、ポイントはエッジとインタセクトしていなければなりません。

ポイントがエッジにインタセクトしない場合には0を返します。

許容差を0より大きくして、ポイント付近のエッジが一つより多い場合には、例外が投げられます。

[Note]

許容差が0の場合には、ST_Intersectsを使い、それ以外では、ST_DWinthinを使います。

GEOSモジュールで実現しています。

Availability: 2.0.0

本例ではAddEdgeで作ったエッジを使います。

SELECT topology.GetEdgeByPoint('ma_topo',geom, 1) As with1mtol, topology.GetEdgeByPoint('ma_topo',geom,0) As withnotol
FROM ST_GeomFromEWKT('SRID=26986;POINT(227622.6 893843)') As geom;
 with1mtol | withnotol
-----------+-----------
         2 |         0
SELECT topology.GetEdgeByPoint('ma_topo',geom, 1) As nearnode
FROM ST_GeomFromEWKT('SRID=26986;POINT(227591.9 893900.4)') As geom;

-- エラー発生 --
ERROR:  Two or more edges found

Name

GetFaceByPoint — 与えられたポイントにインタセクトするフェイスの識別番号を探索します。

Synopsis

integer GetFaceByPoint(varchar atopology, geometry apoint, float8 tol);

説明

与えられたポイントにインタセクトするフェイスの識別番号を探索します。

この関数は、トポロジ、ポイント、許容差を引数にして、整数 (フェイスの識別番号)を返します。許容差が0の場合には、ポイントはフェイスとインタセクトしていなければなりません。

ポイントがフェイスにインタセクトしない場合には.、0を返します。

許容差を0より大きくして、ポイント付近のフェイスが一つより多い場合には、例外が投げられます。

[Note]

許容差が0の場合には、ST_Intersectsを使い、それ以外では、ST_DWinthinを使います。

GEOSモジュールで実現しています。

Availability: 2.0.0

本例ではAddFaceで作ったフェイスを使います。

SELECT topology.GetFaceByPoint('ma_topo',geom, 10) As with1mtol, topology.GetFaceByPoint('ma_topo',geom,0) As withnotol
        FROM ST_GeomFromEWKT('POINT(234604.6 899382.0)') As geom;

         with1mtol | withnotol
        -----------+-----------
                         1 |         0
SELECT topology.GetFaceByPoint('ma_topo',geom, 1) As nearnode
        FROM ST_GeomFromEWKT('POINT(227591.9 893900.4)') As geom;

-- エラー発生--
ERROR:  Two or more faces found

Name

GetNodeByPoint — ポイント位置にあるノードの識別番号を探索します。

Synopsis

integer GetNodeByPoint(varchar atopology, geometry point, float8 tol);

説明

ポイント位置にあるノードの識別番号を探索します。

この関数は、トポロジ、ポイント、許容差を引数にして、整数 (ノードの識別番号) を返します。許容差が0の場合には、完全にインタセクトしているかで判断し、他の場合には、ある程度の間隔で探索します。

ポイントがエッジにインタセクトしない場合には0を返します。

許容差を0より大きくして、ポイント付近のエッジが一つより多い場合には、例外が投げられます。

[Note]

許容差が0の場合には、ST_Intersectsを使い、それ以外では、ST_DWinthinを使います。

GEOSモジュールで実現しています。

Availability: 2.0.0

本例ではAddEdgeで作ったエッジを使います。

SELECT topology.GetNodeByPoint('ma_topo',geom, 1) As nearnode
 FROM ST_GeomFromEWKT('SRID=26986;POINT(227591.9 893900.4)') As geom;
  nearnode
----------
        2
 
SELECT topology.GetNodeByPoint('ma_topo',geom, 1000) As too_much_tolerance
 FROM ST_GeomFromEWKT('SRID=26986;POINT(227591.9 893900.4)') As geom;

 -- エラー発生 --
 ERROR:  Two or more nodes found
 

Name

GetTopologyID — トポロジ名からtopology.topologyテーブル内にあるトポロジの識別番号を返します。

Synopsis

integer GetTopologyID(varchar toponame);

説明

トポロジ名からtopology.topologyテーブル内にあるトポロジの識別番号を返します。

Availability: 1.?

SELECT topology.GetTopologyID('ma_topo') As topo_id;
 topo_id
---------
       1

Name

GetTopologySRID — トポロジ名からtopology.topologyテーブル内にあるトポロジのSRIDを返します。

Synopsis

integer GetTopologyID(varchar toponame);

説明

与えられたトポロジ名からtopology.topologyテーブル内のトポロジの空間参照系識別番号を返します。

Availability: 2.0.0

SELECT topology.GetTopologySRID('ma_topo') As SRID;
 SRID
-------
  4326

Name

GetTopologyName — 識別番号からトポロジ (スキーマ)の名前を返します。

Synopsis

varchar GetTopologyName(integer topology_id);

説明

識別番号からトポロジ (スキーマ)の名前を返します。

Availability: 1.?

SELECT topology.GetTopologyName(1) As topo_name;
 topo_name
-----------
 ma_topo

Name

ST_GetFaceEdges — 順序番号を含む、afaceの境界となる、整列したエッジの集合を返します。

Synopsis

getfaceedges_returntype ST_GetFaceEdges(varchar atopology, integer aface);

説明

順序番号を含む、afaceの境界となる、整列したエッジの集合を返します。それぞれの出力は、順序番号とエッジ識別番号からなります。順序番号は1から始まります。

環ごとのエッジの列挙は、識別番号が最も小さいものから始まります。エッジの順序は左手の法則に従います (境界フェイスは各有向辺の左側にあるようにします)。

Availability: 2.0

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.5

-- 1番フェイスの境界を返します。
SELECT (topology.ST_GetFaceEdges('tt', 1)).*;
-- 結果 --
 sequence | edge
----------+------
        1 |   -4
        2 |    5
        3 |    7
        4 |   -6
        5 |    1
        6 |    2
        7 |    3
(7 rows)
-- 1番フェイスの順序番号、エッジ識別番号とジオメトリを返します。
-- geomとseqが欲しいだけならST_GetFaceGeometryを使います。
SELECT t.seq, t.edge, geom
FROM topology.ST_GetFaceEdges('tt',1) As t(seq,edge)
        INNER JOIN tt.edge AS e ON abs(t.edge) = e.edge_id;

Name

ST_GetFaceGeometry — 指定されたトポロジの中の、フェイス識別番号で指定されたポリゴンを返します。

Synopsis

geometry ST_GetFaceGeometry(varchar atopology, integer aface);

説明

指定されたトポロジの中の、フェイス識別番号で指定されたポリゴンを返します。フェイスを作るエッジからポリゴンを構築します。

Availability: 1.?

This method implements the SQL/MM specification. SQL-MM 3 トポロジ-ジオメトリ および トポロジ-ネットワーク 3: ルーチン詳細: X.3.16

-- AddFaceで追加したポリゴンのWKTを返します。
SELECT ST_AsText(topology.ST_GetFaceGeometry('ma_topo', 1)) As facegeomwkt;
-- 結果 --
               facegeomwkt

--------------------------------------------------------------------------------
 POLYGON((234776.9 899563.7,234896.5 899456.7,234914 899436.4,234946.6 899356.9,
234872.5 899328.7,234891 899285.4,234992.5 899145,234890.6 899069,
234755.2 899255.4,234612.7 899379.4,234776.9 899563.7))

関連情報

AddFace


Name

GetRingEdges — 与えられた側を歩いて得られた、正負符号付きエッジ識別番号の集合を、順序通りに返します。

Synopsis

getfaceedges_returntype GetRingEdges(varchar atopology, integer aring, integer max_edges=null);

説明

与えられた側を歩いて得られた、正負符号付きエッジ識別番号の集合を、順序通りに返します。出力は順序番号と正負符号付きエッジ識別番号からなります。順序番号は1始まりです。

正のエッジ識別番号を渡すと、対応するエッジの左側を歩き、エッジを順方向に進みます。負のエッジ識別番号を渡すと、右側を歩き、エッジを逆方向に進みます。

max_edgesがNULLでな場合には、返されるレコードを超えることはありません。これは、不正なトポロジを扱うときの安全確保のためのパラメータであることを意味します。

[Note]

この関数はメタデータとリンクするエッジ環を使います。

Availability: 2.0.0


Name

GetNodeEdges — 与えられたノードに付随するエッジの集合を整列して返します。

Synopsis

getfaceedges_returntype GetNodeEdges(varchar atopology, integer anode);

説明

与えられたノードに付随するエッジの集合を整列して返します。 出力は、連続する、正負符号を持つエッジ識別番号からなります。順序番号は1から始まります。 正のエッジは与えられたノードから始まるものです。 負のエッジは与えられたノードで終わるものです。 閉じたエッジは2回現れます (正と負になります)。 並び順は北側から時計回りになります。

[Note]

この関数は、並び順を計算していて、メタデータからのデータを使わないので、 連結しているエッジ環を構築するのに使えます。

Availability: 2.0

関連情報

GetRingEdges, ST_Azimuth

4.4.8. トポロジ処理

Abstract

本節では、非標準の手法でのトポロジ処理の関数を挙げます。

Polygonize — トポロジエッジで定義される全てのフェイスを探索し、追加します。
AddNode — 指定したトポロジスキーマのノードテーブルにポイントノードを追加し、新しいノードの識別番号を返します。指定したポイントに既にノードがある場合は既存のノード識別番号を返します。
AddEdge — 指定したラインストリングジオメトリを使って、ラインストリングエッジをエッジテーブルに追加し、指定したトポロジスキーマの始点終点をポイントノードテーブルに追加し、新しい (または既存の)エッジの識別番号を返します。
AddFace — フェイスプリミティブをトポロジに登録し、その識別番号を得ます。
ST_Simplify — 与えたTopoGeometryを「シンプル化した」ジオメトリを返します。ダグラス-ポーカーのアルゴリズムを使います。

Name

Polygonize — トポロジエッジで定義される全てのフェイスを探索し、追加します。

Synopsis

text Polygonize(varchar toponame);

説明

トポロジエッジプリミティブで構築することができる全てのフェイスを登録します。

対象トポロジは自己インタセクトするエッジが無いと仮定しています。

[Note]

既に登録されているフェイスは認識されているので、同じトポロジに対してPolygonizeを複数回呼んでも問題ありません。

[Note]

この関数はエッジテーブルのnext_left_edgeとnext_right_edgeフィールドの読み書きを行いません。

Availability: 2.0.0

関連情報

AddFace, ST_Polygonize


Name

AddNode — 指定したトポロジスキーマのノードテーブルにポイントノードを追加し、新しいノードの識別番号を返します。指定したポイントに既にノードがある場合は既存のノード識別番号を返します。

Synopsis

integer AddNode(varchar toponame, geometry apoint, boolean allowEdgeSplitting=false, boolean computeContainingFace=false);

説明

指定したトポロジスキーマのノードテーブルにポイントノードを追加します。 AddEdge関数は、呼ばれると自動的にエッジの始端と終端のポイントを追加するので、明示的にエッジのノードを追加する必要はあまりありません。

ノードとクロスするエッジが発見された場合は、例外が発生するか、エッジが分割されます。allowEdgeSplittingパラメータの値に依存します。

computeContainingFaceがtrueの場合には、新しく追加されたノードによって、ノードを含む正しいフェイスが計算されます。

[Note]

apointジオメトリが既にノードとして存在する場合、ノードは追加されずに、既存ノードの識別番号を返します。

Availability: 2.0.0

SELECT topology.AddNode('ma_topo', ST_GeomFromText('POINT(227641.6 893816.5)', 26986) ) As nodeid;
-- 結果 --
nodeid
--------
 4

関連情報

AddEdge, CreateTopology


Name

AddEdge — 指定したラインストリングジオメトリを使って、ラインストリングエッジをエッジテーブルに追加し、指定したトポロジスキーマの始点終点をポイントノードテーブルに追加し、新しい (または既存の)エッジの識別番号を返します。

Synopsis

integer AddEdge(varchar toponame, geometry aline);

説明

指定したラインストリングジオメトリを使って、指定したtoponameスキーマのノードテーブルにノードを追加し、新しいまたは既存のレコードのエッジ識別番号を返します。ラインストリングエッジをエッジテーブルに追加し、指定したトポロジスキーマの始点終点をポイントノードテーブルに追加し、新規または既存のエッジの識別番号を返します。新しく追加されたエッジは両側にユニバースフェイスを持ち、自分自身にリンクしています。

[Note]

alineジオメトリが既存のエッジとクロスしたり、既存のエッジをオーバラップしたり、既存のエッジを包含したり、既存のエッジに包含されたりする場合には、エラーが投げられ、エッジは追加されません。

[Note]

alineのジオメトリはsridがトポロジで指定されたものと同じである必要があり、異なる場合には、不正な空間参照系エラーが投げられます。

GEOSモジュールで実現しています。

Availability: 2.0.0

SELECT topology.AddEdge('ma_topo', ST_GeomFromText('LINESTRING(227575.8 893917.2,227591.9 893900.4)', 26986) ) As edgeid;
-- 結果 --
edgeid
--------
 1

SELECT topology.AddEdge('ma_topo', ST_GeomFromText('LINESTRING(227591.9 893900.4,227622.6 893844.2,227641.6 893816.5,
 227704.5 893778.5)', 26986) ) As edgeid;
-- 結果 --
edgeid
--------
 2

 SELECT topology.AddEdge('ma_topo', ST_GeomFromText('LINESTRING(227591.2 893900, 227591.9 893900.4,
  227704.5 893778.5)', 26986) ) As edgeid;
 -- エラー発生 --
 ERROR:  Edge intersects (not on endpoints) with existing edge 1

Name

AddFace — フェイスプリミティブをトポロジに登録し、その識別番号を得ます。

Synopsis

integer AddFace(varchar toponame, geometry apolygon, boolean force_new=false);

説明

フェイスプリミティブをトポロジに登録し、その識別番号を得ます。

新しく追加されたフェイスのために、境界を形成するエッジとフェイスに含まれるエッジはleft_faceとright_faceフィールドに正しい値を持つよう更新されます。フェイスに含まれる孤立ノードも正しいcontaining_faceフィールド値を持つよう更新されます。

[Note]

この関数はエッジテーブルのnext_left_edgeとnext_right_edgeフィールドの読み書きを行いません。

対象トポロジは妥当 (自己インタセクトするエッジが無い)と仮定しています。ポリゴンの境界が既存のエッジでは完全には定義されない場合や、ポリゴンが既存のフェイスにオーバラップする場合には、例外が投げられます。

apolygonジオメトリが既にフェイスとして存在している場合には、 force_newがfalse (デフォルト)の場合は、既存フェイスのフェイス識別番号が返り、force_newがtrueの場合は、新しい識別番号が

[Note]

既存フェイスの新規登録が実行される時(force_new=true)、そのエッジ内の既存のフェイスへの参照のダングルを解決しません。また、関連テーブルのノードと既存フェイスのレコードのMBR(訳注: 最小境界矩形)フィールドの更新も行いません。これに対応するのは、この関数を呼び出した側です。

[Note]

apolygonジオメトリはトポロジと同じsridである必要があり、異なる場合には、不正な空間参照系エラーが投げられます。

Availability: 2.0.0

-- 最初に、反復子にgenerate_seriesを使用してエッジを追加
-- (generate_seriesの最大値の関係上、
-- 頂点が10000個未満のポリゴンでのみ動作します)

SELECT topology.AddEdge('ma_topo', ST_MakeLine(ST_PointN(geom,i), ST_PointN(geom, i + 1) )) As edgeid
    FROM (SELECT  ST_NPoints(geom) AS npt, geom
            FROM
                (SELECT ST_Boundary(ST_GeomFromText('POLYGON((234896.5 899456.7,234914 899436.4,234946.6 899356.9,234872.5 899328.7,
                234891 899285.4,234992.5 899145, 234890.6 899069,234755.2 899255.4,
                234612.7 899379.4,234776.9 899563.7,234896.5 899456.7))', 26986) )  As geom
            )  As geoms) As facen CROSS JOIN generate_series(1,10000) As i
         WHERE i < npt;
-- 結果 --
 edgeid
--------
      3
      4
      5
      6
      7
      8
      9
     10
     11
     12
(10 rows)
-- フェイスの追加

SELECT topology.AddFace('ma_topo',
    ST_GeomFromText('POLYGON((234896.5 899456.7,234914 899436.4,234946.6 899356.9,234872.5 899328.7,
    234891 899285.4,234992.5 899145, 234890.6 899069,234755.2 899255.4,
    234612.7 899379.4,234776.9 899563.7,234896.5 899456.7))', 26986) ) As faceid;
-- 結果 --
faceid
--------
 1


Name

ST_Simplify — 与えたTopoGeometryを「シンプル化した」ジオメトリを返します。ダグラス-ポーカーのアルゴリズムを使います。

Synopsis

geometry ST_Simplify(TopoGeometry geomA, float tolerance);

説明

与えたTopoGeometryを「シンプル化した」ジオメトリを返します。個々の要素エッジに対してダグラス-ポーカーのアルゴリズムを使います。

[Note]

返されるジオメトリは単純でなかったり不正であったりする場合があります。

要素エッジの分割によって単純性/妥当性を維持することがあります。

GEOSモジュールで実現しています。

Availability: 2.1.0

関連情報

ST_Simplify (ジオメトリ), ST_IsSimple, ???, ST_ModEdgeSplit

4.4.9. TopoGeometryコンストラクタ

Abstract

本節では、新しいTopoGeometryを生成するトポロジ関数を挙げます。

CreateTopoGeom — 新しいTopoGeometryオブジェクトをtopoエレメント配列から生成します - tg_type: 1:[multi]point, 2:[multi]line, 3:[multi]poly, 4:collection
toTopoGeom — 単純なジオメトリからTopoGeometryを生成します。
TopoElementArray_Agg — element_idとタイプの配列 (topoelements)からなるtopoelementarrayを返します。

Name

CreateTopoGeom — 新しいTopoGeometryオブジェクトをtopoエレメント配列から生成します - tg_type: 1:[multi]point, 2:[multi]line, 3:[multi]poly, 4:collection

Synopsis

topogeometry CreateTopoGeom(varchar toponame, integer tg_type, integer layer_id, topoelementarray tg_objs);

topogeometry CreateTopoGeom(varchar toponame, integer tg_type, integer layer_id);

説明

layer_idで示されたレイヤでTopoGeometryオブジェクトを生成し、toponameスキーマの関連テーブルに登録します。

tg_typeは次の整数値とします: 1:[multi]point (punctal), 2:[multi]line (lineal), 3:[multi]poly (areal), 4:collection。layer_idは、topology.layerテーブル内のレイヤ識別番号です。

点レイヤはノードの集合から形成され、線レイヤはエッジの集合から形成され、面レイヤはフェイスの集合から形成され、コレクションはノード、エッジ、フェイスの混合から形成されます。

要素の配列を省略した場合、空のTopoGeometryオブジェクトが生成されます。

Availability: 1.?

例: 既存エッジからの形成

ri_topoスキーマ内 (ST_CreateTopoGeoの例でロードしてあります)で、ラインタイプ (整数値で2)の、layer_idが2のレイヤ (ri_roads)の最初のエッジからTopoGeometryを生成します。

INSERT INTO ri.ri_roads(road_name, topo) VALUES('Unknown', topology.CreateTopoGeom('ri_topo',2,2,'{{1,2}}'::topology.topoelementarray);

例: 面ジオメトリから最善と推測されるTopoGeometryへの変換

フェイスのコレクションから形成されるジオメトリがあるとします。blockgroupsテーブルがあり、それぞれの区画群のTopoGeometryを知りたいとします。データが完全に整列しているなら、次のようにできます。

-- TopoGeometryカラムの生成 --
SELECT topology.AddTopoGeometryColumn(
        'topo_boston',
        'boston', 'blockgroups', 'topo', 'POLYGON');

-- addtopgeometrycolumn --
1

-- 全てがエッジに沿っている前提でのカラムのアップデート
UPDATE boston.blockgroups AS bg
        SET topo = topology.CreateTopoGeom('topo_boston'
        ,3,1
        , foo.bfaces)
FROM (SELECT b.gid,  topology.TopoElementArray_Agg(ARRAY[f.face_id,3]) As bfaces
        FROM boston.blockgroups As b
            INNER JOIN topo_boston.face As f ON b.geom && f.mbr
        WHERE ST_Covers(b.geom, topology.ST_GetFaceGeometry('topo_boston', f.face_id))
            GROUP BY b.gid) As foo
WHERE foo.gid = bg.gid;
-- 世界が誤差を完璧に許容することは、ほぼありません。
-- 50%がblockgroupの境界の内側に落ちるフェイスを数えます。
UPDATE boston.blockgroups AS bg
        SET topo = topology.CreateTopoGeom('topo_boston'
        ,3,1
        , foo.bfaces)
FROM (SELECT b.gid,  topology.TopoElementArray_Agg(ARRAY[f.face_id,3]) As bfaces
        FROM boston.blockgroups As b
            INNER JOIN topo_boston.face As f ON b.geom && f.mbr
        WHERE ST_Covers(b.geom, topology.ST_GetFaceGeometry('topo_boston', f.face_id))
        OR
 (  ST_Intersects(b.geom, topology.ST_GetFaceGeometry('topo_boston', f.face_id))
            AND ST_Area(ST_Intersection(b.geom, topology.ST_GetFaceGeometry('topo_boston', f.face_id) ) ) >
                ST_Area(topology.ST_GetFaceGeometry('topo_boston', f.face_id))*0.5
                )
            GROUP BY b.gid) As foo
WHERE foo.gid = bg.gid;

-- TopoGeometryを、ジオメトリに戻したい場合には、
-- topoをgeometry型にキャストします。
-- 戻されたジオメトリは、トポロジの規則に関わりませんが、
-- フェイスとエッジに沿ったものになります。
-- 新しいジオメトリはTigerの道路中心線に沿っていて、とても素晴らしいです。
UPDATE boston.blockgroups SET new_geom = topo::geometry;

Name

toTopoGeom — 単純なジオメトリからTopoGeometryを生成します。

Synopsis

topogeometry toTopoGeom(geometry geom, varchar toponame, integer layer_id, float8 tolerance);

topogeometry toTopoGeom(geometry geom, topogeometry topogeom, float8 tolerance);

説明

単純なジオメトリからTopoGeometryを生成します。

入力ジオメトリを表現するために必要なトポロジプリミティブが、下位にあるトポロジに追加されます。既存のものを分割することもあります。relationテーブル内のTopoGeometryの出力に紐づきます。

既存のTopoGeometryオブジェクトは形状を維持します (topogeomが与えられている場合には、それが例外となる可能性があります)。

toleranceは、与えられた場合には、入力ジオメトリを既存のプリミティブにスナップさせるために使われます。

1番目の形式では、新しいTopoGeometryは、与えられたトポロジ (toponame)の与えられたレイヤ (layer_id)に作られます。

2番目の形式では、変換結果のプリミティブが、既存のTopoGeometry (topogeom)に追加されます。また、最終の形状にスペースを追加することがあります。新しい形状を完全に持つには、古いものを入れ替えます。clearTopoGeomを参照して下さい。

Availability: 2.0

Enhanced: 2.1.0版では、既存のTopoGeometryを取る形式が追加されました。

これは完全に全て揃ったワークフローです。

-- トポロジのセットアップがまだ終わっていない場合に実行します。
-- 許容値を許可しません。
SELECT topology.CreateTopology('topo_boston_test', 2249);
-- 新しいテーブルの生成
CREATE TABLE nei_topo(gid serial primary key, nei varchar(30));
-- TopoGeometryカラムの追加
SELECT topology.AddTopoGeometryColumn('topo_boston_test', 'public', 'nei_topo', 'topo', 'MULTIPOLYGON') As new_layer_id;
new_layer_id
-----------
1

-- 新しいTopoGeometryカラムの投入に新しいレイヤIDを使います。
-- TopoGeometryを新しいレイヤに許容値0で追加します。
INSERT INTO nei_topo(nei, topo)
SELECT nei,  topology.toTopoGeom(geom, 'topo_boston_test', 1)
FROM neighborhoods
WHERE gid BETWEEN 1 and 15;

-- 何が発生したかの確認
SELECT * FROM
    topology.TopologySummary('topo_boston_test');

-- 結果--
Topology topo_boston_test (5), SRID 2249, precision 0
61 nodes, 87 edges, 35 faces, 15 topogeoms in 1 layers
Layer 1, type Polygonal (3), 15 topogeoms
 Deploy: public.nei_topo.topo
-- 全てのTopoGeometryポリゴンを10メートル縮小
UPDATE nei_topo SET topo = ST_Buffer(clearTopoGeom(topo), -10);

-- 上の操作で何も無いようになった土地の取得
-- GRASSでは"polygon0 layer"と呼ばれているものと思います
SELECT ST_GetFaceGeometry('topo_boston_test', f.face_id)
  FROM topo_boston_test.face f
  WHERE f.face_id 
> 0 -- don't consider the universe face
  AND NOT EXISTS ( -- check that no TopoGeometry references the face
    SELECT * FROM topo_boston_test.relation
    WHERE layer_id = 1 AND element_id = f.face_id
  );
        

Name

TopoElementArray_Agg — element_idとタイプの配列 (topoelements)からなるtopoelementarrayを返します。

Synopsis

topoelementarray TopoElementArray_Agg(topoelement set tefield);

説明

TopoElementArrayTopoElementの集合から生成するために使います。

Availability: 2.0.0

SELECT topology.TopoElementArray_Agg(ARRAY[e,t]) As tea
  FROM generate_series(1,3) As e CROSS JOIN generate_series(1,4) As t;
  tea
--------------------------------------------------------------------------
{{1,1},{1,2},{1,3},{1,4},{2,1},{2,2},{2,3},{2,4},{3,1},{3,2},{3,3},{3,4}}

4.4.10. TopoGeometryエディタ

Abstract

本節では、既存のTopoGeometryを編集する関数を挙げます。

clearTopoGeom — TopoGeometryの中身を消去します。
TopoGeom_addElement — TopoGeometryの定義に要素を追加します。
TopoGeom_remElement — TopoGeometryの定義から要素を削除します。
toTopoGeom — ジオメトリの形状を既存のTopoGeometryに追加します。

Name

clearTopoGeom — TopoGeometryの中身を消去します。

Synopsis

topogeometry clearTopoGeom(topogeometry topogeom);

説明

TopoGeometryの中身を消去し、空にします。toTopoGeomと併用して、既存オブジェクトと上位にある依存オブジェクトの形状の置換に、だいたい便利です。

Availability: 2.1

-- 全てのTopoGeometryポリゴンを10メートル縮める
UPDATE nei_topo SET topo = ST_Buffer(clearTopoGeom(topo), -10);
                                

関連情報

toTopoGeom


Name

TopoGeom_addElement — TopoGeometryの定義に要素を追加します。

Synopsis

topogeometry TopoGeom_addElement(topogeometry tg, topoelement el);

説明

TopoElementをTopoGeometryオブジェクトの定義に追加します。要素がすでに定義の一部になっていても、エラーは発生しません。

Availability: 2.3

-- 5番エッジをTopoGeometry tgに追加
UPDATE mylayer SET tg = TopoGeom_addElement(tg, '{5,2}');
                                

Name

TopoGeom_remElement — TopoGeometryの定義から要素を削除します。

Synopsis

topogeometry TopoGeom_remElement(topogeometry tg, topoelement el);

説明

TopoGeometryオブジェクトの定義からTopoElementを削除します。

Availability: 2.3

-- TopoGeometry tgから43番フェイスを削除します
UPDATE mylayer SET tg = TopoGeom_remElement(tg, '{43,3}');
                                

Name

toTopoGeom — ジオメトリの形状を既存のTopoGeometryに追加します。

説明

toTopoGeomを参照して下さい。

4.4.11. TopoGeometryアクセサ

GetTopoGeomElementArray — 与えられたTopoGeometry (プリミティブ要素)のトポロジ要素とタイプを含むtopoelementarray (topoelementの配列)を返します。
GetTopoGeomElements — 与えられたTopoGeometry (プリミティブ要素)の、トポロジのelement_idとelement_typeを含むtopoelementオブジェクトの集合を返します。

Name

GetTopoGeomElementArray — 与えられたTopoGeometry (プリミティブ要素)のトポロジ要素とタイプを含むtopoelementarray (topoelementの配列)を返します。

Synopsis

topoelementarray GetTopoGeomElementArray(varchar toponame, integer layer_id, integer tg_id);

topoelementarray topoelement GetTopoGeomElementArray(topogeometry tg);

説明

トポロジ要素と与えられたTopoGeometry (プリミティブ要素)のタイプを含むTopoElementArrayを返します。GetTopoGeomElementsに近いですが、これは、要素群をデータセットでなく配列で返しています。

tg_idは、topology.layerテーブル内のlayer_idで指定されたレイヤのトポロジにおけるTopoGeometryオブジェクトの識別番号です。

Availability: 1.?


Name

GetTopoGeomElements — 与えられたTopoGeometry (プリミティブ要素)の、トポロジのelement_idとelement_typeを含むtopoelementオブジェクトの集合を返します。

Synopsis

setof topoelement GetTopoGeomElements(varchar toponame, integer layer_id, integer tg_id);

setof topoelement GetTopoGeomElements(topogeometry tg);

説明

toponameスキーマ内の、与えられたTopoGeometryのelement_idとelement_type (topoelements)の集合を返します。

tg_idは、topology.layerテーブル内のlayer_idで指定されたレイヤのトポロジにおけるTopoGeometryオブジェクトの識別番号です。

Availability: 2.0.0

4.4.12. TopoGeometry出力

AsGML — TopoGeometryのGML表現を返します。
AsTopoJSON — opoGeometryのTopoJSON表現を返します。

Name

AsGML — TopoGeometryのGML表現を返します。

Synopsis

text AsGML(topogeometry tg);

text AsGML(topogeometry tg, text nsprefix_in);

text AsGML(topogeometry tg, regclass visitedTable);

text AsGML(topogeometry tg, regclass visitedTable, text nsprefix);

text AsGML(topogeometry tg, text nsprefix_in, integer precision, integer options);

text AsGML(topogeometry tg, text nsprefix_in, integer precision, integer options, regclass visitedTable);

text AsGML(topogeometry tg, text nsprefix_in, integer precision, integer options, regclass visitedTable, text idprefix);

text AsGML(topogeometry tg, text nsprefix_in, integer precision, integer options, regclass visitedTable, text idprefix, int gmlversion);

説明

GML3の書式でTopoGeometryのGML表現を返します。nsprefix_inが指定されていない場合には、gmlが使われます。非修飾名前空間を得るにはnsprefixに空文字列を渡します。精度 (デフォルトは15)とoptions (デフォルトは1)パラメタは、与えられた場合には、裏で呼んでいるST_AsGMLにそのまま渡します。

visitedTableパラメタは、与えられた場合には、訪問したノード要素とエッジ要素のトラックを保持するために使われ、重複定義になるところで相互参照 (xlink:xref)を使います。テーブルは 整数カラムである'element_type'と'element_id'とを持つことを期待されます。この関数を呼び出したユーザは、このテーブルへの読み込み権限と書き込み権限とが必要です。効率よくするには、element_typeとelement_idに、この順序でインデクスを定義します。インデクスは一意制約をカラムに追加すると自動的に生成されます。例を示します。

CREATE TABLE visited (
  element_type integer, element_id integer,
  unique(element_type, element_id)
);

idprefixパラメタは、指定された場合には、Edgeタグ識別子とNodeタグ識別子の前に付きます。

gmlverパラメタは、指定された場合には、裏で呼んでいるST_AsGMLに渡されます。デフォルトは3です。

Availability: 2.0.0

ここではCreateTopoGeomで生成したTopoGeometryを使用しています。

SELECT topology.AsGML(topo) As rdgml
  FROM ri.roads
  WHERE road_name = 'Unknown';

-- rdgml--
<gml:TopoCurve>
    <gml:directedEdge>
        <gml:Edge gml:id="E1">
            <gml:directedNode orientation="-">
                <gml:Node gml:id="N1"/>
            </gml:directedNode>
            <gml:directedNode
></gml:directedNode>
            <gml:curveProperty>
                <gml:Curve srsName="urn:ogc:def:crs:EPSG::3438">
                    <gml:segments>
                        <gml:LineStringSegment>
                            <gml:posList srsDimension="2"
>384744 236928 384750 236923 384769 236911 384799 236895 384811 236890
                            384833 236884 384844 236882 384866 236881 384879 236883 384954 236898 385087 236932 385117 236938
                            385167 236938 385203 236941 385224 236946 385233 236950 385241 236956 385254 236971
                            385260 236979 385268 236999 385273 237018 385273 237037 385271 237047 385267 237057 385225 237125
                            385210 237144 385192 237161 385167 237192 385162 237202 385159 237214 385159 237227 385162 237241
                            385166 237256 385196 237324 385209 237345 385234 237375 385237 237383 385238 237399 385236 237407
                            385227 237419 385213 237430 385193 237439 385174 237451 385170 237455 385169 237460 385171 237475
                            385181 237503 385190 237521 385200 237533 385206 237538 385213 237541 385221 237542 385235 237540 385242 237541
                            385249 237544 385260 237555 385270 237570 385289 237584 385292 237589 385291 237596 385284 237630</gml:posList>
                        </gml:LineStringSegment>
                    </gml:segments>
                </gml:Curve>
            </gml:curveProperty>
        </gml:Edge>
    </gml:directedEdge>
</gml:TopoCurve
>

上の例から名前空間を取った例です。

SELECT topology.AsGML(topo,'') As rdgml
  FROM ri.roads
  WHERE road_name = 'Unknown';

-- rdgml--
<TopoCurve>
    <directedEdge>
        <Edge id="E1">
            <directedNode orientation="-">
                <Node id="N1"/>
            </directedNode>
            <directedNode
></directedNode>
            <curveProperty>
                <Curve srsName="urn:ogc:def:crs:EPSG::3438">
                    <segments>
                        <LineStringSegment>
                            <posList srsDimension="2"
>384744 236928 384750 236923 384769 236911 384799 236895 384811 236890
                            384833 236884 384844 236882 384866 236881 384879 236883 384954 236898 385087 236932 385117 236938
                            385167 236938 385203 236941 385224 236946 385233 236950 385241 236956 385254 236971
                            385260 236979 385268 236999 385273 237018 385273 237037 385271 237047 385267 237057 385225 237125
                            385210 237144 385192 237161 385167 237192 385162 237202 385159 237214 385159 237227 385162 237241
                            385166 237256 385196 237324 385209 237345 385234 237375 385237 237383 385238 237399 385236 237407
                            385227 237419 385213 237430 385193 237439 385174 237451 385170 237455 385169 237460 385171 237475
                            385181 237503 385190 237521 385200 237533 385206 237538 385213 237541 385221 237542 385235 237540 385242 237541
                            385249 237544 385260 237555 385270 237570 385289 237584 385292 237589 385291 237596 385284 237630</posList>
                         </LineStringSegment>
                    </segments>
                </Curve>
            </curveProperty>
        </Edge>
    </directedEdge>
</TopoCurve
>

Name

AsTopoJSON — opoGeometryのTopoJSON表現を返します。

Synopsis

text AsTopoJSON(topogeometry tg, regclass edgeMapTable);

説明

TopoGeometryのTopoJSON表現を返します。edgeMapTableがNULLでない場合には、エッジ識別番号とアーク添え字のルックアップと格納のマッピングに使われます。これは、最終的な文書内のコンパクトな"arcs"配列ができるようにするためです。

このテーブルは、与えられた場合には、"serial"型の"arc_id"カラムと整数型の"edge_id"とを持つことが期待されます。関数はこのテーブルに"edge_id"を問い合わせるので、このカラムにインデクスを追加することが推奨されます。

[Note]

TopoJSONでのアークのインデックスは0始まりですが、"edgeMapTable"テーブルでは1始まりです。

完全なTopoJSON文書は、この関数が返すスニペットだけでなく、実際のarcsメンバと、いくつかのヘッダを含む必要があります。 TopoJSON specificationをご覧ください。

Availability: 2.1.0

Enhanced: 2.2.1 点入力に対応するようになりました

関連情報

ST_AsGeoJSON

CREATE TEMP TABLE edgemap(arc_id serial, edge_id int unique);

-- ヘッダ
SELECT '{ "type": "Topology", "transform": { "scale": [1,1], "translate": [0,0] }, "objects": {'

-- オブジェクトn
UNION ALL SELECT '"' || feature_name || '": ' || AsTopoJSON(feature, 'edgemap')
FROM features.big_parcels WHERE feature_name = 'P3P4';

-- アーク
WITH edges AS (
  SELECT m.arc_id, e.geom FROM edgemap m, city_data.edge e
  WHERE e.edge_id = m.edge_id
), points AS (
  SELECT arc_id, (st_dumppoints(geom)).* FROM edges
), compare AS (
  SELECT p2.arc_id,
         CASE WHEN p1.path IS NULL THEN p2.geom
              ELSE ST_Translate(p2.geom, -ST_X(p1.geom), -ST_Y(p1.geom))
         END AS geom
  FROM points p2 LEFT OUTER JOIN points p1
  ON ( p1.arc_id = p2.arc_id AND p2.path[1] = p1.path[1]+1 )
  ORDER BY arc_id, p2.path
), arcsdump AS (
  SELECT arc_id, (regexp_matches( ST_AsGeoJSON(geom), '\[.*\]'))[1] as t
  FROM compare
), arcs AS (
  SELECT arc_id, '[' || array_to_string(array_agg(t), ',') || ']' as a FROM arcsdump
  GROUP BY arc_id
  ORDER BY arc_id
)
SELECT '}, "arcs": [' UNION ALL
SELECT array_to_string(array_agg(a), E',\n') from arcs

-- フッタ
UNION ALL SELECT ']}'::text as t;

-- 結果 --
{ "type": "Topology", "transform": { "scale": [1,1], "translate": [0,0] }, "objects": {
"P3P4": { "type": "MultiPolygon", "arcs": [[[-1]],[[6,5,-5,-4,-3,1]]]}
}, "arcs": [
 [[25,30],[6,0],[0,10],[-14,0],[0,-10],[8,0]],
 [[35,6],[0,8]],
 [[35,6],[12,0]],
 [[47,6],[0,8]],
 [[47,14],[0,8]],
 [[35,22],[12,0]],
 [[35,14],[0,8]]
 ]}

4.4.13. トポロジ空間関係関数

Abstract

本節では、TopoGeometryとトポロジプリミティブとの間の関係を見るトポロジ関数の一覧を挙げます。

Equals — 二つのTopoGeometryが同じトポロジプリミティブで成っている場合にtrueを返します。
Intersects — 二つのTopoGeometryからのプリミティブの組がインタセクトする場合にtrueを返します。

Name

Equals — 二つのTopoGeometryが同じトポロジプリミティブで成っている場合にtrueを返します。

Synopsis

boolean Equals(topogeometry tg1, topogeometry tg2);

説明

二つTopoGeometryが同じトポロジプリミティブで成っている場合にtrueを返します。

[Note]

この関数はジオメトリコレクションのTopoGeometryに対応していません。異なるトポロジからなるTopoGeometryとの比較もできません。

Availability: 1.1.0

This function supports 3d and will not drop the z-index.


Name

Intersects — 二つのTopoGeometryからのプリミティブの組がインタセクトする場合にtrueを返します。

Synopsis

boolean Intersects(topogeometry tg1, topogeometry tg2);

説明

二つのTopoGeometryからのプリミティブがインタセクトする場合にtrueを返します。

[Note]

この関数はジオメトリコレクションのTopoGeometryに対応していません。異なるトポロジからなるTopoGeometryとの比較もできません。また、現在のところ、階層TopoGeometry (他のTopoGeometryからなるTopoGeometry)に対応していません。

Availability: 1.1.0

This function supports 3d and will not drop the z-index.

関連情報

???

4.5. 住所標準化

これは、PAGC standardizerから分かれたものです (オリジナルのコードはPAGC PostgreSQL Address Standardizerにあります)。

住所標準化は単一行の住所のパーサで、入力に住所を取り、テーブルに保存された規則と、補助テーブルlex (lexicon, 語彙)およびgaz (gazetteer, 地名集)とを基に正規化します。

コードは、address_standardizerという名前の、1つのPostgreSQLエクステンションとしてビルドされます。CREATE EXTENSION address_standardizer;でインストールできます。address_standardizerエクステンションとともに、address_standardizer_data_usというサンプルデータのエクステンションがビルドされます。これには、アメリカのgaz, lexとrulesテーブルデータがあります。このエクステンションはCREATE EXTENSION address_standardizer_data_us;でインストールできます。

このエクステンションのコードはPostGISのextensions/address_standardizer内にあり、現在は自己充足しています。

インストール手順については、Section 2.3, “PAGC住所標準化ツールのインストールと使用”を参照してください。

4.5.1. パーサの動作

パーサは右から左に見ます。最初に郵便番号、州/県、市のMACRO (訳注: マクロ)要素を見ます。その後、番地または交差点もしくはランドマークを扱う場合には、MICRO (訳注: マイクロ)要素を見ます。現在は、国別コードや国名を見ませんが、将来的には導入できると思います。

国別コード

USまたはCAを仮定します。郵便番号か州/県で米国かカナダを分けますが、判別できない場合は米国とします。

郵便番号

Perl互換の正規表現を使用して認識します。正規表現は現在はparseaddress-api.cにあり、必要な際の変更は比較的簡単です。

州/県

Perl互換の正規表現を使用して認識します。正規表現は現在はparseaddress-api.cにありますが、将来的には、メンテナンスを簡単にするためにインクルードファイルに移動するかも知れません。

4.5.2. 住所標準化の型

Abstract

本節では住所標準化でインストールされたPostgreSQLデータ型の一覧を挙げます。独自関数をデザインする時に特に重要となるキャストの振る舞いを記述しています。

stdaddr — 住所の要素からなる複合型です。standardize_address関数が返す型です。

Name

stdaddr — 住所の要素からなる複合型です。standardize_address関数が返す型です。

説明

住所の要素からなる複合型です。standardize_address関数が返す型です。要素の記述のいくつかはPAGC Postal Attributesから借りています。

トークン番号は、規則テーブル内の出力参照番号を示します。

This method needs address_standardizer extension.

building

文字列 (トークン番号0): 建物番号や建物名を参照します。解析されていない建物識別子と型です。一般的に、ほとんどの住所では空白です。

house_num

文字列 (トークン番号1): ストリートの番号です。75 State Streetでは75にあたります。

predir

文字列 (トークン番号2): North, South, East, Westといった、ストリート名の方角前置語です。

qual

文字列 (トークン番号 3): ストリート名の修飾前置語です。3715 OLD HIGHWAY 99ではOLDにあたります。

pretype

文字列 (トークン番号 4): STREET PREFIX TYPE (ストリート名の前置詞の種別)

name

文字列 (トークン番号 5): ストリート名

suftype

文字列 (トークン番号 6): St, Ave, Cir等の、後置詞の種別。ストリート名に続いて記述されるものです。75 State StreetではSTREETが該当します。

sufdir

文字列 (トークン番号 7): ストリート名に続くNorth, South, East, Westといった、ストリート名の方角前置語です。3715 TENTH AVENUE WESTではWESTが該当します。

ruralroute

文字列 (トークン番号 8): RURAL ROUTE (地方集配路線)。RR 7では8が該当します。

extra

文字列: 階番号のような追加的情報です。

city

文字列 (トークン番号 10): 市名です。Boston等が該当します。

state

文字列 (トークン番号 11): 州名です。MASSACHUSETTSが該当します。

country

文字列 (トークン番号 12): 国名です。USAが該当します。

postcode

文字列 (トークン番号 13): 郵便番号 (POSTAL CODE, ZIP CODE)です。02109等です。

box

文字列 (トークン番号 1415): 私書箱番号です。02109等です。

unit

文字列 (トークン番号 17): 部屋番号です。APT 3B3Bが該当します。

4.5.3. 住所標準化テーブル

Abstract

本節では、住所標準化が住所の正規化に使うPostgreSQLテーブルの書式を挙げます。これらのテーブルはここで参照している名前と同じである必要はありません。例または独自ジオコーダのために、国ごとに異なるlex (lexicon, 語彙)、gaz (gazetteer, 地名集)およびrulesテーブルを持つことができます。これらのテーブルの名前は、住所標準化関数に渡されます。

同梱されているaddress_standardizer_data_usエクステンションには、米国の住所標準化のためのデータがあります。

規則テーブル — 規則テーブルには、住所入力順列トークンから標準化した出力順列への対応付けに関する規則の集合が入ります。それぞれの規則は、入力トークン、-1 (終端)、出力トークン、-1、規則の種類を示す数字、規則の階級、からなります。
lexテーブル — lexテーブルは英数字の入力をクラス分けして (a) 入力トークン (the section called “入力トークン” 参照)と (b) 標準化表現 とに関連付けます。
gaz table — gazテーブルは、地名を標準化し、入力と、(a)入力トークン (the section called “入力トークン”を参照して下さい)および (b) 標準化された表現とを関連付けるために使われます。

Name

規則テーブル — 規則テーブルには、住所入力順列トークンから標準化した出力順列への対応付けに関する規則の集合が入ります。それぞれの規則は、入力トークン、-1 (終端)、出力トークン、-1、規則の種類を示す数字、規則の階級、からなります。

説明

規則テーブルには、少なくとも次に示すカラムが必要です。それ以外にカラムを追加してもかまいません。

id

テーブルの主キー。

rule

規則を示す文字列フィールド。 PAGC Address Standardizer Rule recordsに詳細情報があります。

ruleには、入力トークンを表現する非負の整数、終端を示す-1、郵便属性を表現する非負の整数、終端を示す-1、規則種別を表現する整数、規則の階級を示す整数からなる集合が入ります。規則は0 (最低)から17 (最高)まであります。

たとえば、2 0 2 22 3 -1 5 5 6 7 3 -1 2 6は、TYPE NUMBER TYPE DIRECT QUALIFなる入力トークン順列が、STREET STREET SUFTYP SUFDIR QUALIFなる出力トークン順列に対応付けされ、規則はARC_Cで、階級は6となります。

対応する出力トークンはstdaddrに挙げています。

入力トークン

個々の規則は、入力トークン順列、終端を示す-1の順です。PAGC Input Tokensから引用した正当な入力トークンは次の通りです。

書式ベースの入力トークン

AMPERS

(13) アンパサンド (&)は、"and"という語を短縮するために、よく使われます

DASH

(9) 区切り記号。

DOUBLE

(21) 二つの文字の順列。しばしば識別子に用いられます。

FRACT

(25) ときどき"civic nunber"または"unit number" (訳注: 各戸に付けられる番号)で使われます。

MIXED

(23) 英数文字列。識別子に用います。

NUMBER

(0) 数字からなる文字列。

ORD

(15) "First"や"1st"といったものを表現する文字列。しばしばストリート名の中で使われています。

ORD

(18) 一つの文字

WORD

(1) 任意長を持つ文字列です。一つの文字はSINGLEおよびWORDの両方になりえます。

機能ベースの入力トークン

BOXH

(14) 私書箱を示すために使われる語です。たとえば BoxまたはPO Boxです。

BUILDH

(19) 建物またはその複合体を示すための語で、通常は前置語になります。たとえばTower 7AではTowerが該当します。

BUILDT

(24) 建物またはその複合体を示すために使われる語または略語で、通常は後置語になります。たとえばShopping Centreです。

DIRECT

(22) 方位を示す語です。たとえば Northです。

MILE

(20) 距離標の住所を示す語です。

ROAD

(6) 高速道路と道路を示す語または略語です。たとえばInterstate 5Interstateです。

RR

(8) 地方集配路線を示す語または略語です。たとえばRRです。

TYPE

(2) ストリート種別を示す語または略語です。たとえばSTAVEです。

UNITH

(16) 内部の部分住所を示す語または略語です。たとえばAPTUNITです。

郵便型入力トークン

QUINT

(28) 5桁の番号。ZIPコードです。

QUAD

(29) 4桁の番号。ZIP4です。

PCH

(27) 英数3文字の順列です。カナダの郵便番号の先頭3文字であるFSAを示します。

PCT

(26) 英数3文字の順列です。カナダの郵便番号の末尾3文字です。

ストップワード

STOPWORD (訳注: 処理対象外とする語)はWORDと結合します。規則で、複数のWORDとSTOPWORDの列は、単一のWORDトークンで表現されます。

STOPWORD

(7) 重要性が低い語で、パース時に省かれます。たとえばTHEが該当します。

出力トークン

1番目の-1 (終端)の後に、出力トークンが続き、その後に-1が続きます。対応する出力トークンの番号は、stdaddrに挙げています。許されるものは、規則の種類に依存します。それぞれの規則種別で有効なトークンはthe section called “規則種別と階級”に挙げています。

規則種別と階級

規則の最後の部分は規則種別で、次に挙げるものの一つが示すものです。この後には階級が続きます。規則は0 (最低) から17 (最高)までに階級付けされます。

MACRO_C

(トークン番号 = "0") PLACE STATE ZIPのようなMACRO節をパースするための規則のクラス。

MACRO_C出力トークン (http://www.pagcgeo.org/docs/html/pagc-12.html#--r-typ--からの引用)

CITY

(トークン番号 "10") たとえば"Albany" (訳注: ニューヨーク州の州都)等。

STATE

(トークン番号 "11") たとえば"NY" (訳注: ニューヨーク州)等。

NATION

(トークン番号 "12") ほとんどの参照ファイル内で使われない属性です。たとえば"USA"等。

POSTAL

(トークン番号 "13") (SADS elements "ZIP CODE" , "PLUS 4" ). 米国Zip (郵便番号)とカナダ郵便番号の両方で使われます。

MICRO_C

(トークン番号 = "1") 完全なMICRO節 (House, street, sufdir, predir, pretyp, suftype, qualif等)をパースするための規則のクラス (ARC_CとCIVIC_Cの和)。建物フェーズでは使われません。

MICRO_C 出力トークン (http://www.pagcgeo.org/docs/html/pagc-12.html#--r-typ--からの引用)

HOUSE

文字列 (トークン番号1): ストリートの番号です。75 State Streetでは75にあたります。

predir

文字列 (トークン番号2): North, South, East, Westといった、ストリート名の方角前置語です。

qual

文字列 (トークン番号 3): ストリート名の修飾前置語です。3715 OLD HIGHWAY 99ではOLDにあたります。

pretype

文字列 (トークン番号 4): STREET PREFIX TYPE (ストリート名の前置詞の種別)

street

文字列 (トークン番号 5): ストリート名

suftype

文字列 (トークン番号 6): St, Ave, Cir等の、後置詞の種別。ストリート名に続いて記述されるものです。75 State StreetではSTREETが該当します。

sufdir

文字列 (トークン番号 7): ストリート名に続くNorth, South, East, Westといった、ストリート名の方角前置語です。3715 TENTH AVENUE WESTではWESTが該当します。

ARC_C

(トークン番号 = "2") HOUSE属性を除いたMICRO節をパースするための規則のクラス。MICRO_CからHOUSEトークンを除いた出力トークン集合と同じです。

CIVIC_C

(トークン番号 = "3") HOUSE属性をパースするための規則のクラス。

EXTRA_C

(トークン番号 = "4") EXTRA属性 (ジオコーディングから除かれる属性)をパースするための規則のクラス。

EXTRA_C 出力トークン (http://www.pagcgeo.org/docs/html/pagc-12.html#--r-typ--からの引用)

BLDNG

(トークン番号 0): パースされていない建物識別子と種別。

BOXH

(トークン番号 14): BOX 3B内のBOXにあたります。

BOXT

(トークン番号 15): BOX 3B内の3Bにあたります。

RR

(トークン番号 8): RR 7内のRRにあたります。

UNITH

(トークン番号 16): APT 3B内のAPTにあたります。

UNITT

(トークン番号17): APT 3B内の3Bにあたります。

UNKNWN

(トークン番号9): その他分類対象外の出力。


Name

lexテーブル — lexテーブルは英数字の入力をクラス分けして (a) 入力トークン (the section called “入力トークン” 参照)と (b) 標準化表現 とに関連付けます。

説明

lex (lexiconの略語)テーブルは、英数入力を分類し、入力を (a) the section called “入力トークン”および (b) 標準化された表現、に関連付けます。

lexは少なくとも次のカラムを持ちます。追加できます。

id

テーブルの主キー。

seq

整数: 定義番号?

word

文字列: 入力単語

stdword

文字列: 正規化した置き換え語

token

整数: その語の種別。このコンテキストで使われる場合のみ置き換えられます。PAGC Tokensを参照して下さい。


Name

gaz table — gazテーブルは、地名を標準化し、入力と、(a)入力トークン (the section called “入力トークン”を参照して下さい)および (b) 標準化された表現とを関連付けるために使われます。

説明

gaz (gazeteerの略語)テーブルは、地名を分類し、入力を (a) the section called “入力トークン”および (b) 標準化された表現、に関連付けます。

gazテーブルは少なくとも次のカラムを持ちます。独自の目的のために追加することができます。

id

テーブルの主キー。

seq

整数: 定義番号? - 語のインスタンスに使われる識別子

word

文字列: 入力単語

stdword

文字列: 正規化した置き換え語

token

整数: その語の種別。このコンテキストで使われる場合のみ置き換えられます。PAGC Tokensを参照して下さい。

4.5.4. 住所標準化関数

parse_address — 1行の住所を取り、分割します。
standardize_address — lexテーブル、gazテーブルおよび規則テーブルを使って、入力住所をstdaddr形式で返します。

Name

parse_address — 1行の住所を取り、分割します。

Synopsis

record parse_address(text address);

説明

一つの住所を入力に取り、numstreetstreet2address1citystatezipzippluscountryからなるレコードを一つ返します。

初出: 2.2.0

This method needs address_standardizer extension.

単一の住所

SELECT num, street, city, zip, zipplus
        FROM parse_address('1 Devonshire Place, Boston, MA 02109-1234') AS a;
num |      street      |  city  |  zip  | zipplus
-----+------------------+--------+-------+---------
 1   | Devonshire Place | Boston | 02109 | 1234                

住所テーブル

-- 基本テーブル
CREATE TABLE places(addid serial PRIMARY KEY, address text);

INSERT INTO places(address)
VALUES ('529 Main Street, Boston MA, 02129'),
 ('77 Massachusetts Avenue, Cambridge, MA 02139'),
 ('25 Wizard of Oz, Walaford, KS 99912323'),
 ('26 Capen Street, Medford, MA'),
 ('124 Mount Auburn St, Cambridge, Massachusetts 02138'),
 ('950 Main Street, Worcester, MA 01610');

 -- 住所のパース
 -- 全てのフィールドで使う場合には (a).* が使えます
SELECT addid, (a).num, (a).street, (a).city, (a).state, (a).zip, (a).zipplus
FROM (SELECT addid, parse_address(address) As a
 FROM places) AS p;
addid | num |        street        |   city    | state |  zip  | zipplus
-------+-----+----------------------+-----------+-------+-------+---------
     1 | 529 | Main Street          | Boston    | MA    | 02129 |
     2 | 77  | Massachusetts Avenue | Cambridge | MA    | 02139 |
     3 | 25  | Wizard of Oz         | Walaford  | KS    | 99912 | 323
     4 | 26  | Capen Street         | Medford   | MA    |       |
     5 | 124 | Mount Auburn St      | Cambridge | MA    | 02138 |
     6 | 950 | Main Street          | Worcester | MA    | 01610 |
(6 rows)

関連情報


Name

standardize_address — lexテーブル、gazテーブルおよび規則テーブルを使って、入力住所をstdaddr形式で返します。

Synopsis

stdaddr standardize_address(text lextab, text gaztab, text rultab, text address);

stdaddr standardize_address(text lextab, text gaztab, text rultab, text micro, text macro);

説明

指定されたlexテーブルgaz tableおよび規則テーブルのテーブルを使って、入力住所をstdaddr形式で返します。

1番目の形式: 単一行で住所を取る形式です。

2番目の形式: 住所を二つの部分から取ります。microhouse_num street等のような、標準的な宛先書式の1行目です。macroは、city, state postal_code country等のような、標準的な宛先書式の2行目です。

初出: 2.2.0

This method needs address_standardizer extension.

address_standardizer_data_usエクステンションを使います。

CREATE EXTENSION address_standardizer_data_us; -- only needs to be done once

一つ目の版: 単一行住所。米国でない住所では十分に働きません。

SELECT house_num, name, suftype, city, country, state, unit  FROM standardize_address('us_lex',
                           'us_gaz', 'us_rules', 'One Devonshire Place, PH 301, Boston, MA 02109');
house_num |    name    | suftype |  city  | country |     state     |      unit
----------+------------+---------+--------+---------+---------------+-----------------
1         | DEVONSHIRE | PLACE   | BOSTON | USA     | MASSACHUSETTS | # PENTHOUSE 301

Tigerジオコーダに同梱されているテーブルを使います。この例はpostgis_tiger_geocoderをインストールしている場合のみ動作します。

SELECT *  FROM standardize_address('tiger.pagc_lex',
         'tiger.pagc_gaz', 'tiger.pagc_rules', 'One Devonshire Place, PH 301, Boston, MA 02109-1234');

読みやすくするために、hstoreエクステンションを使ってダウンぷします。必要なら CREATE EXTENSION hstore; を実行します。

SELECT (each(hstore(p))).*
 FROM standardize_address('tiger.pagc_lex', 'tiger.pagc_gaz',
   'tiger.pagc_rules', 'One Devonshire Place, PH 301, Boston, MA 02109') As p;
key     |      value
------------+-----------------
 box        |
 city       | BOSTON
 name       | DEVONSHIRE
 qual       |
 unit       | # PENTHOUSE 301
 extra      |
 state      | MA
 predir     |
 sufdir     |
 country    | USA
 pretype    |
 suftype    | PL
 building   |
 postcode   | 02109
 house_num  | 1
 ruralroute |
(16 rows)
                        

二つ目の形式: 二つの部分からなる住所

SELECT (each(hstore(p))).*
 FROM standardize_address('tiger.pagc_lex', 'tiger.pagc_gaz',
   'tiger.pagc_rules', 'One Devonshire Place, PH 301', 'Boston, MA 02109, US') As p;
key     |      value
------------+-----------------
 box        |
 city       | BOSTON
 name       | DEVONSHIRE
 qual       |
 unit       | # PENTHOUSE 301
 extra      |
 state      | MA
 predir     |
 sufdir     |
 country    | USA
 pretype    |
 suftype    | PL
 building   |
 postcode   | 02109
 house_num  | 1
 ruralroute |
(16 rows)

4.6. PostGIS追加機能

本章では、PostGISのソースアーカイブとソースレポジトリのextrasフォルダにある機能を記述します。 これらは必ずPostGISバイナリ版に同梱されているものではありませんが、通常は実行可能なplpgsqlベースのものまたは標準的なシェルスクリプトです。

4.6.1. Tigerジオコーダ

Abstract

米国国勢調査局が公開しているTIGER (Topologically Integrated Geographic Encoding and Referencing system ) / Line and Master Address database exportで動作するよう書かれた、PL/pgSQLベースのジオコーダです。

データローダ機能、住所正規化、住所ジオコーダおよび逆ジオコーダ、の四つの要素があります。

米国のための設計ですが、概念および機能の多くは適用可能で、他国の住所と道路ネットワークで動作するように適合させることができます (訳注: 日本の地名については未知です)。

Tiger関連の関数、道路型前置辞・道路型後置辞・州といった再利用可能な参照データ、データロード管理のための様々な制御テーブル、全てのロードされたテーブルが継承するスケルトンテーブル、を収容するためのtigerというスキーマが、スクリプトによって作成されます。

tiger_dataという、もう一つのスキーマが作られます。ここに、ローダが米国国勢調査サイトからダウンロードしてデータベースにロードした州ごとの全ての国勢調査データが収容されます。現在のモデルでは、州ごとのテーブルは、ma_addrma_edgesといったように名前の先頭に州コードを付けていて、州データのみに強制する制約が付いています。これらのテーブルはtiger schemaにあるaddr, faces, edges等から継承されています。

全てのジオコード関数は基底テーブルを参照するだけです。そのため、tiger_dataデータスキーマやそのデータを他のスキーマに分割できないという条件はありません。例えば、州ごとに異なるスキーマにしても、tiger内のテーブルから継承されているなら使用可能です。

お手持ちのデータベース内のエクステンションを有効にし、使用するデータをロードする方法については、Section 2.4.1, “TigerジオコーダをPostGISデータベースで有効にする: エクステンションを使用”を参照して下さい。

[Note]

Tigerジオコーダ (tiger_2010)を使っている場合には、extras/tiger内にあるupgrade_geocoder.bat / .sh を使ってアップグレードすることができます。tiger_2010tiger_2011以上での大きな変更点は、countyテーブルとstateテーブルが、stateごとに出現することがなくなっています。tiger_2010からのデータを持っていて、tiger_2015に置き換えたい場合には、Section 2.4.5, “Tigerジオコーダのアップグレード”を参照して下さい。

[Note]

PostGIS 2.2.0での新規機能は、Tiger 2015データに対応したことと、住所標準化がPostGISの一部に取り入れられたことです。

PostGIS 2.1.0での新規機能は、PostgreSQL 9.1以上では、TigerジオコーダをPostgreSQLエクステンションモデルでインストールすることができるようになったことです。詳細についてはSection 2.4.1, “TigerジオコーダをPostGISデータベースで有効にする: エクステンションを使用”を参照して下さい。

PostGISが用意しているNormalize_Addressの代替としてPagc_Normalize_Address文字列のストリート住所を与えると、道路後置辞、前置辞、標準タイプ、番地、ストリート名等を複数フィールドに分解して持つnorm_addy複合型を返します。この関数は、tiger_geocoder同梱のルックアップテーブルだけを使います (Tigerデータは不要です)。住所標準化エクステンションが必要です。関数があります。コンパイルとインストールの方法については、Section 2.3, “PAGC住所標準化ツールのインストールと使用”を参照して下さい。

設計:

このプロジェクトの目標は、任意の米国住所文字列を処理し、正規化したTiger国勢調査データを使ってポイントジオメトリを生成し、与えられた住所の位置や、位置のもっともらしさを反映した評価値を算出する、十分に実用的なジオコーダを構築することです。なお、評価値は高いほど悪い結果とします。

PostGIS 2.0.0で導入されたreverse_geocodeは、GPS位置のストリート住所と交差点を得るのに便利です。

ジオコーダは、PostGISに慣れている方ならだれでもインストールと使用が容易な程度に単純であるべきで、PostGISがサポートする全てのプラットフォームで簡便にインストール、使用ができるべきです。

書式や綴りの誤りがあっても確実に機能するための十分なロバスト性があるべきです。

将来のデータ更新が使えるか、最小のプログラムの変更で他のデータが使えるための十分な拡張性もあるべきです。

[Note]

関数が確実に動作するために、tigerスキーマは、データベース検索パスに追加されていなければなりません。

Drop_Indexes_Generate_Script — tigerスキーマとユーザが指定したスキーマ上の、全ての主キーでなく、かつユニークでないインデックスを削除します。スキーマを指定しない場合のデフォルトスキーマは、tiger_dataです。
Drop_Nation_Tables_Generate_Script — 指定したスキーマ内のテーブルのうち、county_all, state_allまたは、county or stateを削除するスクリプトを生成します。
Drop_State_Tables_Generate_Script — 指定したスキーマ内の、名前が州コードから始まるテーブルを全て削除するスクリプトを生成します。スキーマが指定されていない場合のデフォルトスキーマはtiger_dataです。
Geocode — 住所を文字列 (もしくは他の正規化された住所)として取り、可能性のある位置の集合を返します。返される集合の要素は、NAD 83経度緯度のポイントジオメトリ、正規化された住所と評価値を持ちます。評価値は低いほど可能性が高いことを示しています。結果は評価値の低い順に並べ替えられます。オプションにmax_result (最大結果数、デフォルトは10)とrestrict_region (制限領域、デフォルトはNULL)を渡すことができます。
Geocode_Intersection — インタセクトする二つのストリート、州コード、市名、郵便番号を引数に取り、最初の交差点の可能性のある位置の集合を出力します。geomoutにNAD83経度緯度のポイント、normalized_addressにそれぞれの位置、ratingに評価値がそれぞれ入ります。評価値が低いほど合致度が高くなります。結果は評価値の低い順にソートされます。最大結果数を渡すことができ、デフォルトは10です。Tigerデータ (エッジ、フェイス、住所)と、PostgreSQLあいまい文字列合致 (soundex, levenshtein)を使います。
Get_Geocode_Setting — tiger.geocode_settingsテーブルに格納されている設定のうち指定したものの値を返します。
Get_Tract — ジオメトリで指定した位置の米国国勢調査統計区またはtractテーブルのフィールドを返します。デフォルトでは、統計区の短縮名を返します。
Install_Missing_Indexes — ジオコーダで結合や検索条件に使われ、インデックスが付いていなキーカラムを持つ全てのテーブルを探し、インデックスを追加します。
Loader_Generate_Census_Script — 指定した州について、tract (統計区)、bg (block group, 細分区グループ)、tabblock (ブロック)をダウンロードし、tiger_dataに格納するための、指定したプラットフォーム用のシェルスクリプトを生成します。行ごとに州ごとのスクリプトが返されます。
Loader_Generate_Script — 指定したプラットフォーム用の、指定した州のTigerデータをダウンロードし、格納準備を行い、tiger_dataスキーマに格納するシェルスクリプトを生成します。行ごとに州ごとのスクリプトが返ります。最新版ではTiger 2010のデータ構造変更に対応していて、国勢統計区、細分区グループ、細分区 (tabblocks)テーブルをダウンロードすることができます。
Loader_Generate_Nation_Script — 指定したプラットフォーム用の、国と州のルックアップテーブルをロードするシェルスクリプトを生成します。
Missing_Indexes_Generate_Script — ジオコーダで結合に使われるキーカラムを持ち、インデックスが付いていないキーカラムを持つすべてのテーブルを検索し、インデックスを追加するSQLデータ定義言語を出力します。
Normalize_Address — 文字列で住所が与えられると、道路後置辞、前置辞、正規化された種別、番地、ストリート名等をフィールドに分けて持つnorm_addy複合型を返します。tiger_geocoderに同梱されているルックアップデータで動作します (Tigerデータ自体は不要です)。
Pagc_Normalize_Address文字列のストリート住所を与えると、道路後置辞、前置辞、標準タイプ、番地、ストリート名等を複数フィールドに分解して持つnorm_addy複合型を返します。この関数は、tiger_geocoder同梱のルックアップテーブルだけを使います (Tigerデータは不要です)。住所標準化エクステンションが必要です。 — 文字列のストリート住所を与えると、道路後置辞、前置辞、標準タイプ、番地、ストリート名等を複数フィールドに分解して持つnorm_addy複合型を返します。この関数は、tiger_geocoder同梱のルックアップテーブルだけを使います (Tigerデータは不要です)。住所標準化エクステンションが必要です。
Pprint_Addynorm_addy複合型オブジェクトを与えると、印刷表現を返します。通常はnormalize_addressと併用します。
Reverse_Geocode — 登録されている空間参照系に基づくポイントジオメトリを引数に取り、理論的に可能性のある住所の配列と交差するストリートの配列を一つのレコードで返します。include_strnum_range = trueの場合には、交差するストリートに番地範囲を追加します。
Topology_Load_Tiger — Tigerデータの定義領域をPostGISトポロジにロードして、Tigerデータをトポロジの空間参照系に投影変換し、トポロジの許容精度にスナップします。
Set_Geocode_Setting — ジオコーダ関数の振る舞いに影響を与える設定を行います。

PostGIS用の二つのオープンソースジオコーダがあります。これらはTigerジオコーダと違い、他国のジオコーディングに対応している利点があります。

  • Nominatimは、OpenStreetMapの地名集データを使います。データのロードにはosm2pgsqlが必要です。PostgreSQL 8.4以上とPostGIS 1.5以上が必要です。Webサービスのインタフェースとして作られていて、Webサービスと呼ばれるような設計に見えます。Tigerジオコーダと同じように、ジオコーダと逆ジオコーダの要素を持ちます。文書からでは、Tigerジオコーダのような純粋なSQLインタフェースを持っているのか、多くの処理がWebインタフェースに実装されているのか、は明確ではありません。

  • GIS Graphyも、PostGISを使用したもので、NominatimのようにOpenStreetMap (OSM)データを使用します。OSMデータのロードを行うローダとNominatimのように米国だけでなくジオコーディングを行う能力があります。Nominatimとよく似ていて、Webサービスとして動作し、Java 1.5、サーブレットアプリケーション、Apache Solrに依存しています。GisGraphyは、複数プラットフォームで動作し、他の機能の中には逆ジオコーダがあります。

Name

Drop_Indexes_Generate_Script — tigerスキーマとユーザが指定したスキーマ上の、全ての主キーでなく、かつユニークでないインデックスを削除します。スキーマを指定しない場合のデフォルトスキーマは、tiger_dataです。

Synopsis

text Drop_Indexes_Generate_Script(text param_schema=tiger_data);

説明

tigerスキーマとユーザが指定したスキーマ上の、全ての主キーでなく、かつユニークでないインデックスを削除します。スキーマを指定しない場合のデフォルトスキーマは、tiger_dataです。

PostgreSQLのクエリプランナを混乱させる可能性があり、不要なディスク容量を取る、インデックスの膨張を最小化するために使います。ジオコーダで使われるインデックスを追加する関数Install_Missing_Indexesを併用します。

Availability: 2.0.0

SELECT drop_indexes_generate_script() As actionsql;
actionsql
---------------------------------------------------------
DROP INDEX tiger.idx_tiger_countysub_lookup_lower_name;
DROP INDEX tiger.idx_tiger_edges_countyfp;
DROP INDEX tiger.idx_tiger_faces_countyfp;
DROP INDEX tiger.tiger_place_the_geom_gist;
DROP INDEX tiger.tiger_edges_the_geom_gist;
DROP INDEX tiger.tiger_state_the_geom_gist;
DROP INDEX tiger.idx_tiger_addr_least_address;
DROP INDEX tiger.idx_tiger_addr_tlid;
DROP INDEX tiger.idx_tiger_addr_zip;
DROP INDEX tiger.idx_tiger_county_countyfp;
DROP INDEX tiger.idx_tiger_county_lookup_lower_name;
DROP INDEX tiger.idx_tiger_county_lookup_snd_name;
DROP INDEX tiger.idx_tiger_county_lower_name;
DROP INDEX tiger.idx_tiger_county_snd_name;
DROP INDEX tiger.idx_tiger_county_the_geom_gist;
DROP INDEX tiger.idx_tiger_countysub_lookup_snd_name;
DROP INDEX tiger.idx_tiger_cousub_countyfp;
DROP INDEX tiger.idx_tiger_cousub_cousubfp;
DROP INDEX tiger.idx_tiger_cousub_lower_name;
DROP INDEX tiger.idx_tiger_cousub_snd_name;
DROP INDEX tiger.idx_tiger_cousub_the_geom_gist;
DROP INDEX tiger_data.idx_tiger_data_ma_addr_least_address;
DROP INDEX tiger_data.idx_tiger_data_ma_addr_tlid;
DROP INDEX tiger_data.idx_tiger_data_ma_addr_zip;
DROP INDEX tiger_data.idx_tiger_data_ma_county_countyfp;
DROP INDEX tiger_data.idx_tiger_data_ma_county_lookup_lower_name;
DROP INDEX tiger_data.idx_tiger_data_ma_county_lookup_snd_name;
DROP INDEX tiger_data.idx_tiger_data_ma_county_lower_name;
DROP INDEX tiger_data.idx_tiger_data_ma_county_snd_name;
:
:

Name

Drop_Nation_Tables_Generate_Script — 指定したスキーマ内のテーブルのうち、county_all, state_allまたは、county or stateを削除するスクリプトを生成します。

Synopsis

text Drop_Nation_Tables_Generate_Script(text param_schema=tiger_data);

説明

指定したスキーマ内のテーブルのうち、名前がcounty_allstate_all(州コード)_county(州コード)_stateで始まるテーブルを全て削除するスクリプトを生成します。 tiger_2010データからtiger_2011データに更新する際に必要です。

Availability: 2.1.0

SELECT drop_nation_tables_generate_script();
DROP TABLE tiger_data.county_all;
DROP TABLE tiger_data.county_all_lookup;
DROP TABLE tiger_data.state_all;
DROP TABLE tiger_data.ma_county;
DROP TABLE tiger_data.ma_state;

Name

Drop_State_Tables_Generate_Script — 指定したスキーマ内の、名前が州コードから始まるテーブルを全て削除するスクリプトを生成します。スキーマが指定されていない場合のデフォルトスキーマはtiger_dataです。

Synopsis

text Drop_State_Tables_Generate_Script(text param_state, text param_schema=tiger_data);

説明

指定したスキーマ内の、名前が州コードから始まるテーブルを全て削除するスクリプトを生成します。スキーマが指定されていない場合のデフォルトスキーマはtiger_dataです。ある州の以前のデータのロードがうまくいかずに再ロードする際に使います。

Availability: 2.0.0

SELECT drop_state_tables_generate_script('PA');
DROP TABLE tiger_data.pa_addr;
DROP TABLE tiger_data.pa_county;
DROP TABLE tiger_data.pa_county_lookup;
DROP TABLE tiger_data.pa_cousub;
DROP TABLE tiger_data.pa_edges;
DROP TABLE tiger_data.pa_faces;
DROP TABLE tiger_data.pa_featnames;
DROP TABLE tiger_data.pa_place;
DROP TABLE tiger_data.pa_state;
DROP TABLE tiger_data.pa_zip_lookup_base;
DROP TABLE tiger_data.pa_zip_state;
DROP TABLE tiger_data.pa_zip_state_loc;
        

Name

Geocode — 住所を文字列 (もしくは他の正規化された住所)として取り、可能性のある位置の集合を返します。返される集合の要素は、NAD 83経度緯度のポイントジオメトリ、正規化された住所と評価値を持ちます。評価値は低いほど可能性が高いことを示しています。結果は評価値の低い順に並べ替えられます。オプションにmax_result (最大結果数、デフォルトは10)とrestrict_region (制限領域、デフォルトはNULL)を渡すことができます。

Synopsis

setof record geocode(varchar address, integer max_results=10, geometry restrict_region=NULL, norm_addy OUT addy, geometry OUT geomout, integer OUT rating);

setof record geocode(norm_addy in_addy, integer max_results=10, geometry restrict_region=NULL, norm_addy OUT addy, geometry OUT geomout, integer OUT rating);

説明

文字列住所 (または正規化された住所)を引数に取り、NAD 83経度緯度のポイントジオメトリ (geomout)、個々のnormalized_address (addy)、評価値 (rating)からなる、可能性のある位置の集合を出力します。評価値が低いほど合致度が高くなります。Tigerデータ (エッジ、フェイス、住所)、PostgreSQLあいまい文字列合致 (soundex,levenshtein)を使い、Tigerデータのエッジに沿った住所の補間のためにPostGIS線補間関数を使用っています。評価値が高いほどジオコードの正確度が低くなります。ジオコードされたポイントは、ストリート住所を中心線から左/右に移動しますが、デフォルトでは10メートルです。

Enhanced: 2.0.0 Tiger 2010構造のデータに対応しました。実行速度とジオコーディング精度を改善し、ストリート住所の位置を中心線から側線に移動するための改訂を行いました。また、良い結果の数を指定したり、最も良い結果だけを返すようにするのに使う新しいパラメータmax_resultsを導入しました。

例: 基本

下の例は、3.0GHzの単一プロセッサと2GBのメモリを持つWindows 7機で、PostgreSQL 9.1rc1/PostGIS 2.0を走らせて、MA, MN, CA, RI の各州のTigerデータをロードしたものです。

完全一致は速いです (61ミリ秒)

SELECT g.rating, ST_X(g.geomout) As lon, ST_Y(g.geomout) As lat,
    (addy).address As stno, (addy).streetname As street,
    (addy).streettypeabbrev As styp, (addy).location As city, (addy).stateabbrev As st,(addy).zip
    FROM geocode('75 State Street, Boston MA 02109') As g;
 rating |        lon        |       lat        | stno | street | styp |  city  | st |  zip
--------+-------------------+------------------+------+--------+------+--------+----+-------
      0 | -71.0556722990239 | 42.3589914927049 |   75 | State  | St   | Boston | MA | 02109

郵便番号を渡さない場合でも推測可能です (122-150ミリ秒かかりました)

SELECT g.rating, ST_AsText(ST_SnapToGrid(g.geomout,0.00001)) As wktlonlat,
    (addy).address As stno, (addy).streetname As street,
    (addy).streettypeabbrev As styp, (addy).location As city, (addy).stateabbrev As st,(addy).zip
    FROM geocode('226 Hanover Street, Boston, MA',1) As g;
 rating |         wktlonlat         | stno | street  | styp |  city  | st |  zip
--------+---------------------------+------+---------+------+--------+----+-------
      1 | POINT(-71.05528 42.36316) |  226 | Hanover | St   | Boston | MA | 02113

綴りの誤りを処理して、一つ以上の可能性のある答を評価値付きで提供すると遅くなります (500ミリ秒)。

SELECT g.rating, ST_AsText(ST_SnapToGrid(g.geomout,0.00001)) As wktlonlat,
    (addy).address As stno, (addy).streetname As street,
    (addy).streettypeabbrev As styp, (addy).location As city, (addy).stateabbrev As st,(addy).zip
    FROM geocode('31 - 37 Stewart Street, Boston, MA 02116') As g;
 rating |         wktlonlat         | stno | street | styp |  city  | st |  zip
--------+---------------------------+------+--------+------+--------+----+-------
     70 | POINT(-71.06459 42.35113) |   31 | Stuart | St   | Boston | MA | 02116
    

複数住所のジオコードバッチ処理を行います。max_results=1とすると最も簡単です。まだジオコードを行っていない (評価値が無い)もののみ処理します。

CREATE TABLE addresses_to_geocode(addid serial PRIMARY KEY, address text,
        lon numeric, lat numeric, new_address text, rating integer);

INSERT INTO addresses_to_geocode(address)
VALUES ('529 Main Street, Boston MA, 02129'),
 ('77 Massachusetts Avenue, Cambridge, MA 02139'),
 ('25 Wizard of Oz, Walaford, KS 99912323'),
 ('26 Capen Street, Medford, MA'),
 ('124 Mount Auburn St, Cambridge, Massachusetts 02138'),
 ('950 Main Street, Worcester, MA 01610');

-- 全体のジオコードでは、必ず最後に一度コミットが行われます。
-- 多数の住所があって、一度に全てを更新したくない場合として、
-- 最初の三つのアドレスだけ更新します。
-- (323-704ミリ秒 - キャッシュと共有メモリがあるので、最初のジオコーディングは必ず遅くなります)
-- この例では、間違った住所の逆ジオコーディングをしなよう、
-- LEFT JOINで再結合して、合致しないものには-1の評価値を設定しています。
UPDATE addresses_to_geocode
  SET  (rating, new_address, lon, lat)
    = ( COALESCE((g.geo).rating,-1), pprint_addy((g.geo).addy),
       ST_X((g.geo).geomout)::numeric(8,5), ST_Y((g.geo).geomout)::numeric(8,5) )
FROM (SELECT addid
    FROM addresses_to_geocode
    WHERE rating IS NULL ORDER BY addid LIMIT 3) As a
    LEFT JOIN (SELECT addid, (geocode(address,1)) As geo
    FROM addresses_to_geocode As ag
    WHERE ag.rating IS NULL ORDER BY addid LIMIT 3) As g ON a.addid = g.addid
WHERE a.addid = addresses_to_geocode.addid;

結果
-----
Query returned successfully: 3 rows affected, 480 ms execution time.

SELECT * FROM addresses_to_geocode WHERE rating is not null;

 addid |                   address                    |    lon    |   lat    |                new_address                | rating
-------+----------------------------------------------+-----------+----------+-------------------------------------------+--------
     1 | 529 Main Street, Boston MA, 02129            | -71.07181 | 42.38359 | 529 Main St, Boston, MA 02129             |      0
     2 | 77 Massachusetts Avenue, Cambridge, MA 02139 | -71.09428 | 42.35988 | 77 Massachusetts Ave, Cambridge, MA 02139 |      0
     3 | 25 Wizard of Oz, Walaford, KS 99912323       |           |          |                                           |     -1

例: ジオメトリフィルタの使用

SELECT g.rating, ST_AsText(ST_SnapToGrid(g.geomout,0.00001)) As wktlonlat,
    (addy).address As stno, (addy).streetname As street,
    (addy).streettypeabbrev As styp,
    (addy).location As city, (addy).stateabbrev As st,(addy).zip
  FROM geocode('100 Federal Street, MA',
        3,
        (SELECT ST_Union(the_geom)
            FROM place WHERE statefp = '25' AND name = 'Lynn')::geometry
        ) As g;

 rating |        wktlonlat         | stno | street  | styp | city | st |  zip
--------+--------------------------+------+---------+------+------+----+-------
      8 | POINT(-70.96796 42.4659) |  100 | Federal | St   | Lynn | MA | 01905
Total query runtime: 245 ms.
          

Name

Geocode_Intersection — インタセクトする二つのストリート、州コード、市名、郵便番号を引数に取り、最初の交差点の可能性のある位置の集合を出力します。geomoutにNAD83経度緯度のポイント、normalized_addressにそれぞれの位置、ratingに評価値がそれぞれ入ります。評価値が低いほど合致度が高くなります。結果は評価値の低い順にソートされます。最大結果数を渡すことができ、デフォルトは10です。Tigerデータ (エッジ、フェイス、住所)と、PostgreSQLあいまい文字列合致 (soundex, levenshtein)を使います。

Synopsis

setof record geocode_intersection(text roadway1, text roadway2, text in_state, text in_city, text in_zip, integer max_results=10, norm_addy OUT addy, geometry OUT geomout, integer OUT rating);

説明

インタセクトする二つのストリート、州コード、市名、郵便番号を引数に取り、最初の交差点の可能性のある位置の集合を出力します。集合の要素は、NAD83経度緯度のポイント、正規化された住所、評価値を持ちます。評価値が低いほど合致度が高くなります。結果は評価値の低い順にソートされます。最大結果数を渡すことができ、デフォルトは10です。normalized_address (addy)、NAD83経度緯度のポイントとしてgeomout、評価値としてratingを返します。評価値が低いほど合致度が高くなります。結果は評価値の低い順にソートされます。Tigerデータ (エッジ、フェイス、住所)と、PostgreSQLあいまい文字列合致 (soundex, levenshtein)を使います。

Availability: 2.0.0

例: 基本

下の例では、3.0GHz単一プロセッサで2GBメモリのWindows 7機上でPostgreSQL 9.0/PostGIS 1.5を走らせ、マサチューセッツ州のTigerデータをロードしています。この場合は、少し遅いです (3000ミリ秒)。

Windows 2003 64ビット 8GBでPostGIS 2.0、PostgreSQL 64ビット版を動かし、Tiger 2011データがロードされている場合もテストしています (41ミリ秒)。

SELECT pprint_addy(addy), st_astext(geomout),rating
            FROM geocode_intersection( 'Haverford St','Germania St', 'MA', 'Boston', '02130',1);
           pprint_addy            |         st_astext          | rating
----------------------------------+----------------------------+--------
98 Haverford St, Boston, MA 02130 | POINT(-71.101375 42.31376) |      0

郵便番号をジオコーダに渡さない場合でも動作し、Windows 2003 64ビットで741ミリ秒でした(Windows 7機で3500ミリ秒)。

SELECT pprint_addy(addy), st_astext(geomout),rating
                FROM geocode_intersection('Weld', 'School', 'MA', 'Boston');
          pprint_addy          |        st_astext         | rating
-------------------------------+--------------------------+--------
 98 Weld Ave, Boston, MA 02119 | POINT(-71.099 42.314234) |      3
 99 Weld Ave, Boston, MA 02119 | POINT(-71.099 42.314234) |      3

Name

Get_Geocode_Setting — tiger.geocode_settingsテーブルに格納されている設定のうち指定したものの値を返します。

Synopsis

text Get_Geocode_Setting(text setting_name);

説明

tiger.geocode_settingsテーブルに格納されている設定のうち指定したものの値を返します。設定によって、関数のデバッグの制御が可能です。今後の予定では、評価値の制御ができるようにします。現在の設定は次の通りです。

name              | setting |  unit   | category  |                                                             short_desc
--------------------------------+---------+---------+-----------+------------------------------------------------------------------------------------------------------------------------------
 debug_geocode_address          | false   | boolean | debug     | trueの場合には、geocode_addressが呼ばれた時に、クエリ等のデバッグ情報をNOTICEログに出力します
 debug_geocode_intersection     | false   | boolean | debug     | trueの場合には、geocode_intersectionが呼ばれた時に、クエリ等のデバッグ情報をNOTICEログに出力します
 debug_normalize_address        | false   | boolean | debug     | trueの場合には、normalize_addressが呼ばれた時に、クエリや中間表現等のデバッグ情報をNOTICEログに出力します
 debug_reverse_geocode          | false   | boolean | debug     | trueの場合には、reverse_geocodeが呼ばれた時に、クエリや中間表現等のデバッグ情報をNOTICEログに出力します
 reverse_geocode_numbered_roads | 0       | integer | rating    | 州道名と郡道名について、0-どの名前でもよい、1-道路番号優先、2-州/郡名優先
 use_pagc_address_parser        | false   | boolean | normalize | trueの場合には、address_standardizer (pagc_normalize_address経由)を使おうと試みます。    

Changed: 2.2.0 : デフォルト設定をgeocode_settingsに保存するようにしました。ユーザが設定したものだけがgeocode_settings内にあります。

Availability: 2.1.0

デバッグ設定を返す例

SELECT get_geocode_setting('debug_geocode_address) As result;
result
---------
false
        

Name

Get_Tract — ジオメトリで指定した位置の米国国勢調査統計区またはtractテーブルのフィールドを返します。デフォルトでは、統計区の短縮名を返します。

Synopsis

text get_tract(geometry loc_geom, text output_field=name);

説明

ジオメトリを与えると、ジオメトリの位置の米国国勢調査統計区を返します。空間参照系を指定しない場合には、NAD83経度緯度と仮定します。

[Note]

This function uses the census tract whic is not loaded by default. If you have already loaded your state table, you can load tract as well as bg, and tabblock using the Loader_Generate_Census_Script script.

If you have not loaded your state data yet and want these additional tables loaded, do the following

UPDATE tiger.loader_lookuptables SET load = true WHERE load = false AND lookup_name IN('tract', 'bg', 'tabblock');

, Missing_Indexes_Generate_Script

Availability: 2.0.0

例: 基本

SELECT get_tract(ST_Point(-71.101375, 42.31376) ) As tract_name;
tract_name
---------
1203.01
        
-- Tigerの地理識別子を返します
SELECT get_tract(ST_Point(-71.101375, 42.31376), 'tract_id' ) As tract_id;
tract_id
---------
25025120301

関連情報

Geocode >


Name

Install_Missing_Indexes — ジオコーダで結合や検索条件に使われ、インデックスが付いていなキーカラムを持つ全てのテーブルを探し、インデックスを追加します。

Synopsis

boolean Install_Missing_Indexes();

説明

ジオコーダで結合や検索条件に使われ、インデックスが付いていなキーカラムを持つ、tigerスキーマとtiger_dataスキーマ内の全てのテーブルを探し、これらのテーブルにインデックスを追加するためのSQLデータ定義言語を出力し、実行します。これは、クエリの動作速度を上げるのに必要であるのにロード処理で失われたインデックスを追加するのを助ける関数です。インデックス追加スクリプトの生成と実行を行うMissing_Indexes_Generate_Scriptの仲間です。この関数はupdate_geocode.sql更新スクリプトの一部として呼ばれます。

Availability: 2.0.0

SELECT install_missing_indexes();
         install_missing_indexes
-------------------------
 t
        

Name

Loader_Generate_Census_Script — 指定した州について、tract (統計区)、bg (block group, 細分区グループ)、tabblock (ブロック)をダウンロードし、tiger_dataに格納するための、指定したプラットフォーム用のシェルスクリプトを生成します。行ごとに州ごとのスクリプトが返されます。

Synopsis

setof text loader_generate_census_script(text[] param_states, text os);

説明

指定した州について、tract (統計区)、bg (block group, 細分区グループ)、tabblock (ブロック)をダウンロードし、tiger_dataに格納するための、指定したプラットフォーム用のシェルスクリプトを生成します。行ごとに州ごとのスクリプトが返されます。

ダウンロードには、Linuxではunzip (Windowsのデフォルトは7-zip)とwgetとを使います。データの格納にはSection 4.1.4.2, “shp2pgsql: ESRIシェープファイルローダを使う”を使います。最小単位は州全体です。生成されるスクリプトは、格納準備中の一時フォルダ内にあるファイルのみ処理します。

プロセスの制御や異なるOSのシェルの書式の制御のために、次の制御テーブルを使います。

  1. loader_variables 国勢調査ダウンロードサイト、年度、データと準備スキーマといった種々の変数の軌跡を保持します。

  2. loader_platform 種々のプラットフォームのプロファイルと種々の実行ファイルを置いてある位置です。windowsとLinux/unixを備えています。追加も可能です。

  3. レコードごとにテーブルの種類 (州、国)、レコード処理の有無、ロード方法を定義しています。データインポート方法、データ格納準備、カラム追加、カラム削除、インデックス、制約がそれぞれで定義されています。個々のテーブルは、名前の先頭に州コードを持ち、tigerスキーマのテーブルから継承されています。たとえば、tiger.facesから継承されたtiger_data.ma_facesする、といったことが行われます。

Availability: 2.0.0

[Note]

Loader_Generate_Script は、このロジックを含んでいますが、PostGIS 2.0.0 alpha 5より前にTigerジオコーダをインストールしてLoader_Generate_Scriptを実行した場合には、これを実行する必要があります。

Windowsシェルスクリプト書式での選択した州のデータをロードするスクリプトの生成。

SELECT loader_generate_census_script(ARRAY['MA'], 'windows');
-- 結果 --
set STATEDIR="\gisdata\www2.census.gov\geo\pvs\tiger2010st\25_Massachusetts"
set TMPDIR=\gisdata\temp\
set UNZIPTOOL="C:\Program Files\7-Zip\7z.exe"
set WGETTOOL="C:\wget\wget.exe"
set PGBIN=C:\projects\pg\pg91win\bin\
set PGPORT=5432
set PGHOST=localhost
set PGUSER=postgres
set PGPASSWORD=yourpasswordhere
set PGDATABASE=tiger_postgis20
set PSQL="%PGBIN%psql"
set SHP2PGSQL="%PGBIN%shp2pgsql"
cd \gisdata

%WGETTOOL% http://www2.census.gov/geo/pvs/tiger2010st/25_Massachusetts/25/ --no-parent --relative --accept=*bg10.zip,*tract10.zip,*tabblock10.zip --mirror --reject=html
del %TMPDIR%\*.* /Q
%PSQL% -c "DROP SCHEMA tiger_staging CASCADE;"
%PSQL% -c "CREATE SCHEMA tiger_staging;"
cd %STATEDIR%
for /r %%z in (*.zip) do %UNZIPTOOL% e %%z  -o%TMPDIR%
cd %TMPDIR%
%PSQL% -c "CREATE TABLE tiger_data.MA_tract(CONSTRAINT pk_MA_tract PRIMARY KEY (tract_id) ) INHERITS(tiger.tract); "
%SHP2PGSQL% -c -s 4269 -g the_geom   -W "latin1" tl_2010_25_tract10.dbf tiger_staging.ma_tract10 | %PSQL%
%PSQL% -c "ALTER TABLE tiger_staging.MA_tract10 RENAME geoid10 TO tract_id;  SELECT loader_load_staged_data(lower('MA_tract10'), lower('MA_tract')); "
%PSQL% -c "CREATE INDEX tiger_data_MA_tract_the_geom_gist ON tiger_data.MA_tract USING gist(the_geom);"
%PSQL% -c "VACUUM ANALYZE tiger_data.MA_tract;"
%PSQL% -c "ALTER TABLE tiger_data.MA_tract ADD CONSTRAINT chk_statefp CHECK (statefp = '25');"
: 

shスクリプトの生成

STATEDIR="/gisdata/www2.census.gov/geo/pvs/tiger2010st/25_Massachusetts"
TMPDIR="/gisdata/temp/"
UNZIPTOOL=unzip
WGETTOOL="/usr/bin/wget"
export PGBIN=/usr/pgsql-9.0/bin
export PGPORT=5432
export PGHOST=localhost
export PGUSER=postgres
export PGPASSWORD=yourpasswordhere
export PGDATABASE=geocoder
PSQL=${PGBIN}/psql
SHP2PGSQL=${PGBIN}/shp2pgsql
cd /gisdata

wget http://www2.census.gov/geo/pvs/tiger2010st/25_Massachusetts/25/ --no-parent --relative --accept=*bg10.zip,*tract10.zip,*tabblock10.zip --mirror --reject=html
rm -f ${TMPDIR}/*.*
${PSQL} -c "DROP SCHEMA tiger_staging CASCADE;"
${PSQL} -c "CREATE SCHEMA tiger_staging;"
cd $STATEDIR
for z in *.zip; do $UNZIPTOOL -o -d $TMPDIR $z; done
:
: 

Name

Loader_Generate_Script — 指定したプラットフォーム用の、指定した州のTigerデータをダウンロードし、格納準備を行い、tiger_dataスキーマに格納するシェルスクリプトを生成します。行ごとに州ごとのスクリプトが返ります。最新版ではTiger 2010のデータ構造変更に対応していて、国勢統計区、細分区グループ、細分区 (tabblocks)テーブルをダウンロードすることができます。

Synopsis

setof text loader_generate_script(text[] param_states, text os);

説明

指定したプラットフォーム用の、指定した州のTigerデータをダウンロードし、格納準備を行い、tiger_dataスキーマに格納するシェルスクリプトを生成します。行ごとに州ごとのスクリプトが返ります。

ダウンロードには、Linuxではunzip (Windowsのデフォルトは7-zip)とwgetとを使います。データの格納にはSection 4.1.4.2, “shp2pgsql: ESRIシェープファイルローダを使う”を使います。ダウンロードの最小単位は州全体ですが、ファイルを手動でダウンロードすることで上書きできます。生成されるスクリプトは、格納準備中の一時フォルダ内にあるファイルのみ処理します。

プロセスの制御や異なるOSのシェルの書式の制御のために、次の制御テーブルを使います。

  1. loader_variables 国勢調査ダウンロードサイト、年度、データと準備スキーマといった種々の変数の軌跡を保持します。

  2. loader_platform 種々のプラットフォームのプロファイルと種々の実行ファイルを置いてある位置です。windowsとLinux/unixを備えています。追加も可能です。

  3. レコードごとにテーブルの種類 (州、国)、レコード処理の有無、ロード方法を定義しています。データインポート方法、データ格納準備、カラム追加、カラム削除、インデックス、制約がそれぞれで定義されています。個々のテーブルは、名前の先頭に州コードを持ち、tigerスキーマのテーブルから継承されています。たとえば、tiger.facesから継承されたtiger_data.ma_facesする、といったことが行われます。

Availability: 2.0.0 Tiger 2010構造のデータに対応しました。国勢統計区 (tract)、細分区グループ ("block groups", bg)、細分区 (tabblocks)テーブルをダウンロードします。

[Note]

If you are using pgAdmin 3, be warned that by default pgAdmin 3 truncates long text. To fix, change File -> Options -> Query Tool -> Query Editor - > Max. characters per column to larger than 50000 characters.

Using psql where gistest is your database and /gisdata/data_load.sh is the file to create with the shell commands to run.

psql -U postgres -h localhost -d gistest -A -t \
 -c "SELECT Loader_Generate_Script(ARRAY['MA'], 'gistest')" > /gisdata/data_load.sh;

Windowsシェルスクリプト書式で二つの州のデータをロードするスクリプトを生成します。

SELECT loader_generate_script(ARRAY['MA','RI'], 'windows') AS result;
-- 結果 --
set STATEDIR="\gisdata\www2.census.gov\geo\pvs\tiger2010st\44_Rhode_Island"
set TMPDIR=\gisdata\temp\
set UNZIPTOOL="C:\Program Files\7-Zip\7z.exe"
set WGETTOOL="C:\wget\wget.exe"
set PGBIN=C:\Program Files\PostgreSQL\8.4\bin\
set PGPORT=5432
set PGHOST=localhost
set PGUSER=postgres
set PGPASSWORD=yourpasswordhere
set PGDATABASE=geocoder
set PSQL="%PGBIN%psql"
set SHP2PGSQL="%PGBIN%shp2pgsql"

%WGETTOOL% http://www2.census.gov/geo/pvs/tiger2010st/44_Rhode_Island/ --no-parent --relative --recursive --level=2 --accept=zip,txt --mirror --reject=html
:
:

shスクリプトの生成

SELECT loader_generate_script(ARRAY['MA','RI'], 'sh') AS result;
-- result --
STATEDIR="/gisdata/www2.census.gov/geo/pvs/tiger2010st/44_Rhode_Island"
TMPDIR="/gisdata/temp/"
UNZIPTOOL=unzip
PGPORT=5432
PGHOST=localhost
PGUSER=postgres
PGPASSWORD=yourpasswordhere
PGDATABASE=geocoder
PSQL=psql
SHP2PGSQ=shp2pgsql

wget http://www2.census.gov/geo/pvs/tiger2010st/44_Rhode_Island/ --no-parent --relative --recursive --level=2 --accept=zip,txt --mirror --reject=html
:
:

Name

Loader_Generate_Nation_Script — 指定したプラットフォーム用の、国と州のルックアップテーブルをロードするシェルスクリプトを生成します。

Synopsis

text loader_generate_nation_script(text os);

説明

tiger_dataスキーマにcounty_all, county_all_lookup, state_allテーブルをロードする、指定したプラットフォーム用のシェルスクリプトを生成します。それぞれtigerスキーマのcounty, county_lookup, stateから継承されます。

ダウンロードには、Linuxではunzip (Windowsのデフォルトは7-zip)とwgetとを使います。データの格納にはSection 4.1.4.2, “shp2pgsql: ESRIシェープファイルローダを使う”を使います。

プロセスの制御や異なるOSのシェルの書式の制御のために、制御テーブルtiger.loader_platform, tiger.loader_variables, tiger.loader_lookuptablesを使います。

  1. loader_variables 国勢調査ダウンロードサイト、年度、データと準備スキーマといった種々の変数の軌跡を保持します。

  2. loader_platformには、種々のプラットフォームのプロファイルや実行可能ファイルの置いてある位置を持ちます。windowsとLinux/unixを備えています。追加も可能です。

  3. レコードごとにテーブルの種類 (州、国)、レコード処理の有無、ロード方法を定義しています。データインポート方法、データ格納準備、カラム追加、カラム削除、インデックス、制約がそれぞれで定義されています。個々のテーブルは、名前の先頭に州コードを持ち、tigerスキーマのテーブルから継承されています。たとえば、tiger.facesから継承されたtiger_data.ma_facesする、といったことが行われます。

Enhanced: 2.4.1 zip code 5 tabulation area (zcta5) load step was fixed and when enabled, zcta5 data is loaded as a single table called zcta5_all as part of the nation script load.

Availability: 2.1.0

[Note]

If you want zip code 5 tabulation area (zcta5) to be included in your nation script load, do the following:

UPDATE tiger.loader_lookuptables SET load = true WHERE table_name = 'zcta510';
[Note]

tiger_2010を実行してからtiger_2011の再ロードを行うには、このスクリプトを実行する前に、最初に、Drop_Nation_Tables_Generate_Scriptによって、テーブル削除スクリプトを生成、実行する必要があります。

国データをWindowsにロードするスクリプトを生成します。

SELECT loader_generate_nation_script('windows'); 

国データをLinux/Unixシステムにロードするスクリプトを生成します。

SELECT loader_generate_nation_script('sh'); 

Name

Missing_Indexes_Generate_Script — ジオコーダで結合に使われるキーカラムを持ち、インデックスが付いていないキーカラムを持つすべてのテーブルを検索し、インデックスを追加するSQLデータ定義言語を出力します。

Synopsis

text Missing_Indexes_Generate_Script();

説明

tigerスキーマとtiger_dataスキーマ内のジオコーダで結合に使われ、インデックスが付いていないキーカラムを持つ全てのテーブルを検索し、インデックスを付けるSQLデータ定義言語を出力します。これは、クエリの動作速度を上げるのに必要であるのにロード処理で失われたインデックスを追加するのを助ける関数です。ジオコーダが改善されますが、使用される新しいインデックスを受け入れるために、この関数は更新されます。この関数の出力が無い場合がありますが、これは、全てのテーブルにインデックスが付いていると考えられます。

Availability: 2.0.0

SELECT missing_indexes_generate_script();
-- 出力: 多数の修正がロードスクリプトで行われる前のデータベースで実行しました ---
CREATE INDEX idx_tiger_county_countyfp ON tiger.county USING btree(countyfp);
CREATE INDEX idx_tiger_cousub_countyfp ON tiger.cousub USING btree(countyfp);
CREATE INDEX idx_tiger_edges_tfidr ON tiger.edges USING btree(tfidr);
CREATE INDEX idx_tiger_edges_tfidl ON tiger.edges USING btree(tfidl);
CREATE INDEX idx_tiger_zip_lookup_all_zip ON tiger.zip_lookup_all USING btree(zip);
CREATE INDEX idx_tiger_data_ma_county_countyfp ON tiger_data.ma_county USING btree(countyfp);
CREATE INDEX idx_tiger_data_ma_cousub_countyfp ON tiger_data.ma_cousub USING btree(countyfp);
CREATE INDEX idx_tiger_data_ma_edges_countyfp ON tiger_data.ma_edges USING btree(countyfp);
CREATE INDEX idx_tiger_data_ma_faces_countyfp ON tiger_data.ma_faces USING btree(countyfp);
        

Name

Normalize_Address — 文字列で住所が与えられると、道路後置辞、前置辞、正規化された種別、番地、ストリート名等をフィールドに分けて持つnorm_addy複合型を返します。tiger_geocoderに同梱されているルックアップデータで動作します (Tigerデータ自体は不要です)。

Synopsis

norm_addy normalize_address(varchar in_address);

説明

文字列で住所が与えられると、道路後置辞、前置辞、正規化された種別、番地、ストリート名等をフィールドに分けて持つnorm_addy複合型を返します。全ての住所を正規化した郵便形式にするジオコーディング処理の第一段階です。ジオコーダに同梱されるもの以外で必要な者はありません。

tiger_geocoderによって前もってロードされ、tigerスキーマに格納される、様々な方角/州/後置辞のルックアップテーブルを使います。よって、Tigerデータをダウンロードしたり、追加データをする必要はありません。tigerスキーマ内のルックアップテーブルに略語や別名の追加が必要になることがあります。

tigerスキーマ内に、入力アドレスを正規化するための、多様な制御ルックアップテーブルを使います。

この関数が返すnorm_addy型オブジェクトのフィールドは、次に示す順序です。()はジオコーダの必須フィールド、[]は任意フィールドです。

(address) [predirAbbrev] (streetName) [streetTypeAbbrev] [postdirAbbrev] [internal] [location] [stateAbbrev] [zip]

Enhanced: 2.4.0 norm_addy object includes additional fields zip4 and address_alphanumeric.

  1. address 整数: 番地

  2. predirAbbrev varchar型: N, S, E, W等といった道路の方向前置辞。direction_lookupテーブルに制御されます。

  3. streetName varchar型

  4. streetTypeAbbrev varchar型 ストリート種別の短縮名: St, Ave, Cir等。street_type_lookupテーブルに制御されます。

  5. postdirAbbrev varchar型 N, S, E, W等の道路名の方向後置辞。direction_lookupテーブルに制御されます。

  6. internal varchar型 部屋番号といった内部住所。

  7. location varchar型 通常は市名や県名です。

  8. stateAbbrev varchar型 MA, NY, MI等のような米国の州名の2文字表示です。state_lookupテーブルに制御されます。

  9. zip varchar型 02109等の5桁の数字です。

  10. parsed 真偽型 - 住所が正規化処理で整形されたかを示します。normalize_addressは、住所を返す前にこれをTRUEにします。

  11. zip varchar型 02109等の5桁の数字です。

  12. address_alphanumeric Full street number even if it has alpha characters like 17R. Parsing of this is better using