地下管网点云怎么渲？osgPotree + OpenTrench3D 分类显示全流程

前言

地下管线是城市的生命线，但埋在地下看不见；道路开挖、管线暴露的窗口期，是对沟槽做实测、摸清管线真实现状的最好机会。实测得到的是三维点云，而点云的价值在于分清每个点的身份——哪片是新铺的供水管、哪片是别家电缆、哪片只是土方。

本文以公开数据集 OpenTrench3D（310 个标注沟槽点云、约 5.28 亿点）为例，讲 osgPotree（基于 OSG 的点云库）分类显示的三个技术细节：

1. PLY 字段的自动识别与用户指定；
2. 分类数据如何存入 osg::Geometry；
3. 分类渲染与类别显示/隐藏如何实现。

每个点带属性 X, Y, Z, R, G, B, C，C 为类别号（0–4）：

C 值	语义	说明
0	Main Utility	新铺主管线（供水/区域供热）
1	Other Utility	其它权属单位的既有管线
2	Trench	开挖沟槽
3	Inactive Utility	已停用管线
4	Misc	杂项，评估时忽略

源码对应 osg-potree master（f61958b）。

---

一、整体流程

数据线只经过一个插件 osgdb_ply；渲染线的设计原则是"属性进槽位、状态进纹理"：类别号是数据，作为顶点属性跟着几何走；颜色和显隐是状态，放在一张纹理里——改样式只动纹理，不碰几何。

三步概括：插件把 C 列识别为分类号，绑定到几何的 6 号顶点属性；NodeVisitor 数出每个类的点数（直方图）；渲染时着色器按分类号到一张 256×1 的纹理里查颜色和显隐。
分类显示
按RGB显示

---

二、细节一：PLY 字段自动识别与用户指定

PLY 只约定文件结构，不约定列名含义：同样是类别，有的数据叫 classification，有的叫 class，OpenTrench3D 叫 c。所以读文件的第一件事是列名映射，分自动、手动两层。

OpenTrench3D 的属性头大致是（属性名大小写以实际样本为准）：

ply
format binary_little_endian 1.0
element vertex 1835443
property double x
property double y
property double z
property uchar red
property uchar green
property uchar blue
property uchar c
end_header

自动识别：对每个字段给一组候选名，按"从常见到简短"依次匹配，匹配前统一转小写（core/osgPotree/PlyHeader.cpp）：

PlyColumnMapping autoDetectPlyMapping(const PlyHeader& header)
{
    PlyColumnMapping mapping;
    const PlyElement* vertex = header.vertex();
    if (!vertex)
        return mapping;

    // 收集 vertex 元素的全部标量列，统一转小写做匹配
    std::vector<std::pair<std::string, std::string>> columns;
    for (const PlyProperty& property : vertex->properties)
    {
        if (!property.isList)
            columns.emplace_back(toLower(property.name), property.name);
    }

    auto findByNames = [&](std::initializer_list<const char*> names) -> std::string
    {
        for (const char* name : names)
        {
            const std::string wanted = toLower(name);
            const auto iterator = std::find_if(columns.begin(), columns.end(),
                [&](const std::pair<std::string, std::string>& column)
                { return column.first == wanted; });
            if (iterator != columns.end())
                return iterator->second;
        }
        return {};
    };

    mapping.x = findByNames({ "x" });
    mapping.y = findByNames({ "y" });
    mapping.z = findByNames({ "z" });
    mapping.red = findByNames({ "red", "r" });
    mapping.green = findByNames({ "green", "g" });
    mapping.blue = findByNames({ "blue", "b" });
    mapping.classification = findByNames({ "classification", "class", "category", "c" });
    // ...intensity / returnNumber / gpsTime 同理
    return mapping;
}

两个要点：classification 的候选列表收尾于单字母 "c"，正好匹配 OpenTrench3D；red/green/blue 候选里的 "r"/"g"/"b" 用来兼容单字母或全大写（R）命名的数据集。

用户指定：自动识别失手时，可通过 osgDB::Options 传 JSON 覆盖映射（plugins/osgdb_ply/ReaderWriterPly.cpp）；Qt 客户端的 PLY 导入对话框列全部列名供逐字段指认，确认后即以此 JSON 形式传给插件：

if (options && !options->getOptionString().empty())
{
    const nlohmann::json mapping = nlohmann::json::parse(options->getOptionString());
    const auto readField = [&](const char* key, std::string& value)
    {
        if (mapping.contains(key) && mapping[key].is_string())
            value = mapping[key].get<std::string>();
    };
    readField("classification", loadOptions.plyMapping.classification);
    // x / y / z / red / green / blue ... 同理
}

PLY 导入对话框如下所示：

---

三、细节二：分类数据如何存入 osg::Geometry

插件读点后先统一成标准属性（core/osgPotree/PointCloudStandardAttributes.h）：

struct PointCloudStandardAttributes
{
    std::vector<osg::Vec3d> positions;
    std::vector<osg::Vec4ub> colors;
    std::vector<std::uint8_t> classification;
    // ...intensity / returnNumber / gpsTime 等其余 LAS 标准属性
    bool hasClassification = false;
};

再由 buildPointCloudNode() 拼成 osg::Geometry。分类号不进顶点、不进颜色，而是占用一个顶点属性槽位——槽位即顶点属性编号（location），着色器里 layout(location = N) 的输入对应几何上 setVertexAttribArray(N, ...) 绑定的数组，编号一致才能对上。槽位在 core/osgPotree/PointCloudAttributeLayout.h 集中定义：

namespace osgpotree
{
inline constexpr unsigned int kClassificationVertexAttrib = 6;
inline constexpr unsigned int kIntensityVertexAttrib = 7;
inline constexpr unsigned int kReturnNumberVertexAttrib = 8;
inline constexpr unsigned int kGpsTimeVertexAttrib = 9;
// ...其余标准属性依次占用 10–14 号
}

0–5 号留给 OSG 内置数组（本工程着色器用了 0 号 osg_Vertex、3 号 osg_Color），自定义属性从 6 号开始。绑定代码：

if (attributes.hasClassification)
{
    osg::ref_ptr<osg::UByteArray> classes = new osg::UByteArray;
    classes->assign(attributes.classification.begin(), attributes.classification.end());
    geometry->setVertexAttribArray(kClassificationVertexAttrib, classes,
        osg::Array::BIND_PER_VERTEX);
}

buildPointCloudNode 另有两个细节：坐标先减包围盒中心再转 float（测量坐标数值大，直接转 float 丢精度；存相对坐标后数值小，float 够用），中心值放进外层 MatrixTransform；无颜色列时整列填 (205,205,205,255) 占位，避免 gl_Color 取到管线中残留的其他对象颜色。

---

四、细节三：分类渲染与类别显隐

4.1 一张纹理编码颜色与显隐

需求：256 个类各自配色、各自开关；改样式不能重造几何（百万点过一遍 CPU 代价太大）；能与透明度、EDL 叠加。

解法：一张 256×1 像素的 RGBA Texture1D，第 i 个像素对应类别 i——RGB 是颜色，A 是显隐。每类的显示状态存在（core/osgPotreePropertyCore/LasClassification.h）：

// Per-class display state. The 256-entry range covers the complete LAS
// classification byte, including the reserved ASPRS codes.
struct ClassificationStyle
{
    std::array<bool, 256> visible;
    std::array<osg::Vec4ub, 256> colors;

    ClassificationStyle();
    void resetColors();   // 恢复 ASPRS 默认配色
};

写入纹理（DrawableObject.cpp）：

void PointCloudObject::updateClassificationTexture()
{
    unsigned char* data = _classColorImage->data();

    for (int i = 0; i < 256; ++i)
    {
        const osg::Vec4ub& color = _classificationStyle.colors[static_cast<std::size_t>(i)];
        const std::size_t offset = static_cast<std::size_t>(i) * 4;
        data[offset + 0] = color.r();
        data[offset + 1] = color.g();
        data[offset + 2] = color.b();
        // 可见性藏在 alpha 里：不可见的类 alpha = 0
        data[offset + 3] = _classificationStyle.visible[static_cast<std::size_t>(i)] ? 255 : 0;
    }

    _classColorImage->dirty();
    _classColorTexture->dirtyTextureObject();
}

纹理过滤设 NEAREST（查表取整格，不插值），寻址设 CLAMP_TO_EDGE。

4.2 着色器

顶点着色器把 6 号槽位的分类号透传给片元：

#version 330
layout(location = 0) in vec3 osg_Vertex;
layout(location = 6) in float osg_Classification;
uniform mat4 osg_ModelViewProjectionMatrix;
out float vClassification;
void main()
{
    vClassification = osg_Classification;
    gl_Position = osg_ModelViewProjectionMatrix * vec4(osg_Vertex, 1.0);
}

片元着色器十行，是整个方案的核心：

#version 330
uniform sampler1D u_classColors;
uniform float uOpacity;
in float vClassification;
out vec4 fragColor;
void main()
{
    int classId = clamp(int(vClassification + 0.5), 0, 255);
    vec4 classColor = texelFetch(u_classColors, classId, 0);
    if (classColor.a < 0.5)
    {
        discard;   // 不可见的类：直接不产生片元
    }
    fragColor = vec4(classColor.rgb * uOpacity, uOpacity);  // 预乘 alpha
}

三个设计点：

• texelFetch 查表而非 texture 采样。类别号是整数，要的是"取第几格"。texelFetch 直接用纹素下标取值，不经过采样器（无过滤、无归一化），配合 NEAREST，类别 3 一定取到第 3 格，不会差格、不会混色。
• alpha + discard 实现显隐。隐藏某个类只需把对应像素的 alpha 从 255 改成 0——一次 1KB 纹理更新，几何一字节不动。显示状态全在纹理里、几何不携带任何显示信息，这是改样式轻量的根本原因。
• 预乘 alpha 输出。vec4(rgb * uOpacity, uOpacity) 配合根节点 BlendFunc(GL_ONE, GL_ONE_MINUS_SRC_ALPHA)，与其他着色模式走同一条混合管线，透明度行为一致。

4.3 状态组装与 UI 生效

applyRenderType() 在数据节点外套一个 Group，纹理、uniform、program 全放在壳的 StateSet 上——切换显示模式就是换壳，数据不动（DrawableObject.cpp）：

if (_colorMode == static_cast<int>(ColorMode::Classification) && _hasClassification)
{
    osg::ref_ptr<osg::Group> classificationNode = new osg::Group;
    classificationNode->addChild(_contentNode.get());

    osg::StateSet* stateset = classificationNode->getOrCreateStateSet();
    const int textureUnit = 3;
    stateset->setTextureAttributeAndModes(textureUnit, _classColorTexture.get(),
        osg::StateAttribute::ON);
    stateset->addUniform(new osg::Uniform("u_classColors", textureUnit));
    if (_opacityUniform.valid())
        stateset->addUniform(_opacityUniform.get());

    osg::ref_ptr<osg::Program> program = new osg::Program;
    program->setName("classificationColors");
    program->addShader(new osg::Shader(osg::Shader::VERTEX, classification_vertSrc));
    program->addShader(new osg::Shader(osg::Shader::FRAGMENT, classification_fragSrc));
    stateset->setAttributeAndModes(program, osg::StateAttribute::ON | osg::StateAttribute::OVERRIDE);

    coloredNode = classificationNode;
}

OVERRIDE 强制这份 program 生效，压过根节点上默认的透明度 program；再开 EDL 时会再包一层壳，因此分类色与 EDL 可叠加。一个坑：着色器用了 osg_ModelViewProjectionMatrix，必须先在 setRenderContext() 里调 getState()->setUseModelViewAndProjectionUniforms(true)，否则点云整帧消失。

UI 侧：右键菜单仅当 hasClassification() 为真时显示"按类别显示…"；对话框要列出"实际存在"的类，靠的是 NodeVisitor 遍历几何、把 6 号槽位的 UByteArray 数一遍得到的 256 项直方图（与渲染读同一列数据，菜单和屏幕永远一致）：

void apply(osg::Geometry& geometry) override
{
    osg::Array* rawArray = geometry.getVertexAttribArray(kClassificationVertexAttrib);
    if (osg::UByteArray* classes = dynamic_cast<osg::UByteArray*>(rawArray))
    {
        for (const auto value : *classes)
            ++_histogram[static_cast<std::size_t>(value)];   // histogram[类] = 点数
    }
    traverse(geometry);
}

对话框只列直方图计数大于 0 的类，每类一行（勾选、类 ID、类名、颜色）。确定后 setClassificationStyle() 回写样式，唯一的后续动作就是 updateClassificationTexture()——无几何重建、无数据重读、无场景图变动，下一帧生效。

---

五、实战提示

# PLY 直读，属性列自动映射，c 列自动认作分类
osgviewer D:/OpenTrench3D/water/area1/cloud_0001.ply

或用 Qt 客户端 osgPotreeViewerQt 把 .ply 拖进数据面板（列映射不对时在导入对话框指认）。

注意一个语义错位：OpenTrench3D 的类号 0–4 原样进了分类通道，界面显示的是 LAS/ASPRS 标准类名——“新装主管线"显示为"创建点，未分类”、“沟槽"显示为"地面点”。显示机制不受影响（类号只是纹理下标），实战做法：用预设调色板重着色（0 主管线红、1 他营蓝、2 沟槽灰、3 停用橙），并取消勾选 4（Misc）隐藏杂物——正好对应论文"评估时忽略 Misc"的设定。想要正确类名，做一张 OpenTrench3D 专用类名表挂在 LasClassification 旁即可。

---

六、总结

三个细节，三句话：

1. 字段识别——候选名探测（classification/class/category/c 依次匹配、统一转小写）自动识别列，JSON / 导入对话框手动兜底；
2. 分类存储——分类号绑定为 osg::Geometry 的 6 号顶点属性（UByteArray、BIND_PER_VERTEX），随几何走，槽位号即着色器的 location；
3. 分类渲染——256×1 RGBA 纹理编码颜色（RGB）与显隐（A），片元着色器 texelFetch 查表、alpha 为 0 即 discard；改样式只需更新这张 1KB 纹理。

本质仍是"属性进槽位、状态进纹理"：数据记录事实（这个点是哪类），状态决定表达（这个类怎么显示），两者以槽位号、纹理下标为接口解耦。照此套路，按强度、按回波、按 GPS 时间的显示只是换槽位、换纹理的事。

---

参考资料

• OpenTrench3D 数据集与代码仓库：https://github.com/SimonBuusJensen/OpenTrench3D
• OpenTrench3D 论文（CVPR 2024W USM）：https://openaccess.thecvf.com/content/CVPR2024W/USM/papers/Hansen_OpenTrench3D_A_Photogrammetric_3D_Point_Cloud_Dataset_for_Semantic_Segmentation_CVPRW_2024_paper.pdf
• osgPotree 仓库：https://gitee.com/osg_opensource/osg-potree