Custom Text Encoding

Custom Text Encoding

Aspose.Medical.Common.Text.DicomEncoding.Current maps DICOM Specific Character Set values to .NET encodings. Use its registration methods when an application supplies an encoding provider or needs to replace a character set’s encoding implementation.

Inspect Supported Encodings

SupportedEncodings enumerates the registered .NET encodings. TryGetEncoding accepts a DICOM character set identifier or a .NET encoding name and returns false when no supported encoding is found. Use it to detect unsupported input explicitly: GetEncoding instead falls back to the default DICOM ASCII encoding for an unknown value.

Aspose.Medical.Common.Text.IDicomEncoding encodings =
    DicomEncoding.Current;

if (encodings.TryGetEncoding("ISO_IR 192", out System.Text.Encoding? encoding))
{
    System.Console.WriteLine(encoding.WebName); // utf-8
}

foreach (System.Text.Encoding supported in encodings.SupportedEncodings)
{
    System.Console.WriteLine(supported.WebName);
}

Register a Provider and Character Set Mapping

Register the .NET EncodingProvider first, then associate the DICOM identifier with the provider’s encoding name using RegisterEncoding. Registration affects the shared encoding service, so perform it during application initialization before reading or writing datasets that need the mapping.

The complete example below supplies Latin-1 under an application-specific .NET name and maps the standard DICOM identifier ISO_IR 100 to it. Latin-1 is already supported; this demonstrates the registration and round-trip pattern. A provider can return an application-defined System.Text.Encoding implementation in the same way. Such an implementation must implement the abstract encoding members and honor caller-supplied encoder and decoder fallbacks.

public static class CustomEncodingExample
{
    public static string RoundTripPatientName()
    {
        Aspose.Medical.Common.Text.IDicomEncoding encodings =
            DicomEncoding.Current;
        encodings.RegisterProvider(new CustomEncodingProvider());
        encodings.RegisterEncoding("ISO_IR 100", CustomEncodingProvider.EncodingName);

        const string patientName = "Müller^Jörg";
        Aspose.Medical.Dicom.Dataset dataset = new();
        dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.SpecificCharacterSet, "ISO_IR 100");
        dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.PatientName, patientName);
        dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.SOPClassUID,
            Aspose.Medical.Dicom.Uid.SecondaryCaptureImageStorage);
        dataset.AddOrUpdate(Aspose.Medical.Dicom.Tags.Tag.SOPInstanceUID,
            Aspose.Medical.Dicom.Uid.CreateDerivedFromUuid());

        Aspose.Medical.Dicom.DicomFile initial = new(dataset);
        using System.IO.MemoryStream stream = new();
        initial.Save(stream);
        stream.Position = 0;

        Aspose.Medical.Dicom.DicomFile saved = DicomFile.Open(stream);
        return saved.Dataset.GetSingleValue<string>(Aspose.Medical.Dicom.Tags.Tag.PatientName);
    }
}

public sealed class CustomEncodingProvider : System.Text.EncodingProvider
{
    public const string EncodingName = "example-latin1";

    public override System.Text.Encoding? GetEncoding(string name)
        => string.Equals(name, EncodingName, System.StringComparison.OrdinalIgnoreCase)
            ? (System.Text.Encoding)System.Text.Encoding.Latin1.Clone()
            : null;

    public override System.Text.Encoding? GetEncoding(int codepage) => null;

    public override System.Text.Encoding? GetEncoding(
        string name,
        System.Text.EncoderFallback encoderFallback,
        System.Text.DecoderFallback decoderFallback)
    {
        System.Text.Encoding? encoding = GetEncoding(name);
        if (encoding is not null)
        {
            encoding.EncoderFallback = encoderFallback;
            encoding.DecoderFallback = decoderFallback;
        }
        return encoding;
    }

    public override System.Text.Encoding? GetEncoding(
        int codepage,
        System.Text.EncoderFallback encoderFallback,
        System.Text.DecoderFallback decoderFallback) => null;
}

Set SpecificCharacterSet to the DICOM identifier, not the .NET encoding name. Registering an encoding does not create a new standard character repertoire or ISO 2022 escape sequence; the encoding and character-set declaration must agree with the bytes exchanged with other DICOM systems.