__   ___  __                        __  
|__) |__  / _` \_/ |\/| |    |    | |__) 
|  \ |___ \__> / \ |  | |___ |___ | |__) 


INTRODUCTION
============

regxmllib is a collection of tools and libraries for the creation of 
RegXML (SMPTE ST 2001-1) representations of MXF header metadata
(SMPTE ST 377-1). A RegXML Fragment example can be found at [1]

[1] src/test/resources/reference-files

Two implementations of regxmllib are provided:

* regxmllibj, which is implemented in pure Java; and
* regxmllibc, which is implemented in C++03.


KNOWN ISSUES AND LIMITATIONS
============================

regxmllib relies on SMPTE Metadata Registers that conform to SMPTE ST 335, 
ST 395, ST 400, ST 2003. These registers are published at [1].

[1] https://smpte-ra.org/smpte-metadata-registry

regxmllib deviates from ST 2001-1:2013 in a few narrow instances. Such deviations 
are noted in the source code and are expected to be submitted for consideration at 
the next revision of ST 2001-1. In particular:
  
* no baseline metadictionary is used, instead one extension metadictionary per
  namespace is used

Bugs are tracked at [2]

[2] https://github.com/sandflow/regxmllib/issues


REGXMLLIBJ
==========


Prerequisites
-------------

Java 8 language and SDK

Maven

(recommended) Git

(recommended) SMPTE Metadata Registers (Types, Elements, Groups and Labels) 


Quick Start
-----------

The following outputs to path PATH_TO_FRAGMENT an XML representation
of the header metadata of the MXF file at path PATH_TO_MXF_FILE 

* build the 'jar' target using Maven 'package' goal

* choose one of the following:

    * OPTION 1

        * retrieve the four SMPTE Metadata Registers (see [1] above)
    
        * build the metadictionaries from the SMPTE registers

            java -cp <PATH_TO_JAR> com.sandflow.smpte.tools.XMLRegistersToDict -e <PATH_TO_ELEMENTS_REG>
            -l <PATH_TO_LABELS_REG> -g <PATH_TO_GROUPS_REG> -t <PATH_TO_TYPES_REG> PATH_TO_DICT_DIR
                
    * OPTION 2
    
        * retrieve metadictionaries from [3]
        
            [3] https://github.com/sandflow/IMF/tree/master/dict
  
* generate the RegXML fragment
    
    run java -cp <PATH_TO_JAR> com.sandflow.smpte.tools.RegXMLDump -all -d <PATH_TO_DICT1> <PATH_TO_DICT2> ...
    -i <PATH_TO_MXF_FILE> > <PATH_TO_FRAGMENT>

* (optional) generate XSDs for RegXML Fragments

    run java -cp <PATH_TO_JAR> com.sandflow.smpte.tools.GenerateDictionaryXMLSchema -d <PATH_TO_DICT1> <PATH_TO_DICT2> ...
    -o <PATH_TO_OUTPUT_DIR>

* (optional) generate XSDs for SMPTE registers

    run java -cp <PATH_TO_JAR> com.sandflow.smpte.tools.GenerateXMLSchemaDocuments -cp <CLASS_PATH_TO_REGISTER_MODEL>
    -d  <PATH_TO_OUTPUT_DIR>

    where <CLASS_PATH_TO_REGISTER_MODEL> is equal to com.sandflow.smpte.register.catsup.TypesRegisterModel, etc.


Architecture
------------

At the heart of regxmllib is the FragmentBuilder.fragmentFromTriplet() method
that creates an XML fragment from a KLV group given a
a RegXML metadictionary and a collection of KLV groups from which strong
references are resolved. The rules engine implemented in 
FragmentBuilder.fragmentFromTriplet() is intended to follow the rules specified
in ST 2001-1 as closely as possible. A sister method, XMLSchemaBuilder.fromDictionary(),
creates a matching XML Schema that can be used to validate RegXML fragments.

Metadictionaries can be imported and exported from XML documents that conform
to the schema specified in SMPTE ST 2001-1. They can also be created
from SMPTE Metadata Registers published in XML form.

regxmllib includes a minimal MXF and KLV parser library.


Packages
--------

com.sandflow.smpte.klv : Classes for processing SMPTE KLV triplets (ST 336)
    
com.sandflow.smpte.mxf: Classes for processing SMPTE MXF structures (ST 377-1)

com.sandflow.smpte.register: Classes for processing SMPTE metadata registers
    (ST 335, ST 395, ST 400, ST 2003)
    
com.sandfow.smpte.regxml: Classes for managing RegXML metadictionaries and
    creating RegXML representations of MXF structures
    
com.sandfow.smpte.tools: Application-level tools
    
com.sandfow.smpte.util: Utilities classes


Tools
-----

RegXMLDump: dumps either the first essence descriptor or the entire header
            metadata of an MXF file as a RegXML structure
            
XMLRegistersToDict: converts XML-based SMPTE metadata registers to a RegXML metadictionaries

GenerateXMLSchemaDocuments: generates XSDs for the SMPTE metadata registers
                            
GenerateDictionaryXMLSchema: generate XSDs for RegXML Fragments from the RegXML metadictionaries
    

Unit Test
---------

Unit testing is performed by generating RegXML fragments from sample files located
at [1] and registers located at [2]. The resulting RegXML fragments are compared
to reference RegXML fragments located at [3].

[1] src/test/mxf-files
[2] src/test/registers
[3] src/test/regxml-files 

Reference RegXML fragments can regenerated by running the package goal with the build-reference-test-files profile:

    mvn package -Pbuild-reference-files
    

Maven Artifacts
---------------

* GroupId        com.sandflow
* ArtifactId     regxmllib

Snapshots are deployed at https://oss.sonatype.org/content/repositories/snapshots/

Releases are deployed at the central repository


REGXMLLIBC
==========

Prerequisites
-------------

C++03 toolchain

Metadictionaries generated by regxmllibj (see _Building Metadictionaries_ above)

Xerces-C++ Version 3.1.4 (or above) [1]

(recommended) CMake

[1] https://xerces.apache.org/xerces-c/
    

Architecture
------------

regxmllibc generally follows the architecture and idioms of regxmllibj.

Applications will typically call FragmentBuilder::fromTriplet() or
MXFFragmentBuilder::fromInputStream(), and the unit test at [1] provides an example.

[1] src/test/cpp/com/sandflow/smpte/dict/MetaDictionaryTest.cpp

regxmllibc does not however support the conversion of the SMPTE Metadata Registers to
RegXML metadictionaries, and instead relies on the metadictionaries generated by
regxmllibj (see _Building Metadictionaries_ above).


Unit Test
---------

As with regxmllibj, unit testing is performed by generating RegXML fragments from sample files located
at [1] and reference metadictionaries located at [2]. The resulting RegXML fragments are compared
to reference RegXML fragments located at [3].

[1] src/test/mxf-files
[2] src/test/regxml-dicts
[3] src/test/regxml-files 


DIRECTORIES AND NOTABLE FILES
=============================

build.xml                   Helper script (Ant)

pom.xml                     Maven POM file

CMakeLists.txt              CMake build file

target                      Output of the Maven build process, including the JAR
                                        
src/java                    regxmllibj codebase

src/cpp                     regxmllibc codebase

src/main/config/repoversion.properties
                            Template Java properties file used to host the 
                            a unique source code version generated using
                            git by the build system

src/main/resources/reg.xsd
                            Common XML Schema definitions used when generating
                            XML Schemas for RegXML Fragments
                                        
src/test/resources/regxml-files
                            Reference RegXML fragment used for unit testing

src/test/resources/registers
                            Reference SMPTE registers used for unit testing

src/test/resources/mxf-files
                            Sample MXF files used for unit testing  

src/test/resources/regxml-dicts
                            Reference metadictionaries used for unit testing