xmipp_image_base.h

Go to the documentation of this file.

/***************************************************************************
 * Authors:     Joaquin Oton (joton@cnb.csic.es)
 *
 *
 * Unidad de  Bioinformatica of Centro Nacional de Biotecnologia , CSIC
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 * 02111-1307  USA
 *
 *  All comments concerning this program package may be sent to the
 *  e-mail address 'xmipp@cnb.csic.es'
 ***************************************************************************/

#ifndef CORE_IMAGE_BASE_H_
#define CORE_IMAGE_BASE_H_

#include <memory>
#include <array>

#include "xmipp_image_macros.h"
#include "xmipp_datatype.h"
#include "metadata_row_vec.h"
#include "xmipp_array_dim.h"
#include "xmipp_filename.h"
#include "transformations_defines.h"

#include <H5Ipublic.h>

template<typename T>
class Matrix2D;
template<typename T>
class Image;
struct tiff;
typedef struct tiff TIFF;
class MultidimArrayBase;
class MetaData;

/* Minimum size of a TIFF file to be mapped to a tempfile in case of mapping from
 * image file is required
 */
const size_t tiff_map_min_size = 0x12000000;



typedef enum
{
    NoTransform = 0,        // No transform
    Standard = 1,           // Standard transform: origin = (0,0,0)
    Centered = 2,           // Centered transform: origin = (nx/2,ny/2,nz/2)
    Hermitian = 3,          // Hermitian half: origin = (0,0,0)
    CentHerm = 4            // Centered hermitian: origin = (0,ny/2,nz/2)
} TransformType;

typedef enum
{
    WRITE_READONLY,   //only can read the file
    WRITE_OVERWRITE, //forget about the old file and overwrite it
    WRITE_REPLACE,   //replace a particular object by another
    WRITE_APPEND,    //append and object at the end of a stack, so far can not append stacks
    WRITE_LAST_LABEL                       // **** NOTE ****: Do keep this label always at the end
    // it is here for looping purposes
} WriteMode;

typedef enum
{
    _NONE = -2,  // Nothing to do. Used by ImageGeneric to check the right datatype to be used
    HEADER = -1, //Don't read image data, only info from main header(datatype and dimensions)
    _HEADER_ALL = 0, //Read complete header(main and geo), useful for header_extract and header_assign
    DATA = 1, //Read image data and main header, geometrical transformations will be ignored
    _DATA_ALL = 2  //Read data with complete header(the use of this option is not recommended, all Xmipp
                // programs should read and write geo info through metadatas
}DataMode;

/* Cast Write mode
 * This enum defines the cast writing behavior
 */
typedef enum
{
    // prefix needed so extract_image_enums.py script can create the equivalent class for Java
    CW_CAST,       //Only cast the data type
    CW_CONVERT,    //Convert the data from one type to another
    CW_ADJUST,     //Adjust the histogram to fill the gray level range
    CW_LAST_LABEL                       // **** NOTE ****: Do keep this label always at the end
    // it is here for looping purposes
} CastWriteMode;

struct ImageFHandler
{
    FILE*     fimg;       // Image File handler
    FILE*     fhed;       // Image File header handler
    TIFF*     tif;        // TIFF Image file handler
    hid_t     fhdf5;   // HDF5 File handler
    FileName  fileName;   // Image file name
    FileName  headName;   // Header file name
    FileName  ext_name;   // Filename extension
    bool     exist;       // Shows if the file exists. Equal 0 means file does not exist or not stack.
    int        mode;   // Opening mode behavior
};

struct ImageInfo
{
    FileName  filename;
    size_t    offset;
    DataType  datatype;
    bool      swap;
    ArrayDim  adim;
};

struct ApplyGeoParams
{
    bool only_apply_shifts;
    DataMode datamode;
    size_t select_img;
    bool wrap;

    ApplyGeoParams()
    {
        only_apply_shifts = false;
        datamode = DATA;
        select_img = ALL_IMAGES;
        wrap = xmipp_transformation::WRAP;
    }
};

const ApplyGeoParams DefaultApplyGeoParams;


#define VOLMATRIX(V) ((V).data)

#define IMGMATRIX(I) ((I).data)

#define IMGPIXEL(I, i, j) A2D_ELEM(((I).data), (i), (j))

#define DIRECT_IMGPIXEL(I, i, j) DIRECT_A2D_ELEM(((I).data), (i), (j))

#define VOLVOXEL(V, k, i, j) A3D_ELEM(((V).data), (k), (i), (j))

#define DIRECT_VOLVOXEL(I, k, i, j) DIRECT_A3D_ELEM(((I).data), (k), (i), (j))

#define SWAPTRIG     16776960


class ImageBase
{
public:
    MultidimArrayBase * mdaBase;    // Pointer to data from Image<template T> casted as MultidimArrayBase
    std::vector<std::unique_ptr<MDRow>> MD;     // data for each subimage, always non-null data present, pointer is here
                                                // to allow storing MDVec / MDSql
    MDRowVec            MDMainHeader;           // data for the file

protected:
    FileName            filename;       // File name
    FileName            tempFilename;   // Temporary filename
    FileName            dataFName;      // Data File name without flags
    FILE*               fimg;           // Image File handler
    FILE*               fhed;           // Image File header handler
    TIFF*               tif;            // TIFF Image file hander
    hid_t               fhdf5;          // HDF5 File handler
    ImageFHandler*      hFile;          // Image File handler information structure
    ArrayDim            aDimFile;       // Image header file information structure (original info from file)
    DataMode            dataMode;       // Flag to force select what will be read/write from image files
    size_t              offset;         // Data offset
    int                 swap;           // Perform byte swapping upon reading
    int                 swapWrite;      // Perform byte swapping upon writing
    std::array<int,4>   axisOrder;      // Order of the axis (tipically 0,1,2,3)
    TransformType       transform;      // Transform type
    size_t              replaceNsize;   // Stack size in the replace case
    bool                _exists;        // does target file exists?  // equal 0 if not exists or not a stack
    bool                mmapOnRead;     // Mapping when reading from file
    bool                mmapOnWrite;    // Mapping when writing to file
    int                 mFd;            // Handle the file in reading method and mmap
    size_t              mappedSize;     // Size of the mapped file
    size_t              mappedOffset;   // Offset for the mapped file
    size_t              virtualOffset;  // MDA Offset when movePointerTo is used

    static constexpr std::array<int,4> defaultAxisOrder = {0,1,2,3};    // Default axis order

public:

    void init();

    void copy(const ImageBase& other);

    virtual void clear()=0;

    void clearHeader();

    virtual bool isComplexT() const=0;

    bool isComplex() const
    {
        return !(transform==NoTransform);
    }

    virtual ~ImageBase();

    bool isImage(const FileName &name);

    inline bool isMapped()
    {
        return (mmapOnRead || mmapOnWrite);
    }

    bool isRealImage(const FileName &name)
    {
        return (isImage(name) && !isComplex());
    }

    bool isComplexImage(const FileName &name)
    {
        return (isImage(name) && isComplex());
    }

    void rename (const FileName &name)
    {
        filename = name;
    }

    void mapFile2Write(size_t Xdim, size_t Ydim, size_t Zdim, const FileName &_filename,
                       bool createTempFile = false, size_t select_img = APPEND_IMAGE,
                       bool isStack = false, int mode = WRITE_OVERWRITE);

    int read(const FileName &name, DataMode datamode = DATA, size_t select_img = ALL_IMAGES,
             bool mapData = false, int mode = WRITE_READONLY);

    int readBatch(const FileName &name, size_t start_img, size_t batch_size, DataMode datamode = DATA, bool mapData = false, int mode = WRITE_READONLY);

    int readRange(const FileName &name, size_t start_img, size_t end_img, DataMode datamode = DATA, bool mapData = false, int mode = WRITE_READONLY);

    int readApplyGeo(const FileName &name, const MDRow &row,
                     const ApplyGeoParams &params = DefaultApplyGeoParams);

    int readApplyGeo(const FileName &name, const MetaData &md, size_t objId,
                     const ApplyGeoParams &params = DefaultApplyGeoParams);

    int readApplyGeo(const MetaData &md, size_t objId,
                     const ApplyGeoParams &params = DefaultApplyGeoParams);

    void applyGeo(const MetaData &md, size_t objId,
                  const ApplyGeoParams &params = DefaultApplyGeoParams);

    void setGeo(const MDRow &row, size_t n=0);

    /* Read an image with a lower resolution as a preview image.
     * If Zdim parameter is not passed, then all slices are rescaled.
     * If Ydim is not passed, then Ydim is rescaled same factor as Xdim.
     */

    /* Read image mapped from file */
    int readMapped(const FileName &name, size_t select_img = ALL_IMAGES, int mode = WRITE_READONLY);

    /* Initially try to read normally, but if there is a memory allocation problem, then
     * try to read from the mapped file.*/
    int readOrReadMapped(const FileName &name, size_t select_img = ALL_IMAGES, int mode = WRITE_READONLY);

    /* Read a thumb/preview image version from file with other dimensions than image originals'.
     * It is also possible to select an specific image from stack or slice from volume.
     * This function is intended for previews of great image files as the image is not copy to memory.
     */
    virtual int readPreview(const FileName &name, size_t Xdim, size_t Ydim=0, int select_slice = CENTRAL_SLICE, size_t select_img = FIRST_IMAGE) = 0;

    virtual void getPreview(ImageBase *imgOut, size_t Xdim, size_t Ydim=0, int select_slice = CENTRAL_SLICE, size_t select_img = FIRST_IMAGE) = 0;

    int readOrReadPreview(const FileName &name, size_t Xdim, size_t Ydim, int select_slice = CENTRAL_SLICE, size_t select_img = FIRST_IMAGE, bool mapData = false);

    void write(const FileName &name="", size_t select_img = ALL_IMAGES, bool isStack=false,
               int mode=WRITE_OVERWRITE,CastWriteMode castMode = CW_CAST, int _swapWrite = 0);

    virtual void movePointerTo(int select_slice = ALL_SLICES, size_t select_img = ALL_IMAGES) = 0;

    /* Return the datatype of the current image object */
    virtual DataType myT() const = 0;

    virtual bool checkMmapT(DataType datatype)=0;

    virtual void writePageAsDatatype(FILE * fimg, DataType datatype, size_t datasize_n )=0;

    void swapPage(char * page, size_t pageNrElements, DataType datatype, int swap = 1);

    /* Force the swapping of the endianness of the file when writing, except for the case
     * when appending or modifying the file.
     */
    void swapOnWrite()
    {
        swapWrite = true;
    }

    const FileName & name() const
    {
        return filename;
    }

    void getDimensions(size_t &Xdim, size_t &Ydim, size_t &Zdim, size_t &Ndim) const;
    void getDimensions(ArrayDim &aDim)
    {
        aDim = aDimFile;
    }
    ArrayDim getDimensions()
    {
        return aDimFile;
    }

    void getInfo(ImageInfo &imgInfo) const;

    void getInfo(const FileName &name, ImageInfo &imgInfo);

    virtual size_t getSize() const = 0;

    void getOffsetAndSwap(size_t &_offset, int &_swap) const
    {
        _offset = offset;
        _swap = swap;
    }

    int getSwap() const
    {
        return swap;
    }

    MDRow& getGeometry(const size_t n = 0)
    {
        return *MD[n];
    }

    void initGeometry(const size_t n = 0);

    /* Check if the label is in the individual header
    */
    bool individualContainsLabel(MDLabel label) const
    {
        return (!MD.empty() && MD[0]->containsLabel(label));
    }

    /* Check if the label is in the main header */
    bool mainContainsLabel(MDLabel label) const
    {
        return MDMainHeader.containsLabel(label);
    }

    double rot(const size_t n = 0) const;

    double tilt(const size_t n = 0) const;

    double psi(const size_t n = 0) const;

    double Xoff(const size_t n = 0) const;

    double Yoff(const size_t n = 0) const;

    double Zoff(const size_t n = 0) const;

    double weight(const size_t n = 0) const;

    double scale(const size_t n = 0) const;

    bool flip(const size_t n = 0) const;

    DataType datatype() const;

    double samplingRateX() const;

    virtual void setDimensions(int Xdim, int Ydim, int Zdim, size_t Ndim) = 0;
    virtual void setDimensions(ArrayDim &aDim);


    void setADimFile(ArrayDim aDim)
    {
        aDimFile = aDim;
    }
    void setName(const FileName &_filename)
    {
        filename = _filename;
    }

    void setDataMode(DataMode mode)
    {
        dataMode = mode;
    }

    void setEulerAngles(double rot, double tilt, double psi,
                        const size_t n = 0);

    void getEulerAngles(double &rot, double &tilt, double &psi,
                        const size_t n = 0) const;

    void setRot(double rot, const size_t n = 0)
    {
        MD[n]->setValue(MDL_ANGLE_ROT, rot);
    }

    void setTilt(double tilt, const size_t n = 0)
    {
        MD[n]->setValue(MDL_ANGLE_TILT, tilt);
    }

    void setPsi(double psi, const size_t n = 0)
    {
        MD[n]->setValue(MDL_ANGLE_PSI, psi);
    }

    void setShifts(double xoff, double yoff, double zoff = 0.,
                   const size_t n = 0);

    void getShifts(double &xoff, double &yoff, double &zoff,
                   const size_t n = 0) const;

    void setXoff(double xoff, const size_t n = 0)
    {
        MD[n]->setValue(MDL_SHIFT_X, xoff);
    }

    void setYoff(double yoff, const size_t n = 0)
    {
        MD[n]->setValue(MDL_SHIFT_Y, yoff);
    }

    void setZoff(double zoff, const size_t n = 0)
    {
        MD[n]->setValue(MDL_SHIFT_Z, zoff);
    }

    void setScale(double scale, const size_t n = 0)
    {
        MD[n]->setValue(MDL_SCALE, scale);
    }

    void getScale(double &scale, const size_t n = 0)
    {
        MD[n]->getValue(MDL_SCALE, scale);
    }

    void setFlip(bool flip, const size_t n = 0)
    {
        MD[n]->setValue(MDL_FLIP, flip);
    }

    void setWeight(double weight, const size_t n = 0)
    {
        MD[n]->setValue(MDL_WEIGHT, weight);
    }

    virtual void getTransformationMatrix(Matrix2D<double> &A,
                                         bool only_apply_shifts = false,
                                         const size_t n = 0)=0;

    virtual void sumWithFile(const FileName &fn)=0;

    virtual void mirrorY() =0;
    virtual void selfApplyGeometry(int SplineDegree, bool wrap, bool only_apply_shifts)=0;


protected:

    // Functions belonging to this topic are commented in rw*.h
#include "rwDM3.h"
#include "rwDM4.h"
#include "rwIMAGIC.h"
#include "rwMRC.h"
#include "rwINF.h"
#include "rwRAW.h"
#include "rwSPIDER.h"
#include "rwSPE.h"
#include "rwTIA.h"
#include "rwJPEG.h"
#include "rwTIFF.h"
#include "rwEM.h"
#include "rwPIF.h"
#include "rwHDF5.h"
#include "rwEER.h"


    ImageFHandler* openFile(const FileName &name, int mode = WRITE_READONLY) const;

    void closeFile(ImageFHandler* hFile = NULL) const;

    virtual void applyGeo(const MDRow &row, bool only_apply_shifts = false, bool wrap = xmipp_transformation::WRAP) = 0;

    int _read(const FileName &name, ImageFHandler* hFile, DataMode datamode = DATA, size_t select_img = ALL_IMAGES,
              bool mapData = false);

    int _readBatch(const FileName &name, ImageFHandler* hFile, size_t start_img, size_t batch_size, DataMode datamode = DATA,
              bool mapData = false);

    void _write(const FileName &name, ImageFHandler* hFile, size_t select_img = ALL_IMAGES,
                bool isStack=false, int mode=WRITE_OVERWRITE,CastWriteMode castMode = CW_CAST);

    virtual void readData(FILE* fimg, size_t select_img, DataType datatype, size_t pad) = 0;

    virtual void readData4bit(FILE* fimg, size_t select_img, DataType datatype, size_t pad) = 0;

    virtual void writeData(FILE* fimg, size_t offset, DataType wDType, size_t datasize_n,
                           CastWriteMode castMode=CW_CAST) = 0;

    virtual void setPage2T(size_t offset, char * page, DataType datatype, size_t pageSize ) = 0;
    virtual void getPageFromT(size_t offset, char * page, DataType datatype, size_t pageSize ) = 0;
    virtual void getCastConvertPageFromT(size_t offset, char * page, DataType datatype, size_t pageSize, double min0, double max0, CastWriteMode castMode=CW_CONVERT) const = 0;

    virtual void mmapFile() = 0;

    virtual void munmapFile() = 0;

    void setDatatype(DataType datatype);

    friend std::ostream& operator<<(std::ostream& o, const ImageBase& I);
private:
    // Auxiliary image used for special write case
    Image<char> *m_auxI;
};
#endif /* IMAGE_BASE_H_ */