Interfile support in the IO library

Collaboration diagram for Interfile support in the IO library:

Files
file	interfile.h
	Declarations of functions which read/write Interfile data.
file	InterfileDynamicDiscretisedDensityOutputFileFormat.h
	Declaration of class stir::InterfileDynamicDiscretisedDensityOutputFileFormat.
file	InterfileHeader.h
	This file declares the classes stir::InterfileHeader, stir::InterfileImageHeader, stir::InterfilePDFSHeader.
file	InterfileHeaderSiemens.h
	This file declares the classes stir::InterfileHeaderSiemens, stir::InterfileRawDataHeaderSiemens, stir::InterfilePDFSHeaderSiemens, stir::InterfileListmodeHeaderSiemens, stir:InterfileNormHeaderSiemens.
file	InterfileOutputFileFormat.h
	Declaration of class stir::InterfileOutputFileFormat.
file	InterfileParametricDiscretisedDensityOutputFileFormat.h
	Declaration of class stir::InterfileParametricDiscretisedDensityOutputFileFormat.
file	InterfilePDFSHeaderSPECT.h
	This file declares the class stir::InterfilePDFSHeaderSPECT.
file	interfile.cxx
	Implementation of functions which read/write Interfile data.
file	InterfileDynamicDiscretisedDensityOutputFileFormat.cxx
	Implementation of class stir::InterfileDynamicDiscretisedDensityOutputFileFormat.
file	InterfileHeader.cxx
	implementations for the stir::InterfileHeader class
file	InterfileHeaderSiemens.cxx
	implementations for the stir::InterfileHeaderSiemens classes
file	InterfileOutputFileFormat.cxx
	Implementation of class stir::InterfileOutputFileFormat.
file	InterfileParametricDiscretisedDensityOutputFileFormat.cxx
	Implementation of class stir::InterfileParametricDiscretisedDensityOutputFileFormat.
file	InterfilePDFSHeaderSPECT.cxx
	This file implements the classes stir::InterfilePDFSHeaderSPECT.

Classes
class	stir::InterfileDynamicDiscretisedDensityOutputFileFormat
	Implementation of OutputFileFormat paradigm for the Interfile format. More...
class	stir::MinimalInterfileHeader
	a minimal class for Interfile keywords (and parsing) common to all types of data More...
class	stir::InterfileHeader
	a class for Interfile keywords (and parsing) common to all types of data More...
class	stir::InterfileImageHeader
	a class for Interfile keywords (and parsing) specific to images More...
class	stir::InterfilePDFSHeader
	a class for Interfile keywords (and parsing) specific to projection data (i.e. ProjDataFromStream) More...
class	stir::InterfileOutputFileFormat
	Implementation of OutputFileFormat paradigm for the Interfile format. More...
class	stir::InterfileParametricDiscretisedDensityOutputFileFormat< DiscDensityT >
	Implementation of OutputFileFormat paradigm for the Interfile format. More...
class	stir::InterfilePDFSHeaderSPECT
	a class for Interfile keywords (and parsing) specific to SPECT projection data More...

Functions
bool	stir::is_interfile_signature (const char *const signature)
	Checks if the signature corresponds to the start of an interfile header. More...
VoxelsOnCartesianGrid< float > *	stir::read_interfile_image (std::istream &input, const std::string &directory_for_data="")
	This reads the first 3d image in an Interfile header file, given as a stream. More...
VoxelsOnCartesianGrid< float > *	stir::read_interfile_image (const std::string &filename)
	This reads the first 3d image in an Interfile header file, given as a filename. More...
Succeeded	stir::write_basic_interfile_image_header (const std::string &header_file_name, const std::string &image_file_name, const ExamInfo &exam_info, const IndexRange< 3 > &index_range, const CartesianCoordinate3D< float > &voxel_size, const CartesianCoordinate3D< float > &origin, const NumericType output_type, const ByteOrder byte_order, const VectorWithOffset< float > &scaling_factors, const VectorWithOffset< unsigned long > &file_offsets, const std::vector< std::string > &data_type_descriptions=std::vector< std::string >())
	This outputs an Interfile header for an image. More...
const VectorWithOffset< unsigned long >	stir::compute_file_offsets (int number_of_time_frames, const NumericType output_type, const Coordinate3D< int > &dim, unsigned long initial_offset=0)
	a utility function that computes the file offsets of subsequent images
template<class elemT >
Succeeded	stir::write_basic_interfile (const std::string &filename, const Array< 3, elemT > &image, const CartesianCoordinate3D< float > &voxel_size, const CartesianCoordinate3D< float > &origin, const NumericType output_type=NumericType::FLOAT, const float scale=0, const ByteOrder byte_order=ByteOrder::native)
	This outputs an Interfile header and data for a Array<3,elemT> object. More...
template<class elemT >
Succeeded	stir::write_basic_interfile (const std::string &filename, const ExamInfo &exam_info, const Array< 3, elemT > &image, const CartesianCoordinate3D< float > &voxel_size, const CartesianCoordinate3D< float > &origin, const NumericType output_type=NumericType::FLOAT, const float scale=0, const ByteOrder byte_order=ByteOrder::native)
	This outputs an Interfile header and data for a Array<3,elemT> object. More...
template<class elemT >
Succeeded	stir::write_basic_interfile (const std::string &filename, const Array< 3, elemT > &image, const NumericType output_type=NumericType::FLOAT, const float scale=0, const ByteOrder byte_order=ByteOrder::native)
	This outputs an Interfile header and data for a Array<3,elemT> object, assuming unit voxel sizes. More...
Succeeded	stir::write_basic_interfile (const std::string &filename, const VoxelsOnCartesianGrid< float > &image, const NumericType output_type=NumericType::FLOAT, const float scale=0, const ByteOrder byte_order=ByteOrder::native)
	This outputs an Interfile header and data for a VoxelsOnCartesianGrid<float> object. More...
Succeeded	stir::write_basic_interfile (const std::string &filename, const DiscretisedDensity< 3, float > &image, const NumericType output_type=NumericType::FLOAT, const float scale=0, const ByteOrder byte_order=ByteOrder::native)
	This outputs an Interfile header and data for a DiscretisedDensity<3,float> object. More...
ProjDataFromStream *	stir::read_interfile_PDFS (std::istream &input, const std::string &directory_for_data="", const std::ios::openmode openmode=std::ios::in)
	This reads the first 3D sinogram from an Interfile header, given as a stream. More...
ProjDataFromStream *	stir::read_interfile_PDFS (const std::string &filename, const std::ios::openmode open_mode)
	This reads the first 3D sinogram from an Interfile header, given as a filename. More...
Succeeded	stir::write_basic_interfile_PDFS_header (const std::string &header_filename, const std::string &data_filename, const ProjDataFromStream &pdfs)
	This writes an Interfile header appropriate for the ProjDataFromStream object. More...
Succeeded	stir::write_basic_interfile_PDFS_header (const std::string &data_filename, const ProjDataFromStream &pdfs)
	This function writes an Interfile header for the pdfs object. More...

Detailed Description

Function Documentation

is_interfile_signature()

bool stir::is_interfile_signature

(

const char *const

signature

)

Checks if the signature corresponds to the start of an interfile header.

The first line of an Interfile header should contain the

  INTERFILE :=

(potentially preceded by an exclamation mark, and maybe in mixed or lower case). This function checks if the list of characters pointed to by signature satifies these requirements.

Warning

The parameter signature should be 0 terminated.

References stir::standardise_interfile_keyword().

Referenced by stir::DynamicProjData::set_start_time_in_secs_since_1970(), and stir::TimeFrameDefinitions::TimeFrameDefinitions().

read_interfile_image() [1/2]

VoxelsOnCartesianGrid< float > * stir::read_interfile_image	(	std::istream &	input,
		const std::string &	directory_for_data = ""
	)

This reads the first 3d image in an Interfile header file, given as a stream.

If there is trouble interpreting the header, VoxelsOnCartesianGrid<float>::ask_parameters() is called instead If the name for the data file is not an absolute pathname, directory_for_data is prepended (if not NULL).

Warning

it is up to the caller to deallocate the image

This should normally never be used. Use read_from_file<DiscretisedDensity<3,float> >() instead.

References stir::max_filename_length.

Referenced by stir::InterfileImageInputFileFormat::read_from_file(), and stir::read_interfile_image().

read_interfile_image() [2/2]

VoxelsOnCartesianGrid< float > * stir::read_interfile_image

(

const std::string &

filename

)

This reads the first 3d image in an Interfile header file, given as a filename.

The function first opens a stream from 'filename' and then calls the previous function with 'directory_for_data' set to the directory part of 'filename'.

Warning

it is up to the caller to deallocate the image

This should normally never be used. Use read_from_file<DiscretisedDensity<3,float> >() instead.

References stir::error(), stir::get_directory_name(), stir::max_filename_length, and stir::read_interfile_image().

write_basic_interfile_image_header()

Succeeded stir::write_basic_interfile_image_header	(	const std::string &	header_file_name,
		const std::string &	image_file_name,
		const ExamInfo &	exam_info,
		const IndexRange< 3 > &	index_range,
		const CartesianCoordinate3D< float > &	voxel_size,
		const CartesianCoordinate3D< float > &	origin,
		const NumericType	output_type,
		const ByteOrder	byte_order,
		const VectorWithOffset< float > &	scaling_factors,
		const VectorWithOffset< unsigned long > &	file_offsets,
		const std::vector< std::string > &	data_type_descriptions = std::vector<std::string>()
	)

This outputs an Interfile header for an image.

A .hv extension will be added to the header_file_name if none is present.

Returns

Succeeded::yes when succesful, Succeeded::no otherwise.

In fact, at the moment 2 headers are output:

• 'header_file_name' is 'new-style' (suitable for Mediman for instance),
• *.ahv is 'old-style' (Interfile version 3.3) (suitable for Analyze for instance)

They both point to the same file with binary data.

Warning

The .ahv file contains a fix such that Analyze reads the data with the correct voxel size (in z), which is probably non-confirming, and so will get other programs to read the voxel size incorrectly. A relevant comment is written in each .ahv file.

References stir::add_extension(), stir::IndexRange< num_dimensions >::get_regular_range(), and stir::warning().

write_basic_interfile() [1/5]

template<class elemT >

Succeeded stir::write_basic_interfile	(	const std::string &	filename,
		const Array< 3, elemT > &	image,
		const CartesianCoordinate3D< float > &	voxel_size,
		const CartesianCoordinate3D< float > &	origin,
		const NumericType	output_type = NumericType::FLOAT,
		const float	scale = 0,
		const ByteOrder	byte_order = ByteOrder::native
	)

This outputs an Interfile header and data for a Array<3,elemT> object.

Extension .v will be added to the parameter 'filename' (if no extension present). Extensions .hv (and .ahv) will be used for the header filename.

Referenced by stir::InterfileOutputFileFormat::actual_write_to_file(), and stir::InterfileDynamicDiscretisedDensityOutputFileFormat::actual_write_to_file().

write_basic_interfile() [2/5]

template<class elemT >

Succeeded stir::write_basic_interfile	(	const std::string &	filename,
		const ExamInfo &	exam_info,
		const Array< 3, elemT > &	image,
		const CartesianCoordinate3D< float > &	voxel_size,
		const CartesianCoordinate3D< float > &	origin,
		const NumericType	output_type = NumericType::FLOAT,
		const float	scale = 0,
		const ByteOrder	byte_order = ByteOrder::native
	)

This outputs an Interfile header and data for a Array<3,elemT> object.

Extension .v will be added to the parameter 'filename' (if no extension present). Extensions .hv (and .ahv) will be used for the header filename.

write_basic_interfile() [3/5]

template<class elemT >

Succeeded stir::write_basic_interfile	(	const std::string &	filename,
		const Array< 3, elemT > &	image,
		const NumericType	output_type = NumericType::FLOAT,
		const float	scale = 0,
		const ByteOrder	byte_order = ByteOrder::native
	)

This outputs an Interfile header and data for a Array<3,elemT> object, assuming unit voxel sizes.

Extension .v will be added to the parameter 'filename' (if no extension present). Extensions .hv (and .ahv) will be used for the header filename.

Warning

For Visual Studio 7.0 or earlier, only the float version is defined to work around a compiler bug. (Otherwise, the float version is not instantiated for some reason).

write_basic_interfile() [4/5]

Succeeded stir::write_basic_interfile	(	const std::string &	filename,
		const VoxelsOnCartesianGrid< float > &	image,
		const NumericType	output_type = NumericType::FLOAT,
		const float	scale = 0,
		const ByteOrder	byte_order = ByteOrder::native
	)

This outputs an Interfile header and data for a VoxelsOnCartesianGrid<float> object.

Extension .v will be added to the parameter 'filename' (if no extension present). Extensions .hv (and .ahv) will be used for the header filename.

write_basic_interfile() [5/5]

Succeeded stir::write_basic_interfile	(	const std::string &	filename,
		const DiscretisedDensity< 3, float > &	image,
		const NumericType	output_type = NumericType::FLOAT,
		const float	scale = 0,
		const ByteOrder	byte_order = ByteOrder::native
	)

This outputs an Interfile header and data for a DiscretisedDensity<3,float> object.

Extension .v will be added to the parameter 'filename' (if no extension present). Extensions .hv (and .ahv) will be used for the header filename.

Currently the DiscretisedDensity<3,float>& object has to be a reference to a VoxelsOnCartesianGrid<float> object.

read_interfile_PDFS() [1/2]

ProjDataFromStream* stir::read_interfile_PDFS	(	std::istream &	input,
		const std::string &	directory_for_data = "",
		const std::ios::openmode	openmode = std::ios::in
	)

This reads the first 3D sinogram from an Interfile header, given as a stream.

If there is trouble interpreting the header, ProjDataFromStream::ask_parameters() is called instead

Parameters

input	A stream giving the Interfile header.
directory_for_data	If the name for the data file is not an absolute pathname, this string is prepended.
openmode	Mode for opening the data file. ios::binary will be added by the code.

Warning

it is up to the caller to deallocate the object

read_interfile_PDFS() [2/2]

ProjDataFromStream* stir::read_interfile_PDFS	(	const std::string &	filename,
		const std::ios::openmode	open_mode
	)

This reads the first 3D sinogram from an Interfile header, given as a filename.

This first opens a stream and then calls the previous function with 'directory_for_data' set to the directory part of 'filename'.

Warning

it is up to the caller to deallocate the object

This should normally never be used. Use ProjData::read_from_file() instead.

write_basic_interfile_PDFS_header() [1/2]

Succeeded stir::write_basic_interfile_PDFS_header	(	const std::string &	header_filename,
		const std::string &	data_filename,
		const ProjDataFromStream &	pdfs
	)

This writes an Interfile header appropriate for the ProjDataFromStream object.

A .hs extension will be added to the header_file_name if none is present.

Returns

Succeeded::yes when succesful, Succeeded::no otherwise.

References stir::add_extension(), and stir::warning().

Referenced by stir::ProjDataFromStream::set_segment(), and stir::write_basic_interfile_PDFS_header().

write_basic_interfile_PDFS_header() [2/2]

Succeeded stir::write_basic_interfile_PDFS_header	(	const std::string &	data_filename,
		const ProjDataFromStream &	pdfs
	)

This function writes an Interfile header for the pdfs object.

The header_filename is found by replacing the extension in the data_filename with .hs

Returns

Succeeded::yes when succesful, Succeeded::no otherwise.

References stir::add_extension(), stir::find_filename(), stir::find_pos_of_extension(), stir::max_filename_length, stir::replace_extension(), and stir::write_basic_interfile_PDFS_header().