nmWTAI-Platform/Include/nmNum/nmData/nmPebiCellMapping.h

#ifndef NMPEBICELLMAPPING_H
#define NMPEBICELLMAPPING_H

#include "nmData_global.h"

#include <QString>
#include <QVector>

#include <vtkType.h>

class vtkUnstructuredGrid;

/**
 * @brief 读写原始 PEBI 单元与 VTK Cell 之间的内部身份映射。
 *
 * 映射随 vtkUnstructuredGrid 保存在 CellData 和 FieldData 中。本工具类
 * 不缓存网格、数组或 DataManager 指针，但调用方仍须保证传入网格在调用
 * 期间没有被其他线程并发读写。
 */
class NM_DATA_EXPORT nmPebiCellMapping
{
public:
    enum MappingStatus
    {
        MappingStatus_Missing = 0,
        MappingStatus_Valid,
        MappingStatus_Invalid
    };

    /** @brief 返回 CellData 中原始单元 ID 数组的保留名称。 */
    static const char* originalCellIdArrayName();
    /** @brief 返回 FieldData 中原始单元总数数组的保留名称。 */
    static const char* originalCellCountArrayName();

    /**
     * @brief 将一份已验证的正向映射附加到尚未发布的网格。
     *
     * 保留名称已被占用、映射不完整或 ID 不可逆时不修改网格。持久化
     * 数组使用固定 Int32，公开输入仍使用 vtkIdType；该函数只使用
     * AddArray() 登记映射，不会把 OriginalCellId 设为活动 Scalars。
     */
    static bool attach(
            vtkUnstructuredGrid* pGrid,
            const QVector<vtkIdType>& vecVtkToOriginal,
            vtkIdType nOriginalCellCount,
            QString* pError = NULL);

    /**
     * @brief 读取并完整验证网格携带的正向与反向映射。
     *
     * 两个数组均不存在时返回 Missing；只存在一个或任一字段损坏时返回
     * Invalid。读取接受 Int32 和旧内存对象的 vtkIdType 整数表示，拒绝
     * 浮点数组。输出在进入函数时清空，且只在返回 Valid 时接收完整结果。
     */
    static MappingStatus read(
            vtkUnstructuredGrid* pGrid,
            QVector<vtkIdType>* pVtkToOriginal = NULL,
            QVector<vtkIdType>* pOriginalToVtk = NULL,
            QString* pError = NULL);

private:
    nmPebiCellMapping();
};

#endif // NMPEBICELLMAPPING_H