如何自定义DICOM JSON输出与DicomJsonSerializerOptions

此教程展示了如何使用 DicomJsonSerializerOptions在 C# 定制 DICOM JSON 序列化输出。

为什么要定制 JSON 输出?

不同系统可能需要不同的 JSON 格式。

使用人可读的关键字而不是标签数字
包含标签名称文档
检查数字值如何呈现
满足第三方系统的具体要求

原标题:准备环境

设置 Visual Studio 或任何兼容的 .NET IDE.
创建一个新的 .NET 8 控制台应用程序项目。
在 NuGet Package Manager 中安装 Aspose.Medical。

可用的序列化选项

选项	描述	Impact
`UseKeywordsAsJsonKeys`	使用 DICOM 关键字而不是标签数字作为 JSON 密钥	`"PatientName"` vs `"00100010"`
`WriteKeyword`	包含每个标签对象中的关键字字	Adds `"keyword": "PatientName"`
`WriteName`	包含每个标签对象中的名称字段	Adds `"name": "Patient's Name"`
`NumberHandling`	控制数值代表性	作为行或实际 JSON 数字的数字

步骤指南定制 JSON 输出

步骤1:安装 Aspose.Medical

使用 NuGet 将 Aspose.Medical 图书馆添加到您的项目中。

Install-Package Aspose.Medical

步骤2:包含必要的名称空间

在您的代码中添加所需的名称空间的参考.

using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Serialization;
using System.Text.Json.Serialization;

步骤3:创建选项实例

创建 A DicomJsonSerializerOptions 例如设置设置。

DicomJsonSerializerOptions options = new DicomJsonSerializerOptions();

步骤4:设置选项

为您的 JSON 输出设置所需选项。

options.UseKeywordsAsJsonKeys = true;
options.WriteKeyword = true;
options.WriteName = true;
options.NumberHandling = JsonNumberHandling.WriteAsString;

步骤5:通过选项进行序列化

将选项转移到 Serialize 方法。

DicomFile dcm = DicomFile.Open("patient_scan.dcm");
string json = DicomJsonSerializer.Serialize(dcm, options, writeIndented: true);

步骤6:保存自定义输出

保存或使用自定义 JSON。

File.WriteAllText("customized_output.json", json);
Console.WriteLine("Customized JSON output saved!");

完整的代码示例与所有选项

下面是一个完整的例子,显示了所有定制选项:

using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Serialization;
using System.Text.Json.Serialization;

// Load DICOM file
DicomFile dcm = DicomFile.Open("patient_scan.dcm");

// Configure serialization options
DicomJsonSerializerOptions options = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true,
    WriteKeyword = true,
    WriteName = true,
    NumberHandling = JsonNumberHandling.WriteAsString
};

// Serialize with custom options
string json = DicomJsonSerializer.Serialize(dcm, options, writeIndented: true);

// Save output
File.WriteAllText("fully_customized.json", json);

Console.WriteLine("DICOM serialized with all custom options!");
Console.WriteLine(json);

比较输出格式

默认输出(标准PS3.18格式)

{
  "00100010": {
    "vr": "PN",
    "Value": [{ "Alphabetic": "DOE^JOHN" }]
  },
  "00100020": {
    "vr": "LO",
    "Value": ["12345"]
  }
}

使用KeywordsAsJsonKeys = 真实

{
  "PatientName": {
    "vr": "PN",
    "Value": [{ "Alphabetic": "DOE^JOHN" }]
  },
  "PatientID": {
    "vr": "LO",
    "Value": ["12345"]
  }
}

与 WriteKeyword 和 WriteName = 真实

{
  "00100010": {
    "vr": "PN",
    "keyword": "PatientName",
    "name": "Patient's Name",
    "Value": [{ "Alphabetic": "DOE^JOHN" }]
  }
}

与编号操作 = WriteAsString

{
  "00280010": {
    "vr": "US",
    "Value": ["512"]
  }
}

与编号处理 = 允许阅读由 String 和 WriteAsNumber

{
  "00280010": {
    "vr": "US",
    "Value": [512]
  }
}

使用案例示例

人文可读的文档

DicomJsonSerializerOptions docOptions = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true,
    WriteKeyword = true,
    WriteName = true
};

string documentationJson = DicomJsonSerializer.Serialize(dcm, docOptions, writeIndented: true);

PS3.18 兼容的 Web 服务

// Use default options for DICOM PS3.18 compliance
DicomJsonSerializerOptions webOptions = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = false,  // Use tag numbers
    WriteKeyword = false,
    WriteName = false,
    NumberHandling = JsonNumberHandling.WriteAsString
};

string ps318Json = DicomJsonSerializer.Serialize(dcm, webOptions);

JavaScript Frontend 集成

DicomJsonSerializerOptions jsOptions = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true,  // Easier to work with in JS
    NumberHandling = JsonNumberHandling.AllowReadingFromString  // Native numbers
};

string jsCompatibleJson = DicomJsonSerializer.Serialize(dcm, jsOptions);

数据库存储

DicomJsonSerializerOptions dbOptions = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true,  // Better for querying
    WriteKeyword = false,          // Reduce storage size
    WriteName = false
};

string compactJson = DicomJsonSerializer.Serialize(dcm, dbOptions);

重要考虑

互动性警告

非标准选项可能会破坏与某些 DICOM 插件的兼容性:

// WARNING: This format may not be compatible with all DICOM JSON parsers
DicomJsonSerializerOptions nonStandardOptions = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true  // Not PS3.18 compliant
};

// For maximum compatibility, use defaults:
DicomJsonSerializerOptions standardOptions = new DicomJsonSerializerOptions();

遵守的建议

当 DICOM PS3.18 符合要求时,请使用默认设置:

// PS3.18 compliant serialization
string compliantJson = DicomJsonSerializer.Serialize(dcm);  // No custom options

基于流的序列化与选项

对于大文件,使用基于流的序列化:

using Aspose.Medical.Dicom;
using Aspose.Medical.Dicom.Serialization;

DicomFile dcm = DicomFile.Open("large_scan.dcm");

DicomJsonSerializerOptions options = new DicomJsonSerializerOptions
{
    UseKeywordsAsJsonKeys = true,
    WriteKeyword = true
};

using (FileStream fs = File.Create("large_customized.json"))
{
    DicomJsonSerializer.Serialize(fs, dcm.Dataset, options, writeIndented: true);
}

结论

通过配置 DicomJsonSerializerOptions,您可以调整 JSON 格式,以满足具体的集成要求,同时平衡可读性、尺寸和互动性需求。