ImageDescriber.hpp

// This file is part of the AliceVision project.
// Copyright (c) 2016 AliceVision contributors.
// Copyright (c) 2012 openMVG contributors.
// This Source Code Form is subject to the terms of the Mozilla Public License,
// v. 2.0. If a copy of the MPL was not distributed with this file,
// You can obtain one at https://mozilla.org/MPL/2.0/.
 
#pragma once
 
#include <aliceVision/numeric/numeric.hpp>
#include <aliceVision/feature/imageDescriberCommon.hpp>
#include <aliceVision/feature/Regions.hpp>
#include <aliceVision/image/Image.hpp>
#include <memory>
 
#include <string>
#include <iostream>
 
namespace aliceVision {
namespace feature {
 
enum class EImageDescriberPreset
{
    LOW = 0,
    MEDIUM,
    NORMAL,
    HIGH,
    ULTRA
};
 
inline std::string EImageDescriberPreset_information()
{
    return "Feature preset controls the density of the feature extraction:\n"
           "* LOW: Very low density (max 1K points).\n"
           "* MEDIUM: Low density (max 5K points).\n"
           "* NORMAL: Default feature density (max 10K points).\n"
           "* HIGH: High density (max 50K points).\n"
           "* ULTRA: Very high density (max 100K points). Can use large amount of storage and large amount of computation. Use only on small "
           "datasets.\n";
}
 
EImageDescriberPreset EImageDescriberPreset_stringToEnum(const std::string& imageDescriberPreset);
std::string EImageDescriberPreset_enumToString(const EImageDescriberPreset imageDescriberPreset);
std::ostream& operator<<(std::ostream& os, EImageDescriberPreset p);
std::istream& operator>>(std::istream& in, EImageDescriberPreset& p);
 
enum class EFeatureQuality
{
    LOW = 0,
    MEDIUM,
    NORMAL,
    HIGH,
    ULTRA,
};
 
inline std::string EFeatureQuality_information()
{
    return "Feature extraction contains a trade-off between speed and result accuracy:\n"
           "* LOW: Very quick results.\n"
           "* MEDIUM: Quick results.\n"
           "* NORMAL: Default feature quality.\n"
           "* HIGH: Improved quality over performances.\n"
           "* ULTRA: Highest quality at the expense of high computational cost.\n";
}
 
EFeatureQuality EFeatureQuality_stringToEnum(const std::string& v);
std::string EFeatureQuality_enumToString(const EFeatureQuality v);
std::ostream& operator<<(std::ostream& os, EFeatureQuality v);
std::istream& operator>>(std::istream& in, EFeatureQuality& v);
 
enum class EFeatureConstrastFiltering
{
    Static = 0,
    AdaptiveToMedianVariance,
    NoFiltering,
    GridSortOctaves,
    GridSort,
    GridSortScaleSteps,
    GridSortOctaveSteps,
    NonExtremaFiltering
};
 
inline std::string EFeatureConstrastFiltering_information()
{
    return "Contrast filtering method to ignore features with too low contrast that can be consided as noise:\n"
           "* Static: Fixed threshold.\n"
           "* AdaptiveToMedianVariance: Based on image content analysis.\n"
           "* NoFiltering: Disable contrast filtering.\n"
           "* GridSortOctaves: Grid sort by peak value per octave and by scale at the end.\n"
           "* GridSort: Grid sort by scale*peakValue per octave and at the end.\n"
           "* GridSortScaleSteps: Grid sort per scale steps and at the end (scale and then peak value).\n"
           "* GridSortOctaveSteps: Grid sort per octaves and at the end (scale and then peak value).\n"
           "* NonExtremaFiltering: Filter non-extrema peak values.\n";
}
 
EFeatureConstrastFiltering EFeatureConstrastFiltering_stringToEnum(const std::string& v);
std::string EFeatureConstrastFiltering_enumToString(const EFeatureConstrastFiltering v);
std::ostream& operator<<(std::ostream& os, EFeatureConstrastFiltering v);
std::istream& operator>>(std::istream& in, EFeatureConstrastFiltering& v);
 
struct ConfigurationPreset
{
    EImageDescriberPreset descPreset{EImageDescriberPreset::NORMAL};
    int maxNbFeatures{0};
    EFeatureQuality quality{EFeatureQuality::NORMAL};
    bool gridFiltering{true};
    EFeatureConstrastFiltering contrastFiltering{EFeatureConstrastFiltering::Static};
    float relativePeakThreshold{0.02f};
 
    inline ConfigurationPreset& setDescPreset(EImageDescriberPreset v)
    {
        descPreset = v;
        return *this;
    }
    inline ConfigurationPreset& setDescPreset(const std::string& v)
    {
        descPreset = EImageDescriberPreset_stringToEnum(v);
        return *this;
    }
 
    inline ConfigurationPreset& setGridFiltering(bool v)
    {
        gridFiltering = v;
        return *this;
    }
 
    inline ConfigurationPreset& setContrastFiltering(EFeatureConstrastFiltering v)
    {
        contrastFiltering = v;
        return *this;
    }
    inline ConfigurationPreset& setContrastFiltering(const std::string& v)
    {
        contrastFiltering = EFeatureConstrastFiltering_stringToEnum(v);
        return *this;
    }
};
 
class ImageDescriber
{
  public:
    ImageDescriber() = default;
 
    virtual ~ImageDescriber() = default;
 
    virtual bool useCuda() const = 0;
 
    virtual bool useFloatImage() const = 0;
 
    virtual EImageDescriberType getDescriberType() const = 0;
 
    virtual std::size_t getMemoryConsumption(std::size_t width, std::size_t height) const = 0;
 
    virtual void setUpRight([[maybe_unused]] bool upRight) {}
 
    virtual void setUseCuda([[maybe_unused]] bool useCuda) {}
 
    virtual void setCudaPipe([[maybe_unused]] int pipe) {}
 
    virtual void setConfigurationPreset(ConfigurationPreset preset) = 0;
 
    virtual bool describe([[maybe_unused]] const image::Image<unsigned char>& image,
                          [[maybe_unused]] std::unique_ptr<Regions>& regions,
                          [[maybe_unused]] const image::Image<unsigned char>* mask = nullptr)
    {
        throw std::logic_error("Cannot use " + EImageDescriberType_enumToString(getDescriberType()) + " image describer with an 8-bit image.");
        return false;
    }
 
    virtual bool describe([[maybe_unused]] const image::Image<float>& image,
                          [[maybe_unused]] std::unique_ptr<Regions>& regions,
                          [[maybe_unused]] const image::Image<unsigned char>* mask = nullptr)
    {
        throw std::logic_error("Cannot use " + EImageDescriberType_enumToString(getDescriberType()) + " image describer with a float image.");
        return false;
    }
 
    virtual void allocate(std::unique_ptr<Regions>& regions) const = 0;
 
    // IO - one file for region features, one file for region descriptors
 
    void Load(Regions* regions, const std::string& sfileNameFeats, const std::string& sfileNameDescs) const
    {
        regions->Load(sfileNameFeats, sfileNameDescs);
    }
 
    void Save(const Regions* regions, const std::string& sfileNameFeats, const std::string& sfileNameDescs) const;
 
    void LoadFeatures(Regions* regions, const std::string& sfileNameFeats) const { regions->LoadFeatures(sfileNameFeats); }
};
 
std::unique_ptr<ImageDescriber> createImageDescriber(EImageDescriberType imageDescriberType);
 
}  // namespace feature
}  // namespace aliceVision