From bb42944e6c79d5a81dc30840ceebe70dc0d96658 Mon Sep 17 00:00:00 2001 From: Thomas White Date: Wed, 5 Jul 2017 11:46:24 +0200 Subject: Update docs --- libcrystfel/src/detector.h | 46 ++++++++++++++++++++-- libcrystfel/src/image.h | 95 ++++++++++++++++++++++++++++------------------ libcrystfel/src/index.h | 1 + 3 files changed, 102 insertions(+), 40 deletions(-) (limited to 'libcrystfel') diff --git a/libcrystfel/src/detector.h b/libcrystfel/src/detector.h index e9dd1154..a2be2b47 100644 --- a/libcrystfel/src/detector.h +++ b/libcrystfel/src/detector.h @@ -3,12 +3,12 @@ * * Detector properties * - * Copyright © 2012-2016 Deutsches Elektronen-Synchrotron DESY, + * Copyright © 2012-2017 Deutsches Elektronen-Synchrotron DESY, * a research centre of the Helmholtz Association. * Copyright © 2012 Richard Kirian * * Authors: - * 2009-2016 Thomas White + * 2009-2017 Thomas White * 2011-2012 Richard Kirian * 2014 Valerio Mariani * 2011 Andrew Aquila @@ -42,7 +42,6 @@ struct rg_collection; struct detector; struct panel; struct badregion; -struct detector; struct beam_params; struct hdfile; struct event; @@ -80,6 +79,47 @@ struct rg_collection }; +/** + * panel: + * @name: Text name for the panel (fixed length array) + * @cnx: Location of corner, in pixels, x coordinate + * @cny: Location of corner, in pixels, y coordinate + * @coffset: The offset to be applied from @clen (which may come from elsewhere) + * @clen: The distance from the interaction point to the corner of the first pixel + * @clen_from: Location to get @clen from, e.g. from HDF5 file + * @mask: Location of mask data + * @mask_file: Filename for mask data + * @satmap: Location of per-pixel saturation map + * @satmap_file: Filename for saturation map + * @res: Resolution of panel in pixels per metre + * @badrow: Readout direction (for filtering out clusters of peaks) + * @no_index: Non-zero if panel is entirely "bad" + * @adu_per_photon: Number of detector intensity units per photon + * @adu_per_eV: Number of detector intensity units per eV of photon energy + * @max_adu: Saturation value + * @dim_structure: Dimension structure + * @fsx: Real-space x-direction of data fast-scan direction + * @fsy: Real-space y-direction of data fast-scan direction + * @fsz: Real-space z-direction of data fast-scan direction + * @ssx: Real-space x-direction of data slow-scan direction + * @ssy: Real-space y-direction of data slow-scan direction + * @ssz: Real-space z-direction of data slow-scan direction + * @rail_x: x direction of camera length "rail" + * @rail_y: y direction of camera length "rail" + * @rail_z: z direction of camera length "rail" + * @clen_for_centering: Value of clen (without coffset) at which beam is centered + * @xfs: Data fast-scan direction of real-space x-direction + * @yfs: Data fast-scan direction of real-space y-direction + * @xss: Data slow-scan direction of real-space x-direction + * @yss: Data slow-scan direction of real-space y-direction + * @orig_min_fs: Minimum fs coordinate of data in file + * @orig_max_fs: Maximum fs coordinate of data in file + * @orig_min_ss: Minimum ss coordinate of data in file (inclusive) + * @orig_max_ss: Maximum ss coordinate of data in file (inclusive) + * @data: Location of data in file + * @w: Width of panel + * @h: Height of panel + */ struct panel { char name[1024]; /* Name for this panel */ diff --git a/libcrystfel/src/image.h b/libcrystfel/src/image.h index ead5cd4d..9719bb59 100644 --- a/libcrystfel/src/image.h +++ b/libcrystfel/src/image.h @@ -70,7 +70,26 @@ typedef enum { SPECTRUM_TWOCOLOUR } SpectrumType; -/* Structure describing a feature in an image */ + +/** + * imagefeature: + * @parent: Image this feature belongs to + * @fs: Fast scan coordinate + * @ss: Slow scan coordinate + * @p: Pointer to panel + * @intensity: Intensity of peak + * @rx: Reciprocal x coordinate in m^-1 + * @ry: Reciprocal y coordinate in m^-1 + * @rz: Reciprocal z coordinate in m^-1 + * @name: Text name for feature + * + * Represents a peak in an image. + * + * Note carefully that the @fs and @ss coordinates are the distances, measured + * in pixels, from the corner of the panel. They are NOT pixel indices. + * If the peak is in the middle of the first pixel, its coordinates would be + * 0.5,0.5. + */ struct imagefeature { struct image *parent; @@ -84,10 +103,10 @@ struct imagefeature { double ry; double rz; - /* Internal use only */ - int valid; - const char *name; + + /*< private >*/ + int valid; }; @@ -110,44 +129,46 @@ struct sample }; +/** + * beam_params: + * @photon_energy: eV per photon + * @photon_energy_from: HDF5 dataset name + * @photon_energy_scale: Scale factor for photon energy, if it comes from HDF5 + */ struct beam_params { - double photon_energy; /* eV per photon */ - char *photon_energy_from; /* HDF5 dataset name */ - double photon_energy_scale; /* Scale factor for photon energy, if the - * energy is to be from the HDF5 file */ + double photon_energy; + char *photon_energy_from; + double photon_energy_scale; }; /** * image: - * - * - * struct image - * { - * Crystal **crystals; - * int n_crystals; - * IndexingMethod indexed_by; - * - * struct detector *det; - * struct beam_params *beam; - * char *filename; - * const struct imagefile_field_list *copyme; - * - * int id; - * - * double lambda; - * double div; - * double bw; - * - * int width; - * int height; - * - * long long int num_peaks; - * long long int num_saturated_peaks; - * ImageFeatureList *features; - * }; - * + * @crystals: Array of crystals in the image + * @n_crystals: The number of crystals in the image + * @indexed_by: Indexing method which indexed this pattern + * @det: Detector structure + * @beam: Beam parameters structure + * @filename: Filename for the image file + * @copyme: Fields to copy from the image file to the stream + * @id: ID number of the thread handling this image + * @serial: Serial number for this image + * @lambda: Wavelength + * @div: Divergence + * @bw: Bandwidth + * @num_peaks: The number of peaks + * @num_saturated_peaks: The number of saturated peaks + * @features: The peaks found in the image + * @dp: The image data, by panel + * @bad: The bad pixel mask, array by panel + * @sat: The per-pixel saturation mask, array by panel + * @event: Event ID for the image + * @stuff_from_stream: Items read back from the stream + * @avg_clen: Mean of camera length values for all panels + * @spectrum: Spectrum information + * @nsamples: Number of spectrum samples + * @spectrum_size: SIze of spectrum array * * The field data contains the raw image data, if it * is currently available. The data might be available throughout the @@ -204,8 +225,8 @@ struct image { double bw; /* Bandwidth as a fraction */ /* Detected peaks */ - long long int num_peaks; - long long int num_saturated_peaks; + long long num_peaks; + long long num_saturated_peaks; ImageFeatureList *features; }; diff --git a/libcrystfel/src/index.h b/libcrystfel/src/index.h index 8ce553ae..8dd7de21 100644 --- a/libcrystfel/src/index.h +++ b/libcrystfel/src/index.h @@ -75,6 +75,7 @@ * @INDEXING_SIMULATION: Dummy value * @INDEXING_DEBUG: Results injector for debugging * @INDEXING_ASDF: Use in-built "asdf" indexer + * @INDEXING_ERROR: Special value for unrecognised indexing engine name * @INDEXING_CHECK_CELL_COMBINATIONS: Check linear combinations of unit cell * axes for agreement with given cell. * @INDEXING_CHECK_CELL_AXES: Check unit cell axes for agreement with given -- cgit v1.2.3