Aspose.PDF FOSS
Developer Guide
Primitives

Primitives

Primitives

このガイドでは、API の残りの部分にジオメトリとカラー データを伝達する、小さく実質的に不変の値型（2D と 3D のポイント、矩形、変換行列、カラー値）について説明します。シンプルなワークフローでは通常、名前で直接インポートすることはありません — これらはアノテーション、画像配置、3D ビューなどの上位オブジェクトのプロパティ型として現れます — しかし、その形状を理解しておくと、これらオブジェクトのプロパティを読み取りやすく、構築しやすくなります。

ポイント: Point と Point3D

Point は、x と y の float プロパティを持つシンプルな 2D 座標です。Point3D はそれの 3D 版で、Point3D(x, y, z) として構築され、x、y、z の float プロパティを公開します。Point は GradientAxialShading.start / end に使用される型であり、Matrix3D ベースの変換と 3D ビューは、Point3D が表す同じ座標空間で動作します。

Rectangles

Rectangle(x, y, width, height) は位置とサイズを表し、さらに left、bottom、right の計算された float プロパティを、x、y、width、height と共に公開します。Rectangle は PDF3DAnnotation.rect の背後にある型であり、したがって 3D アノテーションのページ上の境界は、API の他のすべての矩形と同じ形状で読み書きされます。

変換行列: Matrix と Matrix3D

Matrix は、6つの浮動小数点コンポーネント — a, b, c, d, e, f — を持つ 2D アフィン変換を保持し、2つのメソッドを提供します: translate(x, y) はその場で平行移動を適用し、multiply(other) は別の Matrix と合成して、結果の Matrix を返します。

Matrix3D は 3D 版です: 3x3 の回転/スケールブロック（m11 から m33）に加えて、dx, dy, dz の平行移動コンポーネントがあり、引数なしで構築され（Matrix3D()）、プロパティを設定して内容を埋めます。PDF3DView.ctm の型は Matrix3D | None です — 保存された 3D ビューの現在の変換行列です。

ヒントとベストプラクティス

  • ドキュメントで示された順序（x, y[, z] / x, y, width, height）で位置引数を使用して Rectangle、Point、Point3D を構築してください — これらの型はキーワード専用引数ではなく、純粋な float を受け取ります。
  • 手動で 6 つの a–f コンポーネントを組み合わせるのではなく、Matrix.multiply() を使用して変換を合成してください。
  • プロパティの型がオプションの場合（例: PDF3DAnnotation.background_color: Color | None または PDF3DView.ctm: Matrix3D | None）、その上のネストされたプロパティを読む前に None が存在するか確認してください。
  • パターンのカラースペースとして 2 色の線形グラデーションが必要なときだけ GradientAxialShading を使用し、フラットで単一の色の場合は直接 Color を使用してください。
  • Rectangle の left、bottom、right プロパティは x、y、および width/height から導出されます — それらは独立した状態ではなく、同じ矩形の便利なビューとして扱ってください。

一般的な問題

問題原因修正
矩形または点の座標が入れ替わっている、またはスケーリングが正しくないRectangle(x, y, width, height) または Point3D(x, y, z) に対して位置引数が誤った順序で渡されているコンストラクタ署名に対して引数の順序を再確認してください — これらの型はキーワード専用の強制がありません
AttributeError（色または行列プロパティを読み取るとき）オプションフィールドからの None 値に対してプロパティがアクセスされている（例: background_color、ctm）ネストされたプロパティにアクセスする前に、値が None でないことを確認してください
グラデーションが単一のフラットカラーとして描画されますGradientAxialShading.start と end の Point 値が同一か、非常に近いですstart と end が意図したグラデーション軸上で視覚的に異なる2点を示すことを確認してください

FAQ

通常の使用時に Point、Rectangle、または Matrix を直接インポートする必要がありますか？

通常はそうではありません — プロパティの型（たとえば PDF3DAnnotation.rect や PDF3DView.ctm）として最も頻繁に目にすることになるでしょう。ゼロから構築する必要はあまりありませんが、スタンドアロンの値が必要なときに直接構築することができないわけではありません。

Color と ColorPrimitive の違いは何ですか？

Color は RGB スタイルのチャンネルデータを保持し、グラデーション塗り用のオプション pattern_color_space を持ちます。ColorPrimitive ははるかに小さい型で、transparency のみの値を公開します。

Matrix を使って 2 つの変換を組み合わせるにはどうすればよいですか？

matrix_a.multiply(matrix_b) を呼び出すと、合成された Matrix が返ります。完全な行列乗算を構築せずにシンプルな平行移動を行う場合は translate(x, y) を使用してください。

Matrix3D は 3D アノテーション以外で使用されていますか？

このクラスタ内では、Matrix3D が PDF3DView.ctm の型として表示されます — 保存された 3D ビューに関連付けられた現在の変換行列です。

API Reference 概要

クラス/メソッド説明
Point2D座標（x, y の浮動小数点プロパティ）
Point3D3D座標 (x, y, z float プロパティ)
Rectangle位置とサイズ (x, y, width, height, 計算された left, bottom, right)
Matrix2Dアフィン変換 (a–f コンポーネント); translate / multiply メソッド
Matrix3D3D変換行列 (m11–m33 回転/スケールブロック, dx/dy/dz 平行移動)
Colorオプションのpattern_color_spaceグラデーション塗りつぶしを持つカラー値
ColorPrimitivetransparency を提供する最小限のカラー・プリミティブ
GradientAxialShading2つのColor値間の軸（線形）グラデーションで、2つのPoint端点に沿って

参照

 日本語