13. ポリゴンファイルについて
13.1. 概要
jVは原子座標を記したファイルだけではなく、ポリゴン(多角形)を表示することもできます。 まず各点の情報を定義し、その上で点、線、多角形などの描画指示を記述します。 各項目についての詳細は次項以降をご覧下さい。ポリゴンファイルの仕様詳細についてはポリゴンファイルスキーマも参照下さい。
13.2. 全体(polygon要素)
- 内容
-
ポリゴンの記述全体を囲う最上位(ルート)要素です。
vertices
要素は子要素として必須で、個々の点の座標などを設定します(設定のみでこれだけでは何も表示されません)。実際に点や線などを表示させるにはpoint_array
(点)、line_array
(線)、triangle_array
(三角形)、quad_array
(四角形)、polyline_array
(折れ線)の各要素を任意で子要素として記述します。 - 要素値
- (規定無し)
- 属性
-
規定無し。jVで読み込む分には特に属性を指定しなくても問題ないが、XMLの仕様上以下の通り既定の名前空間およびスキーマファイルのURIを定義しておくべき。
キー 値 備考 xmlns
http://www.pdbj.org/jv/polygonSchema
要素名に接頭辞がない場合に適用される既定の名前空間。 xmlns:xsi
http://www.w3.org/2001/XMLSchema-instance
xsi:schemaLocationを使うための名前空間定義。 xsi:schemaLocation
http://www.pdbj.org/jv/polygonSchema
スキーマファイルのURI。 - 子要素(番号順に記述)
-
- vertices要素(個数規定無し)
- point_array要素(最小0個、最大個数規定無し)
- line_array要素(最小0個、最大個数規定無し)
- triangle_array要素(最小0個、最大個数規定無し)
- quad_array要素(最小0個、最大個数規定無し)
- polyline_array要素(最小0個、最大個数規定無し)
- スキーマ原文
-
<element name="polygon" type="pv:polygon_type"/> <complexType name="polygon_type"> <sequence> <element ref="pv:vertices"/> <element ref="pv:point_array" minOccurs="0"/> <element ref="pv:line_array" minOccurs="0"/> <element ref="pv:triangle_array" minOccurs="0"/> <element ref="pv:quad_array" minOccurs="0"/> <element ref="pv:polyline_array" minOccurs="0"/> </sequence> </complexType>
- 例
-
<?xml version="1.0"?> <polygon xmlns="http://www.pdbj.org/jv/polygonSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.pdbj.org/jv/polygonSchema"> <vertices count="100" id_numbers="use"> <vertex id="1" image="x y z nx ny nz R G B"/> <vertex id="2" image="x y z nx ny nz R G B"/> ・・・ </vertices> <point_array count="2" size="3"> <point id="1" vertex="v1"/> <point id="2" vertex="v1"/> ・・・ </point_array> <line_array count="2" width="2"> <line id="1" vertex="v1 v2"/> <line id="2" vertex="v1 v2"/> ・・・ </line_array> <triangle_array count="2" transparency="0.5"> <triangle id="1" vertex="v1 v2 v3"/> <triangle id="2" vertex="v1 v2 v3"/> ・・・ </triangle_array> <quad_array count="2"> <quad id="1" vertex="v1 v2 v3 v4"/> <quad id="2" vertex="v1 v2 v3 v4"/> ・・・ </quad_array> <polyline_array count="2" width="1"> <polyline id="1" vertex="v1 v2 v3 v4 v5 ・・・"/> <polyline id="2" vertex="v1 v2 v3 v4 v5 ・・・"/> ・・・ </quad_array> </polygon>
13.3. 点情報定義(vertices要素)
- 内容
-
各点の設定を含む要素です。子要素の
vertex
要素で具体的な各点の情報を記述します。なおこの要素は情報設定のみを行うため、これだけでは何も表示されません。別途point_array
などの要素で図形を描く設定を行う必要があります。 - 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 count 必須 整数 設定する点(子要素 vertex)の個数を記述。子要素 vertex の数と同じ数値を設定する。 id_numbers 必須 文字列 「use」を指定すれば各子要素のid属性値が、「ignore」を指定すれば子要素のid属性値は無視し1から登場順に連番が自動的に割り振られる(但しこの場合も子要素のid属性は省略できない)。定義上は任意の文字列が設定可能。 - 子要素(番号順に記述)
-
- vertex要素(最小個数規定無し、最大個数制限なし)
- スキーマ原文
-
<element name="vertices" type="pv:vertices_type"/> <complexType name="vertices_type"> <sequence> <element ref="pv:vertex" maxOccurs="unbounded"/> </sequence> <attribute name="count" use="required" type="integer"/> <attribute name="id_numbers" use="required" type="string"/> ※ <!-- id_numbers is "use" or "ignore". if set to be "ignore", id number of each vertex element is automatically assigned sequential integer (starts from 1) in order of appearance. --> </complexType> ※本来は "use" と "ignore" のみ指定できるデータ型を規定し、そのデータ型をtypeに指定すべき。 <simpleType name="id_numbersType"> <restriction base="string"> <enumeration value="use"/> <enumeration value="ignore"/> </restriction> </simpleType> <attribute name="id_numbers" use="required" type="pv:id_numbersType"/>
- 書式のまとめ
-
<vertices count="n" id_numbers="use/ignore"> <vertex id="1" image="x座標1 y座標1 z座標1 nx1 ny1 nz1 赤要素1 緑要素1 青要素1">; <vertex id="2" image="x座標2 y座標2 z座標2 nx2 ny2 nz2 赤要素2 緑要素2 青要素2">; ... <vertex id="n" image="x座標n y座標n z座標n nxn nyn nzn 赤要素n 緑要素n 青要素n">; </vertices> ※nx, ny, nz: 法線ベクトルのx, y, z要素 ※n: vertex要素の個数
13.3.1. 個別の点の定義(vertex要素)
- 内容
-
各点の座標、色などの情報を記述します。
vertex
要素の個数はvertices
要素のcount
属性値で指定した数と一致するようにします。 - 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 id 必須 整数 他の vertex
要素のid
属性の値と重複しない一意な値を指定します。親要素vertices
で、id_numbers="ignore"
と指定した場合、この属性は無視されますが属性自体を省略することはできません。image 必須 文字列 9つの値を、空白で区切って指定します。前から順に点のx座標値、y座標値、z座標値、頂点法線ベクトル(normal vector)のx要素、y要素、z要素、色要素の赤(R)、緑(G)、青(B)です。座標値、ベクトル要素は実数値で、色要素は0〜255の整数で指定します。頂点法線ベクトルは境界の形状に影響します。法線ベクトルの方向から見ると明るく見えます。 - 子要素
-
- user_data要素(最小0個、最大個数規定無し)…コメントなど任意を内容を記述。
- スキーマ原文
-
<element name="vertex" type="pv:vertex_type"/> <complexType name="vertex_type"> <sequence> <element name="user_data" type="anyType" minOccurs="0"/> </sequence> <attribute name="id" use="required" type="integer"/> <attribute name="image" use="required" type="string"/> <!-- image has 9 values separated by a space in such an order as "coordinates_x coordinates_y coordinates_z normal_vector_x normal_vector_y normal_vector_z color_R color_G color_B" where RGB values are from 0 to 255 --> </complexType>
- 書式のまとめ
-
<vertex id="id" image="x座標 y座標 z座標 nx ny nz 赤要素 緑要素 青要素">; ※nx, ny, nz: 法線ベクトルのx, y, z要素
13.4. 点の描画(point_array要素)
- 内容
- ポリゴンの点要素群を記述します。具体的な各点の情報は子要素のpoint要素で記述します。
- 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 count 必須 整数 子要素 point の数を設定します。 transparency 任意 実数(float) 点の透明度を設定します。0だと完全に不透明、1だと完全に透明で見えなくなります。指定がない場合の既定値は0(完全不透明)です。0未満または1より大きい値も設定はできますが、値は無視され指定がない場合と同じく完全不透明になります。従って指定値として実際意味のある値は0以上1以下の実数です。 size 任意 実数(float) - 子要素
-
- point要素(最小個数規定無し、最大個数制限無し)
- スキーマ原文
-
<element name="point_array" type="pv:point_array_type"/> <complexType name="point_array_type"> <sequence> <element ref="pv:point" maxOccurs="unbounded"/> </sequence> <attribute name="count" use="required" type="integer"/> <attribute name="transparency" use="optional" type="float"/> <attribute name="size" use="optional" type="float"/> </complexType>
- 書式のまとめ
-
<point_array count="" transparency="" size=""> <point id="" vertex=""/> <point id="" vertex=""/> ... <point id="" vertex=""/> </point_array> ※count: 個別番号(必須) ※transparency: 透過度(任意) ※size: 大きさ(任意)
13.4.1. 個別の点の描画(point要素)
- 内容
- ポリゴンの各点要素の情報を記述します。
- 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 id 必須 整数 他の point
要素の id 属性値と重複しない、一意な整数を指定します。vertex 必須 文字列 この属性値に指定した値と同じ値を、id 属性値に持つ vertex
要素の情報(座標、色など)が適用されます。 - 子要素
- なし
- スキーマ原文
-
<element name="point" type="pv:point_type"/> <complexType name="point_type"> <attribute name="id" use="required" type="integer"/> <attribute name="vertex" use="required" type="string"/> # ↑参照先となる vertex 要素の id 属性値の型は整数(integer)であるため、本来はこのtypeも "integer" であるべき。 <!-- vertex has a single vertex ID --> </complexType>
- 書式のまとめ
-
<point id="id" vertex="対応するvertexのid"/>
13.5. 線の描画(line_array要素)
- 内容
- ポリゴンの線要素群を記述します。具体的な各線の情報は子要素のline要素で記述します。
- 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 count 必須 整数 子要素 line の数を設定します。 transparency 任意 実数(float) 線の透明度を設定します。0だと完全に不透明、1だと完全に透明で見えなくなります。指定がない場合の既定値は0(完全不透明)です。0未満または1より大きい値も設定はできますが、値は無視され指定がない場合と同じく完全不透明になります。従って指定値として実際意味のある値は0以上1以下の実数です。 width 任意 実数(float) - 子要素
-
- line要素(最小個数規定無し、最大個数制限無し)
- スキーマ原文
-
<element name="line_array" type="pv:line_array_type"/> <complexType name="line_array_type"> <sequence> <element ref="pv:line" maxOccurs="unbounded"/> </sequence> <attribute name="count" use="required" type="integer"/> <attribute name="transparency" use="optional" type="float"/> <attribute name="width" use="optional" type="float"/> </complexType>
- 書式のまとめ
-
<line_array count="" transparency="" width=""> <line id="" vertex=""/> <line id="" vertex=""/> ... <line id="" vertex=""/> </line_array> ※count: 個別番号(必須) ※transparency: 透過度(任意) ※width: 線の太さ(任意)
13.5.1. 個別の線の描画(line要素)
- 内容
- ポリゴンの各線要素の情報を記述します。
- 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 id 必須 整数 他の line
要素の id 属性値と重複しない、一意な整数を指定します。vertex 必須 文字列 線の始点と終点となる点を、 vertex
要素の id 属性値で指定します。2つの値は空白で区切ります。両端の点の色はこの属性値に指定した値と同じ値を、id 属性値に持つvertex
要素の情報(座標、色など)が適用されます。線の色は一端の点の色から、もう一方の端の点の色へ連続的に変化するように設定されます。 - 子要素
- なし
- スキーマ原文
-
<element name="line" type="pv:line_type"/> <complexType name="line_type"> <attribute name="id" use="required" type="integer"/> <attribute name="vertex" use="required" type="string"/> <!-- vertex has two vertex IDs separated by a space --> </complexType>
- 書式のまとめ
-
<line id="id" vertex="始点のvertex id 終点のvertex id"/>
13.6. 三角形の描画(traiangle_array要素)
- 内容
- ポリゴンの三角形要素群を記述します。具体的な各三角形の情報は子要素のtriangle要素で記述します。
- 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 count 必須 整数 子要素 triangle の数を設定します。 transparency 任意 実数(float) 三角形の透明度を設定します。0だと完全に不透明、1だと完全に透明で見えなくなります。指定がない場合の既定値は0(完全不透明)です。0未満または1より大きい値も設定はできますが、値は無視され指定がない場合と同じく完全不透明になります。従って指定値として実際意味のある値は0以上1以下の実数です。 - 子要素
-
- triangle要素(最小個数規定無し、最大個数制限無し)
- スキーマ原文
-
<element name="triangle_array" type="pv:triangle_array_type"/> <complexType name="triangle_array_type"> <sequence> <element ref="pv:triangle" maxOccurs="unbounded"/> </sequence> <attribute name="count" use="required" type="integer"/> <attribute name="transparency" use="optional" type="float"/> </complexType>
- 書式のまとめ
-
<triangle_array count="" transparency=""> <triangle id="" vertex=""/> <triangle id="" vertex=""/> ... <triangle id="" vertex=""/> </triangle_array> ※count: 個別番号(必須) ※transparency: 透過度(任意)
13.6.1. 個別の三角形の描画(triangle要素)
- 内容
- ポリゴンの各三角形要素の情報を記述します。
- 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 id 必須 整数 他の triangle
要素の id 属性値と重複しない、一意な整数を指定します。vertex 必須 文字列 三角形の各頂点となる3点を、 vertex
要素の id 属性値で指定します。3つの値は空白で区切ります。 - 子要素
- なし
- スキーマ原文
-
<element name="triangle" type="pv:triangle_type"/> <complexType name="triangle_type"> <attribute name="id" use="required" type="integer"/> <attribute name="vertex" use="required" type="string"/> <!-- vertex has three vertex IDs separated by a space --> </complexType>
- 書式のまとめ
-
<triangle id="id" vertex="頂点1のvertex id 頂点2のvertex id 頂点3のvertex id"/>
13.7. 四角形の描画(quad_array要素)
- 内容
- ポリゴンの四角形要素群を記述します。具体的な各四角形の情報は子要素のquad要素で記述します。
- 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 count 必須 整数 子要素 quad の数を設定します。 transparency 任意 実数(float) 四角形の透明度を設定します。0だと完全に不透明、1だと完全に透明で見えなくなります。指定がない場合の既定値は0(完全不透明)です。0未満または1より大きい値も設定はできますが、値は無視され指定がない場合と同じく完全不透明になります。従って指定値として実際意味のある値は0以上1以下の実数です。 - 子要素
-
- quad要素(最小個数規定無し、最大個数制限無し)
- スキーマ原文
-
<element name="quad_array" type="pv:quad_array_type"/> <complexType name="quad_array_type"> <sequence> <element ref="pv:quad" maxOccurs="unbounded"/> </sequence> <attribute name="count" use="required" type="integer"/> <attribute name="transparency" use="optional" type="float"/> </complexType>
- 書式のまとめ
-
<quad_array count="" transparency=""> <quad id="" vertex=""/> <quad id="" vertex=""/> ... <quad id="" vertex=""/> </quad_array> ※count: 個別番号(必須) ※transparency: 透過度(任意)
13.7.1. 個別の四角形の描画(quad要素)
- 内容
- ポリゴンの各四角形要素の情報を記述します。
- 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 id 必須 整数 他の quad
要素の id 属性値と重複しない、一意な整数を指定します。vertex 必須 文字列 四角形の各頂点となる4点を、 vertex
要素の id 属性値で指定します。4つの値は空白で区切ります。 - 子要素
- なし
- スキーマ原文
-
<element name="quad" type="pv:quad_type"/> <complexType name="quad_type"> <attribute name="id" use="required" type="integer"/> <attribute name="vertex" use="required" type="string"/> <!-- vertex has four vertex IDs separated by a space --> </complexType>
- 書式のまとめ
-
<quad id="id" vertex="頂点1のvertex id 頂点2のvertex id 頂点3のvertex id 頂点4のvertex id"/>
13.8. 折れ線の描画(polyline_array要素)
- 内容
-
ポリゴンの線要素群を記述します。具体的な各線の情報は子要素のpolyline要素で記述します。
line_array
要素と似ていますが、連続する折れ線を描く場合、1つのpolyline
要素で描くことができるのでこちらを利用した方が便利です。 - 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 count 必須 整数 子要素 polyline の数を設定します。 transparency 任意 実数(float) 線の透明度を設定します。0だと完全に不透明、1だと完全に透明で見えなくなります。指定がない場合の既定値は0(完全不透明)です。0未満または1より大きい値も設定はできますが、値は無視され指定がない場合と同じく完全不透明になります。従って指定値として実際意味のある値は0以上1以下の実数です。 width 任意 実数(float) - 子要素
-
- polyline要素(最小個数規定無し、最大個数制限無し)
- スキーマ原文
-
<element name="polyline_array" type="pv:polyline_array_type"/> <complexType name="polyline_array_type"> <sequence> <element ref="pv:polyline" maxOccurs="unbounded"/> </sequence> <attribute name="count" use="required" type="integer"/> <attribute name="transparency" use="optional" type="float"/> <attribute name="width" use="optional" type="float"/> </complexType>
- 書式のまとめ
-
<polyline_array count="" transparency=""> <polyline id="" vertex=""/> <polyline id="" vertex=""/> ... <polyline id="" vertex=""/> </polyline_array> ※count: 個別番号(必須) ※transparency: 透過度(任意) ※width: 線の太さ(任意)
13.8.1. 個別の折れ線の描画(polyline要素)
- 内容
-
ポリゴンの各(折れ)線要素の情報を記述します。
line
要素と似ていますが、こちらは連続する折れ線を1つのpolyline
要素で描くことができます。 - 要素値
- (規定無し)
- 属性
-
キー 要否 値 備考 id 必須 整数 他の polyline
要素の id 属性値と重複しない、一意な整数を指定します。vertex 必須 文字列 (折れ)線の始点と終点となる点を、 vertex
要素の id 属性値で指定します。2つの値は空白で区切ります。両端の点の色はこの属性値に指定した値と同じ値を、id 属性値に持つvertex
要素の情報(座標、色など)が適用されます。線の色は一端の点の色から、もう一方の端の点の色へ連続的に変化するように設定されます。 - 子要素
- なし
- スキーマ原文
-
<element name="polyline" type="pv:polyline_type"/> <complexType name="polyline_type"> <attribute name="id" use="required" type="integer"/> <attribute name="vertex" use="required" type="string"/> <!-- vertex has more than one vertex IDs separated by a space --> </complexType>
- 書式のまとめ
-
<polyline id="id" vertex="頂点1のvertex id 頂点2のvertex id..."/>