%表題   GRPH2 図形処理上位パッケージ
%
%履歴
%\Drireki{
%         91/11/05 西憲敬
%         91/12/10 林祥介
%         91/12/26 塩谷雅人
%         92/01/20 林祥介
%         92/02/25 塩谷雅人
%         92/03/16 塩谷雅人
%         92/04/13 塩谷雅人
%         92/04/22 林祥介   (4.1版)
%         95/04/19 塩谷雅人
%        }
%
%  \Dchapter{使用例 : 座標標軸ルーチン(U[XYZ]PACK,ULPACK,UCPACK)}
\Dchapterhead
\label{uxyzpk}

\section{概要}

ここでは U[XYZ]PACK/ULPACK/UCPACK の基本的な機能を,
いくつかの簡単なプログラム例で示す.
これらのデモプログラムは dcl-x.x/demo/grph2/uxyzpk の中にあるので,
参考にしていただきたい.
以下の例からも, 多種多様な座標軸が描けることはわかっていただけると思うが,
これらは序の口でまだまだ凝った座標軸を描くことができる.

\vspace{1em}
なお, 以下のデモプログラムでは,
GRPACK を用いて初期化や改ページの操作を
おこなっているので,
初期化ルーチン{\tt UZINIT}は呼ばなくてもよいようになっている.

\section{簡単な座標軸}

まず, 最も簡単な例を示そう.
X軸(左右方向) $\cdot$ Y軸(上下方向)とも線形座標軸
(均等な目盛り)を描く.
それぞれの軸には目盛りとラベル(目盛りのところにつける数字),
タイトル(軸の説明)をつける. さらに図のタイトルもつける.

\vspace{1em}
\begin{center}
\Depsf[10cm]{uxyzpk/uxyz01_0001.eps}\\
{\bf uxyz01.f:page1}\\
\end{center}

\vspace{1em}
座標軸関連のパッケージを使用するときに
必ずおこなわなければならないことは,
ウインドウとビューポートを適切に設定することである.
ウインドウとはユーザーの定義する座標系(U座標系: ここでは経度と緯度の座標系)
において定義される矩形領域である;
ビューポートとは仮想直角座標系(V座標系: ふつうは
最大 \ $[0.0,1.0]\times [0.0,1.0]$の閉じた領域に限定される
仮想的な座標系)
において定義される矩形領域である.
ウインドウとビューポートの対応関係は,
サブルーチン{\tt SGSWND}, {\tt SGSVPT}, {\tt SGSTRN}
(「GRPH1」マニュアル, 正規化変換の項参照)を用いて設定し,
{\tt SGSTRF} によって確定する
(Ver.4 までは, これらを {\tt SGSNTR}でおこなっていた).
この例では, X方向について,
経度 --180 $^{\circ}$ から +180 $^{\circ}$までを
描画可能な範囲の0.2から0.8 (左端が0.0, 右端が1.0)へ
対応させている;
またY方向について,
緯度 --90 $^{\circ}$ から +90 $^{\circ}$までを
0.3から0.7 (下端が0.0, 上端が1.0)へ対応させている.
(なおここでの描画可能な範囲は, コーナーマークで示される長方形領域に
最大内接するような正方形領域となっていることに注意していただきたい.)

\vspace{1em}
座標軸の作画を行なうにあたって最も基本的なことは,
1本の座標軸( 1本の軸とそれに付ける目盛りおよびラベルによって構成される)
を描くために作画ルーチンを1回呼ぶということである.
この例では, 上下左右あわせて4回作画ルーチン
( X軸は{\tt UXAXDV}, Y軸は{\tt UYAXDV} )を呼んでいる.
最初の引数 {\tt 'B'}, {\tt 'T'}, {\tt 'L'}, {\tt 'R'}によって,
それぞれ, 下, 上, 左, 右側の軸を描画することを指定する.
座標軸を描くこれらの場所は,
ウインドウとビューポートを設定した矩形領域のちょうど境界線上にある.
次の2つの引数は, 短い目盛りと長い目盛りをどんな間隔で打つか指定する.
単位はU座標系の値(ここでは, 経度, 緯度の値)である.
ラベルは長い目盛りのところにだけ描かれる.

\vspace{1em}
軸につけるタイトルおよび図のタイトルも同じように,
それぞれの軸についてタイトル描画ルーチンを呼ぶ.
小さい文字で描きたいときは {\tt UXSTTL}, {\tt UYSTTL}を,
大きい文字で描きたいときは {\tt UXMTTL}, {\tt UYMTTL}を用いる.
最初の引数によって, タイトルをつける軸の場所を指定する.
2番目の引数はタイトルとして描く文字列を指定する.
最後の引数はタイトルを描く位置を--1から+1までの実数値で指定する.
たとえばX軸については,
--1: 左寄せ, 0: センタリング, +1: 右寄せとなる;
またY軸については,
--1: 下寄せ, 0: センタリング, +1: 上寄せとなる.
この例のX軸(下側), Y軸(左側)のように,
同じ軸に対して2回以上タイトル描画ルーチンを呼んだときは,
重ならないようにだんだんと外側の方へずらして
タイトルが描かれる.
これによって, それぞれの軸に複数のタイトルをつけることができる.

\vspace{1em}
言われるままに作画してみて,
「はて, タイトルやラベルの大きさ,
目盛の長さなどは一体どのように決まっているのだろか?」と,
ほとんどのユーザーは不思議に思っていることであろう.
じつはこれらの属性は,
UZPACKのなかにあるサブルーチン
{\tt UZ}{\it p}{\tt GET/}{\tt UZ}{\it p}{\tt SET}の
管理する内部変数を参照して決められている.
実際, ユーザーがタイトルの大きさやその描く向きなどを
指定することは可能であるが,
ここではそのような立ち入った例は示さない.
ふつうの用途には, パッケージがあらかじめ用意している内部変数の値に
したがっていても, 充分に満足できる座標軸が作画可能なはずである.

\newpage
%\vspace{1em}
\Dproginput{uxyzpk/uxyz01.f}

\newpage

\section{対数座標軸}

次は対数座標軸の例である.
対数座標軸の描画は ULPACK が担当している.

\vspace{1em}
\begin{center}
\Depsf[10cm]{uxyzpk/uxyz02_0001.eps}\\
{\bf uxyz02.f:page1}\\
\end{center}

\vspace{1em}
対数座標軸を描くには, まず{\tt SGSTRN}によって
対数変換をあらわす変換関数番号を設定しなければならない.
すなわち{\tt SGSTRN}の引数として
2 (Y軸のみ対数変換), 3 (X軸のみ対数変換),
4 (X, Y軸とも対数変換) のどれかを指定する.

\vspace{1em}
対数座標軸を描くサブルーチンは{\tt ULXLOG}, {\tt ULYLOG}である.
ここでも, 最初の引数は座標軸を描く場所を指定する.
2つめの引数は, 1桁の範囲に描くラベルの数であり,
X軸については1となっていて, $10^n$のところにのみラベルが描かれている.
またY軸については3となっていて, $10^n$以外の
$2 \times 10^n$, $5 \times 10^n$にもラベルが描かれている.
3つめの引数は, 1桁の範囲に描く目盛りの数を表している.
ここでは1から9すべての目盛を打つように, 9を指定している.

\vspace{1em}
またX軸とY軸につけるタイトルは, それぞれ右寄せ(1.0),
上寄せ(1.0)して描いた.

\newpage
%\vspace{1em}
\Dproginput{uxyzpk/uxyz02.f}

\newpage

\section{中途半端なウインドウ}

ウインドウの境界値は必ずしも切りのよい値でなくてもよい.

\vspace{1em}
\begin{center}
\Depsf[10cm]{uxyzpk/uxyz03_0001.eps}\\
{\bf uxyz03.f:page1}\\
\end{center}

\vspace{1em}
この例では, ウインドウを, X軸については--50から+50の範囲で,
Y軸については1000から0.4の範囲で設定している.
このとき{\tt UXAXDV}は,
きざみ値の整数倍となるところに目盛とラベルを描く.
また{\tt ULYLOG}は,
$10^n$から$10^{n+1}$を1サイクルとして目盛とラベルを描く.
このように,
目盛やラベルは切りのよいサイクルを単位として作画がおこなわれる.

\vspace{1em}
なお, この例では, {\tt ULYLOG}を用いて対数座標軸を描画する際,
{\tt UL}{\it p}{\tt GET/}{\tt UL}{\it p}{\tt SET}の
管理する内部変数{\tt 'IYTYPE'}を変更して
ラベルの書式を変えている.
このように, 対数軸に付けるラベルの書式は何種類も用意されている.

\newpage
%\vspace{1em}
\Dproginput{uxyzpk/uxyz03.f}

\newpage

\section{注文の多い目盛りうち}

好みの間隔で目盛りをうち, 好みのところにラベルを描く.
しかも, ラベルには数字だけでなく文字列も使いたい.
そのような要求にもこのパッケージは対応する.

\vspace{1em}
\begin{center}
\Depsf[10cm]{uxyzpk/uxyz04_0001.eps}\\
{\bf uxyz04.f:page1}\\
\end{center}

\vspace{1em}
スケーリングはuxyz03.fの例と同じで, 緯度のラベルを文字列で表現したい,
また圧力の目盛はデータが存在するレベルだけに打ちたい,
というときには {\tt UXAXLB}, {\tt UYAXLB} を用いるとよい.
最初の引数はおなじみの, 場所を指定する引数である.
2, 3番目の引数には, 小さい目盛りをうつ場所に関する情報を指定する.
具体的には, 2番目の引数として, 小さい目盛りをうつ場所の
U座標系での値(この例では緯度)を実数型配列として与える.
3番目はその配列の大きさである.
4番目から7番目までは, 同様にして, 大きい目盛りについての情報を与える;
目盛りをうつ場所を指定する配列の次に, ラベルを指定する文字型配列,
ラベルの文字数, および配列の大きさに関する情報が付け加わる.

\vspace{1em}
なお, ラベルとして与える文字列の有効な長さは, 後方のブランクを無視して
数える. つまり, X軸の{\tt 'EQ'}のように, DATA文では後方に2文字のブラン
クを含んで文字列を与えても, 先行する有効な2文字のみがラベルの作画対象
となり, 2文字分がセンタリングされて作画される.
Y軸に関しても同様に, 文字列{\tt '.4'}は後方のブランクを無視し
右寄せして描かれる.

\vspace{1em}
この例の{\tt UYAXLB}のように, 小さい目盛りを描きたくなかったら,
小さい目盛りの配列を与えるべきところに適当な変数名を書いておいて
配列の大きさを0とすればよい.

\newpage
%\vspace{1em}
\Dproginput{uxyzpk/uxyz04.f}

\newpage

\section{これはうれしい日付軸}

データ解析をした人なら, 日付軸をつけることの面倒くささはご承知であろう.
UCPACK を用いると,
閏年まで考慮した完ぺきな日付軸を作画することができる.

\vspace{1em}
\begin{center}
\Depsf[10cm]{uxyzpk/uxyz05_0001.eps}\\
{\bf uxyz05.f:page1}\\
\end{center}

\vspace{1em}
サブルーチン{\tt UCXCAL}, {\tt UCYCAL}が日付に関する座標軸を描く.
最初の引数は, これまで通り, 座標軸を描く場所を指定する.
2つ目の引数は起日, つまり座標軸を描きはじめる最初の日であるが,
どのように与えたらよいかはこの例から明かであろう.
最後の引数で, 何日間分を描くかを指定する.
なお日付軸を描くときは,
日数を単位としてウインドウが設定してなければならない.
また座標軸の作画は, U座標系において0に相当する位置からおこなわれる.
たとえばこの例では, X方向のウインドウが$[0.0, 90.0]$として設定してあり,
0に対応する日付が1991年4月1日であるから, グラフの左端は1991年4月1日の
90日後の1991年6月30日となる.

\vspace{1em}
なおこの例では, 右側の座標軸にもラベルを描くようにしてみた.
これまで, 下と上の軸, 左と右の軸をセットにして描きながら,
それぞれ下の軸と左の軸しかラベルが描かれなかった.
これは{\tt UZ}{\it p}{\tt GET/}{\tt UZ}{\it p}{\tt SET}の
管理する内部変数によって,
ラベルを描くか描かないかが制御されていたためである.
ここでは, 右側の座標軸に関して{\tt 'LABELYR'}という内部変数
を{\tt .TRUE.}とすることによって, 右側の座標軸についてもラベルを
描くよう指定した.

\vspace{1em}
また, つけるラベルのフォーマットを変更することができることも示してみた.
X軸については{\tt UXSFMT}によって, Y軸については{\tt UYSFMT}によって,
いわゆるFORTRANでいうところの文字書式仕様を設定してやればよい.
何も設定しない場合(左の軸)と{\tt '(F6.2)'}を指定した場合(右の軸)の
違いを見ていただきたい.
何も設定していないときには,
「有効数字3ケタで文字化し,
小数点以下に続く後方の0は取り除く,
さらに小数点が最下位ならそれも取り除く」ようなフォーマットが,
内部的に決定されて適用される.

\newpage
%\vspace{1em}
\Dproginput{uxyzpk/uxyz05.f}

\newpage

\section{日付軸の例--その2}

日付軸はもちろんY方向についても描くことができる.

\vspace{1em}
\begin{center}
\Depsf[10cm]{uxyzpk/uxyz06_0001.eps}\\
{\bf uxyz06.f:page1}\\
\end{center}

\vspace{1em}
この例からわかるように, 日数のラベルが描けないような場合は,
適当に判断して月と年の目盛だけを描いている.
なお, {\tt UCXACL/UCYACL}の下位ルーチンを
呼ぶことによって, 日, 月, 年の座標軸を別々に描くこともできる.

\vspace{1em}
またここでは, uxyz05.fの知識を生かして, 右側の軸は{\tt UYAXDV}によって
ラベル付きの異なるタイプの座標軸を描いてみた.
さらに{\tt UZFACT}を呼んで, 文字や目盛のサイズを全体的に小さく
(この例では0.8倍)して座標軸を描いている.

\vspace{1em}
{\tt UZFACT} は現在設定されている値を何倍かするルーチンなので,
複数枚の図を描くとき {\tt GRFRM} を呼ぶたびに {\tt UZFACT} を
呼ぶと, 文字や目盛のサイズがどんどん小さく(あるいは大きく)なるので
注意すること.

\newpage
%\vspace{1em}
\Dproginput{uxyzpk/uxyz06.f}

\newpage

\section{好みの場所に軸を描く}

座標軸は {\tt 'B'}, {\tt 'T'}, {\tt 'L'}, {\tt 'R'} で指定する
以外のところにも描くことができる.

\vspace{1em}
\begin{center}
\Depsf[10cm]{uxyzpk/uxyz07_0001.eps}\\
{\bf uxyz07.f:page1}\\
\end{center}

\vspace{1em}
座標軸をウインドウ(またはビューポート)の境界線以外のところへ,
たとえば, この例のようにグラフのまん中に描きたいときは,
場所をあらわす引数として{\tt 'U'}を指定すれば,
それがユーザー指定の座標軸として扱われる.
この例では{\tt UXAXDV}で{\tt 'U'}を指定し,
座標軸を描いている.
具体的にどこに軸を描くかは,
{\tt UZRSET}を用いて, X軸については内部変数{\tt 'UYUSER'}の値を,
Y軸については内部変数{\tt 'UXUSER'}の値を指定してやればよい.
たとえば, この例のX軸の場合, {\tt 'UYUSER'}を0.0と指定することによって,
U座標系でみたY座標の値が0.0のところにX軸が描かれる.
タイトルについても, 場所を示す引数を{\tt 'U'}としてやることによって,
ユーザー指定の座標軸にタイトルを描くことができる.

\vspace{1em}
またこの例では, 目盛と目盛の間にラベルを描いてみた.
これは{\tt UZ}{\it p}{\tt GET/}{\tt UZ}{\it p}{\tt SET}が
管理する内部変数{\tt 'LBTWN'}を
{\tt .TRUE.}とすることによって実現できる.
ただし注意すべきことは, ほかの座標軸を描くときにも
この設定が影響を及ぼすので,
ラベルを間に描き終ったら{\tt .FALSE.}に戻しておく必要がある.

\vspace{1em}
さらにこの例では, {\tt UXSFMT}によってフォーマットを
{\tt '(I4)'}と陽に指定している.
これは, 省略時におけるフォーマットが有効数字3桁で数値を表現しようとす
るためであって, このように4桁目までちゃんと表現する必要があるときには,
ユーザーがフォーマットを指定しなければならない.

\newpage
%\vspace{1em}
\Dproginput{uxyzpk/uxyz07.f}

\newpage

\section{目盛を外向きにつける}

私は, 目盛を外向きに打つのが好きだという人もいることだろう.

\vspace{1em}
\begin{center}
\Depsf[10cm]{uxyzpk/uxyz08_0001.eps}\\
{\bf uxyz08.f:page1}\\
\end{center}

\vspace{1em}
目盛を外向きにつけるときは,
{\tt UZ}{\it p}{\tt GET/}{\tt UZ}{\it p}{\tt SET}が管理する
内部変数{\tt 'INNER'}を--1に設定してやればよい.
ここではユーザーの指定した場所に座標軸を描きながら
目盛を外向きにつける例を示す.
まず, {\tt UZRSET}で内部変数{\tt 'UXUSER'}, {\tt 'UYUSER'}の値を
それぞれ0.0, 0.0としている.
また, {\tt UZLSET}で内部変数{\tt 'LABELXU'}, {\tt 'LABELYU'}を
それぞれ{\tt .FALSE.}にして,
ユーザー指定の軸についてはラベルを描かないようにしている.

\vspace{1em}
ユーザー指定の座標軸については2度書きすることで
軸の両側に目盛を打つように
している. また{\tt UZFACT}を呼んで描くタイトルを小さくしている.

\newpage
%\vspace{1em}
\Dproginput{uxyzpk/uxyz08.f}

\newpage

\section{同じ側に何本もの軸を}

ウインドウ(あるいはビューポート)の境界線から少し離して座標軸を描きたい,
あるいは同じ側に2本以上の座標軸を描きたいということもあろう.

\vspace{1em}
\begin{center}
\Depsf[10cm]{uxyzpk/uxyz09_0001.eps}\\
{\bf uxyz09.f:page1}\\
\end{center}

\vspace{1em}
軸を外側へずらしたい, またはすでに描いた軸の外側に
もう一本軸を描きたいというときは, X軸については{\tt UXSAXS},
Y軸については{\tt UYSAXS}を呼べばよい.
1つだけある引数は, 場所を指定するおなじみの引数である.
これらのルーチンを呼ぶと,
次の軸は適度に(内側の軸と重ならない程度に)外側に描かれる.
これを何回も使えば, 簡単に複数の軸を一つの側に描かせることができる.

\vspace{1em}
この例では, 軸が外側へ移ってしまったために,
本来ならグラフの枠は描かれない.
しかし, サブルーチン{\tt SLPVPR}が呼ばれているために,
ビューポート, つまりグラフの外側の枠が描かれている.

\newpage
%\vspace{1em}
\Dproginput{uxyzpk/uxyz09.f}

\newpage

\section{スケーリングを変えずに別の目盛りを}

1つの側に複数の軸が描けるのはわかったけど,
そのためにいちいちウインドウを設定し直すのはめんどくさそう,
と思ったあなたに最後の例を示そう.

\vspace{1em}
\begin{center}
\Depsf[10cm]{uxyzpk/uxyz10_0001.eps}\\
{\bf uxyz10.f:page1}\\
\end{center}

\vspace{1em}
この例では, Y座標としてセ氏のデータを与えたいのだが,
換算の便のためにカ氏やケルビンの目盛りもあわせて描いている.
スケーリングに影響を与えず,
目盛りだけを変えて描きたいときは, オフセット機能を用いる.
そのためにまず{\tt UZLSET}で内部変数{\tt 'LOFFSET'}を
{\tt .TRUE.}にしておく.
必要なところで, 内部変数{\tt 'YOFFSET'}, {\tt 'YFACT'}
(X軸については{\tt 'XOFFSET'}, {\tt 'XFACT'})を設定すると,
目盛りの位置が平行移動し, 目盛りの間隔が変わる.

\newpage
%\vspace{1em}
\Dproginput{uxyzpk/uxyz10.f}
