milkImage.hpp

Go to the documentation of this file.

/** \file milkImage.hpp
 * \brief Interface to MILK::ImageStreamIO shared memory streams
 * \ingroup image_processing_files
 * \author Jared R. Males (jaredmales@gmail.com)
 *
 */
 
//***********************************************************************//
// Copyright 2025 Jared R. Males (jaredmales@gmail.com)
//
// This file is part of mxlib.
//
// mxlib 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 3 of the License, or
// (at your option) any later version.
//
// mxlib 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 mxlib.  If not, see <http://www.gnu.org/licenses/>.
//***********************************************************************//
 
#ifndef improc_milkImage_hpp
#define improc_milkImage_hpp
 
#ifdef MXLIB_MILK
 
#ifdef MXLIB_CUDA
#define HAVE_CUDA
#endif
 
#include <ImageStreamIO/ImageStreamIO.h>
 
#include "../mxlib.hpp"
#include "eigenImage.hpp"
 
namespace mx
{
namespace improc
{
 
template <typename typeT>
struct ImageStructTypeCode;
 
template <>
struct ImageStructTypeCode<uint8_t>
{
    constexpr static int TypeCode = _DATATYPE_UINT8;
};
 
template <>
struct ImageStructTypeCode<int8_t>
{
    constexpr static int TypeCode = _DATATYPE_INT8;
};
 
template <>
struct ImageStructTypeCode<char>
{
    constexpr static int TypeCode = _DATATYPE_INT8;
};
 
template <>
struct ImageStructTypeCode<uint16_t>
{
    constexpr static int TypeCode = _DATATYPE_UINT16;
};
 
template <>
struct ImageStructTypeCode<int16_t>
{
    constexpr static int TypeCode = _DATATYPE_INT16;
};
 
template <>
struct ImageStructTypeCode<uint32_t>
{
    constexpr static int TypeCode = _DATATYPE_UINT32;
};
 
template <>
struct ImageStructTypeCode<int32_t>
{
    constexpr static int TypeCode = _DATATYPE_INT32;
};
 
template <>
struct ImageStructTypeCode<uint64_t>
{
    constexpr static int TypeCode = _DATATYPE_UINT64;
};
template <>
struct ImageStructTypeCode<int64_t>
{
    constexpr static int TypeCode = _DATATYPE_INT64;
};
template <>
struct ImageStructTypeCode<float>
{
    constexpr static int TypeCode = _DATATYPE_FLOAT;
};
 
template <>
struct ImageStructTypeCode<double>
{
    constexpr static int TypeCode = _DATATYPE_DOUBLE;
};
 
template <>
struct ImageStructTypeCode<std::complex<float>>
{
    constexpr static int TypeCode = _DATATYPE_COMPLEX_FLOAT;
};
 
template <>
struct ImageStructTypeCode<std::complex<double>>
{
    constexpr static int TypeCode = _DATATYPE_COMPLEX_DOUBLE;
};
 
/// Class to interface with an ImageStreamIO image in shared memory
/**
 *
 * Use with Eigen::Map (aliased as mx::improc::eigenMap)
 * \code
 * using namespace mx::improc;
 * milkImage<float> mim("image"); //connects to image.im.shm
 * eigenMap<float> im(mim); //the conversion operator passes a reference to the internal map
 * im.setRandom(); // im is now a map pointed at the image data.  Eigen functions are now available.
 * im(64,64) *= 2000;
 * im /= 0.2;
 * \endcode
 * Once you have changed something via the Eigen::Map you want to notify others connected to the stream
 * via
 * \code
 * mim.post();
 * \endcode
 *
 * \ingroup eigen_image_processing
 */
template <typename _dataT>
class milkImage
{
  public:
    typedef _dataT dataT; ///< The data type
 
  protected:
    std::string m_name;                ///< The image name, from name.im.shm (the .im.shm should not be given).
 
    IMAGE *m_image{ nullptr };         ///< Pointer to the ImageStreamIO IMAGE structure.
 
    dataT *m_raw{ nullptr };           // The raw pointer address is stored here for checks
 
    eigenMap<dataT> *m_map{ nullptr }; // An Eigen::Map of the array
 
    uint64_t m_size_0{ 0 };            ///< The size[0] of the image when last opened.
 
    uint64_t m_size_1{ 0 };            ///< The size[1] of the image when last opened.
 
    bool m_passive{ false }; /**< If true then the cnt0 counter is not incremented on post.  Usage: this will not
                                  trigger the dmcomb process in cacao, so the DM will not pick up the shape until
                                  something does trigger it. */
 
  public:
    /// Default c'tor
    milkImage();
 
    /// Constructor which opens the specified image, which must already exist in shared memory.
    milkImage( const std::string &imname /**< [in] The image name, from name.im.shm
                                                   (the .im.shm should not be given).*/
    );
 
    /// Constructor which (re-)creates the specified image with the given size
    milkImage( const std::string &imname, ///< [in] The image name, from name.im.shm (the .im.shm should not be given).
               uint32_t sz0,              ///< [in] the x size of the image
               uint32_t sz1               ///< [in] the y size of the image
    );
 
    /// Constructor which (re-)creates the specified image and copies the provided image to it
    milkImage( const std::string &imname,  ///< [in] The image name, from name.im.shm (the .im.shm should not be given).
               const eigenImage<dataT> &im ///< [in] An existing eigenImage
    );
 
    /// D'tor
    ~milkImage();
 
    /// Open and connect to an image, allocating the eigenMap.
    /**
     * \throws std::invalid_argument if the image type_code does not match dataT.
     */
    void open( const std::string &imname /**< [in] The image name, from name.im.shm
             (the .im.shm should not be given).*/
    );
 
    /// Create (or re-create) and connect to an image, allocating the eigenMap.
    /**
     * \throws std::invalid_argument if the image type_code does not match dataT.
     */
    void create( const std::string &imname, ///< [in] The image name, for name.im.shm (the .im.shm should not be given).
                 uint32_t sz0,              ///< [in] the x size of the image
                 uint32_t sz1               ///< [in] the y size of the image
    );
 
    /// Create and connect to an image using an existing eigenImage, allocating the eigenMap and copying the image to
    /// the shmim.
    /**
     * \throws std::invalid_argument if the image type_code does not match dataT.
     */
    void create( const std::string &imname, ///< [in] The image name, for name.im.shm (the .im.shm should not be given).
                 const eigenImage<dataT> &im ///< [in] An existing eigenImage
    );
 
    /// Get the raw pointer
    dataT *data();
 
    /// Get the raw pointer
    const dataT *data() const;
 
    /// Get the width of the image
    /**
     * \returns the current value of m_size_0
     */
    uint32_t rows() const;
 
    /// Get the height of the image
    /**
     * \returns the current value of m_size_1
     */
    uint32_t cols() const;
 
    /// Get the total size of the image
    /**
     * \returns the current value of m_size_0 x m_size_1
     */
    uint64_t size() const;
 
    /// Get the size of a dimension of the image
    /**
     * \returns the current value of m_size_0 or m_size_1 depending on n
     */
    uint32_t size( unsigned n /**< [in] the dimension to get the size of*/ ) const;
 
    /// Set the passive flag
    /** Sets \ref m_passive
     *
     */
    void passive( bool pass /**< [in] new value of the \ref m_passive flag */ );
 
    /// Get the passive flag
    /** Gets \ref m_passive
     *
     */
    bool passive() const;
 
    /// Checks if the image is connected and is still the same format as when connected.
    /** Checks on pointer value, size[], and data_type.
     *
     * \todo check inode!
     *
     * \returns true if connected and no changes
     * \returns false if not connected or something changed.  All maps are now invalid.
     */
    bool valid() const;
 
    /// Reopens the image.
    /** Same as
     * \code
     * close();
     * open(m_name);
     * \endcode
     */
    void reopen();
 
    // Close the image
    void close();
 
    /// Get an eigenMap
    /** Use with caution:
     * - there is no way to know if the image has changed
     * - you should check \ref valid() before using
     *
     *
     * \returns an Eigen::Map<Array,-1,-1> reference
     *
     * \throws if the image is not opened
     *
     */
    eigenMap<dataT> &operator()();
 
    /// Get an eigenMap (const version)
    /** Use with caution:
     * - there is no way to know if the image has changed
     * - you should check \ref valid() before using
     *
     *
     * \returns an Eigen::Map<Array,-1,-1> reference
     *
     * \throws if the image is not opened
     *
     */
    const eigenMap<dataT> &operator()() const;
 
    /// Conversion operator returns an eigenMap
    /** Use this like
     * \code
     * milkImage<float> mim("imname");
     * eigenMap<float> im(mim); //you now have an Eigen interface to the image
     * \endcode
     * but with caution:
     * - there is no way to know if the image has changed
     * - you should check \ref valid() before using
     *
     *
     * \returns an Eigen::Map<Array,-1,-1> object
     *
     * \throws if the image is not opened
     *
     */
    operator eigenMap<dataT>();
 
    /// Copy data from another milkImage to this shared memory stream
    /** Sets the write flag, copies using the Eigen assignment to map, unsets the write flag, then posts.
     *
     * \throws on an error
     *
     */
    milkImage &operator=( const milkImage &im /**< [in] the milkImage to copy to this stream*/ );
 
    /// Copy data from an Eigen Array type to the shared memory stream
    /** Sets the write flag, copies using the Eigen assigment to map, unsets the write flag, then posts.
     *
     * \throws on an error
     *
     */
    template <typename eigenT>
    milkImage &operator=( const eigenT &im /**< [in] the eigen array to copy to the stream*/ );
 
    /// Access a single value in the array by its linear index
    /** This does not set the write flag or post after finishing.  You must manage these steps
     *  if using this to modify the array.
     *
     * This is intended for use inside loops and so does no validity or range checks.  You must ensure that the image is
     * connected and valid and that \p idx is in range.
     *
     * \returns a reference to the value at the given position
     */
    dataT &operator[]( size_t idx /**< [in] the linear index of the pixel in the array */ );
 
    /// Access a single value in the array by its linear index (const version)
    /** This does not set the write flag or post after finishing.  You must manage these steps
     *  if using this to modify the array.
     *
     * This is intended for use inside loops and so does no validity or range checks.  You must ensure that the image is
     * connected and valid and that \p idx is in range.
     *
     * \returns a reference to the value at the given position
     */
    const dataT &operator[]( size_t idx /**< [in] the linear index of the pixel in the array */ ) const;
 
    /// Access a single value in the array by its row and column coordinates
    /** This does not set the write flag or post after finishing.  You must manage these steps
     *  if using this to modify the array.
     *
     * This is intended for use inside loops and so does no validity or range checks.  You must ensure that the image is
     * connected and valid and that \p row and \p col are in range.
     *
     * \returns a reference to the value at the given position
     */
    dataT &operator()( int row, /**< [in] the row of the element*/
                       int col  /**< [in] the columnof the element */
    );
 
    /// Access a single value in the array by its row and column coordinates (const version)
    /** This does not set the write flag or post after finishing.  You must manage these steps
     *  if using this to modify the array.
     *
     * This is intended for use inside loops and so does no validity or range checks.  You must ensure that the image is
     * connected and valid and that \p row and \p col are in range.
     *
     * \returns a reference to the value at the given position
     */
    const dataT &operator()( int row, /**< [in] the row of the element*/
                             int col  /**< [in] the columnof the element */
    ) const;
 
    /// Set the write flag
    /** The write flag is set to indicate whether or not the the data is being changed.
     * The write flag will be set to false by \ref post().
     *
     * \throws if the image is not opened
     */
    void setWrite( bool wrflag = true /**< [in] [optional] the desired value of the write flag.  Default is true.*/ );
 
    /// Update the metadata and post all semaphores
    /**
     * \todo need to set wtime, have a version with atime
     *
     * \throws if the image is not opened
     */
    void post();
 
    /// Get the creation time
    /**
     * \returns the ImageStream creationtime
     */
    const timespec &creationtime() const;
 
    /// Get the last access time
    /**
     * \returns ImageStream lastaccesstime
     */
    const timespec &lastaccesstime() const;
 
    /// Get the acquisition time
    /**
     * \returns ImageStream acquisition time
     */
    const timespec &atime() const;
 
    /// Get the write time
    /**
     * \returns ImageStream writetime
     */
    const timespec &writetime() const;
 
    /// Get the value of cnt0 (the frame counter)
    /**
     * \returns the current value of cnt0
     */
    const uint64_t &cnt0() const;
};
 
template <typename dataT>
milkImage<dataT>::milkImage()
{
}
 
template <typename dataT>
milkImage<dataT>::milkImage( const std::string &imname )
{
    open( imname );
}
 
template <typename dataT>
milkImage<dataT>::milkImage( const std::string &imname, const eigenImage<dataT> &im )
{
    create( imname, im );
}
 
template <typename dataT>
milkImage<dataT>::milkImage( const std::string &imname, uint32_t sz0, uint32_t sz1 )
{
    create( imname, sz0, sz1 );
}
 
template <typename dataT>
milkImage<dataT>::~milkImage()
{
    close();
}
 
template <typename dataT>
void milkImage<dataT>::open( const std::string &imname )
{
    if( m_image )
    {
        ImageStreamIO_closeIm( m_image );
        delete m_image;
        m_image = nullptr;
    }
 
    if( m_map )
    {
        delete m_map;
        m_map = nullptr;
    }
 
    m_image = new IMAGE;
 
    errno_t rv = ImageStreamIO_openIm( m_image, imname.c_str() );
 
    if( rv != IMAGESTREAMIO_SUCCESS )
    {
        delete m_image;
        m_image = nullptr;
        throw( mx::exception( error_t::liberr, "ImageStreamIO_openIm returned an error" ) );
    }
 
    if( ImageStructTypeCode<dataT>::TypeCode != m_image->md->datatype )
    {
        delete m_image;
        m_image = nullptr;
        throw( mx::exception( error_t::invalidarg, "shmim datatype does not match template type" ) );
    }
 
    m_name = imname;
    m_raw = (dataT *)m_image->array.raw;
    m_size_0 = m_image->md->size[0];
    m_size_1 = m_image->md->size[1];
 
    m_map = new eigenMap<dataT>( m_raw, m_size_0, m_size_1 );
}
 
template <typename dataT>
void milkImage<dataT>::create( const std::string &imname, uint32_t sz0, uint32_t sz1 )
{
    if( m_image )
    {
        ImageStreamIO_closeIm( m_image );
        delete m_image;
        m_image = nullptr;
    }
 
    if( m_map )
    {
        delete m_map;
        m_map = nullptr;
    }
 
    m_image = new IMAGE;
 
    uint32_t imsize[3];
    imsize[0] = sz0;
    imsize[1] = sz1;
    imsize[2] = 1;
 
    errno_t rv = ImageStreamIO_createIm_gpu( m_image,
                                             imname.c_str(),
                                             3,
                                             imsize,
                                             ImageStructTypeCode<dataT>::TypeCode,
                                             -1,
                                             1,
                                             IMAGE_NB_SEMAPHORE,
                                             0,
                                             CIRCULAR_BUFFER | ZAXIS_TEMPORAL,
                                             0 );
 
    if( rv != IMAGESTREAMIO_SUCCESS )
    {
        delete m_image;
        m_image = nullptr;
        throw( mx::exception( error_t::liberr, "ImageStreamIO_createIm_gpu returned an error" ) );
    }
 
    m_image->md->cnt1 = 0;
 
    if( ImageStructTypeCode<dataT>::TypeCode != m_image->md->datatype )
    {
        delete m_image;
        m_image = nullptr;
        throw( mx::exception( error_t::invalidarg, "shmim datatype does not match template type" ) );
    }
 
    m_name = imname;
    m_raw = (dataT *)m_image->array.raw;
    m_size_0 = m_image->md->size[0];
    m_size_1 = m_image->md->size[1];
 
    m_map = new eigenMap<dataT>( m_raw, m_size_0, m_size_1 );
}
 
template <typename dataT>
void milkImage<dataT>::create( const std::string &imname, const eigenImage<dataT> &im )
{
    create( imname, im.rows(), im.cols() );
    operator=( im );
}
 
template <typename dataT>
eigenMap<dataT> &milkImage<dataT>::operator()()
{
    if( m_map == nullptr )
    {
        throw( mx::exception( error_t::invalidconfig, "Image is not open (map is null)" ) );
    }
 
    return *m_map;
}
 
template <typename dataT>
const eigenMap<dataT> &milkImage<dataT>::operator()() const
{
    if( m_map == nullptr )
    {
        throw( mx::exception( error_t::invalidconfig, "Image is not open (map is null)" ) );
    }
 
    return *m_map;
}
 
template <typename dataT>
milkImage<dataT>::operator eigenMap<dataT>()
{
    return operator()();
}
 
template <typename dataT>
void milkImage<dataT>::reopen()
{
    close();
    open( m_name );
}
 
template <typename dataT>
void milkImage<dataT>::close()
{
    if( m_map != nullptr )
    {
        delete m_map;
        m_map = nullptr;
    }
 
    if( m_image == nullptr )
    {
        return;
    }
 
    errno_t rv = ImageStreamIO_closeIm( m_image );
    delete m_image;
    m_image = nullptr;
 
    if( rv != IMAGESTREAMIO_SUCCESS )
    {
        throw( mx::exception( error_t::liberr, "ImageStreamIO_closeIm returned an error" ) );
    }
}
 
template <typename dataT>
dataT *milkImage<dataT>::data()
{
    return m_raw;
}
 
template <typename dataT>
const dataT *milkImage<dataT>::data() const
{
    return m_raw;
}
 
template <typename dataT>
uint32_t milkImage<dataT>::rows() const
{
    return m_size_0;
}
 
template <typename dataT>
uint32_t milkImage<dataT>::cols() const
{
    return m_size_1;
}
 
template <typename dataT>
uint32_t milkImage<dataT>::size( unsigned n ) const
{
    if( n == 0 )
    {
        return m_size_0;
    }
    else if( n == 1 )
    {
        return m_size_1;
    }
 
    return 0;
}
 
template <typename dataT>
uint64_t milkImage<dataT>::size() const
{
    return m_size_0 * m_size_1;
}
 
template <typename dataT>
void milkImage<dataT>::passive( bool pass )
{
    m_passive = pass;
}
 
template <typename dataT>
bool milkImage<dataT>::passive() const
{
    return m_passive;
}
 
template <typename dataT>
bool milkImage<dataT>::valid() const
{
    if( m_image == nullptr )
    {
        return false;
    }
 
    if( m_raw != (dataT *)m_image->array.raw || m_size_0 != m_image->md->size[0] || m_size_1 != m_image->md->size[1] ||
        ImageStructTypeCode<dataT>::TypeCode != m_image->md->datatype )
    {
        return false;
    }
 
    return true;
}
 
template <typename dataT>
milkImage<dataT> &milkImage<dataT>::operator=( const milkImage<dataT> &im )
{
    if( m_image == nullptr )
    {
        throw( mx::exception( error_t::invalidconfig, "Image is not open (image is null)" ) );
    }
 
    if( m_map == nullptr )
    {
        throw( mx::exception( error_t::invalidconfig, "Image is not open (map is null)" ) );
    }
 
    setWrite( true );
 
    *m_map = im(); // gets the map from im, will throw on invalid
 
    setWrite( false );
 
    post();
 
    return *this;
}
 
template <typename dataT>
template <typename eigenT>
milkImage<dataT> &milkImage<dataT>::operator=( const eigenT &im )
{
    if( m_image == nullptr )
    {
        throw( mx::exception( error_t::invalidconfig, "Image is not open (image is null)" ) );
    }
 
    if( m_map == nullptr )
    {
        throw( mx::exception( error_t::invalidconfig, "Image is not open (map is null)" ) );
    }
 
    setWrite( true );
 
    *m_map = im;
 
    post();
 
    return *this;
}
 
template <typename dataT>
dataT &milkImage<dataT>::operator[]( size_t idx )
{
    return m_raw[idx];
}
 
template <typename dataT>
const dataT &milkImage<dataT>::operator[]( size_t idx ) const
{
    return m_raw[idx];
}
 
template <typename dataT>
dataT &milkImage<dataT>::operator()( int row, int col )
{
    return ( *m_map )( row, col );
}
 
template <typename dataT>
const dataT &milkImage<dataT>::operator()( int row, int col ) const
{
    return ( *m_map )( row, col );
}
 
template <typename dataT>
void milkImage<dataT>::setWrite( bool wrflag )
{
    if( m_image == nullptr )
    {
        throw( mx::exception( error_t::invalidconfig, "Image is not open" ) );
    }
 
    m_image->md->write = wrflag;
}
 
template <typename dataT>
void milkImage<dataT>::post()
{
    if( m_image == nullptr )
    {
        throw( mx::exception( error_t::invalidconfig, "Image is not open" ) );
    }
 
    if( !m_passive )
    {
        errno_t rv = ImageStreamIO_UpdateIm( m_image );
        m_image->md->atime = m_image->md->writetime;
 
        if( rv != IMAGESTREAMIO_SUCCESS )
        {
            throw( mx::exception( error_t::liberr, "ImageStreamIO_UpdateIm returned an error" ) );
        }
    }
    else
    {
        if( clock_gettime( CLOCK_ISIO, &m_image->md->writetime ) == -1 )
        {
            throw( mx::exception( errno2error_t( errno ), "clock_gettime returned an error" ) );
        }
        m_image->md->atime = m_image->md->writetime;
 
        m_image->md->write = 0;
        ImageStreamIO_sempost( m_image, -1 );
    }
}
 
template <typename dataT>
const timespec &milkImage<dataT>::creationtime() const
{
    return m_image->md->creationtime;
}
 
template <typename dataT>
const timespec &milkImage<dataT>::lastaccesstime() const
{
    return m_image->md->lastaccesstime;
}
 
template <typename dataT>
const timespec &milkImage<dataT>::atime() const
{
    return m_image->md->atime;
}
 
template <typename dataT>
const timespec &milkImage<dataT>::writetime() const
{
    return m_image->md->writetime;
}
 
template <typename dataT>
const uint64_t &milkImage<dataT>::cnt0() const
{
    return m_image->md->cnt0;
}
 
 
} // namespace improc
} // namespace mx
 
#endif // MXLIB_MILK
#endif // improc_milkImage_hpp