image.h

Go to the documentation of this file.

/*
* ECVL - European Computer Vision Library
* Version: 0.3.4
* copyright (c) 2021, Università degli Studi di Modena e Reggio Emilia (UNIMORE), AImageLab
* Authors:
*    Costantino Grana (costantino.grana@unimore.it)
*    Federico Bolelli (federico.bolelli@unimore.it)
*    Michele Cancilla (michele.cancilla@unimore.it)
*    Laura Canalini (laura.canalini@unimore.it)
*    Stefano Allegretti (stefano.allegretti@unimore.it)
* All rights reserved.
*/

#ifndef ECVL_IMAGE_H_
#define ECVL_IMAGE_H_

#include <algorithm>
#include <numeric>
#include <stdexcept>
#include <vector>

#include <opencv2/core.hpp>

#include "datatype.h"
#include "hal.h"
#include "iterators.h"
#include "datatype_matrix.h"
#include "type_promotion.h"
#include "standard_errors.h"

namespace ecvl
{
template<typename T>
int vsize(const std::vector<T>& v)
{
    return static_cast<int>(v.size());
}

class MetaData
{
public:
    virtual bool Query(const std::string& name, std::string& value) const = 0;
    virtual ~MetaData() {}
};

enum class ColorType
{
    none,  
    GRAY,  
    RGB,   
    RGBA,  
    BGR,   
    HSV,   
    YCbCr, 
};

class Image;

template <DataType DT>
class View;

template <DataType DT>
class ConstView;

class Image
{
protected:
    void SetDefaultStrides()
    {
        // Compute strides
        strides_ = { elemsize_ };
        int dsize = vsize(dims_);
        for (int i = 0; i < dsize - 1; ++i) {
            strides_.push_back(strides_[i] * dims_[i]);
        }
    }

    size_t GetDefaultDatasize()
    {
        return std::accumulate(std::begin(dims_), std::end(dims_), size_t(elemsize_), std::multiplies<size_t>());
    }

    void SetDefaultDatasize()
    {
        datasize_ = GetDefaultDatasize();
    }

    friend class HardwareAbstractionLayer;

public:
    DataType                    elemtype_;          
    uint8_t                     elemsize_;          
    std::vector<int>            dims_;              
    std::vector<int>            strides_;           
    std::string                 channels_;          
    ColorType                   colortype_;         
    std::vector<float>          spacings_;          
    uint8_t* data_;              
    size_t                      datasize_;          
    bool                        contiguous_;        
    MetaData* meta_;                                
    HardwareAbstractionLayer* hal_;               
    Device                      dev_;               
    template<typename T>
    Iterator<T> Begin() { return Iterator<T>(*this); }

    template<typename T>
    Iterator<T> End() { return Iterator<T>(*this, dims_); }

    template<typename T>
    ConstIterator<T> Begin() const { return ConstIterator<T>(*this); }

    template<typename T>
    ConstIterator<T> End() const { return ConstIterator<T>(*this, dims_); }

    template<typename T>
    ContiguousIterator<T> ContiguousBegin() { return ContiguousIterator<T>(*this); }

    template<typename T>
    ContiguousIterator<T> ContiguousEnd() { return ContiguousIterator<T>(*this, dims_); }

    template<typename T>
    ConstContiguousIterator<T> ContiguousBegin() const { return ConstContiguousIterator<T>(*this); }

    template<typename T>
    ConstContiguousIterator<T> ContiguousEnd() const { return ConstContiguousIterator<T>(*this, dims_); }

    Image() :
        elemtype_{ DataType::none },
        elemsize_{ DataTypeSize(elemtype_) },
        dims_{},
        spacings_{},
        strides_{},
        channels_{},
        colortype_{ ColorType::none },
        data_{ nullptr },
        datasize_{ 0 },
        contiguous_{ true },
        meta_{ nullptr },
        hal_{ nullptr },
        dev_{ Device::NONE }
    {
    }

    Image(const std::vector<int>& dims, DataType elemtype, std::string channels, ColorType colortype,
        const std::vector<float>& spacings = std::vector<float>(), Device dev = Device::CPU) :
        elemtype_{ elemtype },
        elemsize_{ DataTypeSize(elemtype_) },
        dims_{ dims },
        spacings_{ spacings },
        strides_{},
        channels_{ move(channels) },
        colortype_{ colortype },
        data_{ nullptr },
        datasize_{ 0 },
        contiguous_{ true },
        meta_{ nullptr },
        hal_{ HardwareAbstractionLayer::Factory(dev) },
        dev_{ dev }
    {
        if (dims_.size() != channels_.size()) {
            throw std::runtime_error("Number of dimensions must match number of channels.");
        }
        hal_->Create(*this);
    }

    Image(const Image& img) :
        elemtype_{ img.elemtype_ },
        elemsize_{ img.elemsize_ },
        dims_{ img.dims_ },
        spacings_{ img.spacings_ },
        strides_{ img.strides_ },
        channels_{ img.channels_ },
        colortype_{ img.colortype_ },
        data_{},
        datasize_{ img.datasize_ },
        contiguous_{ img.contiguous_ },
        meta_{ img.meta_ },
        hal_{ img.hal_ },
        dev_{ img.dev_ }
    {
        hal_->Copy(img, *this);
    }

    Image(Image&& img)
    {
        elemtype_ = img.elemtype_;
        elemsize_ = img.elemsize_;
        dims_ = img.dims_;
        spacings_ = img.spacings_;
        strides_ = img.strides_;
        channels_ = img.channels_;
        colortype_ = img.colortype_;
        data_ = img.data_;
        datasize_ = img.datasize_;
        contiguous_ = img.contiguous_;
        meta_ = img.meta_;
        hal_ = img.hal_;
        dev_ = img.dev_;
        img.hal_ = nullptr; // This disables destruction of rhs.data_
    }

    friend void swap(Image& lhs, Image& rhs)
    {
        using std::swap;
        swap(lhs.elemtype_, rhs.elemtype_);
        swap(lhs.elemsize_, rhs.elemsize_);
        swap(lhs.dims_, rhs.dims_);
        swap(lhs.spacings_, rhs.spacings_);
        swap(lhs.strides_, rhs.strides_);
        swap(lhs.channels_, rhs.channels_);
        swap(lhs.colortype_, rhs.colortype_);
        swap(lhs.data_, rhs.data_);
        swap(lhs.datasize_, rhs.datasize_);
        swap(lhs.contiguous_, rhs.contiguous_);
        swap(lhs.meta_, rhs.meta_);
        swap(lhs.hal_, rhs.hal_);
        swap(lhs.dev_, rhs.dev_);
    }

    Image& operator=(const Image& rhs)
    {
        // Self-assignment detection
        if (this != &rhs) {
            Image tmp = rhs;  // Copy and swap because I'm lazy, but still want super cheap self assignment
            swap(*this, tmp);
        }
        return *this;
    }

    Image& operator=(Image&& rhs)
    {
        assert(this != &rhs);
        elemtype_ = rhs.elemtype_;
        elemsize_ = rhs.elemsize_;
        dims_ = rhs.dims_;
        spacings_ = rhs.spacings_;
        strides_ = rhs.strides_;
        channels_ = rhs.channels_;
        colortype_ = rhs.colortype_;
        // Release any resource we are holding
        if (hal_) {
            hal_->MemDeallocate(data_);
        }
        data_ = rhs.data_;
        datasize_ = rhs.datasize_;
        contiguous_ = rhs.contiguous_;
        meta_ = rhs.meta_;
        hal_ = rhs.hal_;
        dev_ = rhs.dev_;
        rhs.hal_ = nullptr; // This disables destruction of rhs.data_
        return *this;
    }

    void To(Device dev)
    {
        if (dev_ == dev) {
            return;
        }
        if (dev_ == Device::NONE || dev == Device::NONE) {
            throw std::runtime_error(ECVL_ERROR_MSG "Source or dest device is NONE");
        }

        if (dev_ == Device::CPU) { // Move from CPU to other device
            auto dst_hal_ = HardwareAbstractionLayer::Factory(dev);
            dst_hal_->FromCpu(*this);
        }
        else if (dev == Device::CPU) { // Move from other device to CPU
            hal_->ToCpu(*this);
        }
        else {
            throw std::runtime_error(ECVL_ERROR_MSG "Source or dest device must be CPU");
        }
    }

    void Create(const std::vector<int>& dims, DataType elemtype, std::string channels, ColorType colortype,
        const std::vector<float>& spacings = std::vector<float>(), Device dev = Device::CPU);

    ~Image()
    {
        if (hal_) {
            hal_->MemDeallocate(data_);
        }
    }

    bool IsEmpty() const { return data_ == nullptr; }

    bool IsOwner() const { return hal_->IsOwner(); }

    int Channels() const
    {
        size_t c = channels_.find('c');
        if (c != std::string::npos) {
            return dims_[c];
        }
        c = channels_.find('z');
        if (c != std::string::npos) {
            return dims_[c];
        }
        c = channels_.find('o');
        if (c != std::string::npos) {
            return dims_[c];
        }
        return 0;
    }

    int Width() const
    {
        size_t x = channels_.find('x');
        if (x != std::string::npos) {
            return dims_[x];
        }
        return 0;
    }

    int Height() const
    {
        size_t y = channels_.find('y');
        if (y != std::string::npos) {
            return dims_[y];
        }
        return 0;
    }

    uint8_t* Ptr(const std::vector<int>& coords)
    {
        assert(coords.size() == strides_.size());
        return std::inner_product(std::begin(coords), std::end(coords), std::begin(strides_), data_);
    }
    const uint8_t* Ptr(const std::vector<int>& coords) const
    {
        assert(coords.size() == strides_.size());
        return std::inner_product(std::begin(coords), std::end(coords), std::begin(strides_), data_);
    }

    void Neg()
    {
        hal_->Neg(*this, *this, elemtype_, false);
    }

    template<typename T>
    void Add(const T& rhs, bool saturate = true)
    {
        hal_->Add(*this, rhs, *this, elemtype_, saturate);
    }

    template<typename T>
    void Sub(const T& rhs, bool saturate = true)
    {
        hal_->Sub(*this, rhs, *this, elemtype_, saturate);
    }

    template<typename T>
    void Mul(const T& rhs, bool saturate = true)
    {
        hal_->Mul(*this, rhs, *this, elemtype_, saturate);
    }

    template<typename T>
    void Div(const T& rhs, bool saturate = true)
    {
        hal_->Div(*this, rhs, *this, elemtype_, saturate);
    }

    template<typename T>
    void SetTo(T value)
    {
        hal_->SetTo(*this, value);
    }

    void ConvertTo(DataType dtype, bool saturate = true)
    {
        hal_->ConvertTo(*this, *this, dtype, saturate);
    }

    Image operator-() const;

    Image& operator+=(const Image& rhs);

    Image& operator-=(const Image& rhs);

    Image& operator*=(const Image& rhs);

    Image& operator/=(const Image& rhs);

    friend Image operator+(Image lhs, const Image& rhs);

    friend Image operator-(Image lhs, const Image& rhs);

    friend Image operator*(Image lhs, const Image& rhs);

    friend Image operator/(Image lhs, const Image& rhs);
};

template <typename ViewType>
static void CropViewInternal(ViewType& view, const std::vector<int>& start, const std::vector<int>& size)
{
    std::vector<int> new_dims;
    int ssize = vsize(size);
    for (int i = 0; i < ssize; ++i) {
        if (start[i] < 0 || start[i] >= view.dims_[i])
            throw std::runtime_error("Start of crop outside image limits");
        new_dims.push_back(view.dims_[i] - start[i]);
        if (size[i] > new_dims[i]) {
            throw std::runtime_error("Crop outside image limits");
        }
        if (size[i] >= 0) {
            new_dims[i] = size[i];
        }
    }

    // Check if image has a color dimension
    auto cpos = view.channels_.find('c');
    if (cpos != std::string::npos) {
        // If we are cropping the color channel, we fix the color information
        if (new_dims[cpos] != view.dims_[cpos]) {
            if (new_dims[cpos] == 1) {
                view.colortype_ = ColorType::GRAY;
            }
            else {
                view.channels_[cpos] = 'o';
                view.colortype_ = ColorType::none;
            }
        }
    }

    view.data_ = view.Ptr(start);

    if (view.contiguous_) {
        for (int i = 0; i < view.dims_.size() - 1; ++i) {
            if (new_dims[i] != view.dims_[i]) {
                view.contiguous_ = false;
            }
        }
    }
    if (view.contiguous_) {
        view.datasize_ = std::accumulate(std::begin(new_dims), std::end(new_dims), size_t(view.elemsize_), std::multiplies<size_t>());
    }
    else {
        view.datasize_ = 0; // This is set to zero, because when the View is not contiguous, it's useless to relay on this information
    }

    view.dims_ = std::move(new_dims);
}

#include "iterators_impl.inc.h"
template <DataType DT>
class View : public Image
{
public:
    using basetype = typename TypeInfo<DT>::basetype;

    View() {}

    View(Image& img)
    {
        if (DT != img.elemtype_)
            throw std::runtime_error("View type is different from Image type");
        elemtype_ = img.elemtype_;
        elemsize_ = img.elemsize_;
        dims_ = img.dims_;
        spacings_ = img.spacings_;
        strides_ = img.strides_;
        channels_ = img.channels_;
        colortype_ = img.colortype_;
        data_ = img.data_;
        datasize_ = img.datasize_;
        contiguous_ = img.contiguous_;
        meta_ = img.meta_;
        hal_ = HardwareAbstractionLayer::Factory(img.dev_, true);
        dev_ = img.dev_;
    }

    View(Image& img, const std::vector<int>& start, const std::vector<int>& size) : View(img)
    {
        CropViewInternal(*this, start, size);
    }

    basetype& operator()(const std::vector<int>& coords)
    {
        return *reinterpret_cast<basetype*>(Ptr(coords));
    }

    void Create(std::vector<int> dims, std::string channels, ColorType colortype, uint8_t* ptr,
        const std::vector<float>& spacings = std::vector<float>(), Device dev = Device::CPU)
    {
        elemtype_ = DT;
        elemsize_ = DataTypeSize(elemtype_);
        dims_ = std::move(dims);
        spacings_ = spacings;
        channels_ = std::move(channels);
        colortype_ = colortype;

        SetDefaultDatasize();
        SetDefaultStrides();

        data_ = ptr;
        hal_ = HardwareAbstractionLayer::Factory(dev, true);
        dev_ = dev;
        return;
    }

    Iterator<basetype> Begin() { return Iterator<basetype>(*this); }
    Iterator<basetype> End() { return Iterator<basetype>(*this, dims_); }
};

template <DataType DT>
class ConstView : public Image
{
public:
    using basetype = typename TypeInfo<DT>::basetype;

    ConstView() {}

    ConstView(const Image& img)
    {
        elemtype_ = img.elemtype_;
        elemsize_ = img.elemsize_;
        dims_ = img.dims_;
        spacings_ = img.spacings_;
        strides_ = img.strides_;
        channels_ = img.channels_;
        colortype_ = img.colortype_;
        data_ = img.data_;
        datasize_ = img.datasize_;
        contiguous_ = img.contiguous_;
        meta_ = img.meta_;
        hal_ = HardwareAbstractionLayer::Factory(img.dev_, true);
        dev_ = img.dev_;
    }

    ConstView(const Image& img, const std::vector<int>& start, const std::vector<int>& size) : ConstView(img)
    {
        CropViewInternal(*this, start, size);
    }

    const basetype& operator()(const std::vector<int>& coords)
    {
        return *reinterpret_cast<const basetype*>(Ptr(coords));
    }

    ConstIterator<basetype> Begin() { return ConstIterator<basetype>(*this); }
    ConstIterator<basetype> End() { return ConstIterator<basetype>(*this, dims_); }
};

template <DataType DT>
class ContiguousView : public Image
{
public:
    using basetype = typename TypeInfo<DT>::basetype;

    ContiguousView() {}

    ContiguousView(Image& img)
    {
        elemtype_ = img.elemtype_;
        elemsize_ = img.elemsize_;
        dims_ = img.dims_;
        spacings_ = img.spacings_;
        strides_ = img.strides_;
        channels_ = img.channels_;
        colortype_ = img.colortype_;
        data_ = img.data_;
        datasize_ = img.datasize_;
        contiguous_ = img.contiguous_;
        meta_ = img.meta_;
        hal_ = HardwareAbstractionLayer::Factory(img.dev_, true);
        dev_ = img.dev_;
    }

    basetype& operator()(const std::vector<int>& coords)
    {
        return *reinterpret_cast<basetype*>(Ptr(coords));
    }

    ContiguousIterator<basetype> Begin() { return ContiguousIterator<basetype>(*this); }
    ContiguousIterator<basetype> End() { return ContiguousIterator<basetype>(*this, dims_); }
};

template <DataType DT>
class ConstContiguousView : public Image
{
public:
    using basetype = typename TypeInfo<DT>::basetype;

    ConstContiguousView() {}

    ConstContiguousView(const Image& img)
    {
        elemtype_ = img.elemtype_;
        elemsize_ = img.elemsize_;
        dims_ = img.dims_;
        spacings_ = img.spacings_;
        strides_ = img.strides_;
        channels_ = img.channels_;
        colortype_ = img.colortype_;
        data_ = img.data_;
        datasize_ = img.datasize_;
        contiguous_ = img.contiguous_;
        meta_ = img.meta_;
        hal_ = HardwareAbstractionLayer::Factory(img.dev_, true);
        dev_ = img.dev_;
    }

    const basetype& operator()(const std::vector<int>& coords)
    {
        return *reinterpret_cast<const basetype*>(Ptr(coords));
    }

    ConstContiguousIterator<basetype> Begin() { return ConstContiguousIterator<basetype>(*this); }
    ConstContiguousIterator<basetype> End() { return ConstContiguousIterator<basetype>(*this, dims_); }
};

template <DataType DT>
class ContiguousViewXYC : public Image
{
public:
    using basetype = typename TypeInfo<DT>::basetype;

    ContiguousViewXYC(Image& img)
    {
        if (img.channels_ != "xyc")
            throw std::runtime_error("ContiguousView2D can be built only from \"xyc\" images");
        if (!img.contiguous_)
            throw std::runtime_error("ContiguousView2D can be built only from images with contiguous data");
        elemtype_ = img.elemtype_;
        elemsize_ = img.elemsize_;
        dims_ = img.dims_;
        spacings_ = img.spacings_;
        strides_ = img.strides_;
        channels_ = img.channels_;
        colortype_ = img.colortype_;
        data_ = img.data_;
        datasize_ = img.datasize_;
        contiguous_ = img.contiguous_;
        meta_ = img.meta_;
        hal_ = HardwareAbstractionLayer::Factory(img.dev_, true);
        dev_ = img.dev_;
    }

    int width() const { return dims_[0]; }
    int height() const { return dims_[1]; }
    int channels() const { return dims_[2]; }

    basetype& operator()(int x, int y, int c)
    {
        return *reinterpret_cast<basetype*>(data_ + c * strides_[2] + y * strides_[1] + x * strides_[0]);
    }

    ContiguousIterator<basetype> Begin() { return ContiguousIterator<basetype>(*this); }
    ContiguousIterator<basetype> End() { return ContiguousIterator<basetype>(*this, dims_); }
};

template <DataType DT>
class ConstContiguousViewXYC : public Image
{
public:
    using basetype = typename TypeInfo<DT>::basetype;

    ConstContiguousViewXYC(const Image& img)
    {
        if (img.channels_ != "xyc")
            throw std::runtime_error("ContiguousView2D can be built only from \"xyc\" images");
        if (!img.contiguous_)
            throw std::runtime_error("ContiguousView2D can be built only from images with contiguous data");
        elemtype_ = img.elemtype_;
        elemsize_ = img.elemsize_;
        dims_ = img.dims_;
        spacings_ = img.spacings_;
        strides_ = img.strides_;
        channels_ = img.channels_;
        colortype_ = img.colortype_;
        data_ = img.data_;
        datasize_ = img.datasize_;
        contiguous_ = img.contiguous_;
        meta_ = img.meta_;
        hal_ = HardwareAbstractionLayer::Factory(img.dev_, true);
        dev_ = img.dev_;
    }

    int width() const { return dims_[0]; }
    int height() const { return dims_[1]; }
    int channels() const { return dims_[2]; }

    const basetype& operator()(int x, int y, int c) const
    {
        return *reinterpret_cast<basetype*>(data_ + c * strides_[2] + y * strides_[1] + x * strides_[0]);
    }

    ConstContiguousIterator<basetype> Begin() { return ConstContiguousIterator<basetype>(*this); }
    ConstContiguousIterator<basetype> End() { return ConstContiguousIterator<basetype>(*this, dims_); }
};

void RearrangeChannels(const Image& src, Image& dst, const std::string& channels);

void RearrangeChannels(const Image& src, Image& dst, const std::string& channels, DataType new_type);

void CopyImage(const Image& src, Image& dst, DataType new_type = DataType::none);

void CopyImage(const Image& src, Image& dst, DataType new_type, const std::string& channels);

void ShallowCopyImage(const Image& src, Image& dst);

void ConvertTo(const Image& src, Image& dst, DataType dtype, bool saturate = true);


} // namespace ecvl

#endif // !ECVL_IMAGE_H_