レイヤ上の位置指定 - HuTime API マニュアル

１．概要

図形、文字列、画像などのレイヤ上のオブジェクトを描画するためには、Positionクラス（HuTime.PositionBaseクラスの派生クラス）のオブジェクトでレイヤ上の位置を指定する。HuTimeには、データなどを配置するためのTV座標系と、画面上の描画位置を示すXY座標系があり、位置指定は、これらの座標系を組み合わせて行う。位置の指定方法には、絶対位置の指定と相対位置の指定があり、最初に絶対位置を指定し、必要に応じてこれを基点とした相対位置を指定する。また、特定の座標を示すための定数や、出力されるCanvas上の座標値を整数化するためのクラスが用意されている。

Positionクラス（HuTime.PositionBaseクラスの派生クラス）の一覧。PositionBaseは抽象クラスとして定義されており、実際には使用しない。

２．絶対位置

基本となる位置で、座標系の違いに応じて、２つのクラスがある。グラフや年表上のレコードを表示する場合は、TV座標系のHuTime.TVPositionを用いる。TV座標系で位置が指定された場合、画面の表示方向（タテ表示、ヨコ表示）、t軸の表示範囲、v軸の表示範囲、レイヤの高さなど、表示状態の変化に対応して画面上の表示位置が変化する。一方、レイヤのタイトルなど、画面上の位置が固定されているものにはXY座標系のHuTime.XYPositionを用いる。XY座標系で指定された位置は、表示状態が変化しても画面上の表示位置が変わらない。

コンストラクタ

HuTime.TVPosition(t, v)

TV座標系の絶対位置。

t: 型：数値; 絶対位置のt値。
v: 型：数値; 絶対位置のv値

HuTime.XYPosition(x, y)

XY座標系の絶対位置。

x: 型：数値; 絶対位置のx値。
y: 型：数値; 絶対位置のy値

Differences of displayed position between TV and XY cordinates according to direction of t axis (in case of absolute position)

レイヤ上の絶対位置の表示方向による表示位置の違い。TV座標系で指定された絶対位置（青い丸）は、表示方向に応じた画面上の表示位置を示す。一方、XY座標系系で指定された絶対位置（赤い丸）は、表示方向に拠らず、画面上の表示位置は同じである。

Differences of displayed position between TV and XY cordinates according to displayed t range (in case of absolute position)

t軸の表示範囲の変更（移動、および、拡大・縮小）に伴う表示位置の変化。TV座標系で指定された絶対位置（青い丸）は、t軸の表示範囲に応じて画面上の表示位置が変化する。一方、XY座標系で指定された絶対位置（赤い丸）は、t軸の表示範囲が変更されても画面上の表示位置は変わらない（再描画されると元の位置に戻る）。

サンプルコード（実行例はこちら）。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script type="text/javascript" src="http://web.hutime.org/js/HuTime.min.js"></script>
  <title>Sample Code</title>
</head>
<body>
<div id="timeline"></div>
<script type="text/javascript">
  var ht = new HuTime();
  var pnls = new HuTime.PanelCollection(100, 200);
  ht.appendPanelCollection(pnls, document.getElementById("timeline"));

  var pnl = new HuTime.TilePanel(100);
  pnls.appendPanel(pnl);

  var lyr = new HuTime.Layer(100, 0, 0, 100, 0);
  lyr.vForX = HuTime.VForX.bottomForLeft;
  pnl.appendLayer(lyr);

  var posTV = new HuTime.TVPosition(140, 20);
  var posXY = new HuTime.XYPosition(40, 30);
  var objTV = new HuTime.Circle(new HuTime.FigureStyle(0, "blue", "blue"), posTV, 10);
  lyr.appendObject(objTV);
  var objXY = new HuTime.Circle(new HuTime.FigureStyle(0, "red", "red"), posXY, 10);
  lyr.appendObject(objXY);

  ht.redraw(100, 200);
</script>
<p>
  <input type="radio" title="LtoR" name="displayMode" value="0" onClick="radioChange(event)" checked="checked" />Horizontal　
  <input type="radio" title="TtoB" name="displayMode" value="2" onClick="radioChange(event)" />Vertical
</p>
<script type="text/javascript">
  radioChange = function(ev) {
    pnls.displayMode = parseInt(ev.target.value);
    ht.redraw();
  };
</script>
</body>
</html>

３．相対位置

下記のクラスを用い、Positionオブジェクトで指定された位置を基準にした相対的な位置を指定する。相対値は、TV座標系またはXY座標系で指定するが、基準位置の座標系と一致させる必要はない。例えば、グラフや年表上のレコードにラベルや注釈を加えるには、レコードの表示位置を基準位置とし、そこからの相対位置でラベルや注釈の表示位置を指定する。この場合、レコードの位置はTV座標系で指定されるが、相対位置は、TV座標系でもXY座標系でも指定できる。

コンストラクタ

HuTime.RelativeTVPosition(position, ofsT, ofsV)

TV座標系の相対位置。

position: 型：HuTime.PositionBase; 相対位置のための基準位置。
ofsT: 型：数値; 基準位置からのt値方向の変位。
ofsV: 型：数値; 基準位置からのv値方向の変位。

HuTime.RelativeXYPosition(position, ofsX, ofsY)

XY座標系の相対位置。

position: 型：HuTime.PositionBase; 相対位置のための基準位置。
ofsX: 型：数値; 基準位置からのx値方向の変位。
ofsY: 型：数値; 基準位置からのy値方向の変位。

Differences of displayed position between TV and XY cordinates according to direction of t axis (in case of relative position)

表示方向による相対位置の表示位置の違い。TV座標系で指定された絶対位置（青塗りの丸）を基準に、TV座標による相対位置（青枠の丸）と、XY座標による相対位置（赤枠の丸）が示されている。また同様に、XY座標系で指定された絶対位置（赤塗の丸）を基準に、TV座標による相対位置（青枠の丸）と、XY座標による相対位置（赤枠の丸）が示されている。TV座標による相対位置は、表示方向に応じた基準位置との関係により、画面上の位置は異なる。一方、XY座標による相対位置は、表示方向に拠らず、基準位置との位置関係は同じである。

Differences of displayed position between TV and XY cordinates according to displayed t range (in case of relative position)

t軸の表示範囲の変更（移動、および、拡大・縮小）に伴う描画位置の変化。TV座標系で指定された相対位置（青枠の丸）は、t軸の表示範囲の移動や拡大・縮小に応じて、基準位置との関係（基準位置からの距離）が変化する。一方、XY座標系で指定された相対位置（赤枠の丸）は、t軸の表示範囲が変更されても基準位置との位置関係は変わらない（再描画されると元の位置に戻る）。

サンプルコード（実行例はこちら）。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script type="text/javascript" src="http://web.hutime.org/js/HuTime.min.js"></script>
  <title>Sample Code</title>
</head>
<body>
<div id="timeline"></div>
<script type="text/javascript">
  var ht = new HuTime();
  var pnls = new HuTime.PanelCollection(100, 200);
  ht.appendPanelCollection(pnls, document.getElementById("timeline"));

  var pnl = new HuTime.TilePanel(100);
  pnls.appendPanel(pnl);

  var lyr = new HuTime.Layer(100, 0, 0, 100, 0);
  lyr.vForX = HuTime.VForX.bottomForLeft;
  pnl.appendLayer(lyr);

  var posTV = new HuTime.TVPosition(140, 20);
  var posXY = new HuTime.XYPosition(40, 30);
  var objTV = new HuTime.Circle(new HuTime.FigureStyle(0, "blue", "blue"), posTV, 10);
  lyr.appendObject(objTV);
  var objXY = new HuTime.Circle(new HuTime.FigureStyle(0, "red", "red"), posXY, 10);
  lyr.appendObject(objXY);

  var posTVrTV = new HuTime.RelativeTVPosition(posTV, -10, 0);
  var objTVrTV = new HuTime.Circle(new HuTime.FigureStyle(2, "blue"), posTVrTV, 10);
  lyr.appendObject(objTVrTV);
  var posTVrXY = new HuTime.RelativeXYPosition(posTV, 10, 0);
  var objTVrXY = new HuTime.Circle(new HuTime.FigureStyle(2, "red"), posTVrXY, 10);
  lyr.appendObject(objTVrXY);

  var posXYrTV = new HuTime.RelativeTVPosition(posXY, -10, 0);
  var objXYrTV = new HuTime.Circle(new HuTime.FigureStyle(2, "blue"), posXYrTV, 10);
  lyr.appendObject(objXYrTV);
  var posXYrXY = new HuTime.RelativeXYPosition(posXY, 10, 0);
  var objXYrXY = new HuTime.Circle(new HuTime.FigureStyle(2, "red"), posXYrXY, 10);
  lyr.appendObject(objXYrXY);

  ht.redraw(100, 200);
</script>
<p>
  <input type="radio" title="LtoR" name="displayMode" value="0" onClick="radioChange(event)" checked="checked" />Horizontal　
  <input type="radio" title="TtoB" name="displayMode" value="2" onClick="radioChange(event)" />Vertical
</p>
<script type="text/javascript">
  radioChange = function(ev) {
    pnls.displayMode = parseInt(ev.target.value);
    ht.redraw();
  };
</script>
</body>
</html>

４．座標を示す定数

レイヤの上端、左端など、座標の特定の位置を示すための定数が以下のとおり定義されている。これらは、それぞれの座標系で座標を指定する際に、数値の代わりに用いることができる。定数で指定された座標は、t軸の表示範囲が変更されても、定数が示す位置に留まる（再描画されると元の位置に戻る）。

座標系	座標軸	定数	コンストラクタのパラメータ
TV座標系	t軸	HuTime.PositionConstant.tMin	現在表示されているt軸の範囲の最小値
	t軸	HuTime.PositionConstant.tMax	現在表示されているt軸の範囲の最大値
	v軸	HuTime.PositionConstant.vMin	現在表示されているv軸の範囲の最小値
	v軸	HuTime.PositionConstant.vMax	現在表示されているv軸の範囲の最大値
XY座標系	x軸	HuTime.PositionConstant.xLeft	レイヤの左端
	x軸	HuTime.PositionConstant.xRight	レイヤの右端
	y軸	HuTime.PositionConstant.yTop	レイヤの上端
	y軸	HuTime.PositionConstant.yBottom	レイヤの下端

Differences of displayed position between TV and XY cordinates according to direction of t axis (in case of position constant)

表示方向による、定数で指定された座標の表示位置の違い。TV座標系で指定された位置（青い丸）は、表示方向に応じた画面上の位置に表示される。一方、XY座標系で指定された位置（赤い丸）は、表示方向に拠らず、画面上の位置は同じである。

サンプルコード（該当部分のみ）。

var pos1 = new new HuTime.TVPosition(HuTime.PositionConstant.tMax, 20);
var pos2 = new HuTime.XYPosition(40, HuTime.PositionConstant.yTop);

５．座標値の整数化

HTML5 Canvasで位置指定（XY座標）に小数を含む値を用いた場合、アンチエイリアス処理により描画が不鮮明になる場合がある。HuTime上でこれを避けるには、Positionオブジェクトが出力するcanvas上の座標値を整数化する機能を持つPositionクラスで元のPositionクラスをラッピングする。整数化の方法により、3種類のクラスがある。これらのクラスは、TV座標系、XY座標系いずれのPositionクラスにも適用可能である。

コンストラクタ

HuTime.PositionFloor(position)

切り捨てにより整数化した画面上の座標位置。

position: 型：HuTime.PositionBase; 整数化する位置。

HuTime.PositionFloor(position)

切り上げにより整数化した画面上の座標位置。

position: 型：HuTime.PositionCeil; 整数化する位置。

HuTime.PositionRound(position)

四捨五入により整数化した画面上の座標位置。

position: 型：HuTime.PositionBase; 整数化する位置。

サンプルコード（該当部分のみ）。

var pos1 = new HuTime.PositionFloor(new HuTime.TVPosition(140, 20));
var pos2 = new HuTime.PositionCeil(new HuTime.RelativeTVPosition(new HuTime.XYPosition(40, HuTime.PositionConstant.yTop), -10, 0));

６．使用事例

レイヤ上の位置指定について、いくつかの使用事例を挙げる。

使用事例	位置指定の方法
散布図の特定の点に注釈を表示する。	TV座標の絶対位置（HuTime.TVPosition）で指定された点の位置を起点とし、XY座標の相対位置（HuTime.RelativeXYPosition）で注釈の表示位置を指定する。
棒グラフの先端にエラーバーを表示する。	TV座標の絶対位置（HuTime.TVPosition）で指定された棒の先端位置を起点とし、TV座標の相対位置（HuTime.RelativeTVPosition）でエラーバーの始点と終点を指定する。
レイヤの左上に表題を表示する。	左端と上端を示す定数（HuTime.PositionConstant.xLeft, HuTime.PositionConstant.yTop）により、XY座標の絶対位置（HuTime.XYPosition）でレイヤ左上を指定する。マージンを設定する場合は、XY座標の相対位置（HuTime.RelativeXYPosition）で指定する。

マニュアルの目次へ戻る