rgl の概要

このドキュメントについて

このドキュメントは R Markdown で書かれており、制作には knitr パッケージを使用しています。 rgl のバージョン 0.106.8 に対応しています。

ハイライトされた関数名のほとんどは HTML リンクです。 内部リンクはどのブラウザでも動作します。 ヘルプトピックへのリンクは、R のヘルプシステムから vignette を表示した場合に動作します。

このドキュメントには WebGL の図が含まれています。 これらを表示するには、ブラウザで Javascript と WebGL を有効にする必要があります。 一部の古いブラウザではサポートされていないかもしれません。テストと議論へのリンクは https://get.webgl.org をご覧ください。

原始的な図形

古典的なグラフィックスに points や lines があるように、rgl には現在のアクティブなプロットにグラフィカルな要素を追加するための低レベルの関数がいくつかあります。 primitive な図形とは、OpenGLにネイティブなものです。

上記の各関数は引数 x, y, z を取りますが、ここでも xyz.coords を使って柔軟に対応しています。 また、必要に応じて連続したエントリーをグループ化します。 例えば、triangles3d 関数は、連続した3つの点を三角形の頂点として受け取ります。

これらの関数を使って、現在のグラフに注釈を付けたり、ゼロから図形を作成したりすることができます。

構築された図形

rgl にはプリミティブから構築するオブジェクトもいくつかあります。

軸とその他の “装飾”

以下の低レベル関数は、グラフの外観を制御します。:

例えば、3つのランダムな三角形をプロットするには、次のようにします。

triangles3d(cbind(x=rnorm(9), y=rnorm(9), z=rnorm(9)), col = "green")
decorate3d()
bg3d("lightgray")

aspect3d(1,1,1)

上記の *3d 関数の他に、さらに低レベルの関数として

があります。
これらの関数は、上位の *3d 関数とうまく連携できないので、使用しないようにしてください。 詳しくは ?r3d のヘルプトピックを参照してください。

照明（ライティング）

ほとんどのシーンでは、オブジェクトは「照明」されています。つまり、オブジェクトの見た目は、シーン内のライトとの相対的な位置や方向に依存します。 通常、ライト自体は表示されませんが、オブジェクトへの影響は表示されます。

照明の位置と特性を指定するには、light3d 関数を使用します。 照明は無限に遠くにある場合もあれば、シーンの中に埋め込まれている場合もあります。 照明の特性には、ambient、diffuse、specular の各成分があり、すべてのデフォルトは白です。 デフォルトでは白になります。 ambient 成分は、どの方向から見ても同じように見えます。 diffuse 成分は，表面と光の間の角度に依存し，specular 成分は，見る人の位置も考慮します．

関数 rgl.light は、異なるデフォルトを持つ下位の関数です。 通常は light3d を使用してください。

物質（マテリアル）

rgl で使用されるメンタルモデルは、シーンで表示されているオブジェクトは、空間上の物理的なオブジェクトであり、光がどのように反射するか（または光がどのように照射されるか）に影響を与える材料特性を持っているというものです。 これらは主に material3d 関数や、それに渡される他の関数の引数によって制御されます。

material3d の呼び出しで設定できるマテリアルのプロパティについては、?material3d のヘルプページで詳しく説明されています。 ここではその概要を説明します。

その他のプロパティとしては、“texmipmap”, “texmagfilter”, “texminfilter”, “texenvmap”, “fog”, “point_antialias”, “line_antialias”, “depth_mask”, “depth_test”, “polygon_offset”などがあります。 詳細は the help page を参照してください。

テクスチャ

前節で説明したように、マテリアルのプロパティの一つに「テクスチャ」があります。これは、サーフェイスに表示する画像を含むビットマップファイル（.png 形式）の名前です。 テクスチャの詳細については、このセクションを参照してください。

OpenGL では、ポリゴンの各頂点はビットマップ内の特定の位置に関連付けることができます。 ポリゴンの内部はビットマップ内で補間されます。 これらの座標を指定するために、rgl の関数には2つの規則があります。

プリミティブを指定する関数 (triangles3d など) は，オプションの行列引数 texcoords を受け取ります。 これは、ビットマップ内の s (水平方向) と t (垂直方向) の位置を、頂点ごとに1行の列で指定します。 座標は、左下が (0,0) で、右上が (1,1) です。 例えば、(1.1, 1.1) は、(0.1, 0.1) と同じ点を指定することになります。

surface3d のように、各頂点座標の行列を受け取る他の関数は、引数 texture_s と texture_t で、テクスチャ座標も行列として受け取ります。

例えば、以下のコードでは、2Dプロットの4つのコピーを四角形に表示しています。

filename <- tempfile(fileext = ".png")
png(filename = filename)
plot(rnorm(1000), rnorm(1000))
dev.off()

## quartz_off_screen 
##                 2

open3d()

## null 
##    9

xyz <- cbind(c(0,1,1,0), 0, c(0,0,1,1))
quads3d(xyz, texture = filename, texcoords = xyz[,c(1, 3)]*2, col = "white", specular = "black")

フォント

rgl では、テキストの描画にベースグラフィックスと同じ考え方を採用しており、"sans", "serif", "mono" というフォントファミリーがあり、これらの種類のテキストを描画します。 rgl では、"symbol" のフォントファミリーはサポートされていません。

新しいフォントファミリーは、低レベルの関数 rglFonts を使って定義することができます。 より簡単には、高レベルの関数 rglExtrafonts を使って定義します。 後者の関数を使用するには、extrafont パッケージがインストールされている必要があります。

par3d: その他のグラフィックパラメータ

par3d 関数は、古典的なグラフィックスの par 関数を模したもので、さまざまな rgl 内部パラメータを設定したり、読み出したりします。 完全に読み取り専用のパラメータもあれば、ウィンドウが開かれた時点で固定されているもの、いつでも変更可能なものもあります。

デフォルトの設定

r3dDefaults のリストとgetr3dDefaultsの関数は、open3dで開いた新しいウィンドウのデフォルトを制御します。 この関数は、ユーザのグローバル環境にある変数を探し、見つからなければ rgl 名前空間にある変数を探します。 これにより、ユーザは新しいウィンドウのデフォルト設定をオーバーライドすることができます。

見つかると、r3dDefaults リストが par3d パラメータの初期値を提供し、コンポーネント "material" と "bg" における material3d と bg3d のデフォルト値をそれぞれ提供します。

特定の立体

特定の形状を生成する関数です。 オプションの引数で色や変形などの属性を指定することができます。

cols <- rainbow(7)
layout3d(matrix(1:16, 4,4), heights=c(1,3,1,3))
text3d(0,0,0,"tetrahedron3d"); next3d()
shade3d(tetrahedron3d(col=cols[1])); next3d()
text3d(0,0,0,"cube3d"); next3d()
shade3d(cube3d(col=cols[2])); next3d()
text3d(0,0,0,"octahedron3d"); next3d()
shade3d(octahedron3d(col=cols[3])); next3d()
text3d(0,0,0,"dodecahedron3d"); next3d()
shade3d(dodecahedron3d(col=cols[4])); next3d()
text3d(0,0,0,"icosahedron3d"); next3d()
shade3d(icosahedron3d(col=cols[5])); next3d()
text3d(0,0,0,"cuboctahedron3d"); next3d()
shade3d(cuboctahedron3d(col=cols[6])); next3d()
text3d(0,0,0,"oh3d"); next3d()
shade3d(oh3d(col=cols[7]))

非常に大きな多面体のコレクションが Rpolyhedra パッケージに含まれています。

新しい図形の生成

これらの関数は新しい形状を生成します。:

関連する関数として、triangulate があります。 これは、2次元の多角形を受け取り、“ear-clipping” アルゴリズムを用いてそれを三角形に分割します。

汎用関数 as.mesh3d は、他のコードが生成したデータ構造をメッシュ構造に変換するために提供されています。 現在、以下のクラスがサポートされています。:

デフォルトの as.mesh3d.default メソッドは、頂点の行列からメッシュを構築するシンプルな方法です。mergeVertices (単独でも使用可能) を使用して、行列内の繰り返される頂点をマージすることができ、addNormals を使用して滑らかな外観を得ることができます。

関数 tmesh3d, qmesh3d は廃止されました。 代わりに mesh3d を使用してください。

シェイプの基本的なクラス構造は次のとおりです。

"shape3d"が基本的な抽象型です。 このクラスのオブジェクトは、 shade3d (面の影をつける)、 wire3d (辺を描く)、 dot3d (各頂点に点を描く)で表示できます。

"mesh3d"はその子孫型です。 この型のオブジェクトには以下のフィールドがあります。:

形状の輪郭抽出

これらの関数は、曲面上の関数の輪郭を計算してプロットしたり、関数の輪郭に沿ってオブジェクトをクリップしたりします。

形状の操作

これらの関数は、メッシュオブジェクトを操作、修正します。:

また、subdivision3dの個々のステップも利用できます。: r indexfns(c(“deform.mesh3d”, “divide.mesh3d”, “normalize.mesh3d”))`。 これらは主に内部利用を目的としています。

推奨方法

現在、rgl シーンをドキュメントに埋め込むための最良の方法は、R Markdownを使ってHTMLでドキュメントを作成することです。 ドキュメントの初期段階では、セットアップコードチャンクの一つに以下のようなコードがあるはずです。:

```{r echo=FALSE, include=FALSE}
library(rgl)
setupKnitr(autoprint = TRUE)
```

setupKnitr()を呼び出すと、rglコードが適切に処理されるように、knitrにいくつかのフックをインストールしたり、オプションを設定したりします。 autoprint = TRUE 引数は、rgl がドキュメント内で、コンソールで動作するのとほぼ同じように、あるいは knitr でベースグラフィックスが処理されるのと同じように動作させます。 高レベルの rgl 関数の値を印刷すると、プロットが出力に挿入されますが、それは低レベルの修正が完了した後になるでしょう。 例えば、このコードブロックは三角形と球体の両方を最後に1つのプロットで表示します。:

xyz <- matrix(rnorm(27), ncol = 3)
triangles3d(xyz, col = rainbow(9))
spheres3d(xyz, col = rainbow(9), radius = 0.1)

複雑な事情がある場合には、いくつかの違いがあります。

• このメカニズムは、rgl関数の呼び出しの結果が自動的にプリントされるかどうかに依存します。 呼び出しがループやその他のコードブロックの中にあって、自動印刷が行われない場合は、印刷させるために何らかの工夫が必要になります。 例えば、これは3つのプロットを印刷します。:

plots <- NULL
for (i in 1:3) {
  plot3d(rnorm(10), rnorm(10), rnorm(10))
  plots <- htmltools::tagList(plots, rglwidget())
  close3d()
}
plots

• また、rgl 関数が lowlevel() や highlevel() を使って、どの種類のプロットかを示す結果を返すかどうかにも依存します。 プロットを生成するために他のパッケージの関数を使用している場合には、印刷するためにこれらの関数のいずれかを明示的に呼び出す必要があるかもしれません。 関数が既存のプロットを変更するだけならば、lowlevel()を使い、新しいプロットを開始するならば、highlevel()を使います。 例えば、以下のようになります。

foreignHigh()   # Produces a high level plot, but doesn't return
                # an appropriate value
highlevel()
foreignLow()    # Modifies the previous plot
lowlevel()

これにより、コードチャンクの最後に、修正が完了したとみなされる出力が表示されます。

PDF 出力の作成

PDF プレビューアの中には、インタラクティブな 3D グラフィックをサポートしているものもありますが、ほとんどのものはサポートしていません。 R Markdown ドキュメント内の rgl シーンのスクリーンショットを PDF 出力で作成するには、上記の指示に従うだけです。 自動印刷はPDF出力を検出し、snapshot3dを使って挿入用のPNGファイルを作成します。 (他のフォーマットのグラフィックを挿入したい場合は、以下を参照してください。)

どうしてもインタラクティブな出力が必要な場合は、writeASY関数を参照してください。

プロットの手動挿入

前述の setupKnitr(autoprint = TRUE) メソッドは、あまり使いたくないかもしれません。 これは非常に新しく、まだバグがあるかもしれません。また、古いドキュメントを持っていて、そのように動作するように編集したくない場合もあるでしょう。

このような場合には、手動でプロットを挿入することができます。 U セットアップコードを見る

```{r echo=FALSE, include=FALSE}
library(rgl)
setupKnitr()
```

そして、プロットを挿入したいときはいつでもトップレベルで rglwidget() を呼び出します。

autoprint` を使用していない場合のデフォルトの動作には、他にもいくつかの違いがあります。

• デフォルトでは、各コードチャンクは以前のチャンクの rgl シーンを継続します。 クリーンなウィンドウを得るためには、明示的に open3d を呼び出す必要があります。

• また、デフォルトでは、チャンクの終了時に rgl ウィンドウは閉じられません。 これはおそらく問題ではありませんが、シーンが非常に大きい場合にはメモリ不足になる可能性があります。

古い方法

rgl のシーンをドキュメントに挿入するオリジナルの方法は、writeWebGL 関数を使って、ドキュメントに挿入する HTML コードを書くことでした。 その後、Sweaveとknitrのフックが追加されました。 これらはもうメンテナンスされていませんので、古い文書を更新して新しい方法を使うことをお勧めします。 これらを使用する必要がある場合は、writeWebGL, rgl.Sweave, hook_rgl のヘルプトピックで詳細を確認してください。 もし、これらのメソッドを使うことを推奨しているドキュメントを読んでいたら、作者にアップデートが必要であることを伝えてください。

ユーザーインタラクション

デフォルトでは、rgl はシーン内でのマウスのクリックを検出して処理し、それらを使って外観をコントロールします。 現在のハンドラーは以下のコードで確認できます。:

par3d("mouseMode")

##        left       right      middle       wheel 
## "trackball"      "zoom"       "fov"      "pull"

ラベル c("left", "right", "middle") は，3ボタンマウスのボタン，あるいは他のマウスのボタンのシミュレーションを意味する。 "wheel" はマウスのホイールのことです。

ボタンの動作は、一般的にはクリックやドラッグに相当します。 “mouseMode” で指定できるボタンやホイールの値は以下の通りです。

以下の機能は、シーン内での選択にマウスを使用します。

selectionFunction3d は，投影とマウスの選択領域の情報から，選択関数を生成します． これは上記の関数で内部的に使用されます。

rgl.select3d 関数は select3d の古いバージョンであり、 rgl.select は低レベルのサポート関数です。

アニメーション

rgl にはアニメーションを作成するためのいくつかの関数があります。 これらの関数は、現在の現実世界の時間に応じてシーンを更新する関数をベースにしており、それらの関数を繰り返し呼び出すことで実現しています。 これらの関数は:

There are three functions in rgl that support control of an rgl scene using the TCL/TK framework.

アニメーションをディスク上のファイルに出力する方法については、movie3d 関数を参照してください。 現在、アニメーションは rglwidget で書かれたHTMLではサポートされていませんが、 playwidget 関数で同等の機能が提供されています。

TCL/TKとの連携

rglには、TCL/TKフレームワークを使ったrglシーンの制御をサポートする3つの関数があります。

これらの関数は、以前は tkrgl パッケージに含まれていました (名前に tk のプレフィックスは付いていません)。 このパッケージは現在では非推奨となっています。

シーンのエクスポートとインポート

rgl には、シーンをディスクに書き出して他のソフトウェアで利用したり、読み込んだりするためのいくつかの関数が含まれています。

忠実度の高いものから低いものの順に、以下のような関数があります。:

また、3D情報を保存せずに、スナップショットなどのシーンの記録を保存する機能もあります。:

rgl.snapshot 関数は、snapshot3d() の低レベルバージョンです。 この関数は、rgl ディスプレイが画面上にあることを要求し、そこからコピーします。 関数 snapshot3d() は webshot2 パッケージを使おうとするので、ディスプレイがなくても動作します。 関数 rgl.Sweave.off, Sweave.snapshot は、Sweave の処理に関与しており、通常ユーザーが呼び出すことはありません。

デフォルトの表示

Rの中でrglシーンを表示する方法は2種類あります。 1つは専用のウィンドウで表示する方法です。 Unix系ではX11ウィンドウです。 Microsoft Windowsでは、ネイティブウィンドウです。 macOSでは、これをサポートするために、XQuartz システム（ https://www.xquartz.org 参照）をインストールする必要があります。

この表示を抑制するには、新しい rgl ウィンドウを開く前に options(rgl.useNULL = TRUE) を設定してください。 Rを起動する前にこの設定を行う方法については、rgl.useNULL関数のヘルプページを参照してください。

シーンを表示する新しい方法は、ブラウザのウィンドウや RStudio の Viewer ペインで WebGL を使用することです。 これを選択するには、options(rgl.printRglwidget = TRUE) を設定します。 シーンを変更する各操作は、印刷時に新しい WebGL 表示のトリガーとなる値を返します。 を表示します。

WebGL シーンの操作

シーンを Web ページにエクスポートするには、次のような方法があります。 また、古い方式もありますが、これはもうサポートされていません。

推奨される方法は、htmlwidgets フレームワークで動作します（http://www.htmlwidgets.org/ 参照）。 knitr の R Markdown ドキュメントで、rglwidget 関数を使います。 (チャンクオプションのwebgl=TRUEを使うこともできますが、rglwidget を明示的に使うことをお勧めします)。 この方法では、RStudio でも rgl のシーンを表示することができます。 また、rglシーン以外にも、様々なコントロールを表示することができますし、便利なユーティリティー関数もいくつかあります。:

これらの関数は、Shiny アプリで上記の方式で動作します。:

また、selectionFunction3d 関数は、Shiny を使用する際に、マウスのインタラクションに関与する可能性があります。

主に内部で使用される関数もあります。 elementId2Prefix, playwidgetOutput, renderPlaywidget, rglwidgetOutput, renderRglwidget, registerSceneChange. 詳細は，vignette User Interaction in WebGL に記載されています。 また，関数 lowlevel, highlevel, rglId は，関数の結果を自動的に印刷するためにマークする内部用の関数です． 最後に、実験的な関数である setUserShaders は、WebGLで手書きのシェーダーを使用することができます。

従来の方法では、writeWebGL 関数を使用して、シーンを HTML と Javascript のコードにエクスポートします。 これらの関数は、エクスポートされたシーンを操作するための HTML と Javascript を記述します。: propertySlider, clipplaneSlider, subsetSlider, toggleButton, propertySetter, subsetSetter, ageSetter, par3dinterpSetter, vertexSetter, matrixSetter. 代わりに、より新しい関数を使ってください。

シーンの操作

rgl は表示する全てのシーンの内部構造を保持しています。 以下の関数は、それらの情報を見つけたり、操作するためのものです。 関数のバージョンに *3d と rgl.* の両方がある場合、ほとんどのユーザーは *3d バージョンを使用する必要があります。

これらの関数は主にプログラミングを目的としており、対応する*3dの関数はありません。:

as.triangles3d の汎用関数は、triangles3d に渡すのに適した形式で座標を抽出することを目的としています。 現在、rglIdオブジェクトに対するメソッドが提供されています。

これらに加えて、ユーザーが滅多に呼び出すことのない関連関数がいくつかあります。rgl.init, rgl.open, rgl.quit

3次元ベクトルの扱い

ほとんどの rgl 関数は、内部的には「同次座標」で動作します。 このシステムでは、3次元の点は一般的に (x, y, z, w) と呼ばれる4つの座標で表されます。 w が 0 でない場合、対応するユークリッド点は (x/w, y/w, z/w) となり、w の 0 値は「無限遠の点」に対応します。 このシステムの利点は，並進や視点の移動を含むアフィン変換が，4×4の行列の乗算による線形変換になることです．

rgl には，同次座標を扱うための以下の関数があります。:

関数 GramSchmidt もありますが、これは主に内部使用のためのもので、3x3の行列のグラムシュミット直交化を行いますが、cyliner3d で使用するためにいくつかの特殊化を行っています。

他のパッケージとの連携

シーンをインタラクティブに回転させて特定のビューにし、それを lattice やベースグラフィックスで表示するのが便利な場合があります。 rglToLattice と rglToBase 関数はこれをサポートします。

例えば、まず火山のデータを rgl で表示します。:

persp3d(volcano, col = "green")

この表示はインタラクティブなものですが、lattice wireframe や base graphics persp の機能を使って、初期の表示を再現することができます。

lattice::wireframe(volcano, col = "green", 
           screen = rglToLattice())

angles <- rglToBase()
persp(volcano, col = "green", shade = TRUE,
      theta = angles$theta, phi = angles$phi)

なお、これらの機能を利用するには、orientlibパッケージが利用可能である必要があります。

pkgdown ウェブサイトの作成

pkgdown WebサイトでのRGLの使用方法については、“Using RGL in pkgdown Web sites” vignetteで説明しています。 ユーティリティー関数 in_pkgdown_example は、pkgdown が使用されていることを検出するために使用できます。

Javascriptとの連携

rglwidgetで作成されるWebGLディスプレイは、本パッケージに含まれる大量の Javascript コードに依存しています。 このコードの開発を支援するために、makeDependency 関数が書かれました。 Javascript を含む他のパッケージでも役に立つかもしれません。

その他の機能

このセクションでは、このドキュメントの他のカテゴリに当てはまらない雑多な機能を説明します。

setGraphicsDelay 関数は、macOS のバグと思われる現象を回避するためのものです。 rgl ウィンドウの後に標準のプロットウィンドウがすぐに開かれると、Rがクラッシュすることがあります。 この関数は、必要と思われるときに1秒の遅延を挿入します。