%表題   GRPH2 図形処理上位パッケージ
%
%履歴
%\Drireki{
%         90/04/02 酒井敏
%         91/09/05 林祥介
%         91/12/10 林祥介
%         92/01/31 塩谷雅人 (一部のlabelのコメントを外した)
%         92/03/02 酒井敏
%         92/04/22 林祥介   (4.1版)
%         94/03/27 酒井敏   (5.y版)
%         95/02/16 塩谷雅人
%         95/04/14 酒井敏   (5.z版)
%        }
%
%  \Dchapter{USPACK ： 1次元量のグラフ表示ルーチン}
\Dchapterhead
\label{uspack}

\section{概要}
%\label{uspack.概要}

USPACK はデータを簡単にグラフ化することを主目的とした
いわゆるオート・スケーリング・ルーチンのパッケージである.
このパッケージの主な機能は,
\begin{enumerate}
  \item データの最大最小値を調べて, 適切な正規化変換パラメタを求める.
  \item 現在設定されている正規化変換に対して,
        適切な目盛及びラベル間隔を計算して座標軸を描く.
\end{enumerate}
ことである.
2番目の座標軸を描くルーチンは,
独立に呼ぶことができるので,
簡単に座標軸を描くユーティリティーをしても使える.
コンターを描くUDPACKなどと組み合せて使うと便利である.
\vspace{1em}

なお, 実際の折れ線グラフはUUPACK,
座標軸やタイトルはUXPACK/UYPACKなどに依存している.

%=======================================================================
\section{基本構造}

USPACK は与えられたデータに対して,
適当な正規化変換のパラメタを求める「スケーリング・ルーチン」と,
設定された正規化変換に対して,
適当な目盛り間隔などを求めて座標軸を描く「座標軸ルーチン」がある.
スケーリング・ルーチンと座標軸ルーチンは基本的に独立に動作し,
どちらか一方だけを使うことができる.

さらに, これらを組み合わせて簡便にグラフを描くための
「簡単ルーチン ({\tt USGRPH})」からなる.

%----------------------------------------------------------------------
\subsection{簡単描画ルーチン ({\tt USGRPH})}
とにかく簡単にデータをグラフ化するためのルーチンで,
1行で折れ線グラフまで描いてくれる.
これらを使ったプログラムは次のようになる.

\begin{Dprogram}
       CALL GROPN(IWS)    ! デバイスオープン
       CALL GRFRM         ! フレームを用意
       CALL GRSTRN(ITR)   ! 変換関数番号の指定 (省略可, 省略値 1)

       CALL USSTTL(....)  ! タイトル設定 (省略可)
       CALL USGRPH(N,X,Y) ! グラフ描画

       CALL GRCLS         ! デバイスのクローズ
\end{Dprogram}

{\tt GRFRM} と {\tt USGRPH} の間で,
変換関数に関するパラメタを GRPACK や SGPACK で設定したり,
その他のパラメタを \USPSET により設定することができる.
また, {\tt USSTTL} により座標軸のタイトルなどを指定することもできる.
\vspace{1em}

これらのルーチンは, とにかく簡便にデータをグラフ化するには便利である.
しかし, 複数の折れ線を一つの図に入れたり,
他のパッケージと組み合わせて使うなどの応用をするには
スケーリング・ルーチンと座標軸ルーチンを直接使う方がよい.
上記のプログラムをこれらの基本的なルーチンを使って書き直すと
次のようになる.

\begin{Dprogram}
       CALL GROPN(IWS)    ! デバイスをオープン
       CALL GRFRM         ! フレームを用意
       CALL GRSTRN(ITR)   ! 変換関数番号の指定 (省略可)

       CALL USSPNT(N,X,Y) ! データ範囲の指定
       CALL USPFIT        ! 変換関数パラメタ設定
       CALL GRSTRF        ! 変換関数確定

       CALL USSTTL(....)  ! タイトル設定 (省略可)
       CALL USDAXS        ! 座標軸描画

       CALL UULIN (N,X,Y) ! 折れ線描画

       CALL GRCLS         ! デバイスのクローズ
\end{Dprogram}


%-----------------------------------------------------------------------
\subsection{スケーリング・ルーチン}

スケーリング・ルーチンは与えられたデータから適当な正規化変換の
パラメタを求めるもので,
{\tt GRSWND}, {\tt GRSVPT} の代わりをするルーチンである.
変換関数の確定は行わないので, {\tt GRSTRF} により関数の確定をする
必要がある.
\vspace{1em}

正規化変換のパラメタを決めるためには,
これから描こうとする折れ線などのデータ範囲を知らなければならない.
{\tt USSPNT} はそのデータを指定するもので,
{\tt USPFIT} を呼ぶ前に何回でも呼ぶことができる.
例えば複数の折れ線を描くためには,
それらのデータをすべて与えなければならない.
{\tt USPFIT} はこれらのデータの最大最小値を切りの良い数値に丸めて
ウインドウを決定する.
なお, {\tt GRSWND/SGSWND} または \SGPGETSET などにより,
ウインドウをユーザーが陽に指定した場合は,
これらの値が優先される.
\vspace{1em}

ビューポートは, USPACK が描く座標軸関係の文字がすべて描けるように,
最大作画領域から文字の大きさ
(\UZPGETSET の管理する内部変数{\tt 'RSIZEL1'}) に比例した幅の
マージンをとった大きさに設定される.
したがって, {\tt UZFACT} 等によりラベルの文字の大きさを変えたり,
\SGPGETSET の管理する内部変数 {\tt 'LFULL'} を{\tt .TRUE.} にしたりすると,
グラフの大きさも変る.
また, ビューポートも{\tt GRSVPT/SGSVPT} または \SGPSET , \SGPSTX により
陽に指定されている場合は,
これらの値が優先される.
\vspace{1em}

%-----------------------------------------------------------------------
\subsection{座標軸ルーチン}

{\tt USDAXS}は現在設定されている変換関数に対して,
目盛間隔やラベルの間隔を適切に設定して座標軸を描くものである.
座標軸を描く位置は {\tt USCSET}の内部変数{\tt CXSIDE/CYSIDE}で指定され,
タイトルなどは {\tt USSTTL}または{\tt USCSET}で指定することができる.
なお, {\tt USDAXS} は基本的に X--軸とY--軸を独立に処理しており,
しかも, ラベル間隔の決めるときにラベルと軸の角度(平行か垂直)により
異なった処理を行う.
通常は X--軸, y--軸ともにラベルを水平 (x--軸と並行) にするようになって
いるので,
X--軸とY--軸のデータ範囲が同じであっても,
ラベル間隔が異なることがある.
それが気持ち悪いときには, {\tt USLSET}で{\tt 'LMATCH'} を {\tt .TRUE.}
にすると,
実際のラベルの向きに関わらず,
ラベルが軸と平行に書かれるものと仮定して
ラベル間隔を求めるようになるので,
X--軸とY--軸のラベル間隔を揃えることができる.
\vspace{1em}


{\tt USDAXS} はX--軸とY--軸の両方を描くが,
片方ずつ描画する {\tt USXAXS}, {\tt USYAXS} もある.

%-----------------------------------------------------------------------
\subsection{内部変数管理}

USPACK 固有のパラメタは \USPGETSET
によって管理されているが, タイトルをまとめて指定するルーチン
{\tt USSTTL}も用意されている.
このうち {\tt USINIT} は, {\tt GRFRM} {\tt GRFIG} から呼ばれるので,
通常ユーザーが呼ぶ必要はない.
\vspace{1em}

なお, USPACKはUUPACKやUXPACK/UYPACKの
ルーチンを使って座標軸や折れ線を描くので,
これらのパッケージの内部変数に影響される.
各制御項目とそれを制御するルーチン名及び内部変数名は以下のとおり.
\vspace{1em}

\begin{center}
\begin{tabular}{lll} \hline
{\bf 制御項目}  & {\bf 設定ルーチン}  & {\bf 内部変数名}   \\ \hline
座標軸の最大最小値 & {\tt * \SGPSET /SGSWND} & {\tt UXMIN/UXMAX/UYMIN/UYMAX} \\
ビューポート       & {\tt * \SGPSET /SGSVPT} & {\tt VXMIN/VXMAX/VYMIN/VYMAX} \\
座標軸の向き       & {\tt USLSET}        & {\tt LXINV/LYINV}          \\
オフセット値       & {\tt USRSET}        & {\tt XOFF/YOFF}            \\
ファクター値       & {\tt USRSET}        & {\tt XFAC/YFAC}            \\
目盛間隔           & {\tt USRSET}        & {\tt DXT/DYT}              \\
座標軸の位置       & {\tt USCSET}        & {\tt CXSIDE/CYSIDE}        \\
目盛の向き         & {\tt *UZISET}       & {\tt INNER}                \\
ラベル間隔         & {\tt USRSET}        & {\tt DXL/DYL}              \\
ラベルの向き       & {\tt *UZISET}       & {\tt IROTL}{\it zs}        \\
ラベルのセンタリング
オプション         & {\tt *UZISET}       & {\tt ICENT}{\it zs}        \\
タイトル文字       & {\tt USCSET/USSTTL} & {\tt CXTTL/CYTTL}          \\
サブラベルの単位   & {\tt USCSET}        & {\tt CXUNIT/CYUNIT}        \\
サブラベルの括弧   & {\tt USCSET}        & {\tt CBLKT}                \\
サブラベルの位置   & {\tt USCSET}        & {\tt CXSPOS/CYSPOS}        \\
タイトル,サブラベル,
ラベルのフラグ     & {\tt *UZLSET}       & {\tt LABEL}{\it zs}        \\
文字の大きさ       & {\tt *UZFACT}       & 引数                 \\
折れ線の属性       & {\tt *UUSLNI/UUSLNT}& 引数                 \\
\hline
\end{tabular}
\end{center}


%=======================================================================
\newpage
\section{USPACKによる作画範囲}
%\label{uspack.cnf}

USPACKによる最大作画範囲を下の図に示す.
これらの範囲は内部変数によって変化するが,
初期状態では目盛を内側に描く($x_1=y_1=0$)ので,
左マージンが$x_2+x_3 = 0.1463$,
右マージンが${\tt RSIXEL1} \times 2 = 0.042$,
上マージンが$s_y=0.0537$,
下マージンが$y_2+y_3+y_4=0.119$
あれば
タイトルまで含めて全て作画範囲に入る.
\vspace{1em}

なお初期状態で上下左右とも0.2のマージンを取る.
\vspace{1em}

\begin{center}
\Depsf[10cm]{uspack/uscnf_0001.eps}\\
{\bf uscnf.f:page1}\\
\end{center}
\vspace{1em}

\begin{eqnarray*}
 x_1 & = & {\tt RSIZET2}                                     = 0.014  \\
 x_2 & = & ({\tt MXDGTY} + {\tt PAD1} ) \times {\tt RSIZEL1} = 0.0987 \\
 x_3 & = & (           1 + {\tt PAD1} ) \times {\tt RSIZEC1} = 0.0476 \\
\end{eqnarray*}
\begin{eqnarray*}
 y_1 & = & {\tt RSIZET2}                                     = 0.014  \\
 y_2 & = & (           1 + {\tt PAD1} ) \times {\tt RSIZEL1} = 0.0357 \\
 y_3 & = & (           1 + {\tt PAD1} ) \times {\tt RSIZEL1} = 0.0357 \\
 y_4 & = & (           1 + {\tt PAD1} ) \times {\tt RSIZEC1} = 0.0476 \\
\end{eqnarray*}
\begin{eqnarray*}
 s_x & = & {\tt RSIZET2} +
          ({\tt MXDGTSY} + {\tt PAD1} ) \times {\tt RSIZEL1} = 0.1547 \\
 s_y & = & {\tt SOFFYLT} + (1+{\tt PAD1})\times{\tt RSIZEL1} = 0.0537
\end{eqnarray*}

%------------------------------------------------------------------------
\section{サブルーチンのリスト}

\subsubsection {簡単ルーチン}
  \begin{quote}
  \begin{tabular}{lp{10cm}}
    {\tt USGRPH(N,X,Y)}		&  X座標値, Y座標値を与えて,
				   折れ線グラフを描く. \\
  \end{tabular}
  \end{quote}

\subsubsection {スケーリング・ルーチン}
  \begin{quote}
  \begin{tabular}{lp{10cm}}
    {\tt USSPNT(N,X,Y)}	&  ウインドウの範囲に含めたいデータを指定する. \\
    {\tt USPFIT} 			&  変換パラメータの決定. \\
  \end{tabular}
  \end{quote}

\subsubsection {座標軸ルーチン}
  \begin{quote}
  \begin{tabular}{lp{10cm}}
    {\tt USDAXS} 			&  座標軸描画. \\
    {\tt USXAXS(CXSIDE)}		& X座標軸を描画する. \\
    {\tt USYAXS(CYSIDE)}		& Y座標軸を描画する. \\
    {\tt USSTTL(CXTTL, CXUNIT, CYTTL, CYUNIT)}	& タイトル設定
  \end{tabular}
  \end{quote}

\subsubsection{パラメタ管理}

  \begin{quote}
  \begin{tabular}{lp{10cm}}
    {\USPGET \tt (CP, IPARA)} 	&  内部変数参照. \\
    {\USPSET \tt (CP, IPARA)} 	&  内部変数設定. \\
    {\USPSTX \tt (CP, IPARA)} 	&  内部変数設定
				   (実行時オプションによる変更可). \\
    {\tt USINIT}		&  内部変数初期化 \\
  \end{tabular}
  \end{quote}