Skip to content
Snippets Groups Projects

ONELAB JSON interface

Last edited by Christophe Geuzaine

ONELAB parameters can be imported and exported in JSON format using the Gmsh API.

The ONELAB JSON database is structured as follows (current version number of the database format is 1.3):

"onelab":{
  "creator":"Gmsh",
  "date":"Mon Jan 01 00:00:00 2021",
  "version":"1.3",
  "parameters":[
     ...
  ]
}

All the parameters are given in the "parameters" array. Each parameter is an object with mandatory members "type", "name" and "values":

 { "type":"number", "name":"Path/to/my numeric parameter", "values":[1.234]}
 { "type":"string", "name":"Path/to/my string parameter", "values":["a string"]}
  • "type" (string): either "number" (for numeric parameters) or "string" (for string parameters)
  • "name" (string): the unique name of the parameter in the ONELAB database, in the form of a /-separated path
  • "values" (array): an array of numbers or strings, depending on the value of "type"

The /-separated path defining the unique "name" of each parameter is used in the Gmsh graphical user interface to create an item in the ONELAB parameter tree. Starting spaces, braces and numbers (in that order) are automatically stripped by Gmsh when displaying the parameters. This is useful to define a custom ordering of the tree, as the tree branches and leaves are sorted alphanumerically (numbers will appear before all letters; braces will appear after all letters).

Other members common to both numeric and string parameters:

  • "visible" (boolean): should the parameter be visible in the GUI?
  • "readOnly" (boolean): if true, the parameter cannot be changed in the GUI
  • "highlight" (string): color used to highlight the parameter widget in the GUI
  • "closed" (boolean): should the subtree in the GUI containing the parameter be closed?
  • "help" (string): help string for the parameter, displayed in a tooltip in the GUI
  • "label" (string): alternative label used in the GUI, replacing the part of "name" located after the last /
  • "attributes" (object): optional parameter attributes
    • "AutoCheck" (string): if set to "0", disable the automatic ONELAB "check" event when the value is changed
    • "GmshOption" (string): interpret the parameter name as the name of a Gmsh option
    • "Units"" (string): append the given string after the variable name between square brackets
    • "Persistent" (string): if set to "1", the parameter is not removed when the database is reset
    • "ServerAction" (string): action performed by the ONELAB server when the parameter is changed. Currently supported actions: "Reset" (to force a full model reset) and "ResetDatabase" (to reset only the ONELAB database)
    • "ServerActionReset", "ServerActionHide" or "ServerActionShow" (string): reset, hide or show the parameters with comma-separated names given in the string when the parameter is changed; an initial % character in a name is replaced by the path of the parameter
    • "ServerActionReset value", "ServerActionHide value" or "ServerActionShow value" (string): reset, hide or show the parameters with comma-separated names given in the string when the parameter value is changed to value; an initial % character in a name is replaced by the path of the parameter
    • "ServerActionResetMatch", "ServerActionHideMatch" or "ServerActionShowMatch" (string): reset, hide or show the parameters given by the regular expression in the string when the parameter is changed
    • "ServerActionResetMatch value", "ServerActionHideMatch value" or "ServerActionShowMatch value" (string): reset, hide or show the parameters given by the regular expression in the string when the parameter value is changed to value
    • "ServerActionSet" (string): set parameters to given values, with the parameter names and the values given as a comma-separated list in the string, when the parameter is changed; an initial % character in a name is replaced by the path of the parameter
    • "ServerActionSet value" (string): set parameters to given values, with the parameter names and the values given as a comma-separated list in the string, when the parameter value is changed to value; an initial % character in a name is replaced by the path of the parameter

Other members specific to numeric parameters:

  • "min" (number): minimum value allowed when scrolling in the GUI, and when looping on the parameter value
  • "max" (number): maximum value allowed when scrolling in the interface, and when looping on the parameter value
  • "step" (number): step value used when scrolling in the interface, and when looping on the parameter value
  • "choices" (array of numbers): possible choices for the parameter value
  • "valueLabels" (object): string labels for each the choices, i.e. {"label1":choice1, "label2":choice2, ...}
  • "attributes" (object): optional numeric parameter attributes
    • "ReadOnlyRange" (string): if set to "1", treat the range (or the choices, if they are provided) as read-only
    • "Loop" (string): loop over the parameter, with the string indicating the loop imbrication level (currently "1", "2" or "3")
    • "Graph" (string): display the list of values stored in "choices" as a 2D graph. The string encodes for which coordinate (x or y) in the predefined graphs (top left, top right, ...) the values will be used. Each graph is encoded as 4 characters, corresponding to the use of the values as the x, y, x' and y' coordinates (x' and y' are used when two curves should be drawn on the same graph): possible character values are 0 (value not used), 1 (iso-values), 2 (continuous map), 3 (discrete map), 4 (numeric value). The first group of 4 characters controls the pre-defined top-left graph, the second group controls the top-right graph, etc. For example, the string "0200" will use the values for the y coordinates on the top-left graph, displaying the curve with the continuous style; the string "10000200" will use the data for the x coordinates on the top-left graph and also use them as the y coordinates on the top-right graph
    • "NumberFormat" (string): display the value using the given printf-style formatting string, instead of the default "%g"

Other members specific to string parameters:

  • "kind" (string): mutable kind of the string (currently: "" or "file")
  • "choices" (array of strings): possible choices for the parameter
  • "attributes" (object): optional string parameter attributes
    • "MultipleSelection" (string): allow multiple selection in choices. The string indicates the initial selection pattern, e.g. "1001111"
    • "Macro" (string): if the string is "Action", trigger a ONELAB "check" event with the ONELAB parameter "ONELAB/Action" set to the value of the parameter; if the string is "GmshMergeFile", trigger Gmsh to merge the file with name given by the value of the parameter; if the string is "GmshParseString", trigger Gmsh to parse the string given by the value of the parameter
    • "Aspect" (string): if the string is "Button" (resp. "ReturnButton"), display the widget as a "3D" button (resp. return button) instead of the standard text; "Left", "Middle" or "Right" can be prefixed to "Button" and "ReturnButton" to create smaller buttons in the ONELAB context window, vertically padded and positioned horizontally on the left, middle or right.

Comments

    Please register or sign in to add a comment.