SLLIB + SFITSIO ダイジェスト版 HTML マニュアル

使用頻度の高い API について，主要な内容を記述した， ビギナー向けのリファレンスマニュアルです．

SFITSIO: 規約外FITS拡張

CFITSIO互換のローカルFITS拡張

SFITSIOでは，CFITSIOと同様に，ヘッダの文字列値が 1行のヘッダレコードに収まらない場合，次のように CONTINUE を使って保存します．

TELEM6  = 'CREON,SHTOP,FWPOSON,FWPOS_B1,FWPOS_B0,MPOSON,MPOS_B1,MPOS_B0,&'
CONTINUE  'RSTWIDELON,RSTWIDESON,RSTN170ON,RSTN60ON,LWBOOSTON,SWBOOSTON,&'
CONTINUE  'LWBIASON,SWBIASON,CALALON,CALASON,CALBON,SINALON,SINASON&'
CONTINUE  '' / elements in STATUS

SFITSIOの場合は，ファイルからの読み書きの時にこの拡張のための処理， すなわち，ファイル・オブジェクト間のデータ変換を行ないます． SFITSIOのオブジェクトには，文字列長の制限はありませんから， CFITSIOのようなロング値専用のAPIは存在しません． つまり，ファイル上の CONTINUE レコードの有無をユーザが気にする必要は無いわけです．

バイナリテーブルの固定長文字列の配列

CFITSIOでは， TFORMn = '120A10' のような指定をするか， TFORMn = '120A' かつ TDIMn = '(10,12)' のように指定する事で， 12個の10文字の文字列を1つのカラムで扱えるようになります． これらのFITS拡張は，SFITSIOでもサポートしています．

SFITSIOではさらに， TFORMn = '120A10' かつ TDIMn = '(6,2)' のように指定する事で，10文字の文字列を， 6×2の配列として扱う事も可能です．この指定は， TFORMn = '120A' かつ TDIMn = '(10,6,2)' と書く事もできます．

チェックサムとデータサムの書き込み

SFITSIOは，各HDUのヘッダに CHECKSUM または DATASUM キーワードが存在した場合，FITSファイルを保存する時に CFITSIO互換のチェックサムまたはデータサムを自動的に書き込みます． 例を示します．

CHECKSUM= 'LNXALNX2LNX8LNX8'   / HDU checksum : 2012-01-16T13:34:03
DATASUM = '2155872383'         / data unit checksum : 2012-01-16T13:34:03

なお，このチェックサムとデータサムは，基本的にはHDUのバイトデータすべてを 32ビット整数とみなして足し算をしているだけです． したがって，このチェックサムはデータの同一性を保証するには不十分である と考えられます．そのような用途には，md5sumを使う事をお勧めします．

なお，現在のバージョンの SFITSIOにはこのチェックサムとデータサムをチェックする機能はありません．

SFITSIOのローカルFITS拡張

この章で述べるFITSの拡張は，そのほとんどがバイナリテーブルに関するものです． かなりの部分が 宇宙科学研究開発機構・宇宙科学研究所の「あかり」プロジェクトや L1TSDプロジェクトで生まれたもので， 観測衛星の複雑なデータをわかりやすく格納し， 効率的にプロセッシングできるよう，長期にわたる 関係者の様々な議論を経て策定されたものです．

FMTTYPE，FTYPEVERによるFITSのエラーチェックとバージョン管理

pdf版マニュアルで紹介したように，「あかり」プロジェクトでは TSDファイルを定義したわけですが， プロジェクトがある程度進捗した段階において， プロジェクトで開発したソフトウェアがTSDファイルを読み込んだ時に， どのようにFITSファイルの妥当性のチェックを行ない， TSDのバージョンによる動作の切り替えを行なうか， という議論が行なわれました．

そこで考え出されたのが， FITSフォーマットの「名前」と「バージョン」 とを，プライマリHDUのヘッダの 「FMTTYPE」，「FTYPEVER」にセットする， という取り決めです． キーワード FMTTYPE の値には， (可能な限り)世界的に unique なデータフォーマットを規定する文字列，すなわち 「プロジェクト名 装置名 ファイルの種類」 のような文字列をセットします． 「あかり」プロジェクトでは「ASTRO-F TSD FIS_LW」のように 定めました． FTYPEVER は，そのデータフォーマットのバージョンを示し， 整数値で指定します．

なお，FTYPEVER の値は マイナーバージョンを示すために， 3ケタ以上の数値を使う事をお勧めします． あるいは，20080101 のような日付を使う方法もあります．

SFITSIOは， 「FMTTYPE」，「FTYPEVER」を 専用のAPIでサポートします．

ヘッダキーワードの大文字・小文字の区別

現在のFITS規約では，キーワードに小文字を使う事は許されていません． しかし，SFITSIOではFITSヘッダのキーワードの大文字と小文字とは区別されます． 例えば，次のようなヘッダレコードを作る事ができます．

FOO     = 123
Foo     = 456

ヘッダのロングキーワード(最大54文字)

現在のFITS規約では，ヘッダのキーワードは8文字までに制限されており， 「空白8文字のキーワード」以外の場合においては， ヘッダレコードの 9文字目は必ず "=" か空白文字 が現れます． つまり，9文字目がそれら以外の場合については定義されていないわけです．

この未定義の部分を 「ヘッダレコードの 9文字目に "=" でも空白文字でもない文字が 現れた場合，それは 8文字を越えるロングキーワードとする」と定義し， 「ロングキーワードは "=" と空白は含んではならない」と約束すれば， 過去のFITSファイルにおける互換性の問題を引き起こさずに， 可読性の高いロングキーワードを使う事ができます．

この定義に従って，SFITSIOでは次のように単純にロングキーワードを保存します．

TTYPE12345= 'Mag     '         / column name
TFORM12345= '1D      '         / data format : 8-byte REAL

キーワードは最大54文字までで， 「=」や空白文字を使う事はできません．

なお， ESOのコンベンションでは，ロングキーワードのヘッダレコードは そのレコードの先頭に HIERARCH をつけて区別していますが， これはスジが悪いと考えます．

999を越えるアスキーテーブル・バイナリテーブルのカラム数

現在のFITS規約におけるヘッダキーワードの長さ制限(8文字)により， アスキーテーブル，バイナリテーブルのカラムは999個までしか定義できません．

SFITSIOでは，前項のヘッダのロングキーワード拡張により， アスキーテーブルまたはバイナリテーブルのカラム数は 事実上無制限となっています．

COMMENT レコードは長い文章をFITSヘッダに入れられるので便利ですが， 「このコメントはどこのヘッダレコードについての記述か」をライブラリは判断 できません．これは，自動化の妨げになるので，コメント文はできるだけ 通常のヘッダレコードの「/」の後に書くべきです．

一方，「/」の後のコメント文は，文字列値が長い場合には， 単純なアルゴリズムでヘッダをフォーマットすると， コメント後部がカットされてしまうという問題があります．

この問題を解決するため，SFITSIOでは できる限りコメント文をすべて残すように，次のように ロング文字列拡張を使って文字列の最後で次の CONTINUE に接続するようにし， 十分なコメント領域を確保するようにしています．

TELEM34 = 'BAD_FRAME,UNDEF_ANOM_FRAME,BLANK,IN_SAA,NEAR_MOON,UNTRUSTED_FRAME&'
CONTINUE  '' / element names

さらに，上記のようにしても切れてしまう場合は，コメント文も CONTINUE キーワードで保存するようにしています．例を示します．

MESSAGE = 'FITS (Flexible Image Transport System) format is defined in &'
CONTINUE  '"Astronomy and Astrophysics", volume 376, page 359; bibcode: &'
CONTINUE  '2001A&A...376..359H' / In SFITSIO, this message is not written
CONTINUE  / automatically. Therefore, SFITSIO is not CFITSIO :-)

この拡張は，ISAS/JAXAのL1TSDプロジェクトで考案されました．

ヘッダの文字列値における改行文字の定義

バイナリテーブルやアスキーテーブルのカラムの説明などは， HTML，VOTable，LaTeX 等の形式に変換しなければならない事があります． このような場合の自動化処理を考えると，カラムの説明などは，COMMENT にではなく，キーワードに対する文字列値として保存すべきです． この場合，様々なフォーマットにおいて統一性を確保するためには，改行 文字の定義が必要です．

SFITSIOでは，ヘッダの文字列値での「\n」 (C言語では "\\n")を 改行文字とみなし，ヘッダレコードを整形する場合に，改行文字で レコードを分離します．

TDESC3  = 'Trigger type flag,\n&'
CONTINUE  '  b1000000:SUD(trigd by SuperUpper Discriminator),\n&'
CONTINUE  '  b0100000:ANODE,\n&'
CONTINUE  '  b0010000:PIN0 b0001000:PIN1 b0000100:PIN2,\n&'
CONTINUE  '  b0000010:PIN3 b0000001:PSEUDO' / description of column

この拡張は，ISAS/JAXAのL1TSDプロジェクトで考案されました．

テーブルのカラム(フィールド)に関する キーワードを独自に定義する事は，様々な機関においてよく行なわれている事です． 代表的なものとしては，TLMINn，TLMAXn が挙げられます．

しかし，FITS の I/Oライブラリでは，これらがテーブルのカラム(フィールド)に 属するキーワードなのか，そうではないのかは判定できません． したがって，FITS の I/Oライブラリでテーブルのカラムを削除したり移動したり すると，新たに定義されたカラムに関するキーワードは取り残されてしまったり， 必要なものがコピーされないといった問題が発生します． また，テーブルの情報を HTML，VOTable，LaTeX 等に 完全自動で変換する事もできません．

そこで，"TXFLDKWD" というキーワードを定義し， 新規に追加されたテーブルのカラムに関するキーワードを次のように csv 形式で宣言するというルールを定めます．

TXFLDKWD= 'TLMIN,TLMAX,TALAS,TELEM,TDESC' / extended field keywords

なお，"TXFLDKWD" は，TTYPEn等の定義の前に 現れるべきです． SFITSIOでは，TXFLDKWD の拡張にAPIレベルで対応しています．

この拡張は，ISAS/JAXAのL1TSDプロジェクトで考案されました．

次のように，キーワード TALASn を使って， カラム名の別名を定義できます．

TTYPE4  = 'QUATERNION'         / Quaternion at boresight
TALAS4  = 'AOCU_ADS_Q'         / aliases of column name

ここで定義された別名は，SFITSIOのAPIでも有効です． なお， 複数の別名を定義する場合は，csv形式で定義します．

この拡張は，ISAS/JAXAの「あかり」プロジェクトで考案されました．

キーワード TELEMn を使って， 次のようにバイナリテーブルの配列型のカラム中の要素に対して， 名前をつける事ができます．

TTYPE34 = 'FLAG    '           / Flag for detector condition
TELEM34 = 'BAD_FRAME,UNDEF_ANOM_FRAME,BLANK,IN_SAA,NEAR_MOON,UNTRUSTED_FRAME&'
CONTINUE  '' / element names
TFORM34 = '8X      '           / data format : BIT

各要素の名前は TELEMn キーワードのレコードに csv形式で定義します． すべての要素に対して名前をつける必要はなく，省略した場合は 左詰めで要素名が定義されます． この例では，データフォーマットは「ビット型」ですが，他の型 (整数型や実数型など)でも同様に指定できます．

SFITSIO の API においては， dvalue()， assign() などのメンバ関数 の引数に，これらの要素名を指定して値を読み書きする事ができます．

この拡張は，ISAS/JAXAの「あかり」プロジェクトで考案されました．

カラムがビット型の配列の場合 (TFORMn が 'mX' の場合)， TELEMn の値に， C言語の構造体のビットフィールドと同様の記法でそれぞれの要素のビット幅を定義できます (同じ要素名を複数個連続して指定する事でビット幅を定義する事もできます)．

次に例を示します．

TTYPE36 = 'QUALITY '           / Quality for each pixel condition
TFORM36 = '4000X   '           / data format : BIT
TDIM36  = '(40,100)'
TELEM36 = 'QUAL_CV_PARAM:2,QUAL_RC_PARAM:2,QUAL_RC_CF:2,QUAL_DF_EQ:2,&'
CONTINUE  'QUAL_RP_DATA:2,QUAL_RP_PARAM:2,QUAL_RP_TABLE:2,QUAL_FF_PARAM:2,&'
CONTINUE  'QUAL_FF_CF:2,QUAL_GPGL_CORR:2,QUAL_MTGL_CORR:2,QUAL_TR_HIST:2,&'
CONTINUE  'QUAL_TR_PARAM:2,QUAL_DK_DATA:2,QUAL_DK_PARAM:2,QUAL_DK_TABLE:2,&'
CONTINUE  'QUAL_FX_CORR:2,QUAL_FX_PARAM:2,,,,' / element names

この場合，TTYPE36，TFORM36，TDIM36 までは FITS標準の記法であり， テーブルの1つのセルに，横40×縦100(合計4000個)のビットが定義されています． TELEM36 では，横40個に対して2ビットずつ要素名を定義しています． すべての要素に対して名前をつける必要はなく，省略した場合は 左詰めで要素名が定義されます． 1つの要素が持つビットの数は，要素名の後のコロン「:」 の後に記載します．なお，要素名にコロンを使うことはできますが， 将来的に互換性に関する問題が引き起こされる可能性があるため， 使うべきではないでしょう．

もちろん，SFITSIO の API においては，定義されたビット数からなる整数(32ビットまで) を読み書きできます．APIによる値の読み書きは， FITSファイル上のバイトデータをそのままメモリに保持した状態で行われるので， ビットフィールドの定義は， ファイルサイズを小さくできると同時に，メモリの節約にもなります．

この拡張は，ISAS/JAXAの「あかり」プロジェクトで考案されました．