Data Files
The data files are organized in a hierarchy with an info.json file at the top, which describes the data files conforming to the API described here.
API
1 - arguments
"arguments": {Contains a list of arguments for Tonic where only filename required. We provide default for the argument, label to possibly be used in a graphical user interface, type equal to item, list or range that applies to values, which is the actual argument.
filename
"filename": {
"default": "rgb.jpg",
"label": "filename",
"type": "list",
"values": [ "rgb.jpg", "composite.json" ]
},Defines the filenames of the files to be pulled into Tonic.
field
"field": {
"default": "bottomDepth",
"label": "field",
"type": "list",
"values": [ "bottomDepth", "temperature", "salinity" ]
},Defines the fields available to color map the visualization objects.
layer
"layer": {
"default": "_",
"label": "layer",
"type": "list",
"values": [ "_", "A", "B", "C", "D", "E", "F", "G", "H", "I", "J" ]
},List of the layers that could be composited by Tonic. The convention is to use “_” for the background layer and base64 characters (“A”, …, “Z”, “a”, …, “z”, …) for the additional layers.
phi
"phi": {
"default": "0.0",
"label": "phi",
"type": "range",
"values": [ "0.0", "20.0", "40.0", "60.0", "80.0", "100.0", "120.0", "140.0", "160.0", "180.0",
"200.0", "220.0", "240.0", "260.0", "280.0", "300.0", "320.0", "340.0" ]
},List of the phi (longitude) samplings for the camera.
theta
"theta": {
"default": "15.0",
"label": "theta",
"type": "range",
"values": [ "15.0", "40.0", "65.0", "90", "115.0", "140.0", "165.0" ]
},List of the theta (latitude) samplings for the camera.
time
"time": {
"default": "0",
"label": "time",
"type": "range",
"values": [ "0", "10", "20", "30", "40", "50", "60", "70", "80", "90", "100" ]
}
},List of the time (temporal) samplings the data files.
2 - cost
"cost": {
"image-width": 500,
"images": 1386,
"space": 2971263922,
"time": 13566.501937627792
},Contains cost measurements for data files construction. image-width is the width of the images. images is the number of images contained in the data files. space is the bytes used to hold the data files. time is the compute wall clock time used to create the data files.
3 - metadata
"metadata": {Contains the core metadata that describes the data files to Tonic.
description
"description": "MPAS 120KM simulation collecting contours on salinity and temperature.",A description of the analysis and data files.
dimensions
"dimensions": [ 500, 500 ],Size of the imagery in the data files.
fields
"fields": {
"A": "salinity",
"B": "temperature",
"C": "bottomDepth"
},Defines the RGB fields available to color map the visualization objects.
scalars
"scalars": {
"D": "vRTData",
"E": "vBrownianVectorsX",
"F": "vBrownianVectorsY"
},Defines the scalar fields available for the visualization objects.
id
"id": "composite-contours",Like any other identification, id is intended to be used to distinguish this data files from another data files in the In Situ Tonic setting, but has been, typically, set to the same value as the path and working directory (working_dir). We should find another way to identify the individual data files and remove this key from the metadata.
layer_fields
"layer_fields": {
"A": [ "C" ],
"B": [ "B", "A" ],
"C": [ "B", "A" ],
"D": [ "B", "A" ],
"E": [ "B", "A" ],
"F": [ "B", "A" ],
"G": [ "B", "A" ],
"H": [ "B", "A" ],
"I": [ "B", "A" ],
"J": [ "B", "A" ],
"K": [ "B", "A" ]
},layer_fields defines the mapping between layers and fields or scalars for color mapping. The layer key is associated with a list of fields to color the layer or scalars that can be used to compute colors dynamically.
layers
"layers": "ABCDEFGHIJK",layers defines a string of layers by a single character (64 layers).
offset
"offset": {
"AC": 1, "BB": 2,
"BA": 3, "CB": 4,
"CA": 5, "DB": 6,
"DA": 7, "EB": 8,
"EA": 9, "FB": 10,
"FA": 11, "GB": 12,
"GA": 13, "HB": 14,
"HA": 15, "IB": 16,
"IA": 17, "JB": 18,
"JA": 19, "KB": 20,
"KA": 21
},offset defines offset of each image layer into the image sprite.
path
"path": "composite-contours",path was intended to provide the base path prepend the name_pattern. Over time, the name_pattern was assumed to be relative to the info.json file. In this example, the path is the same as the id, which is the same as the working_dir.
pipeline
"pipeline": [pipeline is a list that describes the grouping of layers to use in defining a graphical user interface (GUI).
type=layer
{
"ids": [ "A" ],
"name": "Earth core",
"type": "layer"
},ids is a single layer list associating a visualization object layer with this pipeline layer. name provides a label of this layer to use for a graphical user interface element. type is layer.
type=directory
{
"children": [...],
"ids": [ "B", "C", "D", "E", "F" ],
"name": "Contour by temperature",
"type": "directory"
},ids and name are defined similarly as with type=layer. type is directory.
children of type=directory
{
"ids": [ "B" ],
"name": "t=5.0",
"type": "layer"
},
{
"ids": [ "C" ],
"name": "t=10.0",
"type": "layer"
},
{
"ids": [ "D" ],
"name": "t=15.0",
"type": "layer"
},
{
"ids": [ "E" ],
"name": "t=20.0",
"type": "layer"
},
{
"ids": [ "F" ],
"name": "t=25.0",
"type": "layer"
}children is a list of the individual children layers in the directory, and are described as type=layer above.
title
"title": "Composite contours",title is a short name of the analysis and data files.
type
"type": "composite-image-stack"type is the overall class of the analysis set. Examples include: “parametric-image-stack”, “image-data-stack”, “line-prober-csv-stack”, “point-series-prober-csv-stack”, “time-csv-stack”, “composite-image-stack”, and “catalyst-viewer”.
4 - name_pattern
"name_pattern": "{time}/{theta}/{phi}/{filename}",name_pattern is a string that describes the data files hierarchy. “{}” bracketed arguments are separated by “/”’s to indicate directory/subdirectory order. Each individual argument corresponds to one of the arguments. For example “{time}”.
5 - working_dir
"working_dir": "composite-contours",working_dir was intended to provide the base path prepend the name_pattern. Over time, the name_pattern was assumed to be relative to the info.json file. In this example, the working_dir is the same as the id, which is the same as the path.
example
{
"arguments": {
"filename": {
"default": "rgb.jpg",
"label": "filename",
"type": "list",
"values": [ "rgb.jpg", "composite.json" ]
},
"field": {
"default": "bottomDepth",
"label": "field",
"type": "list",
"values": [ "bottomDepth", "temperature", "salinity" ]
},
"layer": {
"default": "_",
"label": "layer",
"type": "list",
"values": [ "_", "A", "B", "C", "D", "E", "F", "G", "H", "I", "J" ]
},
"phi": {
"default": "0.0",
"label": "phi",
"type": "range",
"values": [ "0.0", "20.0", "40.0", "60.0", "80.0", "100.0", "120.0", "140.0", "160.0", "180.0",
"200.0", "220.0", "240.0", "260.0", "280.0", "300.0", "320.0", "340.0" ]
},
"theta": {
"default": "15.0",
"label": "theta",
"type": "range",
"values": [ "15.0", "40.0", "65.0", "90", "115.0", "140.0", "165.0" ]
},
"time": {
"default": "0",
"label": "time",
"type": "range",
"values": [ "0", "10", "20", "30", "40", "50", "60", "70", "80", "90", "100" ]
}
},
"cost": {
"image-width": 500,
"images": 1386,
"space": 2971263922,
"time": 13566.501937627792
},
"metadata": {
"description": "MPAS 120KM simulation collecting contours on salinity and
temperature.",
"dimensions": [ 500, 500 ],
"fields": {
"A": "salinity",
"B": "temperature",
"C": "bottomDepth"
},
"id": "composite-contours",
"layer_fields": { "A": [ "C" ],
"B": [ "B", "A" ],
"C": [ "B", "A" ],
"D": [ "B", "A" ],
"E": [ "B", "A" ],
"F": [ "B", "A" ],
"G": [ "B", "A" ],
"H": [ "B", "A" ],
"I": [ "B", "A" ],
"J": [ "B", "A" ],
"K": [ "B", "A" ]
},
"layers": "ABCDEFGHIJK",
"offset": { "AC": 1,
"BA": 3, "BB": 2,
"CA": 5, "CB": 4,
"DA": 7, "DB": 6,
"EA": 9, "EB": 8,
"FA": 11, "FB": 10,
"GA": 13, "GB": 12,
"HA": 15, "HB": 14,
"IA": 17, "IB": 16,
"JA": 19, "JB": 18,
"KA": 21, "KB": 20
},
"path": "composite-contours",
"pipeline": [
{
"ids": [ "A" ],
"name": "Earth core",
"type": "layer"
},
{
"children": [
{
"ids": [ "B" ],
"name": "t=5.0",
"type": "layer"
},
{
"ids": [ "C" ],
"name": "t=10.0",
"type": "layer"
},
{
"ids": [ "D" ],
"name": "t=15.0",
"type": "layer"
},
{
"ids": [ "E" ],
"name": "t=20.0",
"type": "layer"
},
{
"ids": [ "F" ],
"name": "t=25.0",
"type": "layer"
}
],
"ids": [ "B", "C", "D", "E", "F" ],
"name": "Contour by temperature",
"type": "directory"
},
{
"children": [
{
"ids": [ "G" ],
"name": "s=34.0",
"type": "layer"
},
{
"ids": [ "H" ],
"name": "s=35.0",
"type": "layer"
},
{
"ids": [ "I" ],
"name": "s=35.5",
"type": "layer"
},
{
"ids": [ "J" ],
"name": "s=36.0",
"type": "layer"
},
{
"ids": [ "K" ],
"name": "s=36.5",
"type": "layer"
}
],
"ids": [ "G", "H", "I", "J", "K" ],
"name": "Contour by salinity",
"type": "directory"
}
],
"title": "Composite contours",
"type": "composite-image-stack"
},
"name_pattern": "{time}/{theta}/{phi}/{filename}",
"working_dir": composite-contours"
}proposed changes
Proposed changes attempt to maintain backwards compatibility while both clarifying the data model API and enabling new features.
1 - arguments
files
"files": {
"image": "rgb.jpg",
"composite": "composite.json"
},Either files or the old argument filename is required to define the filenames of the files to be pulled into Tonic. In the case of compositing, Tonic requires an image sprite, image, and a layer ordering file, composite.
3 - metadata
fields
"fields": {
"A": "temperature",
...
},fields maintains the same format, but is to be strictly for rgb-based image color mapping.
scalars
"scalars": {
"B": "x position",
...
},scalars is a new metadata item that uses 24-bit float-based images for interactive color mapping.