datatemplate.h File Reference

Data Structures
struct	dg_group_info

Typedefs
typedef struct _datatemplate	DataTemplate

Functions
DataTemplate *	data_template_new_from_file (const char *filename)
DataTemplate *	data_template_new_from_string (const char *string_in)
void	data_template_free (DataTemplate *dt)
const char *	data_template_panel_number_to_name (const DataTemplate *dt, int pn)
int	data_template_panel_name_to_number (const DataTemplate *dt, const char *panel_name, int *pn)
int	data_template_file_to_panel_coords (const DataTemplate *dt, float *pfs, float *pss, int pn)
int	data_template_slabby_file_to_panel_coords (const DataTemplate *dt, float *pfs, float *pss, int *ppn)
int	data_template_panel_to_file_coords (const DataTemplate *dt, int pn, float *pfs, float *pss)
void	data_template_add_copy_header (DataTemplate *dt, const char *header)
int	data_template_get_slab_extents (const DataTemplate *dt, int *pw, int *ph)
double	data_template_get_wavelength_if_possible (const DataTemplate *dt)
double	data_template_get_clen_if_possible (const DataTemplate *dt)
struct detgeom *	data_template_get_detgeom_if_possible (const DataTemplate *dt, int no_clen_ok)
void	data_template_show_hierarchy (const DataTemplate *dtempl)
int	data_template_translate_group_px (DataTemplate *dtempl, const char *group_name, double x, double y, double z)
int	data_template_translate_group_m (DataTemplate *dtempl, const char *group_name, double x, double y, double z)
int	data_template_rotate_group (DataTemplate *dtempl, const char *group_name, double ang, char axis)
int	data_template_write_to_fh (const DataTemplate *dtempl, FILE *fh)
int	data_template_write_to_file (const DataTemplate *dtempl, const char *filename)
struct dg_group_info *	data_template_group_info (const DataTemplate *dtempl, int *n)
void	data_template_reset_total_movements (DataTemplate *dtempl)
void	data_template_print_total_movements (const DataTemplate *dtempl)

Detailed Description

Template for loading data.

Typedef Documentation

DataTemplate

typedef struct _datatemplate DataTemplate

This data structure is opaque. You must use the available accessor functions to read and write its contents.

Function Documentation

data_template_get_clen_if_possible()

double data_template_get_clen_if_possible ( const DataTemplate * dt )

extern

Returns the mean panel z-position in m, provided that:

1. The individual panel distances vary by no more than 10% of the average
2. The tilt of the panel creates a distance variation of no more than 10% of the corner value over the extent of the panel
3. The detector geometry is static (no per-frame clen)

If these prerequisites are not met, returns NAN.

The very notion of a single "camera length" value relies on the traditional experiment model of a flat detector, perpendicular to the beam. You should avoid embedding this assumption into any programs, as much as possible. Therefore, avoid using this routine.

Returns

the mean camera length, or NAN.

data_template_get_detgeom_if_possible()

struct detgeom * data_template_get_detgeom_if_possible ( const DataTemplate * dt, int no_clen_ok )

extern

Create a detgeom structure from the DataTemplate, if it's possible to do so.

This procedure will create a detgeom structure, provided that this can be done without loading an image. References to image metadata (e.g. HDF5 datasets) for clen or detector_shift_x/y will prevent this from working.

If you do not care about the overall detector distance, set no_clen_ok to any non-zero value. In this case, the relative z-positions of the panels will be correct, but the overall z-position (along the beam direction) may be wrong.

You should take care to gracefully handle a NULL return value from this routine.

Returns

the detgeom structure, or NULL if impossible.

data_template_get_wavelength_if_possible()

double data_template_get_wavelength_if_possible ( const DataTemplate * dt )

extern

Get the wavelength from a DataTemplate, if possible.

WARNING: This is probably not the routine you are looking for! See the disclaimer for image_create_for_simulation(), which applies equally to this routine.

Returns

the wavelength, in metres, or NAN if impossible.

data_template_rotate_group()

int data_template_rotate_group ( DataTemplate * dtempl, const char * group_name, double ang, char axis )

extern

Alters dtempl by rotating the named panel group by ang (radians) about the specified axis (char 'x', 'y' or 'z'), around the center of the group.

Returns

zero for success, non-zero on error

data_template_slabby_file_to_panel_coords()

int data_template_slabby_file_to_panel_coords ( const DataTemplate * dt, float * pfs, float * pss, int * ppn )

extern

Convert image-data-space fs/ss coordinates to panel-relative fs/ss coordinates and panel number, assuming that the data is all in one slab.

WARNING: This is probably not the routine you are looking for! If you use this routine, your code will only work with 'slabby' data, and will break for (amongst others) EuXFEL data. Use data_template_file_to_panel_coords instead, and provide the panel number.

Returns

0 on success, 1 on failure

data_template_translate_group_m()

int data_template_translate_group_m ( DataTemplate * dtempl, const char * group_name, double x, double y, double z )

extern

Alters dtempl by shifting the named panel group by x,y,z in the CrystFEL coordinate system. x,y,z are in metres.

Returns

zero for success, non-zero on error

data_template_translate_group_px()

int data_template_translate_group_px ( DataTemplate * dtempl, const char * group_name, double x, double y, double z )

extern

Alters dtempl by shifting the named panel group by x,y,z in the CrystFEL coordinate system. x,y,z are in pixels, and all panels in the group must have the same pixel size (but, this will not be checked).

Returns

zero for success, non-zero on error