1 Introduction

The purpose of this guide is to explain what AtlaBase library data contains and how you can work with it.

Our library editors gather data from a variety of file formats, usually PDF, PNG, DWG and IES files. The information therein is then transferred to our relational database in an information schema we call the ABF (AtlaBase Format). It is then regularly exported to our customers in the form of XML files in the CEF (Common Export Format) schema. The isolation between ABF and CEF allows us to develop new features without disturbing our customers with unnecessary CEF changes. It also allows us to export CEF files of different versions to different customers as required.

For both historical and technical reasons Capture are our only client with direct access to ABF data. We rely on the Capture Component for fixture visualisation in our ABF editor, which requires faster turnaround times than possible through batch exports. This also explains why some data may appear to be missing from the CEF.

CEF files are UTF-8 encoded XML files using the AtlaBase CEF schema. The CEF schema contains entity definitions for various types of objects such as fixtures and filters. A CEF file may contain one or many such objects.

The CEF schema is the primary documentation of our CEF file format. The rest of this guide provides additional information and explanations for things you can find in a CEF file.

1.1 About XML schemas

An XML schema is the recipe for the contents of an XML file. It defines the content structure of an XML file. XML schemas are XML files themselves, but with an XSD file ending. If you are new to working with XML schemas we recommend that you invest some time into studying them.

XML schema files are useful in many ways:

  • They document an XML file format.
  • They can be used for validation of XML files.
  • They can be used to generate software code that make development easier.
  • They can be used by XML editors for syntax checking and autocompletion.

1.2 Working with XML files

All common programming languages come with XML support of some kind. They all have their pros and cons, but we stress the importance of first surveying your options. Generally speaking, there are three common approaches to reading XML files available:

  • XML readers. In Java called SAX and in .Net XmlTextReader. It reads bit by bit of an XML file and lets the application know what it has found. It is the most performant approach, but only supports forward scanning.

  • DOM readers. In Java the DocumentBuilder classes and in .Net the XmlDocument and XDocument classes. DOM is short for “Document Object Model” and this approach reads the entire contents of the XML document into memory in a structure fashion that allows for random access of the entire document, either by specific navigation of the substructure, or by means of XPath which is a very powerful way of identifying specific elements of an XML (or rather any DOM structure).

  • Object mapping. The contents of the XML file are mapped into code objects of classes that match the contents of the XML file. This is done either by manually declaring classes in code that match the structure of the XML or by automatic generation of such. In Java this is known as JAXB and in .Net as XML Serialization.

The most powerful approach and the one that we would recommend is the last, object mapping.

In C#.Net there is a command line tool available called Xsd.exe that can generate all code necessary to serialize and deserialize XML files with only a few lines of code.

1.3 Releases

1.3.1 Version 2.8.0

Version 2.8.0 was released the XXXX of November 2022.

CEF 2.8.0 Downloads
CEF schema AtlaBase.CommonExportFormat_2.8.0.xsd
CEF schema diff from 2.7.0 Schema_Diff_2.7.0_2.8.0.pdf
Sample fixtures SampleFixtures_2.8.0.zip

Changes (page numbers refer to the schema diff linked above):

  • The new (optional) GroupName attribute of Channel elements can provide names for channel groups, in particular those of different effect engines (page 11).
  • The new (optional) Cells attribute of Channel elements can provide cell association for channels without cell specifying commands that still have a logical connection to a group of cells (page 11).
  • The new SetLightModesMixLevel command describes crossfades between different light modes (pages 8 and 17).
  • The new SetPrismScaleLevel command describe some fixtures’ ability to move the prism in the light train in order, providing a scaling effect (page 9).
  • The new Random wheel mode and SetWheelRandomPositionSpeed commands for wheels that change to random gobos or colours (pages 9 and 19).
  • The new SelectMacroCatalog, SelectMacro, MacroParameterCommand, SetMacroIntensityLevel, SetMacroColorRedLevel, SetMacroColorGreenLevel, SetMacroColorBlueLevel, SetMacroColorWhiteLevel, SetMacroShutterOpen, SetMacroShutterClosed, SetMacroShutterStrobe, SetMacroShutterSpeed, SetMacroSpeed, SetMacroDirection, SetMacroRotationPosition, SetMacroRotationSpin, SetMacroRotationDirection, SetMacroFadeTime and CustomMacroCommand effect engine commands (pages 10-11 and 21-23).

1.3.2 Version 2.7.0

Version 2.7.0 was released the 6th of January 2022.

CEF 2.7.0 Downloads
CEF schema AtlaBase.CommonExportFormat_2.7.0.xsd
CEF schema diff from 2.6.0 Schema_Diff_2.6.0_2.7.0.pdf
Sample fixtures SampleFixtures_2.7.0.zip

Changes (page numbers refer to the schema diff linked above):

  • A new ShutterRelation element in the ColourMixing element describes the relation between shutter and colour mixing layers (page 5).
  • Frost flags are now described in a new FrostFlags element and flag indexes have been added to the SetFrostLevel, SetFrostStrobe and CustomFrostCommand commands (pages 3, 9, 17-18 and 24).
  • DMX mode parameters can be marked as starting points of external modes with a new ExternalModeStart attribute (page 11).
  • A new AnimationDiscRatio attribute in gobos describes the size of the aperture in relation to the pattern of the disc (page 2).
  • Video projector lens shift information has been added in a new Shift element (page 6).

1.3.3 Version 2.6.0

Version 2.6.0 was released the 29th of September 2021.

CEF 2.6.0 Downloads
CEF schema AtlaBase.CommonExportFormat_2.6.0.xsd
CEF schema diff from 2.5.3 Schema_Diff_2.5.3_2.6.0.pdf
Sample fixtures SampleFixtures_2.6.0.zip

Changes (page numbers refer to the schema diff linked above):

  • The Mode attribute has been removed from the SetShutterSpeed command (page 16) as it applies regardless of which mode the shutter is currently in.
  • New CIE light mode with commands SetLightChromaticityXLevel, SetLightChromaticityYLevel and SetLightLuminanceLevel for additive CIE xyY colour mixing (pages 7, 21 and 23). The ranges of the x and y level commands are documented as part of the new ColourMixing element (page 5).
  • New SetLightEnabled command (pages 7 and 15) adds additional dimming/switching capabilities to colour mixing layers.
  • Cell information in the SetPreset command (pages 20 and 22).
  • Wheel index information in CustomWheelCommand (pages 9 and 18).
  • New ColorFlags element (pages 3 and 11)
  • New Visibility attribute (pages 11 and 21).

1.3.4 Version 2.5.3

Version 2.5.3 was released the 26th of May 2021.

CEF 2.5.3 Downloads
CEF schema AtlaBase.CommonExportFormat_2.5.3.xsd
CEF schema diff from 2.4.2 Schema_Diff_2.4.2_2.5.3.pdf
Sample fixtures SampleFixtures_2.5.3.zip

Changes (page numbers refer to the schema diff linked above):

  • Names of parts (page 5).
  • Parametric geometry information for parts (page 3) and light source location information (page 4).
  • Names of controllers (page 11).
  • New DefaultLevelType attribute on channels to distinguish between default levels provided by the fixture manufacturer and such computed by our CEF exporter (page 10).
  • Expansion of all custom commands’ descriptions. (page 19)
  • New SetLightColorRenderingIndex command for fixture CRI control (page 7, 15 and 21).
  • New SetRedFlagLevel, SetGreenFlagLevel and SetBlueFlagLevel commands for fixtures with subtractive RGB colour flags (page 7).
  • Renamed Preset command to SetPreset (page 9).
  • New SetPresetScroll and SetPresetScrollSpeed commands for virtual colour wheels (page 9 and 20).
  • Expansion of media server DMX ranges (page 12 and 13).
  • New CITPMediaType values for media servers (page 12).

1.3.5 Version 2.4.2

Version 2.4.2 was released the 3rd of September 2020.

CEF 2.4.2 Downloads
CEF schema AtlaBase.CommonExportFormat_2.4.2.xsd
Sample fixtures SampleFixtures_2.4.2.zip

This version was the first to be documented online.