# class cogs::PointCloud

## Overview

Management class for a set of data points in a 3D space. More…

    #include <PointCloud.h>

    class PointCloud {
    public:
        // typedefs

        typedef std::function<bool(const glm::vec3&, const glm::vec3&)> PointNormalPredicate;

        // structs

        struct Chunk;
        struct CopyCommand;

        // fields

        static const cogs::PointCloudProperty::Key POSITIONS;
        static const cogs::PointCloudProperty::Key NORMALS;
        static const cogs::PointCloudProperty::Key COLORS;
        static const cogs::PointCloudProperty::Key UVS;
        static const cogs::PointCloudProperty::Key INTENSITIES;

        // construction

        PointCloud();
        PointCloud(const PointCloud& source);
        PointCloud(PointCloud&&);
        virtual ~PointCloud();

        // methods

        PointCloud& operator=(const PointCloud& source);
        PointCloud& operator=(PointCloud&&);
        virtual bool Import(const std::string& filename);
        virtual bool Export(const std::string& filename) const;
        virtual bool Resize(uint32_t new_size);
        virtual uint32_t GetSize() const;
        virtual void Reserve(uint32_t new_capacity);
        uint32_t GetCapacity() const;
        virtual void ShrinkToFit();
        virtual void Clear();
        virtual bool Erase(std::vector<uint32_t> indices_to_erase, std::vector<int>* replacement_map = nullptr);
        virtual bool Erase(const PointNormalPredicate& Predicate, std::vector<int>* replacement_map = nullptr);
        virtual bool Append(const PointCloud& pc);
        glm::vec3* GetPositions();
        const glm::vec3* GetPositions() const;
        bool HasNormals() const;
        glm::vec3* GetNormals();
        const glm::vec3* GetNormals() const;
        const PointCloudProperty& AddNormals();
        bool HasColors() const;
        struct Color3f* GetColors();
        const struct Color3f* GetColors() const;
        const PointCloudProperty& AddColors();
        bool HasIntensities() const;
        float* GetIntensities();
        const float* GetIntensities() const;
        const PointCloudProperty& AddIntensities();
        const std::vector<PointCloudProperty>& GetProperties() const;
        const PointCloudProperty& AddProperty(const PointCloudProperty::Key& key, DataType type);
        const PointCloudProperty& AddProperty(const PointCloudProperty::Key& key, size_t bytes_per_point);
        void RemoveProperty(const PointCloudProperty::Key& key);
        void ClonePropertiesOf(const PointCloud& pc);
        bool HasProperty(const PointCloudProperty::Key& key) const;
        std::optional<PointCloudProperty> GetProperty(const PointCloudProperty::Key& key);
        std::optional<const PointCloudProperty> GetProperty(const PointCloudProperty::Key& key) const;
        virtual void* GetVoidData(const PointCloudProperty::Key& key);
        const void* GetVoidData(const PointCloudProperty::Key& key) const;

        template <typename T>
        T* GetData(const PointCloudProperty::Key& key);

        template <typename T>
        const T* GetData(const PointCloudProperty::Key& key) const;

        virtual void Transform(const glm::mat4& transformation, const std::optional<utils::SpaceDefinition>& resulting_space = std::nullopt);
        bool HasSpace() const;
        const std::optional<utils::SpaceDefinition>& GetSpace() const;
        std::string GetSpaceId() const;
        void SetSpace(const std::optional<utils::SpaceDefinition>& new_space);
        bool TransformToSpace(const utils::SpaceDefinition& new_space);

    protected:
        // methods

        void MakeCloneOf(const PointCloud& source);
        virtual void ExecuteCopyCommands(const std::vector<CopyCommand>& copy_info);
        virtual void TruncateSize(size_t delta_size);
    };

## Detailed Documentation

Management class for a set of data points in a 3D space.

Class stores point data separated in data buffers. Every data record is called a property, and by default, only a single property exists - PointCloud::POSITIONS. User can specify custom properties which will be assigned to all points in the cloud.

### Typedefs

    typedef std::function<bool(const glm::vec3&, const glm::vec3&)> PointNormalPredicate

A predicate over points and normals. A function that returns true or false.

### Fields

    static const cogs::PointCloudProperty::Key POSITIONS

Common identifier for point positions.

    static const cogs::PointCloudProperty::Key NORMALS

Common identifier for point normals.

    static const cogs::PointCloudProperty::Key COLORS

Common identifier for point colors.

    static const cogs::PointCloudProperty::Key UVS

Common identifier for point texture coordinates.

    static const cogs::PointCloudProperty::Key INTENSITIES

Common identifier for point intensities.

### Construction

    PointCloud()

Creates a cloud with no points.

    PointCloud(const PointCloud& source)

Make a deep copy of the source PointCloud.

    PointCloud(PointCloud&&)

Move-construct PointCloud.

    virtual ~PointCloud()

Destroys cloud and frees all property data.

### Methods

    PointCloud& operator=(const PointCloud& source)

Make a deep copy of the source PointCloud.

    PointCloud& operator=(PointCloud&&)

Move-construct PointCloud.

    virtual bool Import(const std::string& filename)

Imports point cloud from a file.

    virtual bool Export(const std::string& filename) const

Exports point clouds to a file.

    virtual bool Resize(uint32_t new_size)

Resizes point count to the new value without initialization of data of newly created points.

    virtual uint32_t GetSize() const

Returns number of points currently stored in the cloud.

    virtual void Reserve(uint32_t new_capacity)

Changes capacity of cloud. This method is not adding any points.

    uint32_t GetCapacity() const

Returns how much points can be added with currently reserved memory.

    virtual void ShrinkToFit()

Frees spare memory so that new capacity exactly matches size.

    virtual void Clear()

Removes all points from cloud.

    virtual bool Erase(std::vector<uint32_t> indices_to_erase, std::vector<int>* replacement_map = nullptr)

Removes points with specific indices from cloud.

Every chunk of points that should be erased, is replaced with the points from the back of cloud. This ensures minimal copy operations. Method changes point ordering. Memory for erased points is not released, you should call ShrinkToFit afterwards, to free excess memory.

Parameters:

indices_to_erase | Indices of points to erase.
replacement_map | Optional output parameter - vector representing the mapping old_index->new_index.

    virtual bool Erase(const PointNormalPredicate& Predicate, std::vector<int>* replacement_map = nullptr)

Removes all points from cloud that satisfy a specified condition.

Every chunk of points that should be erased, is replaced with the points from the back of cloud. This ensures minimal copy operations. Method changes point ordering. Memory for erased points is not released, you should call ShrinkToFit afterwards, to free excess memory.

Parameters:

Predicate | The erase condition. A point is removed from the point cloud if it returns true.
replacement_map | Optional output parameter - vector representing the mapping old_index->new_index.

    virtual bool Append(const PointCloud& pc)

Increments size of this by the size of pc and copies property data available in both.

Properties not available in this will not be copied. To add also properties not currently available in this, use PointCloud::ClonePropertiesOf before calling this function.

    glm::vec3* GetPositions()

Returns pointer to position data.

Equivalent to PointCloud::GetData<glm::vec3>(PointCloud::POSITIONS);

    const glm::vec3* GetPositions() const

Returns pointer to position data.

Equivalent to PointCloud::GetData<glm::vec3>(PointCloud::POSITIONS);

    bool HasNormals() const

Checks whether normal property exists.

Equivalent to PointCloud::HasProperty(PointCloud::NORMALS);

    glm::vec3* GetNormals()

When normal property exists, returns the pointer to data, nullptr otherwise.

Equivalent to PointCloud::GetData<glm::vec3>(PointCloud::NORMALS);

    const glm::vec3* GetNormals() const

When normal property exists, returns the pointer to data, nullptr otherwise.

Equivalent to PointCloud::GetData<glm::vec3>(PointCloud::NORMALS);

    const PointCloudProperty& AddNormals()

Creates PointCloud::NORMALS property buffer if it was not added already.

Do not add this property using PointCloud :AddProperty method.

    bool HasColors() const

Checks whether color property exists.

Equivalent to PointCloud::HasProperty(PointCloud::COLORS);

    struct Color3f* GetColors()

When color property exists, returns the pointer to data, nullptr otherwise.

Equivalent to PointCloud::GetData<COGS::Color3f>(PointCloud::COLORS);

    const struct Color3f* GetColors() const

When color property exists, returns the pointer to data, nullptr otherwise.

Equivalent to PointCloud::GetData<COGS::Color3f>(PointCloud::COLORS);

    const PointCloudProperty& AddColors()

Creates PointCloud::COLORS property buffer if it was not added already.

Do not add this property using PointCloud :AddProperty method.

    bool HasIntensities() const

Checks whether intensity property exists.

Equivalent to PointCloud::HasProperty(PointCloud::INTENSITIES);

    float* GetIntensities()

When intensity property exists, returns the pointer to data, nullptr otherwise.

Equivalent to PointCloud::GetData<float>(PointCloud::INTENSITIES);

    const float* GetIntensities() const

When intensity property exists, returns the pointer to data, nullptr otherwise.

Equivalent to PointCloud::GetData<float>(PointCloud::INTENSITIES);

    const PointCloudProperty& AddIntensities()

Creates PointCloud::INTENSITIES property buffer if it was not added already.

Do not add this property using PointCloud :AddProperty method.

    const std::vector<PointCloudProperty>& GetProperties() const

Returns all available properties.

    const PointCloudProperty& AddProperty(const PointCloudProperty::Key& key, DataType type)

Creates new property buffer.

Parameters:

key | Property identifier. If it already exists, does nothing and returns existing property.
type | Specific type of data in buffer.

Returns:

Newly created property.

    const PointCloudProperty& AddProperty(const PointCloudProperty::Key& key, size_t bytes_per_point)

Creates new property buffer.

Parameters:

key | Property identifier. If it already exists, does nothing and returns existing property.
bytes_per_point | Number of bytes reserved for each point.

Returns:

Newly created property.

    void RemoveProperty(const PointCloudProperty::Key& key)

Remove a single property by key..

    void ClonePropertiesOf(const PointCloud& pc)

Adds all properties, which are not already present in this.

    bool HasProperty(const PointCloudProperty::Key& key) const

Checks whether a specific property exists.

    std::optional<PointCloudProperty> GetProperty(const PointCloudProperty::Key& key)

Returns property with specified key if it exists, std::nullopt otherwise.

    std::optional<const PointCloudProperty> GetProperty(const PointCloudProperty::Key& key) const

Returns property with specified key if it exists, std::nullopt otherwise.

    virtual void* GetVoidData(const PointCloudProperty::Key& key)

When property exists, returns the pointer to data, nullptr otherwise.

    const void* GetVoidData(const PointCloudProperty::Key& key) const

When property exists, returns the pointer to data, nullptr otherwise.

    template <typename T>
    T* GetData(const PointCloudProperty::Key& key)

When property exists, returns the pointer to data of a template type, nullptr otherwise.

    template <typename T>
    const T* GetData(const PointCloudProperty::Key& key) const

When property exists, returns the pointer to data of a template type, nullptr otherwise.

    virtual void Transform(const glm::mat4& transformation, const std::optional<utils::SpaceDefinition>& resulting_space = std::nullopt)

Transforms point positions and normals.

Parameters:

transformation | Transformation matrix applied on every point and camera parameter.
resulting_space | Resulting point cloud space after the transformation is applied.

    bool HasSpace() const

Returns true, if there is a space defined for this structure.

    const std::optional<utils::SpaceDefinition>& GetSpace() const

Returns current space definition, if there is one.

    std::string GetSpaceId() const

Returns string representation of current space definition. Returns “N/A” otherwise.

    void SetSpace(const std::optional<utils::SpaceDefinition>& new_space)

Assigns a new space definition to the structure, overwriting the previous one.

    bool TransformToSpace(const utils::SpaceDefinition& new_space)

Transforms the structure to the new space. Fails, if the current space is not defined.

    void MakeCloneOf(const PointCloud& source)

Make a deep copy of the source PointCloud.

    virtual void ExecuteCopyCommands(const std::vector<CopyCommand>& copy_info)

Copies chunks of points according to copy commands.

    virtual void TruncateSize(size_t delta_size)

Decreases cloud size by the specified number of points.