types.hpp

Go to the documentation of this file.

/*****************************************************************************
 * This file is part of uvgVPCCenc V-PCC encoder.
 *
 * Copyright (c) 2024-present, Tampere University, ITU/ISO/IEC, project contributors
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted (subject to the limitations in the disclaimer below) provided that the following conditions are met:
 *
 * * Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright notice, this
 *   list of conditions and the following disclaimer in the documentation and/or
 *   other materials provided with the distribution.
 *
 * * Neither the name of Tampere University, ITU/ISO/IEC nor the names of its
 *   contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE.
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION HOWEVER CAUSED AND ON
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF THIS
 ****************************************************************************/
 
 
#pragma once
 
#include <array>
#include <cassert>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <semaphore>
#include <sstream>
#include <string>
#include <vector>
 
#include "uvgformat/uvgFrame.hpp"
#include "uvgformat/uvgFramePayload.hpp"
#include "uvgutils/utils.hpp"
#include "constants.hpp"
#include "parameters.hpp"
 
namespace uvgvpcc_enc {
 
// Forward declaration to break the FrameContext <-> GOF circular dependency.
struct GOF;
 
// A patch is a 3D object. Though, the word 'patch' can refer to the "2D version" of this patch
struct Patch {
    size_t patchIndex_;
    size_t patchPpi_;  // viewId
 
    size_t normalAxis_;     // x
    size_t tangentAxis_;    // y
    size_t bitangentAxis_;  // z
 
    size_t posU_;  // u1_ minU_       // tangential shift
    size_t posV_;  // v1_ minV_       // bitangential shift
    size_t posD_;  // d1_ minD_       // depth shift
 
    bool projectionMode_;  // 0: related to the min depth value; 1: related to the max value
 
    size_t sizeD_;  // while posD_ is the minimum 'depth', sizeD_ store the maximum depth. TODO(lf): check if it is usefull
 
    std::vector<uint8_t> patchOccupancyMap_;  // patch occupancy map (boolean vector)
    std::vector<uint8_t> patchOccupancyMapColor_; // Patch occupancy map colored per patch
 
    size_t widthInPixel_ = 0;   // size for U  // width of the patch occupancy map (in pixels)
    size_t heightInPixel_ = 0;  // size for V  // height of the patch occupancy map (in pixels)
 
    size_t widthInPPBlk_;  // sizeU0_   Width in term of patch packing block (not related to the occupancy map downscaling factor)
    size_t heightInPPBlk_;  // sizeV0_  Height in term of patch packing block (not related to the occupancy map downscaling factor)
                           
    size_t omPPPosX_;  // u0_ 2dPosX Position in the occupancy map in term of patch packing block (not related to the occupancy map downscaling factor)
    size_t omPPPosY_;  // v0_ 2dPosY
 
    bool axisSwap_;  // patch orientation    // in canvas atlas  (false default, true axis swap)
 
    std::vector<typeGeometryInput> depthL1_;  // depth value First layer // TODO(lf): Using the geo type here might lead to issue?
    std::vector<typeGeometryInput> depthL2_;  // depth value Second layer
 
    // Index of the point in the PC for attribute retrieving during attribute map generation TODO(lf): use for Surface separation?
    std::vector<size_t> depthPCidxL1_;
    std::vector<size_t> depthPCidxL2_;
 
    // inter packing //
    size_t area_ = 0;
 
    size_t referencePatchId_ = g_infinitenumber;
    // Store the id of the best reference patch in the previous frame. Notice that even if the current patch is not
    // matched, a reference patch id is still found. Then, this reference id will be used to check if the iou treshold
    // is respected or not, then indicating if this patch is matched or not.
 
    size_t bestMatchIdx = INVALID_PATCH_INDEX;
    // Store not the id but the position in the list of patch of the best reference patch in the previous frame. Notice that even if
    // the current patch is not matched, a reference patch id is still found. Then, this reference id will be used to check if the
    // iou treshold is respected or not, then indicating if this patch is matched or not.
    bool isLinkToAMegaPatch = false;
    size_t unionPatchReferenceIdx = INVALID_PATCH_INDEX;
 
    bool isDiscarded = false; // If dynamicMapHeight=false et minimumMapHeight=??? is too small, then some patch can't be packed. There are then discarded (they will not be encoded).
 
    void setAxis(size_t normalAxis, size_t tangentAxis, size_t bitangentAxis, bool projectionMode) {
        normalAxis_ = normalAxis;
        tangentAxis_ = tangentAxis;
        bitangentAxis_ = bitangentAxis;
        projectionMode_ = projectionMode;  // TODO(lf): projection mode optimization per patch
    }
 
    inline void setPatchPpiAndAxis(size_t patchPpi) {
        patchPpi_ = patchPpi;
        // now set the other variables according to the viewId
        switch (patchPpi_) {
            case 0:
                setAxis(0, 2, 1, 0);
                break;
            case 1:
                setAxis(1, 2, 0, 0);
                break;
            case 2:
                setAxis(2, 0, 1, 0);
                break;
            case 3:
                setAxis(0, 2, 1, 1);
                break;
            case 4:
                setAxis(1, 2, 0, 1);
                break;
            case 5:
                setAxis(2, 0, 1, 1);
                break;
            default:
                throw std::runtime_error("ViewId (" + std::to_string(patchPpi) + ") not allowed... exiting");
                break;
        }
    }
 
    std::string toString() const {
        std::stringstream str;
        str << "patchIndex=" << patchIndex_;
        str << ", patchPpi=" << patchPpi_;
        str << ", normalAxis=" << normalAxis_;
        str << ", tangentAxis=" << tangentAxis_;
        str << ", bitangentAxis=" << bitangentAxis_;
        str << ", projectionMode=" << projectionMode_;
        str << ", minU=" << posU_;
        str << ", minV=" << posV_;
        str << ", minD=" << posD_;
        str << ", sizeD=" << sizeD_;
        str << ", sizeU=" << widthInPixel_;
        str << ", sizeV=" << heightInPixel_;
        str << ", sizeUom=" << widthInPPBlk_;
        str << ", sizeVom=" << heightInPPBlk_;
        str << ", omPPPosX_=" << omPPPosX_;
        str << ", omPPPosY_=" << omPPPosY_;
        str << ", axisSwap=" << axisSwap_;
        return str.str();
    }
};
 
struct FrameContext {
    // ---- User payload (shared ownership, zero-copy) ----
    // Declared first so references below are bound to valid memory.
    std::shared_ptr<uvgformat::uvgFrame> uvgframe;
 
    // ---- Convenience references into the payload (non-owning, bound at construction) ----
    std::vector<uvgutils::VectorN<typeGeometryInput, 3>>& pointsGeometry;
    std::vector<uvgutils::VectorN<uint8_t, 3>>& pointsAttribute;
 
    // ---- Encoder-assigned identity ----
    size_t frameId;
    size_t gofId;
    size_t frameNumber;  // copied from uvgframe->frameNumber
 
    // ---- Encoder lifecycle ----
    std::weak_ptr<GOF> gof;
    std::shared_ptr<std::counting_semaphore<UINT16_MAX>> conccurentFrameSem;
 
    // ---- Map sizing ----
    size_t mapHeight;
    size_t mapHeightDS;
 
    // ---- Centralized memory pointers (set by GOF::setFrameMemoryPtrs) ----
    std::vector<Patch>* patchList;
    std::vector<uint8_t>* occupancyMap;
    std::vector<uint8_t>* occupancyMapColored;
    std::vector<uint8_t>* occupancyMapDS;
    std::vector<uint8_t>* geometryMapL1;
    std::vector<uint8_t>* geometryMapL2;
    std::vector<uint8_t>* attributeMapL1;
    std::vector<uint8_t>* attributeMapL2;
 
    FrameContext(const size_t frameId, std::shared_ptr<uvgformat::uvgFrame> frame)
        : uvgframe(std::move(frame))
        , pointsGeometry(uvgformat::getGeometryRgb(uvgframe->payload).geometry)
        , pointsAttribute(uvgformat::getGeometryRgb(uvgframe->payload).attribute)
        , frameId(frameId)
        , gofId(0)
        , frameNumber(uvgframe->frameNumber)
        , mapHeight(p_->minimumMapHeight)
        , mapHeightDS(p_->minimumMapHeight / p_->occupancyMapDSResolution)
        , patchList(nullptr)
        , occupancyMap(nullptr)
        , occupancyMapColored(nullptr)
        , occupancyMapDS(nullptr)
        , geometryMapL1(nullptr)
        , geometryMapL2(nullptr)
        , attributeMapL1(nullptr)
        , attributeMapL2(nullptr) {}
 
    ~FrameContext() {
        if (conccurentFrameSem) {
            conccurentFrameSem->release();
        }
    }
 
    void printInfo() const;
};
 
struct GOF {
    std::vector<std::shared_ptr<FrameContext>> frames;
    size_t nbFrames;
    size_t gofId;
 
    size_t mapHeightGOF;
    size_t mapHeightDSGOF;
 
    std::vector<uint8_t> bitstreamOccupancy;
    std::vector<uint8_t> bitstreamGeometry;
    std::vector<uint8_t> bitstreamAttribute;
 
    // lf: centralized memory handling //
    std::array<std::vector<Patch>, MAX_GOF_SIZE>* framePatches;
    std::array<std::vector<uint8_t>, MAX_GOF_SIZE>* frameOccupancyMaps;
    std::array<std::vector<uint8_t>, MAX_GOF_SIZE>* frameOccupancyMapsColor;
    std::array<std::vector<uint8_t>, MAX_GOF_SIZE>* frameOccupancyMapsDS;
    std::array<std::vector<uint8_t>, MAX_GOF_SIZE>* frameGeometryMapsL1;
    std::array<std::vector<uint8_t>, MAX_GOF_SIZE>* frameGeometryMapsL2;
    std::array<std::vector<uint8_t>, MAX_GOF_SIZE>* frameAttributeMapsL1;
    std::array<std::vector<uint8_t>, MAX_GOF_SIZE>* frameAttributeMapsL2;
 
    GOF(const size_t& gofId);
    void setFrameMemoryPtrs(std::shared_ptr<FrameContext>& frame);
    ~GOF();
};
 
}  // namespace uvgvpcc_enc