GLDF.Net 0.8.0

dotnet add package GLDF.Net --version 0.8.0                
NuGet\Install-Package GLDF.Net -Version 0.8.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="GLDF.Net" Version="0.8.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add GLDF.Net --version 0.8.0                
#r "nuget: GLDF.Net, 0.8.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install GLDF.Net as a Cake Addin
#addin nuget:?package=GLDF.Net&version=0.8.0

// Install GLDF.Net as a Cake Tool
#tool nuget:?package=GLDF.Net&version=0.8.0                

GLDF .NET library

GLDF Logo

OnPublishedRelease
OnPush develop
NuGet Status

Intro

.NET 6.0 library for the Global Lighting Data Format GLDF

Features

  • Serialize and deserialize GLDF XML
  • 100% format coverage of version 1.0-rc3
  • Validate GLDF XML with the GLDF XmlSchema (XSD)
  • Read and write .gldf container files, including all assets and meta-information.xml
  • Validate .gldf container files
  • Parse XML/container either into 1:1 .NET POCOs or alternatively with resolved references
  • No dependencies, small footprint (~1MB)
  • Windows & Unix compatible

If you would like to read the GLDF L3D format as well, have a look on GLDF.L3d

How to get started

Requirements

Nuget package

Add the package within your IDE or using the CLI

dotnet add package GLDF.Net

GLDF XML Serialization

Serialize GLDF domain DTOs to XML string

All models in the following examples are incomplete. For valid GLDF luminaires/sensors read the docs.

IGldfXmlSerializer serializer = new GldfXmlSerializer();
Root root = new Root {Header = new Header {Author = "Github Example"}};
string xml = serializer.SerializeToXml(root);
Serialize GLDF domain DTOs to .xml file
IGldfXmlSerializer serializer = new GldfXmlSerializer();
Root root = new Root {Header = new Header {Author = "Github Example"}};
serializer.SerializeToXmlFile(root, @"c:\some\file\path\product.xml");
Serialize GLDF domain DTOs to XML stream
IGldfXmlSerializer serializer = new GldfXmlSerializer();
Root root = new Root {Header = new Header {Author = "Github Example"}};
using Stream stream = new MemoryStream();
serializer.SerializeToXmlStream(root, stream);
Deserialize GLDF XML string to domain DTOs
IGldfXmlSerializer serializer = new GldfXmlSerializer();
string xml = @"<Root><Header><Author>Github Example</Author></Header></Root>";
Root root = serializer.DeserializeFromXml(xml);
Deserialize GLDF .xml file to domain DTOs
IGldfXmlSerializer serializer = new GldfXmlSerializer();
string filePath = @"c:\some\file\path\product.xml";
Root root = serializer.DeserializeFromXmlFile(filePath);
Deserialize GLDF stream to domain DTOs
IGldfXmlSerializer serializer = new GldfXmlSerializer();
string filePath = @"c:\some\file\path\product.xml";
using Stream stream = new FileStream(filePath, FileMode.Open);
Root root = serializer.DeserializeFromXmlStream(stream);
Set custom XML Serializer settings
XmlWriterSettings settings = new XmlWriterSettings();
settings.Encoding = Encoding.UTF32; // UTF-8 by default
settings.Indent = false; // true by default
// ...more settings
IGldfXmlSerializer serializer = new GldfXmlSerializer(settings);

GLDF XML validation

Validate XML string with GLDF XmlSchema
IGldfXmlValidator gldfXmlValidator = new GldfXmlValidator();
string xml = @"<Root><Header><Author>Github Example</Author></Header></Root>";
IEnumerable<ValidationHint> validationResult = gldfXmlValidator.ValidateXml(xml);

foreach (var validationHint in validationResult)
{
    Console.Write(validationHint.Severity); // Error/Info/Warning
    Console.Write(validationHint.ErrorType); // For XML validation its always XmlSchema
    Console.Write(validationHint.Message); // E.g. missing XML Elements etc.
    Console.Write(Environment.NewLine);
}
Validate a .xml file with GLDF XmlSchema
IGldfXmlValidator gldfXmlValidator = new GldfXmlValidator();
string filePath = @"c:\some\file\path\product.xml";
IEnumerable<ValidationHint> validationResult = gldfXmlValidator.ValidateXmlFile(filePath);
Validate a .xml Stream with GLDF XmlSchema
IGldfXmlValidator gldfXmlValidator = new GldfXmlValidator();
string filePath = @"c:\some\file\path\product.xml";
using Stream stream = new FileStream(filePath, FileMode.Open);
IEnumerable<ValidationHint> validationResult = gldfXmlValidator.ValidateXmlStream(stream, leaveOpen:false);
Validate a .gldf container file with GLDF XmlSchema (the product.xml inside the zip)
IGldfXmlValidator gldfXmlValidator = new GldfXmlValidator();
string filePath = @"c:\some\file\path\luminaire.gldf";
IEnumerable<ValidationHint> validationResult = gldfXmlValidator.ValidateGldfFile(filePath);
Validate a .gldf container Stream with GLDF XmlSchema (the product.xml inside the zip)
IGldfXmlValidator gldfXmlValidator = new GldfXmlValidator();
string filePath = @"c:\some\file\path\luminaire.gldf";
using Stream stream = new FileStream(filePath, FileMode.Open);
IEnumerable<ValidationHint> validationResult = gldfXmlValidator.ValidateGldfStream(stream, leaveOpen:false);
Set Encoding for validation
var encoding = Encoding.UTF32;
var gldfXmlValidator = new GldfXmlValidator(encoding);
var filePath = @"c:\some\file\path\product.xml";
gldfXmlValidator.ValidateFile(filePath);

GLDF container read/write

Create a .gldf container file
IGldfContainerWriter containerWriter = new GldfContainerWriter();
GldfContainer gldf = new GldfContainer
{
    Product = new Root {Header = new Header {Author = "Github example"}},
    Assets = new GldfAssets(),
    MetaInformation = new MetaInformation()
};
var filePath = @"c:\some\file\path\luminaire.gldf";
containerWriter.WriteToGldfFile(filePath, gldf);
Write to a .gldf container Stream
IGldfContainerWriter containerWriter = new GldfContainerWriter();
GldfContainer gldf = new GldfContainer
{
    Product = new Root {Header = new Header {Author = "Github example"}},
    Assets = new GldfAssets(),
    MetaInformation = new MetaInformation()
};
using Stream stream = new MemoryStream();
containerWriter.WriteToGldfStream(stream, leaveOpen:false, gldf);
Read a .gldf container file
IGldfContainerReader containerReader = new GldfContainerReader();
string filePath = @"c:\some\file\path\luminaire.gldf";
GldfContainer container = containerReader.ReadFromGldfFile(filePath);
Console.WriteLine($"GLDF author: {container.Product.Header.Author}");
Read a .gldf container file with ContainerLoadSettings
IGldfContainerReader containerReader = new GldfContainerReader();
string filePath = @"c:\some\file\path\luminaire.gldf";
var settings = new ContainerLoadSettings
{
    ProductLoadBehaviour = ProductLoadBehaviour.Load,
    AssetLoadBehaviour = AssetLoadBehaviour.FileNamesOnly,
    MetaInfoLoadBehaviour = MetaInfoLoadBehaviour.Skip
};
GldfContainer container = containerReader.ReadFromGldfFile(filePath, settings);
Console.WriteLine($"GLDF author: {container.Product.Header.Author}");
Read from a .gldf container Stream
IGldfContainerReader containerReader = new GldfContainerReader();
string filePath = @"c:\some\file\path\luminaire.gldf";
using Stream stream = new FileStream(filePath, FileMode.Open);
GldfContainer container = containerReader.ReadFromGldfStream(stream, leaveOpen:false);
Console.WriteLine($"GLDF author: {container.Product.Header.Author}");
Extract a .gldf container content to a directory
IGldfContainerReader containerReader = new GldfContainerReader();
string sourceFilePath = @"c:\some\file\path\luminaire.gldf";
string targetFolder = @"c:\some\file\path\extractedContent\";
containerReader.ExtractToDirectory(sourceFilePath, targetFolder);
Create a .gldf container from content in a directory
IGldfContainerWriter containerWriter = new GldfContainerWriter();
string sourceDirectory = @"c:\some\file\path\extractedContent\";
string targetFile = @"c:\some\file\path\luminaire.gldf";
containerWriter.CreateFromDirectory(sourceDirectory, targetFile);

GLF container validation

Validate a GLDF container
IGldfValidator validator = new GldfValidator();
GldfContainer gldfContainer = new GldfContainer
{
    Product = new Root {Header = new Header {Author = "Github example"}},
    Assets = new GldfAssets(),
    MetaInformation = new MetaInformation()
};
IEnumerable<ValidationHint> validationResult = validator.ValidateGldf(gldfContainer);

foreach (var validationHint in validationResult)
{
    Console.Write(validationHint.Severity); // Enum: Error/Info/Warning
    Console.Write(validationHint.ErrorType); // Enum: E.g. InvalidZipFile
    Console.Write(validationHint.Message); // E.g. Not a valid ZIP file etc.
    Console.Write(Environment.NewLine);
}
Validate a GLDF container file
IGldfValidator validator = new GldfValidator();
var filePath = @"c:\some\file\path\luminaire.gldf";
var result = validator.ValidateGldfFile(filePath, ValidationFlags.All);
Validate GLDF partially with ValidationFlags
IGldfValidator validator = new GldfValidator();
var filePath = @"c:\some\file\path\luminaire.gldf";
var flags = ValidationFlags.Schema | ValidationFlags.Zip;
var result = validator.ValidateGldfFile(filePath, flags);

See source for individual Rules

Validate a GLDF container Stream
IGldfValidator validator = new GldfValidator();
string filePath = @"c:\some\file\path\luminaire.gldf";
using Stream stream = new FileStream(filePath, FileMode.Open); 
var result = validator.ValidateGldfStream(stream, leaveOpen:false, ValidationFlags.All);

Deserialize GLDF with resolved references

The GldfXmlSerializer and GldfContainerReader classes produce an exact 1:1 representation of the GLDF XML in .NET (Root). Which implies that any references such as Variant ➜ Emitter ➜ Equipment ➜ LightSource ➜ Photometry ➜ File are mapped in the form of Ids, which have to be resolved manually in your application. With the GldfParser you have an option to let it resolve during deserialisation for you. And optionally load the GLDF File element content as well:

Parse into POCOs with resolved references
var parserSettings = new ParserSettings
{
    LocalFileLoadBehaviour = LocalFileLoadBehaviour.Skip,
    OnlineFileLoadBehaviour = OnlineFileLoadBehaviour.Load,
    HttpClient = new HttpClient()
};
IGldfParser gldfParser = new GldfParser(parserSettings);

var rootTyped = gldfParser.ParseFromXml(/* GLDF XML string */);
// Or
var rootTyped = gldfParser.ParseFromXmlFile(/* GLDF XML filepath */);
// Or
var rootTyped = gldfParser.ParseFromXmlStream(/* GLDF XML stream */);
// Or
var rootTyped = gldfParser.ParseFromRoot(/* Root POCO */);
// Or
var rootTyped = gldfParser.ParseFromGldf(/* GldfContainer POCO */);
// Or
var rootTyped = gldfParser.ParseFromGldfFile(/* GLDF container filepath */);
// Or
var rootTyped = gldfParser.ParseFromGldfStream(/* GLDF container stream */);

Meta-Information XML Serialization

See gldf.io to learn more about meta-information.xml

Serialize Meta-Information DTO to XML string
IMetaInfoSerializer serializer = new MetaInfoSerializer();
var metaInformation = new MetaInformation();
string xml = serializer.SerializeToXml(metaInformation);
Serialize Meta-Information DTO to XML file
IMetaInfoSerializer serializer = new MetaInfoSerializer();
var metaInformation = new MetaInformation();
var filePath = @"c:\some\file\path\meta-information.xml";
serializer.SerializeToXmlFile(metaInformation, filePath);
Serialize Meta-Information DTO to XML Stream
IMetaInfoSerializer serializer = new MetaInfoSerializer();
var metaInformation = new MetaInformation();
using Stream stream = new MemoryStream();
serializer.SerializeToXmlStream(metaInformation, stream);
Deserialize Meta-Information from XML string
IMetaInfoSerializer serializer = new MetaInfoSerializer();
var xml = "<MetaInformation></MetaInformation>";
MetaInformation metaInformation = serializer.DeserializeFromXml(xml);
Deserialize Meta-Information from XML file
IMetaInfoSerializer serializer = new MetaInfoSerializer();
var filePath = @"c:\some\file\path\meta-information.xml";
MetaInformation metaInformation = serializer.DeserializeFromXmlFile(filePath);
Deserialize Meta-Information from XML stream
IMetaInfoSerializer serializer = new MetaInfoSerializer();
string xml = "<MetaInformation></MetaInformation>";
using Stream stream = new MemoryStream(Encoding.UTF8.GetBytes(xml));
MetaInformation metaInformation = serializer.DeserializeFromXmlStream(stream);

Other

Read FormatVersion from GLDF XML string or XML file. Or from GLDF container
const string xml = "<Root><Header><FormatVersion major='1' minor='2'/></Header></Root>";
var formatVersion = GldfFormatVersionReader.GetFromXml(xml);
// or
const string filePath = @"c:\path\product.xml";
var formatVersion = GldfFormatVersionReader.GetFromXmlFile(filePath);
// or
const string filePath = @"c:\path\product.gldf";
var formatVersion = GldfFormatVersionReader.GetFromGldfFile(filePath);
// or
using var stream = File.OpenRead(@"c:\path\product.gldf");
var formatVersion = GldfFormatVersionReader.GetFromGldfStream(stream, leaveOpen: false);
Get all embedded XSD versions
foreach (var knownVersion in GldfEmbeddedXsdLoader.KnownVersions)
    Console.WriteLine(
        $"{knownVersion.Major}." +
        $"{knownVersion.Minor}." +
        $"{(knownVersion.PreReleaseSpecified ? knownVersion.PreRelease : string.Empty)}");
Load embedded GLDF XSD in specific version
// On unknown versions, the latest embedded will be loaded
var formatVersion = new FormatVersion(1, 0, 2);
string xsd = GldfEmbeddedXsdLoader.Load(formatVersion);

Interfaces

In summary, you can use the following interfaces

// 1) Serialize GLDF XML
IGldfXmlSerializer serializer = new GldfXmlSerializer();
// 2) Validate GLDF XML
IGldfXmlValidator gldfXmlValidator = new GldfXmlValidator();

// 3) Read GLDF container
IGldfContainerReader containerReader = new GldfContainerReader();
// 4) Write GLDF container
IGldfContainerWriter containerWriter = new GldfContainerWriter();
// 5) Validate GLDF Container
IGldfValidator validator = new GldfValidator();

// 6) Parse GLDF with resolved references
IGldfParser parser = new GldfParser();

// 7) Serialize Meta-Information XML
IMetaInfoSerializer serializer = new MetaInfoSerializer();

Questions, Issues & Contribution

Please use the discussion section for questions or create issues, when something seems to be wrong. PRs are welcome.

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net6.0

    • No dependencies.
  • net8.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.8.0 143 7/26/2024
0.7.1 242 9/19/2023
0.7.1-dev 184 7/5/2023
0.7.0 203 6/30/2023
0.7.0-dev.7 87 6/29/2023
0.6.0 208 6/5/2023
0.5.0 503 5/3/2022
0.4.0 499 2/28/2022
0.3.0 340 12/1/2021
0.2.0 1,433 11/26/2021
0.1.0 394 7/16/2021