EikonalWorks Intensity Files

EikonalWorks Intensity files use the .ewi extension. EWI is the native EikonalWorks binary format for luminous intensity distribution documents.

The format is intended to preserve data that older exchange formats cannot represent cleanly, including multiple emitter channels, document and channel properties, color data, hit counts, photometry type, symmetry type, and channel intensity scale.

Format status

The current file version is 1. Files begin with the ASCII magic bytes EWI and a version field. Readers should reject files whose magic bytes are not EWI or whose version is not supported.

All fixed-size structures are written as packed binary data. Strings are UTF-8 byte sequences preceded by a 32-bit unsigned byte length. Numeric values are written in the native representation used by the current implementation.

Top-level file header

Every EWI file starts with EWIFileHeaderV1.

Field Type Description
Magic char[3] ASCII bytes E, W, I.
Version uint32 File format version. Current value: 1.
CreationTimestampUtc int64 Unix epoch timestamp in seconds, UTC.
NumberOfChannels uint32 Number of channel sections written by the file.
UniqueID char[32] 32 hexadecimal characters. Not null-terminated.
LuminaireNameLength uint32 Length in bytes of the luminaire name that follows the header.

If LuminaireNameLength is greater than zero, the header is followed immediately by that many UTF-8 bytes.

Section model

After the file header and optional luminaire name, the file is a sequence of sections. Each section begins with EWISectionHeader.

Field Type Description
SectionId uint32 Identifies the payload type.
SectionSize uint64 Payload size in bytes, excluding the section header.

Readers skip unknown top-level or channel-level sections by seeking to payloadStart + SectionSize. This allows future format versions to add optional data without breaking older readers that can safely ignore it.

Section identifiers

Section ID Hex Scope Description
EWI_SECTION_DOCUMENT_PROPERTIES 0x1001 File Serialized document-level properties.
EWI_SECTION_CHANNEL 0x2000 File Complete channel payload.
EWI_SECTION_CHANNEL_PROPERTIES 0x2001 Channel Serialized channel or mesh properties.
EWI_SECTION_ANGLE_TABLES 0x2002 Channel Planar and conic angle arrays.
EWI_SECTION_CELL_DATA 0x2003 Channel Per-cell intensity, optional color data, and optional hit counts.

Channel header

Each channel section starts with EWIChannelHeaderV1.

Field Type Description
PlaResolution int32 Number of planar-angle rows expected by the channel.
ConResolution int32 Number of conic-angle columns expected by the channel.
PhotometryType int32 Numeric value of PHOTOMETRY_TYPE.
SymmetryType int32 Numeric value of INTENSITY_SYMMETRY_TYPE.
ColorDataMode uint8 Numeric value of IntensityMeshData::ColorDataMode.
HasNumberOfHits uint8 1 when each cell stores a hit count, otherwise 0.
Reserved0 uint8 Reserved. Written as zero.
Reserved1 uint8 Reserved. Written as zero.
IntensityScale double Channel scale factor used when combining channels.
ChannelNameLength uint32 Length in bytes of the UTF-8 channel name following the header.

If ChannelNameLength is greater than zero, the channel header is followed immediately by that many UTF-8 bytes.

Photometry and symmetry values

The channel header stores enum values as integers. Current photometry type values are:

Value Meaning
0 Type A
1 Type B
2 Type C
3 HEALPix

Current symmetry type values are:

Value Meaning
0 No symmetry
1 C0-C180 symmetry
2 C90-C270 symmetry
3 Quadratic symmetry
4 Rotational symmetry

Angle tables

The angle table section stores the planar and conic angle arrays used by the mesh.

Payload layout:

  1. uint32 planar angle count.
  2. double[planar angle count] planar angles.
  3. uint32 conic angle count.
  4. double[conic angle count] conic angles.

A valid channel must contain non-empty planar and conic angle tables before cell data can be read.

Cell data

The cell data section stores data row by row. The loops are planar index first, then conic index.

For every cell, the payload always includes:

Field Type Description
Intensity double Luminous intensity value for the cell.

If ColorDataMode is not None, the payload also includes:

Field Type Description
ColorA float First color component.
ColorB float Second color component.
ColorC float Third color component, present only for tristimulus color data.

If HasNumberOfHits is 1, the payload also includes:

Field Type Description
NumberOfHits int32 Simulation or sampling hit count for the cell.

Color data modes are:

Value Meaning Stored color components
0 None No color components.
1 Tristimulus ColorA, ColorB, ColorC.
2 CIE 1931 ColorA, ColorB.
3 CIE 1960 ColorA, ColorB.
4 CIE 1976 ColorA, ColorB.

Property sections

Document and channel property sections use the same property payload structure.

Payload layout:

  1. uint32 property count.
  2. For each property:
    • property name string.
    • uint32 serializable field count.
    • for each field:
      • field name string.
      • uint32 property type.
      • field value encoded according to the property type.

Known document properties include manufacturer, luminaire, drive gear, regulatory, and report properties. Known channel properties include lamp and optics properties. Unknown properties are skipped on read.

Property field types

Property type Stored value
String UTF-8 string.
Double double.
Integer int32.
Bool uint8, where non-zero means true.
Enum int32 choice index.
Key-value list uint32 item count, followed by key string and value string pairs.
List uint32 item count, followed by strings.
DateTime UTF-8 string.
Image original filename string, uint64 byte count, then raw image bytes.

Only fields that contain serializable values are written.

Reader requirements

A valid reader should:

  • Verify the magic bytes and version.
  • Read the optional luminaire and channel names using byte lengths, not null termination.
  • Skip unknown sections using the section size.
  • Require angle tables and cell data for each channel.
  • Treat cell data as planar-major order.
  • Rebuild calculations after loading the mesh data.

Use .ewi as the master format for EikonalWorks projects. Export IES, EULUMDAT, TM-33, or other exchange formats only when a downstream workflow requires them.