6-3. Canvas3D

Table of Contents

• Point, Transform
• 送信
  • Geometry (3次元)
    • Line
    • Plane
    • Box
    • Circle
    • Cylinder
    • Sphere
  • オプション
• 受信
  • Entry, Event

Since

1.4 1.3 1.1

See also

• C++ webcface::Canvas3D (webcface/canvas3d.h)
• JavaScript Canvas3D
• Python webcface.Canvas3D

3D空間上のオブジェクト配置データを送受信する型です。

Point, Transform

WebCFaceでは3次元の座標を表すクラスとして webcface::Point, 座標変換(平行移動してから回転)を表すクラスとして webcface::Transform があります。 (Canvas2Dでの2次元の座標を表すクラスと共通です)。

Note

WebCFaceの内部では3次元の回転はz-y-xの順で回転するオイラー角で表現するのを標準としています。

• C++ Point, Transformオブジェクトからはpos(), rot() 2.5 rotEuler() で座標と回転角を取得できます。

  Point p{1, 2, 3};
  std::cout << p.pos(0) << ", " << p.pos(1) << ", " << p.pos(2); // 1, 2, 3 (x, y, z 座標)
  Transform r{{1, 2, 3}, rotFromEuler(std::numbers::pi / 2, 0, 0)};
  std::cout << r.pos(0) << ", " << r.pos(1) << ", " << r.pos(2); // 1, 2, 3 (x, y, z 座標)
  std::cout << r.rotEuler()[0]; // pi / 2 (z軸回り)

  • Transform のコンストラクタには、3次元の平行移動(x, y, zの値)と、 3次元の回転を指定します。
    • 2.5 3次元の回転は webcface::rotX(), rotY(), rotZ(), rotFromEuler(), rotFromMatrix(), rotFromQuat(), rotFromAxisAngle() を使って指定します。
    • webcface::rotFromEuler() や Transform::rotEuler() ではデフォルトではz-y-xの順で回転する系のオイラー角 (webcface::AxisSequence::ZYX) を扱いますが、引数で別の系(全12種類)も指定可能です。 詳細は AxisSequence の説明を参照
  • webcface::identity() は原点、回転なしのTransformを返します。
  • 2.5 回転なしで平行移動のみのTransformを得るには、 webcface::translate() を使ってください。 平行移動なしで回転のみのTransformを得るには、 rotFrom〜 系の関数で得られる Rotation クラスがTransformの代わりとして使えます(またはTransformにキャストできます。)
  • 2.5 Point同士は加算、減算ができます。 また、実数の乗算、除算ができます。
  • 2.5 Transform * Transform, Transform * Point の乗算ができます。 右辺の座標系全体を、左辺の値の分だけ回転移動してから平行移動したものになります。
    • 同じ効果を持つ関数として Transform::appliedTo() があります。
  • 2.5 Transform::inversed() で逆変換が得られます。
  • 2.5 Point同士、Transform同士は ==, !=での比較ができます。
    • 完全一致での判定ではなく、各要素の差がそれぞれ 1e-8 未満であればtrueになります。
• JavaScript Point, Transform オブジェクトからはpos, rotで座標と回転角を取得できます。

  import { Point, Transform } from "webcface";
  const p = new Point([1, 2, 3]);
  console.log(p.pos[0]); // 1 (x座標)
  const r = new Transform([1, 2, 3], [Math.PI / 2, 0, 0]);
  console.log(r.pos[0]); // 1 (x座標)
  console.log(r.rot[0]); // pi / 2 (z軸回り)

  また、Transform.rotMatrix で3x3の回転行列、Transform.tfMatrix で4x4の同次変換行列が得られます。
• Python webcface.Point, webcface.Transform オブジェクトからはpos, rot 3.0 rot_euler() で座標と回転角を取得できます。

  p = webcface.Point([1, 2, 3])
  print(p.pos) # (1, 2, 3) (x, y, z 座標)
  r = webcface.Transform([1, 2, 3], webcface.rot_from_euler([math.pi / 2, 0, 0]))
  print(p.pos) # (1, 2, 3) (x, y, z 座標)
  print(r.rot_euler()[0]) # pi / 2 (z軸回り)

  • Transform のコンストラクタには、3次元の平行移動(x, y, zの値)と、 3次元の回転を指定します。
    • 3.0 3次元の回転は webcface.rot_x(), rot_y(), rot_z(), rot_from_euler(), rot_from_matrix(), rot_from_quat(), rot_from_axis_angle() を使って指定します。
    • webcface.rot_from_euler() や Transform.rot_euler() ではデフォルトではz-y-xの順で回転する系のオイラー角 (AxisSequence.ZYX) を扱いますが、引数で別の系(全12種類)も指定可能です。 詳細は webcface.AxisSequence の説明を参照
  • webcface.identity() は原点、回転なしのTransformを返します。
  • 3.0 回転なしで平行移動のみのTransformを得るには、 webcface.translate() を使ってください。 平行移動なしで回転のみのTransformを得るには、 rot_from〜 系の関数で得られる Rotation クラスがTransformの代わりとして使えます
  • Point同士は加算、減算ができます。 また、int,floatと乗算、除算ができます。
  • 3.0 Transform * Transform, Transform * Point の乗算ができます。 右辺の座標系全体を、左辺の値の分だけ回転移動してから平行移動したものになります。
    • 同じ効果を持つ関数として Transform.applied_to_point(), applied_to_transform() があります。
  • 3.0 Transform.inversed() で逆変換が得られます。
  • Point同士、Transform同士は ==, !=での比較ができます。
    • 3.0 完全一致での判定ではなく、各要素の差がそれぞれ 1e-8 未満であればtrueになります。
  • 引数にPointやTransformをとる関数では、webcface.Point に変換することなく [1, 2] や [[1, 2], pi / 2] のようなリストのままでも使えるものもあります。

送信

使い方はViewとだいたい同じになっています。

• C++ Client::canvas3d からCanvas3Dオブジェクトを作り、 Viewと同様に Canvas3D::add() または operator<< で要素を追加し、 最後にCanvas3D::sync()をしてからClient::sync()をすることで送信されます。

  Note

  1.9 add関数の仕様を変更し << 演算子も実装して、Viewと同じ使い方になりました

  例

  webcface::Canvas3D world = wcli.canvas3D("omniwheel_world");
  // world.init(); // ←オブジェクトcanvasを新規に構築せず繰り返し使いまわす場合は必要
  world << webcface::plane(webcface::identity(), 3, 3)
              .color(webcface::ViewColor::white);
  world << webcface::box({-1.5, -1.5, 0}, {1.5, -1.5, 0.1})
              .color(webcface::ViewColor::gray);
  world << webcface::box({-1.5, 1.5, 0}, {1.5, 1.5, 0.1})
              .color(webcface::ViewColor::gray);
  world << webcface::box({-1.5, -1.5, 0}, {-1.5, 1.5, 0.1})
              .color(webcface::ViewColor::gray);
  world << webcface::box({1.5, -1.5, 0}, {1.5, 1.5, 0.1})
              .color(webcface::ViewColor::gray);
  // RobotModel のドキュメントを参照
  world << wcli.robotModel("omniwheel")
              .origin(...)
              .angle("line_rotation", -i);
  world.sync(); // ここまでにcanvasに追加したものをクライアントに反映
  wcli.sync();

  

  C++ではCanvas3Dのデストラクタでも自動的にCanvas3D::sync()が呼ばれます。

  Note

  Canvas3Dオブジェクトをコピーした場合、Canvas3Dオブジェクトの内容はコピーされるのではなく共有され、そのすべてのコピーが破棄されるまでsync()は呼ばれません。

• JavaScript Client::canvas3D からCanvas3Dオブジェクトを作り、 set()の引数に要素をまとめてセットして使います。

  wcli.canvas3D("hoge").set([
      ...
  ]);

• Python Client.canvas3d からCanvas3Dオブジェクトを作り、 Canvas3D.add() で要素を追加し、 最後にCanvas3D.sync()をしてからClient.sync()をすることで送信されます。

  with構文を使って with wcli.canvas3d("hoge") as canvas: などとするとwithを抜けるときに自動でcanvas.sync()がされます。

Note

Viewと同様、Canvas3Dの2回目以降の送信時にはWebCFace内部では前回からの差分のみが送信されます

Canvas3Dに追加できる要素として、Geometry(後述)、RobotModel があります。

Geometry (3次元)

3次元の図形を表示するにはGeometryを指定します。 一部の図形は2次元のGeometryと共通のインタフェースになっています。

• C++

  Since

  1.9

  webcface::geometries 名前空間に定義されています。

  using namespace webcface::geometries;

  をすると便利かもしれません

  Note

  namespace geometries はinlineなので、 webcface:: の名前空間でもアクセス可能です

  各要素はそれぞれの関数から webcface::Canvas3DComponent または webcface::TemporalComponent のオブジェクトとして得られます。
• JavaScript JavaScriptでは geometries オブジェクト内にそれぞれの要素を表す関数があります

  import { geometries } from "webcface";

• Python Pythonでは webcface.geometries モジュール内にあり、

  from webcface.geometries import *

  とすることもできます

Line

指定した2点間に直線を引きます

line(Point begin, Point end)

Plane

originのxy平面上に、originを中心として幅(x方向の長さ)がwidth, 高さ(y方向の長さ)がheightの長方形を描画します

plane(Transform origin, double width, double height)

webcface内部では2次元の Rect と同じ扱いです

Box

指定した2点を頂点とし、各辺がx, y, z軸に平行な直方体を描画します

box(Point vertex1, Point vertex2)

Circle

originのxy平面上に、originを中心として半径radiusの円を描画します

circle(Transform origin, double radius)

Cylinder

originのyz平面上にoriginを中心として半径radiusの円を描画し、 それをx軸方向にlength押し出した円柱を描画します

cylinder(Transform origin, double radius, double length)

Sphere

originを中心とし半径radiusの球を描画します

sphere(Point origin, double radius)

オプション

各要素には以下のオプションを指定することができます。 (要素の種類によっては効果がないものもあります)

• origin: 図形の位置を移動・回転します。
  • それぞれのgeometryに対しても位置を指定することができますが、 それに加えてoriginを指定した場合最終的な座標は origin * 図形の座標 になります
• color: 図形の枠線の色を変更します。
• id: 2.53.0 Viewのbuttonなどと同様です。
  • 指定する場合は一意な文字列を指定してください。

• C++ rect(...).color(...) などのようにメソッドチェーンすることで各要素にオプションを設定できます。 詳細は webcface::TemporalCanvas3DComponent のリファレンスを参照してください。

  色はViewと同様 webcface::ViewColor のenumで指定します。

• JavaScript rect(..., { color: ..., })) などのように、オプションはそれぞれ関数の引数にオブジェクトで渡すことができます。

• Python canvas3d.add(box(...), color=...) などのように、add() の引数にキーワード引数を渡すことでオプションを設定できます。

  色はViewと同様 ViewColor のenumで指定します。

受信

Viewなどと同様、Member::canvas3D() でCanvas3Dクラスのオブジェクトが得られ、 Canvas3D::tryGet() で値のリクエストをするとともに受信した値を取得できます。

Canvas3Dデータは webcface::Canvas3DComponent (JavaScript Canvas3DComponent)

のリストとして得られ、 Canvas3DComponentオブジェクトから各種プロパティを取得できます。

Entry, Event

いずれも使い方は Value と同様なのでそちらを参照してください

Previous	Next
6-2. Image	6-4. RobotModel