JSON Setup upgrade guide
Numerous changes have been made to the JSON Setup dataset, especially within the groups object. This page presents all the modifications impacting each one of the higher level objects in the JSON file hierarchy, which are represented below. Note that only the name of the dataEncodings object was updated to dataMappings at this level:
$schema¶
This key needs to be updated to the latest version of the JSON schema, which is version 4.0.0
version¶
This key needs to be updated to the latest version of the .nde standard, which is 4.0.0.
scenario¶
No modifications were made to this object so far. The official release of .nde version 4.0 will confirm whether this object can be duplicated safely from 3.3. to 4.0.
groups¶
The overal groups structure needs to be upgraded with the following modifications that will be detailed below:
Property | Version 4.0 | Version 3.3 | Comment |
---|---|---|---|
id [number] | Unchanged | ||
name [string] | Unchanged | ||
usage [string] | Unchanged | ||
dataset [object] | Now defined in the datasets array | ||
ut [object] | Replaced by the ultrasonicConventional processes array item | ||
paut [object] | Replaced by the ultrasonicPhasedArray processes array item | ||
fmc [object] | Replaced by the ultrasonicMatrixCapture and totaFocusingMethod processes array items | ||
datasets [array] | - | New datasets array array | |
processes [array] | - | New processes array array |
= property conserved | = new property | = property removed and replaced
Converting dataset object properties to datasets array¶
Converting previous dataset objects to new datasets array items require some important modifications. Please refer to the following tables for correlations between previous properties and new ones.
Previous dataset object in version 3.3:
Property | JSON Depth | Comment |
---|---|---|
ascan [object] | 0 | Divided into a AScanAmplitude and AScanStatus dataset |
ascan{velocity} [number] | 1 | Moved to the ultrasonicPhasedArray process |
ascan{skewAngle} [number] | 1 | Removed as already found in the paut object |
ascan{refractedAngle} [number] | 1 | Removed as already found in the paut object |
ascan{amplitude} [object] | 1 | Replaced by a AScanAmplitude dataset |
ascan{status} [object] | 1 | Replaced by a AScanStatus dataset |
firingSource [object] | 0 | Replaced by a FiringSource dataset |
storageMode [string] | 0 | Moved inside each datasets item definition |
dataSampling [object] | 2 | Merged with the dataValue object |
dataValue [object] | 2 | Moved with its child components inside each datasets item definition |
path [string] | 2 | Moved with its child components inside each datasets item definition |
dimensions [object] | 2 | Moved with its child components inside each datasets item definition |
overwriteCriteria [string] | 0 | Removed as not necessary |
New datasets array in version 4.0:
Property | JSON Depth | Comment |
---|---|---|
id [number] | 0 | Needs to be unique within a group |
dataTransformations [array] | 0 | References the process chains in charge of processing the dataset |
dataTransformations[{processId}] [number] | 1 | The processId of the last process in the chain |
dataTransformations[{groupId}] [number] | 1 | The groupId of the last process in the chain (not required if in the same group) |
dataClass [string] | 0 | |
storageMode [string] | 0 | Same as storageMode in version 3.3 |
dataValue [object] | 0 | Same as dataValue in version 3.3 |
path [string] | 0 | Same as path in version 3.3 |
dimensions [object] | 0 | Same as dimensions object in version 3.3 |
AScanAmplitude datasets¶
The following example shows how a version 3.3 ascan{amplitude} dataset can be converted to a AScanAmplitude datasets item in version 4.0:
This notation is used to define and object{and a child} inside the JSON hierarchy.
"datasets": [
{
"id": 0,
"dataTransformations":[
{
"processId": 0
}
],
"dataClass": "AScanAmplitude",
"storageMode": "Paintbrush",
"dataValue": {
"min": 0, // (1)!
"max": 32767, // (2)!
"unitMin": 0.0, // (3)!
"unitMax": 200.0, // (4)!
"unit": "Percent"
},
"path": "/Public/Groups/0/Datasets/0-AScanAmplitude",
"dimensions": [
{
"axis": "UCoordinate",
"offset": 0.0,
"quantity": 351,
"resolution": 0.001
},
{
"axis": "VCoordinate",
"offset": -0.07455,
"quantity": 114,
"resolution": 0.001
},
{
"axis": "Ultrasound",
"offset": 0.0,
"quantity": 568,
"resolution": 2E-08
}
],
}
]
- Corresponds to the min value previously stored in the dataSampling objects
- Corresponds to the max value previously stored in the dataSampling objects
- Corresponds to the previous min value of the dataValue object
- Corresponds to the previous max value of the dataValue object
"dataset": {
"ascan": {
"velocity": 2700.0,
"skewAngle": 0.0,
"refractedAngle": 0.0,
"amplitude": {
"dataSampling": {
"min": 0,
"max": 32767
},
"dataValue": {
"min": 0,
"max": 200,
"unit": "Percent"
},
"path": "/Domain/DataGroups/0/Datasets/0/Amplitude",
"dimensions": [
{
"axis": "UCoordinate",
"offset": 0.0,
"quantity": 351,
"resolution": 0.001
},
{
"axis": "VCoordinate",
"offset": -0.07455,
"quantity": 114,
"resolution": 0.001
},
{
"axis": "Ultrasound",
"offset": 0.0,
"quantity": 568,
"resolution": 2E-08
}
]
}
},
"overwriteCriteria": "Last",
"storageMode": "Paintbrush"
}
AScanStatus datasets¶
Note
This type of dataset is specific to the files saved with an Evident instrument and may be different with other vendors.
The following example shows how a version 3.3 ascan{status} dataset can be converted to a AScanStatus datasets item in version 4.0:
"datasets": [
{
"id": 1,
"dataTransformations":[
{
"processId": 0
}
],
"dataClass": "AScanStatus",
"storageMode": "Paintbrush",
"dataValue": {
"hasData": 1,
"saturated": 2,
"noSynchro": 4,
"unit": "Bitfield"
},
"path": "/Public/Groups/0/Datasets/1-AScanStatus",
"dimensions": [
{
"axis": "UCoordinate",
"offset": 0.2,
"quantity": 301,
"resolution": 0.001
},
{
"axis": "VCoordinate",
"offset": 0.0,
"quantity": 155,
"resolution": 0.001
}
],
}
]
"dataset": {
"ascan": {
"velocity": 2700.0,
"skewAngle": 0.0,
"refractedAngle": 0.0,
"status": {
"dataValue": {
"hasData": 1,
"saturated": 2,
"noSynchro": 4,
"unit": "Bitfield"
},
"path": "/Domain/DataGroups/0/Datasets/0/Status",
"dimensions": [
{
"axis": "UCoordinate",
"offset": 0.2,
"quantity": 301,
"resolution": 0.001
},
{
"axis": "VCoordinate",
"offset": 0.0,
"quantity": 155,
"resolution": 0.001
}
]
}
},
"overwriteCriteria": "Last",
"storageMode": "Paintbrush"
}
FiringSource datasets¶
Note
This type of dataset is specific to the files saved with an Evident instrument and may be different with other vendors.
This example shows how a version 3.3 firingSource dataset can be converted to a FiringSource datasets item in version 4.0:
"datasets": [
{
"id": 2,
"dataTransformations":[
{
"processId": 0
}
],
"dataClass": "FiringSource",
"storageMode": "Paintbrush",
"dataValue": {
"min": 0,
"max": 64,
"unit": "BeamId"
},
"path": "/Public/Groups/0/Datasets/2-FiringSource",
"dimensions": [
{
"axis": "UCoordinate",
"offset": 0.2,
"quantity": 301,
"resolution": 0.001
},
{
"axis": "VCoordinate",
"offset": 0.0,
"quantity": 155,
"resolution": 0.001
}
],
}
]
"dataset": {
"firingSource": {
"path": "/Domain/DataGroups/0/Datasets/1/FiringSource",
"dataValue": {
"min": 0,
"max": 64,
"unit": "BeamId"
},
"dimensions": [
{
"axis": "UCoordinate",
"offset": 0.2,
"quantity": 301,
"resolution": 0.001
},
{
"axis": "VCoordinate",
"offset": 0.0,
"quantity": 155,
"resolution": 0.001
}
]
},
"overwriteCriteria": "Last",
"storageMode": "Paintbrush"
}
Converting ut, paut, and fmc objects to processes array items¶
Each new processes array item has the same basic structure:
Property | Comment |
---|---|
id* [integer] | The unique process id in the JSON structure |
implementation [string] | The process implementation type, which can be Software or Hardware |
inputs [object] | An inputs array describing the different inputs of the process |
outputs [object] | An outputs array describing the different outputs of the process |
dataMappingId [number] | Previously found inside a paut, ut, or tfmDescription object, refers to the corresponding dataMapping object Id |
One of the following subobjects:
|
Converting previous ut, paut, fmc, and tfmDescriptions objects to new processes array items require some slight modifications. Please refer to the following tables for correspondance between previous properties and new ones.
ultrasonicPhasedArray process¶
Most of the previous paut object properties remain unchanged in the new ultrasonicPhasedArray object, which is now found inside the processes array.
Property | ultrasonicPhasedArray{} | paut{} | Comment |
---|---|---|---|
dataEncodingId [number] | Moved to datasets array item as dataMappingId | ||
pulseEcho [object] | |||
waveMode [string] | |||
velocity [number] | |||
focusing [object] | |||
beams [array] | |||
pulse [object] | |||
gates [array] | |||
rectification [string] | |||
digitizingFrequency [number] | |||
ascanSynchroMode [string] | |||
ascanCompressionFactor [number] | |||
gain [number] | |||
wedgeDelay [number] | |||
ultrasoundMode [string] | |||
highAmplitude [number] | Removed as it was a redundant with the dataset dataValue object content | ||
referenceAmplitude [number] | |||
referenceGain [number] | |||
digitalBandPassFilter [object] | |||
smoothingFilter [number] | |||
averagingFactor [number] | |||
softwareProcess [object] | Moved to a dedicated ultrasonicThickness processes array item |
Additionally, please note that some irrelevant parameters associated with the instrument configuration were removed:
- Removed from the gates array: produceCscanData, peakDetection and timeSelection
- Removed from the tcg object (inside the beams array): enabled
The following shows how a version 3.3 paut object can be converted to a ultrasonicPhasedArray processes array item in version 4.0:
"processes": [
{
"inputs": [],
"outputs": [
{
"id": 0,
"datasetId": 0,
"dataClass": "AScanAmplitude"
},
{
"id": 1,
"datasetId": 1,
"dataClass": "AScanStatus"
}
],
"id": 0, // (1)!
"dataMappingId": 0,
"implementation": "Hardware",
"ultrasonicPhasedArray": { // (2)!
"pulseEcho": {},
"waveMode": "TransversalVertical",
"velocity": 3100.0,
"focusing": {},
"beams": [],
"pulse": {},
"gates": [],
"rectification": "Full",
"digitizingFrequency": 100000000.0,
"ascanSynchroMode": "Pulse",
"ascanCompressionFactor": 6,
"gain": 33.1,
"wedgeDelay": 0.0,
"ultrasoundMode": "TrueDepth",
"referenceAmplitude": 80.0,
"referenceGain": 33.1,
"digitalBandPassFilter": {},
"averagingFactor": 1,
"calibrationStates": []
}
},
{
"inputs": [
{
"processId": 0
}
],
"outputs": [],
"id": 1,
"dataMappingId": 0,
"implementation": "Software",
"thickness": { // (3)!
"min": 0.0065000000000000006,
"max": 0.0273,
"gates": [
{
"id": 1,
"gateDetection": "MaximumPeak"
}
]
}
}
]
- As per convention, a process with an Id = 0 defines the group. This group is hence a "Phased Array" group.
- This object is almost identical to the previous paut object.
- This process replaces the previous softwareProcess inside the paut object.
"paut": {
"dataEncodingId": 0,
"pulseEcho": {},
"waveMode": "TransversalVertical",
"velocity": 3100.0,
"focusing": {},
"beams": [],
"pulse": {},
"gates": [],
"rectification": "Full",
"digitizingFrequency": 100000000.0,
"ascanSynchroMode": "Pulse",
"ascanCompressionFactor": 6,
"gain": 33.1,
"wedgeDelay": 0.0,
"ultrasoundMode": "TrueDepth",
"highAmplitude": 200.0,
"referenceAmplitude": 80.0,
"referenceGain": 33.1,
"digitalBandPassFilter": {},
"averagingFactor": 1,
"calibrationStates": [],
"softwareProcess": {
"thickness": {
"min": 0.0065000000000000006,
"max": 0.0273,
"gates": [
{
"id": 1,
"timeSelection": "Peak"
}
]
}
}
}
ultrasonicConventional process¶
Most of the previous ut object properties remain unchanged in the new ultrasonicConventional object now found inside the processes array.
Property | ultrasonicConventional{} | ut{} | Comment |
---|---|---|---|
dataEncodingId [number] | Moved to datasets array item as dataMappingId | ||
pulseEcho [object] or pitchCatch [object] or tofd [object] | |||
waveMode [string] | |||
velocity [number] | |||
refractedAngle [number] | Moved inside the beams array | ||
wedgeDelay [number] | |||
ascanStart [number] | Moved inside the beams array | ||
ascanLength [number] | Moved inside the beams array | ||
pulse [object] | |||
gates [array] | |||
rectification [string] | |||
digitizingFrequency [number] | |||
ascanSynchroMode [string] | |||
ascanCompressionFactor [number] | |||
gain [number] | |||
ultrasoundMode [string] | |||
referenceAmplitude [number] | |||
referenceGain [number] | |||
digitalBandPassFilter [object] | |||
smoothingFilter [number] | |||
averagingFactor [number] | |||
softwareProcess [object] | Moved to a dedicated thickness processes array item | ||
recurrence [number] | Moved inside the beams array | ||
tcg [object] | Moved inside the beams array | ||
calibrationStates [array] | |||
beams [array] | New array for uniformity with the ultrasonicPhasedArray process |
Additionally, please note that some irrelevant parameters associated with the instrument configuration were removed:
- Removed from the gates array: produceCscanData, peakDetection and timeSelection
- Removed from the tcg object: enabled
The following shows how a version 3.3 ut object can be converted to a ultrasonicConventional processes array item in version 4.0:
"processes": [
{
"inputs": [],
"outputs": [
{
"id": 0,
"datasetId": 0,
"dataClass": "AScanAmplitude"
},
{
"id": 1,
"datasetId": 1,
"dataClass": "AScanStatus"
}
],
"id": 0, // (1)!
"dataMappingId": 0,
"implementation": "Hardware",
"ultrasonicConventional": { // (2)!
"pulseEcho": {
"probeId": 0
},
"waveMode": "TransversalVertical",
"velocity": 3100.0,
"wedgeDelay": 6.4799999999999989E-06,
"digitizingFrequency": 100000000.0,
"pulse": {},
"gates": [],
"rectification": "Full",
"ascanCompressionFactor": 6,
"gain": 50.0,
"ultrasoundMode": "TrueDepth",
"referenceAmplitude": 80.0,
"referenceGain": 0.0,
"digitalBandPassFilter": {},
"smoothingFilter": 5000000.0,
"averagingFactor": 1,
"beams": [
{
"id": 0,
"refractedAngle": 60.0,
"ascanStart": 0.0,
"ascanLength": 3.408E-05
}
]
}
},
{
"inputs": [
{
"processId": 0
}
],
"outputs": [],
"id": 1,
"dataMappingId": 0,
"implementation": "Software",
"thickness": { // (3)!
"min": 0.00375,
"max": 0.01575,
"gates": [
{
"id": 1,
"gateDetection": "MaximumPeak"
}
]
}
}
]
- As per convention, a process with an Id = 0 defines the group. This group is hence a "Ultrasonic Conventional" group.
- This object is almost identical to the previous ut object.
- This process replaces the previous softwareProcess inside the ut object.
"ut": {
"dataEncodingId": 0,
"pulseEcho": {
"probeId": 0
},
"waveMode": "TransversalVertical",
"velocity": 3100.0,
"refractedAngle": 60.0,
"wedgeDelay": 6.4799999999999989E-06,
"ascanStart": 0.0,
"digitizingFrequency": 100000000.0,
"ascanLength": 3.408E-05,
"pulse": {},
"gates": [],
"rectification": "Full",
"ascanCompressionFactor": 6,
"gain": 50.0,
"ultrasoundMode": "TrueDepth",
"highAmplitude": 200.0,
"referenceAmplitude": 80.0,
"referenceGain": 0.0,
"digitalBandPassFilter": {},
"smoothingFilter": 5000000.0,
"averagingFactor": 1,
"softwareProcess": {
"thickness": {
"min": 0.00375,
"max": 0.01575,
"gates": [
{
"id": 1,
"timeSelection": "Peak"
}
]
}
}
}
ultrasonicMatrixCapture and totalFocusingMethod processes¶
Previously, a TFM was described by a fmc object in which a tfmDescriptions was nested. These are now two different processes in two different groups that are interconnected.
Converting previous fmc objects to new ultrasonicMatrixCapture array items require some significant modifications. Please refer to the following tables for correspondance between previous properties and new ones.
Previous fmc object in version 3.3:
Property | JSON Depth | Comment |
---|---|---|
dataEncoding [integer] | 0 | Moved one layer above in the general structure of the process |
probeId [number] | 0 | Moved inside each beams[{pulsers[]}] and beams[{pulsers[]}] array items |
pulse [object] | 0 | Moved inside the waveforms object |
pulserFrequency [number] | 0 | Moved inside the ultrasonicMatrixCapture object |
digitizingFrequency [number] | 0 | Moved inside the ultrasonicMatrixCapture object |
pulsers [object] | 0 | Moved inside the ultrasonicMatrixCapture{beams[]} array |
receivers [object] | 0 | Moved inside the ultrasonicMatrixCapture{beams[]} array |
tfmDescriptions [object] | 0 | Replaced by the totalFocusingMethod process |
New ultrasonicMatrixCapture object in version 4.0:
Property | JSON Depth | Comment |
---|---|---|
acquisitionPattern [string] | 0 | Indicates which type of acquisition pattern is used, such as FMC , PWI , or Sparse |
digitizingFrequency [number] | 0 | Same as digitizingFrequency in version 3.3 |
pulserFrequency [number] | 0 | Same as pulserFrequency in version 3.3 |
digitalBandPassFilter [number] | 0 | Same as digitalBandPassFilter found in tfmDescriptions array in version 3.3 |
waveforms [array] | 0 | Describes any type of waveform that could be used for firing a transducer element |
waveforms[{pulse}] [object] | 1 | Same as pulse in version 3.3 |
beams [array] | 0 | Lists all the different beams used for acquisitions, in a similar structure as ultrasonicPhasedArray |
The following shows how a version 3.3 fmc object can be converted to ultrasonicMatrixCapture and fullMatrixCapture processes in version 4.0:
"groups": [
{
"id": 0,
"processes": [
{
"inputs": [],
"outputs": [],
"id": 0,
"dataMappingId": 0,
"implementation": "Hardware",
"ultrasonicMatrixCapture": {
"acquisitionPattern": "FMC",
"digitalBandPassFilter": {},
"digitizingFrequency": 80000000.0,
"pulserFrequency": 5000000.0,
"waveforms": [
{
"id": 0,
"pulse": {
"width": 1.0000000000000001E-07,
"voltage": 40.0,
"polarity": "Bipolar"
}
}
],
"beams": [
{
"id": 0,
"pulsers": [
{
"id": 0,
"probeId": 0, // (1)!
"elementId": 0,
"waveformId": 0 // (2)!
}
],
"receivers": [
{
"id": 0,
"probeId": 0,
"elementId": 0,
"ascanStart": 0.0, // (3)!
"ascanLength": 0.00020480000000000002 // (4)!
},
{
"id": 1,
"probeId": 0,
"elementId": 1,
"ascanStart": 0.0,
"ascanLength": 0.00020480000000000002
}
{...}
]
}
]
}
}
]
},
{
"id": 1,
"processes": [
{
"inputs": [
{
"processId": 0,
"groupId": 0
}
],
"outputs": [
{
"id": 0,
"datasetId": 0,
"dataClass": "TfmValue"
}
],
"id": 0,
"dataMappingId": 0,
"implementation": "Hardware",
"totalFocusingMethod": {} // (5)!
}
]
}
]
- The probeId was added to each pulsers and/or receivers array items to cover more advanced cases.
- The waveformId was added to each pulsers array items to cover more advanced cases.
- The ascanStart was added to each receivers array items to cover more advanced cases.
- The ascanLength was added to each receivers array items to cover more advanced cases.
- The totalFocusingMethod parameters are now described in a dedicated process (see below).
"groups": [
{
"id": 0,
"fmc": {
"dataEncodingId": 0,
"probeId": 0,
"pulse": {
"width": 1.0000000000000001E-07,
"voltage": 40.0,
"polarity": "Bipolar"
},
"pulserFrequency": 5000000.0,
"digitizingFrequency": 80000000.0,
"pulsers": [
{
"id": 0,
"elementId": 0
},
{...}
],
"receivers": [
{
"id": 0,
"elementId": 0
},
{
"id": 1,
"elementId": 1
},
{...}
],
"tfmDescriptions": []
}
}
]
Most of the previous tfmDescriptions object properties remain unchanged in the new totalFocusingMethod object now found inside the processes array.
Property | totalFocusingMethod{} | tfmDescriptions{} | Comment |
---|---|---|---|
id [integer] | Removed as it was not necessary | ||
name [string] | Removed as it can be specified directly in the group name | ||
signalSource [string] | |||
gain [number] | |||
referenceAmplitude [number] | |||
referenceGain [number] | |||
rectangularGrid [object] | |||
fmcPulserIds [array] | |||
fmcReceiverIds [array] | |||
pathName [string] | |||
waveSet [object] | |||
digitalBandPassFilter [object] | Moved to the ultrasonicMatrixCapture processes array item | ||
columns [array] | |||
softwareProcess [object] | Moved to a dedicated tfmBoxGates processes array item |
The following shows how a version 3.3 tfmDescriptions object can be converted to a totalFocusingMethod processes array item in version 4.0:
"tfmDescriptions": [
{
"id": 0,
"name": "GR-1",
"signalSource": "Analytic",
"gain": 22.0,
"referenceAmplitude": 80.0,
"referenceGain": 0.0,
"rectangularGrid": {},
"fmcPulserIds": [],
"fmcReceiverIds": [],
"pathName": "L-L",
"waveSet": {},
"digitalBandPassFilter": {},
"softwareProcess": {
"boxGates": []
}
}
]
dataMappings¶
The dataEncodings object is renamed dataMappings to avoid confusion with other types of encoding.
The following properties need to be moved up one level in the JSON structure: specimenId and surfaceId.
The terms ScanLength
, ScanWidth
, ScanAlong
and ScanAround
used for the uCoordinatedOrientation parameter were renamed Length
, Width
, Along
and Around
respectively to remove the notion of scan axis from this parameter.
The following shows how a version 3.3 dataEncodings object can be converted to a dataMappings object in version 4.0:
probes¶
No modifications were made to this object so far. The official release of .nde 4.0 will confirm whether this object can be duplicated safely from 3.3. to 4.0.
wedges¶
No modifications were made to this object so far. The official release of .nde 4.0 will confirm whether this object can be duplicated safely from 3.3. to 4.0.
specimens¶
No modifications were made to this object so far. The official release of .nde 4.0 will confirm whether this object can be duplicated safely from 3.3. to 4.0.
acquisitionUnits¶
No modifications were made to this object so far. The official release of .nde 4.0 will confirm whether this object can be duplicated safely from 3.3. to 4.0.
motionDevices¶
Note that the unit of the stepResolution parameter was converted from step/mm to step/m in version 4.0 to be consistent with the rest of the units used in the file.
"motionDevices": [
{
"id": 0,
"name": "Glider",
"encoder": {
"mode": "Quadrature",
"stepResolution": 13000.0,
"preset": 0.0,
"acquisitionDirection": "Bidirectional"
}
},
{
"id": 1,
"name": "Glider",
"encoder": {
"mode": "Quadrature",
"stepResolution": 13000.0,
"preset": 0.0,
"acquisitionDirection": "Bidirectional"
}
}
]
"motionDevices": [
{
"id": 0,
"name": "Glider",
"encoder": {
"mode": "Quadrature",
"stepResolution": 13.0,
"preset": 0.0,
"acquisitionDirection": "Bidirectional"
}
},
{
"id": 1,
"name": "Glider",
"encoder": {
"mode": "Quadrature",
"stepResolution": 13.0,
"preset": 0.0,
"acquisitionDirection": "Bidirectional"
}
}
]