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

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

SFITSIO: fitsccクラス

fitsccクラスは，FITSファイル全体を表現します． オブジェクト内で， fits_imageクラス(Image HDUを表現) または fits_tableクラス(Binar Table or ASCII Table HDUを表現) のオブジェクトを管理します． FITS ファイルとの I/O， HDU を表現するオブジェクトへのアクセス， HDU の追加・削除などを行なうには， このクラスのメンバ関数を使用します．

fitscc クラスは単独のクラスです．継承関係はありません．

基本機能のためのメンバ関数

fitscc &init();
fitscc &init( const fitscc &obj );

オブジェクトの内容すべて破棄し，初期化し ます． 引数が指定されている場合は，オブジェクト objの 内容をすべて自身にコピーします．

返り値

自身の参照

ssize_t read_stream( const char *path );            ... 1
ssize_t readf_stream( const char *path_fmt, ... );  ... 2

path で指定されたファイルあるいは URL(file://，http://，ftp://に対応) からFITSファイルを読み込み，内容すべてまたは 一部 をオブジェクトに取り込みます．

pathのファイル名，httpサーバから得たMIMEヘッダから判断 して，必要な場合はzlib，bzlib経由で読み込みを行ないます (これは，SLLIBのdigeststreamioクラス で行なっています)． ftpサーバから読み込む場合は，pathに ftp://username:password@hostname/… の書式で，ユーザ名とパスワードを設定できます． ユーザ名とパスワードを設定しない場合は， 匿名(anonymous)でアクセスします．

引数pathに "image.fits.gz[1:100,*]" のような文字列を与えてFITSファイルの部分読み出し(画像・テーブルに対応) を行なう場合の […] 内の文法については， FITSファイルの部分読み出し機能の解説 をご覧ください． SFITSIOの部分読み出し機能では， FITSファイルの内容すべてをメモリに取り込む事はなく， ディスクのシーケンシャルリードと順方向のシーク(可能な場合)により実現しています． したがって，メモリに載らないような巨大なFITSファイルでも (圧縮ファイルであっても)， 必要な部分を読み出す事ができます．

readf_stream()メンバ関数の場合， path_fmt以降の引数をlibcの printf()のそれと同様に指定します．

返り値

非負の値: 読み込んだストリームのバイトサイズ(圧縮ファイルの場合は展開後のサイズ)

負の値(エラー): ファイルが見つからないなど，ストリームの読み込みに失敗した場合．

ssize_t write_stream( const char *path );            ... 1
ssize_t writef_stream( const char *path_fmt, ... );  ... 2

オブジェクトの内容すべてを path で指定されたファイルへ書き出します．

pathのファイル名から判断して， 必要な場合はzlib，bzlib経由で書き込みを行ないます (これは，SLLIBのdigeststreamioクラス で行なっています)． ftpサーバへ書き込む場合は，pathに ftp://username:password@hostname/… の書式で，ユーザ名とパスワードを設定できます． ユーザ名とパスワードを設定しない場合は， 匿名(anonymous)でアクセスします．

writef_stream()メンバ関数の場合， path_fmt以降の引数をlibcの printf()のそれと同様に指定します．

返り値

非負の値: 書き込んだストリームのバイトサイズ(圧縮ファイルの場合は圧縮前のサイズ)

負の値(エラー): パーミッションに問題がある場合などの理由で， ストリームの書き込みに失敗した場合．

ssize_t access_stream( const char *path );
ssize_t accessf_stream( const char *path_fmt, ... );

これらのメンバ関数の引数は， スクリプト言語Perlのopen()のそれに似ており， pathあるいはpath_fmtがファイルやURLを 示している場合はそれに対して読み込みか書き込みを行ないます． また，コマンドを示している場合はそれを実行し，パイプで接続して， パイプ経由で読み込みか書き込みを行ないます (これは，SLLIBのdigeststreamioクラス で行なっています)．

読み込みか書き込みかは，pathあるいはpath_fmtが ファイルやURLを示している場合は， "< infile.fits" や "> outfile.fits" のように 「<」あるいは「>」をつけて表現します． 「<」がある場合は読み込みを行ない(EXAMPLE-1参照)， 「>」がある場合は書き込みを行ないます． 「<」「>」の指定が無い場合は， 読み込みを行ないます． 圧縮されたファイル(gzipかbzip2形式)が指定された場合， 自動的に圧縮・伸長します．

pathあるいはpath_fmtが コマンドを示している場合， "command |" や "| command" のように， 「|」をpathの最後か先頭につけて表現します. 「|」がpathの最後につけられている場合は， 指定したコマンドを実行してパイプで接続し， そのコマンドの標準出力からの出力を FITSファイルの内容として読み込みます:

    fitscc fits;
    r_size = fits.accessf_stream("wget -O - %s | gzip -dc |",
                                 "https://foo/secret.fits.gz");

「|」がpathの先頭につけられている場合は， 指定したコマンドを実行してパイプで接続し， このコマンドに対して FITSファイルの内容を書き出します． pathあるいはpath_fmtがコマンドの場合， 「/bin/sh -c コマンド」の形で実行しますので， pathにはパイプやリダイレクトの記号 (|,<,>)を含む事ができます．

引数pathに "image.fits.gz[1:100,*]" のような文字列を与えてFITSファイルの部分読み出し(画像・テーブルに対応) を行なう場合の […] 内の文法については， FITSファイルの部分読み出し機能の解説 をご覧ください．

accessf_stream()メンバ関数の場合， path_fmt以降の引数をlibcの printf()のそれと同様に指定します．

返り値

非負の値: 読み書きしたストリームのバイトサイズ(圧縮ファイルの場合は圧縮前のサイズ)

負の値(エラー): ファイルが見つからないなど，ストリームの読み込みに 失敗した場合，やパーミッションに問題がある場合などの理由で， ストリームの書き込みに失敗した場合

ssize_t read_template( const char *path );
ssize_t readf_template( const char *path_fmt, ... );

pathで指定されたパスあるいは URL(file://，http://，ftp://に対応) から FITSテンプレート (SFITSIO: FITSテンプレート を参照) を読み込み， その内容に従ってfitsccオブジェクトを新規に作成します． pathのファイル名，httpサーバから得たMIMEヘッダから判断 して，必要な場合はzlib，bzlib経由で読み込みを行ないます． ftpサーバから読み込む場合は，pathに ftp://username:password@hostname/… の書式で，ユーザ名とパスワードを設定できます． ユーザ名とパスワードを設定しない場合は， 匿名(anonymous)でのアクセスとなります．

readf_template()メンバ関数の場合， path_fmt以降の引数をlibcの printf()のそれと同様に指定します．

返り値

0: 正常終了

負の値(エラー): ファイルが見つからないなど，ストリームの読み込みに失敗した場合．

ssize_t stream_length();

システムヘッダ(NAXISなど，SFITSIO側で自動的に整備されるFITSヘッダ項目)を再編し， write_stream()で書き出されるファイルサイズを返します．

返り値

非負の値: ストリームへ書き出されるサイズ

負の値(エラー): エラーが発生した場合(debugモードのみ)

long index( const char *name ) const;
long indexf( const char *fmt, ... ) const;

HDU名 name の番号を返します． "Primary" だけは特別で， ヘッダキーワードEXTNAMEが設定されていない場合でも， プライマリHDUが存在すれば，常に0番を返します．

見つからない場合は，負の値を返します．

name_fmt以降の引数は， libcのprintf()のそれと同様に指定可能です．

fits_hdu &hdu( long index );                          ... 1
fits_hdu &hdu( const char *hduname );                 ... 2
const fits_hdu &hdu( long index ) const;              ... 3
const fits_hdu &hdu( const char *hduname ) const;     ... 4
const fits_hdu &hdu_cs( long index ) const;           ... 5
const fits_hdu &hdu_cs( const char *hduname ) const;  ... 6

HDU番号 index または HDU名 hduname に対応する内部 fits_hdu オブジェクトへの参照を返します． メンバ関数3〜6は読み取り専用です．

これらのメンバ関数で取得した fits_hdu オブジェクトへの参照を経由し， ヘッダ情報とそれに基いた情報にアクセスします． これらのメンバ関数はどのタイプのHDUに対しても使えますが， 画像やテーブルのデータへアクセスする事はできません．

指定されたHDUが存在しない場合，メンバ関数1,2では 新規Image HDUが作られ，メンバ関数3〜6では例外を発生します．

返り値

内部 fits_hdu オブジェクトへの参照

注意

Image HDUを表現する fits_imageクラス および，Binary/ASCII Table HDUを表現する fits_tableクラス は，一般のHDUを表現する fits_hduクラス を継承しています．

fits_image &image( long index );                          ... 1
fits_image &image( const char *hduname );                 ... 2
const fits_image &image( long index ) const;              ... 3
const fits_image &image( const char *hduname ) const;     ... 4
const fits_image &image_cs( long index ) const;           ... 5
const fits_image &image_cs( const char *hduname ) const;  ... 6

HDU番号 index または HDU名 hduname に対応する内部 fits_image オブジェクトへの参照を返します． メンバ関数3〜6は読み取り専用です．

これらのメンバ関数はImage HDUに対して使用します． 取得した fits_image オブジェクトへの参照を経由し， ヘッダや画像データへアクセスします．

指定されたImage HDUが存在しない場合，メンバ関数1,2では 新規Image HDUが作られ，メンバ関数3〜6では例外を発生します．

返り値

内部 fits_image オブジェクトへの参照

注意

Image HDUを表現する fits_imageクラス は，一般のHDUを表現する fits_hduクラス を継承しています．

fits_table &table( long index );                          ... 1
fits_table &table( const char *hduname );                 ... 2
const fits_table &table( long index ) const;              ... 3
const fits_table &table( const char *hduname ) const;     ... 4
const fits_table &table_cs( long index ) const;           ... 5
const fits_table &table_cs( const char *hduname ) const;  ... 6

HDU番号 index または HDU名 hduname に対応する内部 fits_table オブジェクトへの参照を返します． メンバ関数3〜6は読み取り専用です．

これらのメンバ関数はBinary Table HDU または ASCII Table HDU に対して使用します． 取得した fits_table オブジェクトへの参照を経由し， ヘッダやテーブルのデータへアクセスします．

指定された Binary Table HDU または ASCII Table HDU が存在しない場合， メンバ関数1,2では 新規Binary Table HDUが作られ，メンバ関数3〜6では例外を発生します．

返り値

内部 fits_table オブジェクトへの参照

注意

Binary/ASCII Table HDUを表現する fits_tableクラス は，一般のHDUを表現する fits_hduクラス を継承しています．

int hdutype( long index ) const;
int hdutype( const char *name ) const;

index または name で指定された HDUの種別 を返します．返る値は， FITS::IMAGE_HDU， FITS::ASCII_TABLE_HDU， FITS::BINARY_TABLE_HDU のいずれかです．

const char *hduname( long index ) const;

indexで指定されたHDUの名称 (ヘッダのEXTNAMEキーワードの値) を返します． 設定されていない場合は，NULLを返します．

返される値はオブジェクト内部バッファのアドレスですから， オブジェクトが破棄されたり， 名称が変更された場合は無効になります．

fitscc &assign_hduname( long index, const char *name );

indexで指定されたHDUの名称 (ヘッダのEXTNAMEキーワードの値) を変更します．

Primary HDUの場合も指定可能です．

返り値

自身の参照

bool hduver_is_set( long index ) const;
bool hduver_is_set( const char *name ) const;

index または name で指定されたHDUのバージョン番号 (ヘッダのEXTVERキーワードの値) が設定されているか判定します．

返り値

HDUのバージョン番号が設定されていればtrue， そうでなければfalse

long long hduver( long index ) const;
long long hduver( const char *name ) const;

index または name で指定されたHDUのバージョン (ヘッダのEXTVERキーワードの値) を返します．

fitscc &assign_hduver( long index, long long ver );

indexで指定されたHDUのバージョン番号 (ヘッダのEXTVERキーワードの値) を変更します．

Primary HDUの場合も指定可能です．

返り値

自身の参照

HDUの編集のためのメンバ関数

fitscc &append_image( const char *hduname, long long hduver );
fitscc &append_image( const char *hduname, long long hduver,
                      int type, long naxis0 = 0, long naxis1 = 0, long naxis2 = 0 );
fitscc &append_image( const char *hduname, long long hduver,
                      int type, long naxisx[], long ndim, bool init_buf );
fitscc &append_image( const char *hduname, long long hduver,
                      const fits_image &src );
fitscc &append_image( const fits_image &src );

Image HDUを追加します． 引数hdunameは，HDUの名前を指定し， hduverはそのバージョンを指定します． これらの値はFITSヘッダのEXTNAME，EXTVER に反映されます． 引数hdunameにNULLを指定すると， この機能を無効にできます．

typeには 画像のデータ型 として FITS::DOUBLE_T， FITS::FLOAT_T， FITS::LONGLONG_T， FITS::LONG_T， FITS::SHORT_T， FITS::BYTE_T のいずれかを指定します．

naxis0，naxis1，naxis2はそれぞれ， 軸 x, y, z のピクセル数を指定します． naxis1，naxis2は省略可能で， naxis0だけを指定した時は一次元， naxis1までを指定した時は二次元となります． 三次元を越える場合や画像バッファを初期化したくない場合は， 各軸のピクセル数を配列naxisxに， 次元数をndimに， 画像バッファの初期化実施の有無をinit_bufに 指定します．

自身にImage HDUを追加し，既存のImage HDUの内容をそこにコピーする場合は， コピー元としてsrcを指定します．

返り値

自身の参照

fitscc &append_table( const char *hduname, long long hduver,
                      bool ascii = false );
fitscc &append_table( const char *hduname, long long hduver,
                      const fits::table_def defs[], bool ascii = false );
fitscc &append_table( const char *hduname, long long hduver,
                      const fits_table &src );
fitscc &append_table( const fits_table &src );

Ascii Table HDU または Binary Table HDU を追加します． 引数 ascii が true の場合は， Ascii Table HDU を追加します． 引数hdunameは，HDUの名前を指定し， hduverはそのバージョンを指定します． これらの値はFITSヘッダのEXTNAME，EXTVERに 反映されます． 引数 hduname に NULL を指定すると，この機能を無効にできます．

構造体の配列 defs で，アスキーテーブルまたはバイナリテーブルの定義を与えます． fits::table_def構造体のメンバは次のようになっています:

    typedef struct {
        const char *ttype;          /* カラム名 */
        const char *ttype_comment;
        const char *const *talas;   /* カラム名の別名 */
        const char *const *telem;   /* 要素名 */
        const char *tunit;          /* 物理単位 */
        const char *tunit_comment;
        const char *tdisp;          /* ディスプレイフォーマット */
        const char *tform;          /* カラムの型 */
        const char *tdim;           /* 配列の指定 */
        const char *tnull;          /* ブランクの値 */
        const char *tzero;          /* ゼロ点 */
        const char *tscal;          /* スケーリングファクター */
    } fits::table_def;

わかりやすさのため， この構造体のメンバ名はバイナリテーブルのヘッダのキーワード名を そのまま使っています． バイナリテーブルの場合は，それぞれのメンバに TTYPEn，TFORMn 等の値をそのまま代入すれば良いようになっています．

一方，アスキーテーブルの場合は，この構造体のメンバ名は ヘッダのキーワード名と一対一になっていないので注意してください． まず，メンバ tformには，必ず数字+「A」の形で カラムの文字列の長さを "16A" のように指定します(ただし， "120A10" のような指定はできません)． また，telem，tdimの指定は無意味です． tdispには，アスキーテーブルの TFORMn の指定を与え， これはSFITSIOのメンバ関数の引数の値(数値または文字列)を アスキーテーブルに書き込む時に， 引数の値から文字列に変換するフォーマットとして利用されます． 指定できる形式は， Aw，Iw， Fw.d， Ew.d， Dw.d のいずれかです．

指定が不要な項目は，NULL か "" を代入します． 配列 defs の最後では，すべてのメンバがNULLになっている必要があります．

自身に Binary Table HDU または ASCII Table HDU を追加し， 既存の Binary Table HDU または ASCII Table HDU の内容をそこにコピーする場合は， コピー元としてsrcを指定します．

テンプレート機能 (read_template()， SFITSIO: FITSテンプレート を参照) を使うと，新規のバイナリテーブルをテキストファイルで定義でき， 様々な場面で柔軟に対応できます．

返り値

自身の参照

fitscc &insert_image( long index0, 
                      const char *hduname, long long hduver );
fitscc &insert_image( const char *hduname0,
                      const char *hduname, long long hduver );
fitscc &insert_image( long index0,
                      const char *hduname, long long hduver,
                      int type, long naxis0 = 0, long naxis1 = 0, long naxis2 = 0 );
fitscc &insert_image( const char *hduname0,
                      const char *hduname, long long hduver,
                      int type, long naxis0 = 0, long naxis1 = 0, long naxis2 = 0 );
fitscc &insert_image( long index0,
                      const char *hduname, long long hduver,
                      int type, long naxisx[], long ndim, bool init_buf );
fitscc &insert_image( const char *hduname0,
                      const char *hduname, long long hduver,
                      int type, long naxisx[], long ndim, bool init_buf );
fitscc &insert_image( long index0,
                      const char *hduname, long long hduver, 
                      const fits_image &src );
fitscc &insert_image( const char *hduname0,
                      const char *hduname, long long hduver,
                      const fits_image &src );
fitscc &insert_image( long index0, const fits_image &src );
fitscc &insert_image( const char *hduname0, const fits_image &src );

index0 または hduname0 で指定されたHDUの前に Image HDU を挿入します．

引数 index0 または hduname0 より後の引数の仕様は， append_image()メンバ関数の場合と同様です．

返り値

自身の参照

fitscc &insert_table( long index0, 
                      const char *hduname, long long hduver, bool ascii=false );
fitscc &insert_table( const char *hduname0, 
                      const char *hduname, long long hduver, bool ascii=false );
fitscc &insert_table( long index0,
                      const char *hduname, long long hduver,
                      const fits::table_def defs[],
                      bool ascii = false );
fitscc &insert_table( const char *hduname0,
                      const char *hduname, long long hduver,
                      const fits::table_def defs[],
                      bool ascii = false );
fitscc &insert_table( long index0,
                      const char *hduname, long long hduver,
                      const fits_table &src );
fitscc &insert_table( const char *hduname0,
                      const char *hduname, long long hduver,
                      const fits_table &src );
fitscc &insert_table( long index0, const fits_table &src );
fitscc &insert_table( const char *hduname0, const fits_table &src );

index0 または hduname0 で指定されたHDUの前に Ascii Table HDU または Binary Table HDU を挿入します． ただし，Primary HDUの前に挿入する事はできません．

index0 または hduname0 より後の引数の仕様は， append_table() の場合と同様です．

返り値

自身の参照

fitscc &erase( long index );
fitscc &erase( const char *hduname );

index または hduname で指定されたHDUを削除します．

ただし，Primary HDU の次のHDUが Image HDU ではない場合， Primary HDU を削除する事はできません．

返り値

自身の参照