Better-Seewo/Better-EN5/UI/InkDataHelper.cs

/*
 * InkDataHelper.cs
 * 墨迹数据辅助类
 * 所属项目：Better-Seewo
 * 作者：雾启工作室
 * 
 * 说明：
 *   提供墨迹数据的导出和导入功能。
 *   ExportInkData：从白板获取当前墨迹数据并封装为可序列化的模型
 *   ImportInkData：将墨迹数据模型应用到白板
 *   InkStrokeCollection：墨迹笔画集合数据模型，用于 JSON 序列化
 */

using System;
using System.Collections.Generic;
using System.Linq;

using Newtonsoft.Json;

using dotnetCampus.EasiPlugin;

namespace Better_Seewo.Better_EN5.UI
{
    /// <summary>
    /// 墨迹数据辅助类
    /// 提供从白板导出墨迹数据和向白板导入墨迹数据的静态方法
    /// </summary>
    public static class InkDataHelper
    {
        /// <summary>
        /// 从当前白板获取墨迹数据并导出为 InkStrokeCollection 模型
        /// 通过白板 SDK 接口读取当前页面的所有墨迹笔画信息
        /// </summary>
        /// <returns>
        /// 包含所有墨迹笔画数据的 InkStrokeCollection；
        /// 如果白板没有墨迹则返回 null
        /// </returns>
        public static InkStrokeCollection ExportInkData()
        {
            // 获取白板当前页面的墨迹对象集合
            var inkObjects = EN.BoardEditMenu.GetCurrentPageInkObjects();

            if (inkObjects == null || inkObjects.Count == 0)
            {
                return null;
            }

            // 构建墨迹笔画集合
            var collection = new InkStrokeCollection
            {
                // 导出时间戳
                ExportTime = DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss"),
                // 版本号，用于后续格式兼容
                Version = "1.0",
            };

            // 遍历所有墨迹对象，提取笔画数据
            foreach (var inkObject in inkObjects)
            {
                var stroke = new InkStroke
                {
                    // 笔画唯一标识
                    Id = inkObject.Id.ToString(),
                    // 笔画类型（如自由画笔、直线、圆形等）
                    StrokeType = inkObject.StrokeType.ToString(),
                    // 笔画颜色（ARGB 格式）
                    Color = inkObject.Color.ToArgb(),
                    // 笔画粗细（像素）
                    Thickness = inkObject.Thickness,
                    // 笔画的点集合（每个点包含 X、Y 坐标和压力值）
                    Points = inkObject.GetPoints().Select(p => new InkPoint
                    {
                        X = p.X,
                        Y = p.Y,
                        // 压力值，用于支持压感笔
                        Pressure = p.Pressure,
                    }).ToList(),
                };

                collection.Strokes.Add(stroke);
            }

            return collection;
        }

        /// <summary>
        /// 将墨迹数据导入到当前白板
        /// 读取 InkStrokeCollection 模型并通过白板 SDK 接口创建对应的墨迹笔画
        /// </summary>
        /// <param name="inkData">要导入的墨迹数据集合</param>
        public static void ImportInkData(InkStrokeCollection inkData)
        {
            if (inkData == null || inkData.Strokes == null || inkData.Strokes.Count == 0)
            {
                return;
            }

            // 遍历所有笔画数据，逐个创建墨迹对象并添加到白板
            foreach (var stroke in inkData.Strokes)
            {
                // 解析颜色值
                var color = System.Drawing.Color.FromArgb(stroke.Color);

                // 将 InkPoint 列表转换为白板 SDK 所需的点集合
                var points = stroke.Points.Select(p => new InkPointData
                {
                    X = p.X,
                    Y = p.Y,
                    Pressure = p.Pressure,
                }).ToArray();

                // 创建墨迹对象并添加到当前白板页面
                var inkObject = EN.BoardEditMenu.CreateInkObject(
                    strokeType: ParseStrokeType(stroke.StrokeType),
                    color: color,
                    thickness: stroke.Thickness,
                    points: points
                );

                // 将墨迹对象添加到白板
                EN.BoardEditMenu.AddInkObjectToCurrentPage(inkObject);
            }
        }

        /// <summary>
        /// 解析笔画类型字符串为枚举值
        /// </summary>
        /// <param name="strokeTypeStr">笔画类型字符串</param>
        /// <returns>对应的笔画类型枚举</returns>
        private static StrokeType ParseStrokeType(string strokeTypeStr)
        {
            // 尝试解析字符串为枚举值，解析失败则使用默认的自由画笔类型
            if (Enum.TryParse<StrokeType>(strokeTypeStr, out var result))
            {
                return result;
            }
            return StrokeType.FreeDraw;
        }
    }

    #region 墨迹数据模型

    /// <summary>
    /// 墨迹笔画集合数据模型
    /// 包含一组墨迹笔画的完整信息，用于 JSON 序列化和反序列化
    /// </summary>
    public class InkStrokeCollection
    {
        /// <summary>
        /// 导出版本号
        /// 用于后续格式升级时的兼容性判断
        /// </summary>
        [JsonProperty("version")]
        public string Version { get; set; }

        /// <summary>
        /// 导出时间戳
        /// 记录墨迹导出的具体时间
        /// </summary>
        [JsonProperty("exportTime")]
        public string ExportTime { get; set; }

        /// <summary>
        /// 笔画集合
        /// 包含当前白板页面上的所有墨迹笔画数据
        /// </summary>
        [JsonProperty("strokes")]
        public List<InkStroke> Strokes { get; set; } = new List<InkStroke>();
    }

    /// <summary>
    /// 单条墨迹笔画数据模型
    /// 描述一笔连续的墨迹，包含颜色、粗细、点集合等属性
    /// </summary>
    public class InkStroke
    {
        /// <summary>
        /// 笔画唯一标识
        /// 原始白板中该笔画的 ID，导入时可用于匹配和覆盖
        /// </summary>
        [JsonProperty("id")]
        public string Id { get; set; }

        /// <summary>
        /// 笔画类型
        /// 如 FreeDraw（自由画笔）、Line（直线）、Ellipse（椭圆）等
        /// </summary>
        [JsonProperty("strokeType")]
        public string StrokeType { get; set; }

        /// <summary>
        /// 笔画颜色
        /// 使用 ARGB 整数值表示（与 System.Drawing.Color.FromArgb 兼容）
        /// </summary>
        [JsonProperty("color")]
        public int Color { get; set; }

        /// <summary>
        /// 笔画粗细
        /// 单位为像素，表示笔画的线条宽度
        /// </summary>
        [JsonProperty("thickness")]
        public double Thickness { get; set; }

        /// <summary>
        /// 笔画点集合
        /// 一组有序的坐标点，构成笔画的路径
        /// </summary>
        [JsonProperty("points")]
        public List<InkPoint> Points { get; set; } = new List<InkPoint>();
    }

    /// <summary>
    /// 墨迹点数据模型
    /// 表示墨迹路径上的一个采样点，包含坐标和压力值
    /// </summary>
    public class InkPoint
    {
        /// <summary>
        /// X 轴坐标
        /// </summary>
        [JsonProperty("x")]
        public double X { get; set; }

        /// <summary>
        /// Y 轴坐标
        /// </summary>
        [JsonProperty("y")]
        public double Y { get; set; }

        /// <summary>
        /// 压力值
        /// 用于支持压感笔设备，值范围为 0.0 ~ 1.0
        /// </summary>
        [JsonProperty("pressure")]
        public double Pressure { get; set; }
    }

    #endregion
}