ViewDesignEngine/include/vde/foundation/io_ply.h

#pragma once
#include "vde/core/point.h"
#include "vde/mesh/halfedge_mesh.h"
#include <string>

namespace vde::foundation {

/**
 * @brief 读取 PLY 文件（Stanford Polygon Format）
 *
 * 解析 PLY 格式文件，支持 ASCII 和二进制（小端序）两种编码。
 * 支持的 PLY 元素：vertex（位置、法线、颜色）、face（顶点索引列表）。
 *
 * @param filepath PLY 文件路径
 * @return 解析后的半边网格
 *
 * @throws std::runtime_error 若文件无法打开、格式不支持或数据损坏
 *
 * @note 自动检测文件头部 magic number 判断 ASCII / 二进制格式
 * @note 二进制格式仅支持小端序（little-endian）
 * @note 返回类型为 HalfedgeMesh，内部自动建立半边拓扑
 *
 * @code{.cpp}
 * auto mesh = read_ply("scan.ply");
 * std::cout << "Vertices: " << mesh.vertex_count() << "\n";
 * std::cout << "Faces: " << mesh.face_count() << "\n";
 * @endcode
 *
 * @see write_ply
 * @ingroup foundation
 */
mesh::HalfedgeMesh read_ply(const std::string& filepath);

/**
 * @brief 写入 PLY 文件（ASCII 格式）
 *
 * 将半边网格以 ASCII PLY 格式写出，包含顶点位置和面信息。
 *
 * @param filepath 输出文件路径
 * @param mesh 要导出的半边网格
 *
 * @note 输出的 PLY 为 ASCII 编码，易于人工阅读和编辑
 * @note 若需要二进制输出以提高性能，请使用 BinarySerializer
 *
 * @code{.cpp}
 * mesh::HalfedgeMesh mesh = // ...;
 * write_ply("output.ply", mesh);
 * @endcode
 *
 * @see read_ply, BinarySerializer
 * @ingroup foundation
 */
void write_ply(const std::string& filepath, const mesh::HalfedgeMesh& mesh);

}  // namespace vde::foundation