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 を指定することで、無効にできます。
- getfaceedges_returntype — 順序番号とエッジ番号で構成される複合型。
- TopoGeometry — トポロジとして定義されたジオメトリを表現する型です。
- validatetopology_returntype — エラーメッセージとエラーの場所を示すid1とid2からなる複合型です。これは
ValidateTopologyが返す型です。
- TopoElement — 二つの整数の配列で、通常TopoGeometry要素を識別するために使われます。
- TopoElementArray — TopoElementオブジェクトの配列。
- AddTopoGeometryColumn — 既存のテーブルにTopoGeometryカラムを追加し、topology.layer内に新しいレイヤとして新しいカラムを登録して、新しい layer_id を返します。
- RenameTopoGeometryColumn — TopoGeometryカラムの名前を変更します
- DropTopology — 使用上の注意: この関数によって、トポロジスキーマが削除され、topology.topologyテーブルからの参照が削除され、geometry_columnsテーブルから削除対象スキーマ内のテーブルへの参照が削除されます。
- RenameTopology — トポロジ名を変更します
- DropTopoGeometryColumn —
schema_nameで指定されたスキーマ内にあるtable_nameで指定されたテーブルからTopoGeometryカラムを削除し、topology.layerテーブルにある登録を解除します。 - Populate_Topology_Layer — テーブルからメタデータを読み、topology.layerテーブルに不足しているものを追加します。
- TopologySummary — トポロジ名を取り、トポロジ内のオブジェクトの型に関する概要の全体を提供します。
- ValidateTopology — トポロジの問題についての詳細を示すvalidatetopology_returntypeの集合を返します。
- ValidateTopologyRelation — 不正なトポロジ関係の行に関する情報を返します。
- FindTopology — 異なる方法でトポロジ行を返します。
- FindLayer — 様々な方法でtopology.layer行を返します。
トポロジに要素を追加すると、そのトリガとして、分割されることになる既存のエッジを探索し、ノードを追加し、新しいラインでノードを作成するエッジを更新するために多数のデータベースクエリが発生します。このため、トポロジテーブル内のデータに関する統計情報が最新の状態になっているなら、統計情報を使うと便利です。
PostGISトポロジーの追加や編集の関数は、自動的に統計情報を更新することはありません。トポロジにおいて逐次変更していては、統計情報の更新が過剰になるためです。処理は呼び出し元の義務となっています。
![[Note]](../images/note.png) | |
autovacuumで更新された統計情報は、autovacuumプロセス完了前に始まったトランザクションからは見えないので、更新した統計情報を使うには、実行時間の長いトランザクションではANALYZE自体を実行する必要があります。 |
- CreateTopology — 新しいトポロジスキーマを生成し、topology.topologyテーブルに登録します。
- CopyTopology — トポロジ (ノード、エッジ、フェイス、レイヤとTopoGeometry)の新しいスキーマに複写します。
- ST_InitTopoGeo — 新しいトポロジスキーマを生成し、topology.topologyテーブルに登録します。
- ST_CreateTopoGeo — 空のトポロジにジオメトリのコレクションを追加し、成否を示すメッセージを返します。
- TopoGeo_AddPoint — 許容差を使って既存のトポロジにポイントを追加し、可能ならエッジを分割します。
- TopoGeo_AddLineString — 許容差を使って既存のトポロジにラインストリングを追加し、可能ならエッジ/フェイスを分割します。エッジ識別番号を返します。
- TopoGeo_AddPolygon — 許容差を使って既存のトポロジにラインストリングを追加し、可能ならエッジ/フェイスを分割します。エッジ識別番号を返します。
- ST_AddIsoNode — フェイスに孤立ノードを追加し、新しいノードの識別番号を返します。フェイスがNULLの場合でもノードは生成されます。
- ST_AddIsoEdge —
anodeとanothernodeで指定される二つの既存孤立ノードを接続するトポロジに、ジオメトリ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 — 孤立エッジを削除し、実行結果の記述を返します。エッジが孤立していない場合には、例外が投げられます。
- GetEdgeByPoint — 与えられたポイントにインタセクトするエッジの識別番号を探索します。
- GetFaceByPoint — 与えたポイントとインタセクトするフェイスを見つけます。
- GetFaceContainingPoint — ポイントを含むフェイスを見つけます。
- GetNodeByPoint — ポイント位置にあるノードの識別番号を探索します。
- GetTopologyID — トポロジ名からtopology.topologyテーブル内にあるトポロジの識別番号を返します。
- GetTopologySRID — トポロジ名からtopology.topologyテーブル内にあるトポロジのSRIDを返します。
- GetTopologyName — 識別番号からトポロジ (スキーマ)の名前を返します。
- ST_GetFaceEdges — 順序番号を含む、
afaceの境界となる、整列したエッジの集合を返します。 - ST_GetFaceGeometry — 指定されたトポロジの中の、フェイス識別番号で指定されたポリゴンを返します。
- GetRingEdges — 与えられた側を歩いて得られた、正負符号付きエッジ識別番号の集合を、順序通りに返します。
- GetNodeEdges — 与えられたノードに付随するエッジの集合を整列して返します。
- Polygonize — トポロジエッジで定義される全てのフェイスを探索し、追加します。
- AddNode — 指定したトポロジスキーマのノードテーブルにポイントノードを追加し、新しいノードの識別番号を返します。指定したポイントに既にノードがある場合は既存のノード識別番号を返します。
- AddEdge — 指定したラインストリングジオメトリを使って、ラインストリングエッジをエッジテーブルに追加し、指定したトポロジスキーマの始点終点をポイントノードテーブルに追加し、新しい (または既存の)エッジの識別番号を返します。
- AddFace — フェイスプリミティブをトポロジに登録し、その識別番号を得ます。
- ST_Simplify — 与えたTopoGeometryを「シンプル化した」ジオメトリを返します。ダグラス-ポーカーのアルゴリズムを使います。
- RemoveUnusedPrimitives — 存在する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を返します。 - TopoElement — TopoGeometryをTopoElementに変換します。
- clearTopoGeom — TopoGeometryの中身を消去します。
- TopoGeom_addElement — TopoGeometryの定義に要素を追加します。
- TopoGeom_remElement — TopoGeometryの定義から要素を削除します。
- TopoGeom_addTopoGeom — TopoGeometryの要素を他のTopoGeometryの定義に追加します。
- toTopoGeom — ジオメトリの形状を既存のTopoGeometryに追加します。
- GetTopoGeomElementArray — 与えられたTopoGeometry (プリミティブ要素)のトポロジ要素とタイプを含む
topoelementarray(topoelementの配列)を返します。 - GetTopoGeomElements — 与えられたTopoGeometry (プリミティブ要素)の、トポロジのelement_idとelement_typeを含む
topoelementオブジェクトの集合を返します。 - ST_SRID — TopoGeometryの空間参照識別子を返します。
- AsGML — TopoGeometryのGML表現を返します。
- AsTopoJSON — opoGeometryのTopoJSON表現を返します。
- Equals — 二つのTopoGeometryが同じトポロジプリミティブで成っている場合にtrueを返します。
- Intersects — 二つのTopoGeometryからのプリミティブの組がインタセクトする場合にtrueを返します。
トポロジを生成したり、場合によってはトポロジレイヤに関連付けると、バックアップや他のデータベースへの転送のために、ファイルに出力するフォーマットでエクスポートした方がいいでしょう。
トポロジはテーブルの集合 (プリミティブで4テーブル、レイヤで任意数)と、メタデータテーブルのレコード (topology.topologyとtopology.layer)になっているため、PostgreSQLの標準的なダンプ/レストアのツールでは問題があります。さらに、トポロジの識別子はデータベース間で同じではないため、トポロジのパラメータはレストア時に変更する必要があります。
トポロジのエクスポート/レストアを簡単化するために、二つの実行可能ファイルが提供されています。pgtopo_exportとpgtopo_importです。使用例は次の通りです。
pgtopo_export dev_db topo1 | pgtopo_import topo1 | psql staging_db
pgtopo_exportスクリプトはデータベース名とトポロジ名を取り、トポロジ (と関連するレイヤ)を新しいデータベースにインポートするために使うことができるダンプファイルを出力します。
デフォルトではpgtopo_exportはダンプファイルを標準出力に書くので、pgtopo_importにパイプで繋げたり、ファイルにリダイレクトする (端末への出力を止める)ことができます。出力ファイル名をコマンドラインスイッチ-fで指定することもできます。
デフォルトではpgtopo_exportは、指定されたトポロジに対して定義されたレイヤの全てのダンプが含まれます。これは、必要なデータより多い場合もありますし、動作しない場合もあり (レイヤテーブルが複雑な依存関係を持っている場合)、この場合には--skip-layersスイッチでレイヤをスキップし、別々に処理することができます。
pgtopo_exportを--help (または短縮の-h)スイッチで実行すると、常に短い使用法文字列を印字します。
ダンプファイルフォーマットは、少なくともフォーマットバージョン情報を持つpgtopo_dump_versionファイルを含むpgtopo_exportディレクトリの圧縮されたtarアーカイブです。バージョン1では、ディレクトリにはトポロジのプリミティブテーブル (node, edge_data, face, relation)と、プリミティブと関連付けられたトポロジとレイヤとを持つタブ区切りCSVファイルが含まれ、(--skip-layersが与えられない場合)与えられたトポロジのレイヤとして報告されたテーブルのPostgrfeSQLダンプのカスタムフォーマットも含まれます。
pgtopo_importスクリプトはpgtopo_export書式のトポロジのダンプと、生成するトポロジに与える名前とを取り、そこからトポロジと関連するレイヤを再構築するSQLスクリプトを出力します。
生成されたSQLには、与えられた名前でトポロジを生成し、プリミティブなデータをロードし、格納して、TopoGeometry値を確実に正しいトポロジに関連付けることで全てのトポロジレイヤを登録する手続きが含まれます。
デフォルトではpgtopo_importは標準入力からダンプを読むので、pgtopo_exportをパイプで繋げて併用することができます。入力ファイル名をコマンドラインスイッチ-fで指定することもできます。
デフォルトではpgtopo_importのSQLファイル出力には、ダンプで発見された全てのレイヤを格納するためのコードが含まれます。
これらは、ダンプ内にあるテーブル名が既に対象データベース内のテーブル名で使われている場合には、望ましくないようになるか動作しない可能性があります。この場合には、レイヤをスキップする--skip-layersスイッチを使い、別に (または後で)処理することができます。
ロードして、レイヤを名前付きトポロジにリンクするSQLは--only-layersスイッチで生成できます。これは、名前の競合を解決した*後に*レイヤをロードしたり、異なるトポロジのレイヤ (開始トポロジで空間的に単純化されたもの等が挙げられます)にリンクするのに使えます。