Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Major formatting & doxygen pass #179

Merged
merged 1 commit into from
Nov 22, 2022
Merged

Major formatting & doxygen pass #179

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .clang-format
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ BreakBeforeTernaryOperators: true
BreakConstructorInitializersBeforeComma: false
BreakConstructorInitializers: AfterColon
BreakStringLiterals: true
ColumnLimit: 120
CommentPragmas: '^ IWYU pragma:'
ColumnLimit: 100
CommentPragmas: '@copydetails '
CompactNamespaces: false
ConstructorInitializerAllOnOneLineOrOnePerLine: false
ConstructorInitializerIndentWidth: 3
Expand Down
307 changes: 185 additions & 122 deletions include/E57Exception.h
View file
Open in desktop

Large diffs are not rendered by default.

346 changes: 169 additions & 177 deletions include/E57Format.h
View file
Open in desktop

Large diffs are not rendered by default.

773 changes: 497 additions & 276 deletions include/E57SimpleData.h
View file
Open in desktop

Large diffs are not rendered by default.

224 changes: 117 additions & 107 deletions include/E57SimpleReader.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,172 +30,182 @@

#pragma once

//! @file
//! @brief E57 Simple API for reading E57.
//! @details This includes support for the [E57_EXT_surface_normals](http://www.libe57.org/E57_EXT_surface_normals.txt)
//! extension.
/// @file
/// @brief E57 Simple API for reading E57.
/// @details This includes support for the
/// [E57_EXT_surface_normals](http://www.libe57.org/E57_EXT_surface_normals.txt) extension.

#include "E57SimpleData.h"

namespace e57
{
//! Options to the Reader constructor
/// Options to the Reader constructor
struct E57_DLL ReaderOptions
{
//! Set how frequently to verify the checksums (see ReadChecksumPolicy).
/// Set how frequently to verify the checksums (see ReadChecksumPolicy).
ReadChecksumPolicy checksumPolicy = ChecksumAll;
};

//! @brief Used for reading an E57 file using E57 Simple API.
//!
//! The Reader includes support for the [E57_EXT_surface_normals](http://www.libe57.org/E57_EXT_surface_normals.txt)
//! extension.
/// @brief Used for reading an E57 file using E57 Simple API.
///
/// The Reader includes support for the
/// [E57_EXT_surface_normals](http://www.libe57.org/E57_EXT_surface_normals.txt) extension.
class E57_DLL Reader
{
public:
//! @brief Reader constructor
//! @param [in] filePath Path to E57 file
//! @param [in] options Options to be used for the file
/// @brief Reader constructor
/// @param [in] filePath Path to E57 file
/// @param [in] options Options to be used for the file
Reader( const ustring &filePath, const ReaderOptions &options );

//! @brief Reader constructor (deprecated)
//! @param [in] filePath Path to E57 file
//! @deprecated Will be removed in 4.0. Use Reader( const ustring &, const ReaderOptions & ) instead.
[[deprecated(
"Will be removed in 4.0. Use Reader( const ustring, const ReaderOptions & )." )]] // TODO Remove in 4.0
/// @brief Reader constructor (deprecated)
/// @param [in] filePath Path to E57 file
/// @deprecated Will be removed in 4.0. Use Reader( const ustring &, const ReaderOptions & )
/// instead.
[[deprecated( "Will be removed in 4.0. Use Reader( const ustring, const ReaderOptions & "
")." )]] // TODO Remove in 4.0
explicit Reader( const ustring &filePath );

//! @brief Returns true if the file is open
/// @brief Returns true if the file is open
bool IsOpen() const;

//! @brief Closes the file
/// @brief Closes the file
bool Close();

//! @name File information
//!@{
/// @name File information
///@{

//! @brief Returns the file header information
//! @param [out] fileHeader is the main header information
//! @return Returns true if successful
/// @brief Returns the file header information
/// @param [out] fileHeader is the main header information
/// @return Returns true if successful
bool GetE57Root( E57Root &fileHeader ) const;

//!@}
///@}

//! @name Image2D
//!@{
/// @name Image2D
///@{

//! @brief Returns the total number of Picture Blocks
//! @return Returns the number of Image2D blocks
/// @brief Returns the total number of Picture Blocks
/// @return Returns the number of Image2D blocks
int64_t GetImage2DCount() const;

//! @brief Returns the image2D header and positions the cursor
//! @param [in] imageIndex This in the index into the image2D vector
//! @param [out] image2DHeader pointer to the Image2D structure to receive the picture information
//! @return Returns true if successful
/// @brief Returns the image2D header and positions the cursor
/// @param [in] imageIndex This in the index into the image2D vector
/// @param [out] image2DHeader pointer to the Image2D structure to receive the picture
/// information
/// @return Returns true if successful
bool ReadImage2D( int64_t imageIndex, Image2D &image2DHeader ) const;

//! @brief Returns the size of the image data
//! @param [in] imageIndex This in the index into the image2D vector
//! @param [out] imageProjection identifies the projection in the image2D.
//! @param [out] imageType identifies the image format of the projection.
//! @param [out] imageWidth The image width (in pixels).
//! @param [out] imageHeight The image height (in pixels).
//! @param [out] imageSize This is the total number of bytes for the image blob.
//! @param [out] imageMaskType This is E57_PNG_IMAGE_MASK if "imageMask" is defined in the projection
//! @param [out] imageVisualType This is image type of the VisualReferenceRepresentation if given.
//! @return Returns true if successful
bool GetImage2DSizes( int64_t imageIndex, Image2DProjection &imageProjection, Image2DType &imageType,
int64_t &imageWidth, int64_t &imageHeight, int64_t &imageSize, Image2DType &imageMaskType,
/// @brief Returns the size of the image data
/// @param [in] imageIndex This in the index into the image2D vector
/// @param [out] imageProjection identifies the projection in the image2D.
/// @param [out] imageType identifies the image format of the projection.
/// @param [out] imageWidth The image width (in pixels).
/// @param [out] imageHeight The image height (in pixels).
/// @param [out] imageSize This is the total number of bytes for the image blob.
/// @param [out] imageMaskType This is E57_PNG_IMAGE_MASK if "imageMask" is defined in the
/// projection
/// @param [out] imageVisualType This is image type of the VisualReferenceRepresentation if
/// given.
/// @return Returns true if successful
bool GetImage2DSizes( int64_t imageIndex, Image2DProjection &imageProjection,
Image2DType &imageType, int64_t &imageWidth, int64_t &imageHeight,
int64_t &imageSize, Image2DType &imageMaskType,
Image2DType &imageVisualType ) const;

//! @brief Reads an image
//! @param [in] imageIndex index of the image. Must be less than GetImage2DCount()
//! @param [in] imageProjection identifies the projection desired.
//! @param [in] imageType identifies the image format desired.
//! @param [out] buffer pointer the raw image buffer
//! @param [in] start position in the block to start reading
//! @param [in] count size of desired chuck or buffer size
//! @return Returns the number of bytes transferred.
int64_t ReadImage2DData( int64_t imageIndex, Image2DProjection imageProjection, Image2DType imageType,
void *buffer, int64_t start, int64_t count ) const;

//!@}

//! @name Data3D
//!@{

//! @brief Returns the total number of Data3D Blocks
//! @return Returns number of Data3D blocks.
/// @brief Reads an image
/// @param [in] imageIndex index of the image. Must be less than GetImage2DCount()
/// @param [in] imageProjection identifies the projection desired.
/// @param [in] imageType identifies the image format desired.
/// @param [out] buffer pointer the raw image buffer
/// @param [in] start position in the block to start reading
/// @param [in] count size of desired chuck or buffer size
/// @return Returns the number of bytes transferred.
int64_t ReadImage2DData( int64_t imageIndex, Image2DProjection imageProjection,
Image2DType imageType, void *buffer, int64_t start,
int64_t count ) const;

///@}

/// @name Data3D
///@{

/// @brief Returns the total number of Data3D Blocks
/// @return Returns number of Data3D blocks.
int64_t GetData3DCount() const;

//! @brief Returns the Data3D header
//! @param [in] dataIndex This in the index into the images3D vector. Must be less than GetData3DCount().
//! @param [out] data3DHeader Data3D header
//! @return Returns true if successful
/// @brief Returns the Data3D header
/// @param [in] dataIndex This in the index into the images3D vector. Must be less than
/// GetData3DCount().
/// @param [out] data3DHeader Data3D header
/// @return Returns true if successful
bool ReadData3D( int64_t dataIndex, Data3D &data3DHeader ) const;

//! @brief Returns the size of the point data
//! @param [in] dataIndex This in the index into the images3D vector. Must be less than GetData3DCount().
//! @param [out] rowMax This is the maximum row size
//! @param [out] columnMax This is the maximum column size
//! @param [out] pointsSize This is the total number of point records
//! @param [out] groupsSize This is the total number of group records
//! @param [out] countSize This is the maximum point count per group
//! @param [out] columnIndex This indicates that the idElementName is "columnIndex"
//! @return Return true if successful, false otherwise
bool GetData3DSizes( int64_t dataIndex, int64_t &rowMax, int64_t &columnMax, int64_t &pointsSize,
int64_t &groupsSize, int64_t &countSize, bool &columnIndex ) const;

//! @brief Reads the group data into the provided buffers.
//! @param [in] dataIndex This in the index into the images3D vector. Must be less than GetData3DCount().
//! @param [in] groupCount size of each of the buffers given
//! @param [out] idElementValue pointer to the buffer holding indices index for this group
//! @param [out] startPointIndex pointer to the buffer holding Starting index in to the "points" data vector for
//! the groups
//! @param [out] pointCount pointer to the buffer holding size of the groups given
//! @return Return true if successful, false otherwise
/// @brief Returns the size of the point data
/// @param [in] dataIndex This in the index into the images3D vector. Must be less than
/// GetData3DCount().
/// @param [out] rowMax This is the maximum row size
/// @param [out] columnMax This is the maximum column size
/// @param [out] pointsSize This is the total number of point records
/// @param [out] groupsSize This is the total number of group records
/// @param [out] countSize This is the maximum point count per group
/// @param [out] columnIndex This indicates that the idElementName is "columnIndex"
/// @return Return true if successful, false otherwise
bool GetData3DSizes( int64_t dataIndex, int64_t &rowMax, int64_t &columnMax,
int64_t &pointsSize, int64_t &groupsSize, int64_t &countSize,
bool &columnIndex ) const;

/// @brief Reads the group data into the provided buffers.
/// @param [in] dataIndex This in the index into the images3D vector. Must be less than
/// GetData3DCount().
/// @param [in] groupCount size of each of the buffers given
/// @param [out] idElementValue pointer to the buffer holding indices index for this group
/// @param [out] startPointIndex pointer to the buffer holding Starting index in to the
/// "points" data vector for the groups
/// @param [out] pointCount pointer to the buffer holding size of the groups given
/// @return Return true if successful, false otherwise
bool ReadData3DGroupsData( int64_t dataIndex, int64_t groupCount, int64_t *idElementValue,
int64_t *startPointIndex, int64_t *pointCount ) const;

//! @brief Use this to read the actual 3D data
//! @details All the non-NULL buffers in buffers have number of elements = pointCount.
//! Call the CompressedVectorReader::read() until all data is read.
//! @param [in] dataIndex data block index
//! @param [in] pointCount size of each element buffer.
//! @param [in] buffers pointers to user-provided buffers
//! @return vector reader setup to read the selected data into the provided buffers
/// @brief Use this to read the actual 3D data
/// @details All the non-NULL buffers in buffers have number of elements = pointCount.
/// Call the CompressedVectorReader::read() until all data is read.
/// @param [in] dataIndex data block index
/// @param [in] pointCount size of each element buffer.
/// @param [in] buffers pointers to user-provided buffers
/// @return vector reader setup to read the selected data into the provided buffers
CompressedVectorReader SetUpData3DPointsData( int64_t dataIndex, size_t pointCount,
const Data3DPointsData &buffers ) const;

//! @overload
/// @overload
CompressedVectorReader SetUpData3DPointsData( int64_t dataIndex, size_t pointCount,
const Data3DPointsData_d &buffers ) const;

//!@}
///@}

//! @name Foundation API file information
//!@{
/// @name File information
///@{

//! @brief Returns the file raw E57Root Structure Node
/// @brief Returns the file raw E57Root Structure Node
StructureNode GetRawE57Root() const;

//! @brief Returns the raw Data3D Vector Node
/// @brief Returns the raw Data3D Vector Node
VectorNode GetRawData3D() const;

//! @brief Returns the raw Image2D Vector Node
/// @brief Returns the raw Image2D Vector Node
VectorNode GetRawImages2D() const;

//! @brief Returns the ram ImageFile Node which is need to add enhancements
/// @brief Returns the ram ImageFile Node which is need to add enhancements
ImageFile GetRawIMF() const;

//!@}
///@}

//! @cond documentNonPublic The following isn't part of the API, and isn't documented.
protected:
/// @cond documentNonPublic The following isn't part of the API, and isn't documented.
friend class ReaderImpl;

E57_OBJECT_IMPLEMENTATION( Reader ) // Internal implementation details, not part of API, must be last in object
//! @endcond
E57_OBJECT_IMPLEMENTATION( Reader ) // must be last in object
/// @endcond
}; // end Reader class

} // end namespace e57
Loading