\label{sec:grammar}

The base Chaplin
file, ``info.json'',
must adhere to the JSON standard, such that it can be parsed
by JSON readers.
Descriptive database elements are stored as 
JSON lists, objects (dictionaries), strings, and numbers.
To describe the grammar (syntax) for this file, we mostly follow 
from a typical Bachus-Naur form (BNF)-like/
Regular Expression (RE)-like conventions.
Certain grammar additions or deviations
from BNF and RE are explained below, which are intended
to shorten the description of the Chaplin grammar. 

The ``+''/``++'' and ``*'' repetition tokens are meant 
to represent a rule of a
repetition, as usual, but
with the convention that there is
a comma separating between each element
(i.e., it is shorthand for a comma
separated list, which is common in JSON). That is:
RULE+ or RULE++ means 
RULELIST ::= RULE , RULELIST $|$ RULE and
RULE* means EMPTYORRULELIST ::= ``'' $|$ RULELIST.
The ``++'' rule has an additional meaning that in its expansion,
each sub-rule must exist at least
once and only once (i.e., it is a list of unique
keys or key-value pairs that must be present).
The ``??'' token,  i.e., RULE??,
it means that rule is optional in a ``++'' production rule.
This means that that all right-hand elements that 
are produced from a ``RULE++'' are required to appear
at least once unless noted with a ``??''.
Furthermore, a ``??'' element is represented with $<$RULE$>$
on the left-hand side to further represent that it is optional.

To describe unique JSON values (keys), we introduce two
additions to the grammar specification.
KEY(NAME, SET) represents that a token, from a production
rule NAME, is added to a list SET during parsing,
where the list is named by the token generated by the rule SET.
The token generated by NAME must be
unique within that list SET (a specific token must appear only
once in its production
rule during parsing). REF(NAME, SET) means that
it is referring to a token within the list SET 
(a token may appear as many times as necessary
from a production rule during parsing,
but the specific token must exist in the list SET
as generated by KEY at the end of parsing).
If SET is the token ``global''
rather than a production rule, it means that the tokens generated
by KEY NAME are globally unique.  Otherwise,
it means that the tokens
generated by KEY NAME are ``scoped'' to a list, specifically
named by a token that is generated by the rule SET
(the list of unique tokens is the list named by SET).
Additionally, unique token production
rules are represented as \$NAME\$
on the left-hand side to indicate that they are meant to be unique.

JSONSTRING represents a valid JSON string, JSONNUMBER
represents a valid JSON number, and JSONVALUE
represents any valid JSON value, i.e., string, number, list, or dictionary.
``['' and ``]'' represent literal list enclosing elements for JSON,
rather than character range elements, such as typically used in 
RE notation. Likewise, ``\{'' and ``\}'' represent literal dictionary
enclosing brackets for JSON objects. 
``('', ``)'', and ``$|$'' represent
their typical RE expression meanings (groups and option).

\subsubsection{Top level}

As noted before, the Chaplin file must conform to JSON standards,
which contains nested dictionaries (objects). 
The top level anonymous JSON dictionary
must contain four elements that describe the contents
of a Chaplin database.

\begin{verbatim}
CHAPLIN ::= { TOP++ }
TOP ::= METADATADICT | NAMEPATTERNSTR | PARAMETERDICT | CONSTRAINTDICT 
\end{verbatim}

The four sub-sections are the metadata dictionary,
a name pattern string, parameter dictionary, and the constraint dictionary,
which are described further below.

\subsubsection{Metadata}

\begin{verbatim}
METADATADICT ::= "metadata" : { METADATA++ }
METADATA ::= DBTYPESTR | DBVERSIONNUM | STORETYPESTR | 
  CAMERAMODESTR | ENDIANSTR | IMAGESIZEPAIR |
  VALUEMODENUM?? | CAMERADATA?? | PIPELINELIST??  
\end{verbatim}

The metadata section is a collection of miscellaneous non-parametric
(input) information, such as database type and
version information, camera
information, output data format and size,
and a representation of the source generating 
data pipeline. It is further
described in section~\ref{sec:CONSTRAINTS}.

\begin{verbatim}
DBTYPESTR :: = "type" : 
  ("composite-image-stack" | "parameteric-image-stack")
DBVERSIONNUM :: = "version" : JSONNUMBER.JSONNUMBER
STORETYPESTR ::= "store_type" : ("FS" | "SFS")
CAMERATYPESTR ::= "camera_model" : ("static" | 
  "phi-theta" | "azimuth-elevation-roll" | "roll-pitch-yaw")
ENDIANSTR ::= "endian" : ("little" | "big")
IMAGESIZEPAIR ::= "image_size" : [ JSONNUMBER, JSONNUMBER ]
<VALUEMODENUM> ::= "value_mode": (1 | 2)
\end{verbatim}

At at minimum, the metadata requires the database type,
database version, storage type, camera model type, byte
endianness, and image size.
Value mode, the pipeline information, and camera information
are optional. The
pipeline information and camera information elements
are described further below.

\begin{verbatim}
<CAMERADDATA> ::= LOOK++
LOOK ::= EYELIST | ATLIST | UPLIST | NEARFARLIST | ANGLELIST
EYELIST ::= "camera_eye" : [ CARTESIAN3+ ]
ATLIST ::= "camera_at" : [ CARTESIAN3+ ]
UPLIST ::= "camera_up" : [ CARTESIAN3+ ]
NEARFARLIST ::= "camera_nearfar": [ NEARFARPAIR+ ]
ANGLELIST ::= "camera_angle": [ JSONNUMBER+ ]
CARTESIAN3 ::= [ JSONNUMBER, JSONNUMBER, JSONNUMBER ]
NEARFARPAIR ::= [ JSONNUMBER, JSONNUMBER ]
\end{verbatim}

The optional camera information is described by several
elements: the eye position list, looking at position list,
camera up list, the near-far plane list, and the 
vertical view angle (FOV) list.  

\begin{verbatim}
PIPELINELIST ::= "pipeline" : [ FILTERDICT+ ]
FILTERDICT ::= { FILTERDATA++ }
FILTERDATA ::= NAMESTR | IDNUM | VISNUM | PARENTLIST | CHILDRENLIST
NAMESTR ::= "name" : JSONSTRING
IDNUM ::= "id" : KEY(UUID, global)
$UUID$ ::= JSONNUMBER
VISNUM ::= "visibility" : (0 | 1)
PARENTLIST ::= "parents" : [ REF(UUID, global)* ]
CHILDRENLIST ::= "children" : [ REF(UUID, global)* ]
\end{verbatim}

The optional pipeline information is a description
of a set of filters (program objects)
that are connected together from inputs
to outputs in a directed acyclic graph (DAG).
These connections are
represented by parent and children relationships.
The ID value, UUID, is required to be a globally
unique number to identify each filter, in
the pipeline DAG. These IDs are referred to 
in the PARENTLIST and CHILDRENLIST, to create the DAG.

\subsubsection{Name Pattern}

\begin{verbatim}
NAMEPATTERNSTR ::= "name_pattern" : JSONSTRING
\end{verbatim}

The name pattern section describes
the default image channel file type and the file path for
image production. This primarily is used to locate
the image data channels on storage,
as described by the parameters.

\subsubsection{Parameters}

\begin{verbatim}
PARAMETERDICT ::= "parameter_list" : { PARAMETERDATADICT+ }
PARAMETERDATADICT ::= KEY(PARAMETERNAME, global) : { PARAMETERDATA++ } 
$PARAMETERNAME$ ::= JSONSTRING
PARAMETERDATA ::= LABELSTR | VALUELIST | DEFAULTVAL?? | 
  ROLESTR?? | VALUERANGEDICT?? | HINTSTR?? | CHANNELLIST??  
\end{verbatim}

The parameter section is the dictionary of changeable  
variables (independent,
input data). The database will contain,
on storage, image data channels.
These channels
are the result of the Cartesian product of parameters,
which generate
results (dependent, output data)
for every parameter value, except when a parameter is
constrained by another parameter value. 
PARAMETERNAME is the name of the parameter, which
is globally unique in the JSON file, and the right-hand
value is a dictionary containing the description
of that named parameter. 
Parameters are described fully in
section~\ref{sec:PARAMETERS}. 

\begin{verbatim}
LABELSTR ::= "label" : JSONSTRING
VALUELIST ::= "values" : [ (JSONVALUE | KEY(VALUENAME, PARAMETERNAME))+ ]
$VALUENAME$ ::= JSONSTRING
\end{verbatim}

At a minimum, the description of a
parameter requires a LABELSTR and VALUELIST.
If a VALUENAME key appears in VALUELIST
(a unique name per PARAMETERNAME of the parameter that VALUELIST
is contained in), 
it will be referenced
in VALUERANGEDICT to describe the value range of VALUENAME
for that PARAMETERNAME parameter.

\begin{verbatim}
<DEFAULTVAL> ::= "default" : JSONVALUE
<ROLESTR> ::= "role" : ("layer" | "control" | "field")
<VALUERANGEDICT> ::= "valuesRanges" : { RANGELIST+ }
RANGELIST ::= REF(VALUENAME, PARAMETERNAME) : [ JSONNUMBER, JSONNUMBER ] 
<HINTSTR> ::= "type" : ("hidden" | "range" | "option")
<CHANNELLIST> ::= "types" : [ CHANNELSTR+ ]
CHANNELSTR ::= "depth" | "luminance" | "value" | "color" | "lut"
\end{verbatim}

Parameter data have optional descriptors, DEFAULTVAL, ROLESTR,
VALUERANGEDICT, HINTSTR, and CHANNELLIST.
ROLESTR describes the primary use for this parameter.
VALUERANGEDICT entries are specific to
parameters that have a
ROLESTR of ``field'' to describe the value range of the parameter
(primarily to be used for color maps).
HINTSTR describes a hint for the how the parameter ought to be 
presented to the user.
CHANNELLIST is used to indicate the type of image
channels that are stored in the database for this parameter.

\subsubsection{Constraints}
\label{sec:g-constraints}

\begin{verbatim}
CONSTRAINTDICT ::= "constraints" : { CONSTRAINEDDICT+ }
CONSTRAINEDDICT ::= REF(PARAMETERNAME, global) : { VALIDLIST+ }
VALIDLIST ::= REF(PARAMETERNAME, global) : [ JSONVALUE+ ]
\end{verbatim}

The constraints section describes the relationships between variables
and how parameters are restricted by other parameter's
values. It is
described further
in section~\ref{sec:CONSTRAINTS}. Briefly, a
constrained parameter will be
ignored (not used to locate image data channels
on storage) whenever any of the listed valid parameters,
in VALIDLIST, have values outside of the listed set
(i.e., it is not used in the production of inputs
to outputs).

