Difference between revisions of "TDJSON"

From TouchDesigner Documentation
Jump to: navigation, search
(updating dead tutorial links)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
=Summary=
 
=Summary=
  
The '''TDJSON''' module provides a variety of Python utility functions for JSON features in TouchDesigner. Most of the functions deal with [[Custom parameters]] and [[Page Class|Parameter Pages]], but some are good for more general use. To use TDJSON put the following line at the top of your Python script:
+
The '''TDJSON''' module provides a variety of Python utility functions for JSON features in TouchDesigner. Most of the functions deal with [[Custom parameters]] and [[Page Class|Parameter Pages]], but some are good for more general use. When the documentation below refers to a "'''JSON object'''" it means a JSONable Python object, while "JSON text" is a text representation of such an object.
 +
 
 +
To use TDJSON put the following line at the top of your Python script:
  
 
<code>TDJ = op.TDModules.mod.TDJSON</code>
 
<code>TDJ = op.TDModules.mod.TDJSON</code>
Line 9: Line 11:
 
<code>TDJ.<function name>(...)</code>
 
<code>TDJ.<function name>(...)</code>
  
'''See also:''' [http://www.json.org/ JSON], [https://www.makeuseof.com/tag/json-laymans-overview/ JSON overview]
+
'''See also:''' [[JSON]], [http://www.json.org/ JSON], [https://www.makeuseof.com/tag/json-laymans-overview/ JSON overview]
 
=Functions=
 
=Functions=
  
 
<!--PYHMVK jsonToText-->
 
<!--PYHMVK jsonToText-->
'''<code>jsonToText(jsonObject)</code>''' &rarr; '''<code>JSON text</code>'''
+
'''<code>jsonToText(jsonObject, indent='\t')</code>''' &rarr; '''<code>JSON text (from json.dumps)</code>'''
:Return a JSON object as text.
+
:Return a JSON object as JSON text with tab indents for readability.  
 
:* <code>jsonObject</code> - a JSONable Python object.
 
:* <code>jsonObject</code> - a JSONable Python object.
 +
:* <code>indent</code> - '''(Optional)''' The indent argument to json.dumps. Defaults to '\t' for readability.
 +
Set to None for default json.dumps behavior.
 
<!--PYHEND-->
 
<!--PYHEND-->
  
 
<!--PYHMVK jsonToDat-->
 
<!--PYHMVK jsonToDat-->
 
'''<code>jsonToDat(jsonObject, dat)</code>'''
 
'''<code>jsonToDat(jsonObject, dat)</code>'''
:Write a JSON object into a dat.
+
:Write a JSON object as JSON text into a dat.
 
:* <code>jsonObject</code> - a JSONable Python object.
 
:* <code>jsonObject</code> - a JSONable Python object.
:* <code>dat</code> - a DAT to be filled with the JSON object. Other text will be overwritten.
+
:* <code>dat</code> - a DAT to be filled with the JSON text (uses jsonToText). Other text will be overwritten.
 
<!--PYHEND-->
 
<!--PYHEND-->
  
 
<!--PYHMVK textToJSON-->
 
<!--PYHMVK textToJSON-->
 
'''<code>textToJSON(text, orderedDict=True, showErrors=False)</code>''' &rarr; '''<code>JSON object or None</code>'''
 
'''<code>textToJSON(text, orderedDict=True, showErrors=False)</code>''' &rarr; '''<code>JSON object or None</code>'''
:Turn a JSON object stored as text into a Python object. Returns None if conversion fails unless <code>showErrors</code> is True.
+
:Turn JSON text into a JSON Python object. Returns None if conversion fails unless <code>showErrors</code> is True.
 
:* <code>text</code> - a JSON text string.
 
:* <code>text</code> - a JSON text string.
 
:* <code>orderedDict</code> - '''(Optional)''' If True, the JSON object returned will be an OrderedDict (from core python module 'collections').
 
:* <code>orderedDict</code> - '''(Optional)''' If True, the JSON object returned will be an OrderedDict (from core python module 'collections').
Line 35: Line 39:
 
<!--PYHMVK datToJSON-->
 
<!--PYHMVK datToJSON-->
 
'''<code>datToJSON(dat, orderedDict=True, showErrors=False)</code>''' &rarr; '''<code>JSON object or None</code>'''
 
'''<code>datToJSON(dat, orderedDict=True, showErrors=False)</code>''' &rarr; '''<code>JSON object or None</code>'''
:Turn a JSON object stored as DAT text into a Python object. Returns None if conversion fails unless <code>showErrors</code> is True.
+
:Turn JSON text stored in a DAT into a JSON Python object. Returns None if conversion fails unless <code>showErrors</code> is True.
 
:* <code>dat</code> - a DAT containing a JSON text string.
 
:* <code>dat</code> - a DAT containing a JSON text string.
 
:* <code>orderedDict</code> - '''(Optional)''' if True, the JSON object returned will be an OrderedDict (from core python module 'collections').
 
:* <code>orderedDict</code> - '''(Optional)''' if True, the JSON object returned will be an OrderedDict (from core python module 'collections').
 
:* <code>showErrors</code> - '''(Optional)''' if True, raise an exception for conversion errors, otherwise return None if there is an error.
 
:* <code>showErrors</code> - '''(Optional)''' if True, raise an exception for conversion errors, otherwise return None if there is an error.
 +
<!--PYHEND-->
 +
 +
<!--PYHMVK serializeTDData-->
 +
'''<code>serializeTDData(data, verbose=True)</code>''' &rarr; '''<code>standardized serializable format or repr(data) if not of type listed or int, float, str, long, bool, None</code>'''
 +
:Return a serializable value for a piece of TD data. Standardizes serialized
 +
format for TD types OP, Cell, Channel, Page, Par, ParMode.
 +
:* <code>data</code> - anything
 +
:* <code>verbose</code> - '''(Optional)''' if True, provide extra details for Cell, Channel, Page, Par
 
<!--PYHEND-->
 
<!--PYHEND-->
  
 
<!--PYHMVK parameterToJSONPar-->
 
<!--PYHMVK parameterToJSONPar-->
'''<code>parameterToJSONPar(p, extraAttrs=None)</code>''' &rarr; '''<code>JSON object</code>'''
+
'''<code>parameterToJSONPar(p, extraAttrs=None, forceAttrLists=False)</code>''' &rarr; '''<code>JSON object</code>'''
:Convert a parameter or tuplet to a jsonable python dictionary. '''NOTE''': a parameter that is a member of a multi-value tuplet will create a JSON object for the entire tuplet.
+
:Convert a custom parameter or tuplet to a JSONable Python dict. '''NOTE''': a parameter that is a member of a multi-value tuplet will create a JSON object for the entire tuplet.
 
:* <code>p</code> - the parameter to convert.
 
:* <code>p</code> - the parameter to convert.
:* <code>extraAttrs</code> - '''(Optional)''' a list or tuple of attribute names that are not normally stored as part of a parameter's definition e.g. 'val' and 'order'.
+
:* <code>extraAttrs</code> - '''(Optional)''' a list or tuple of attribute names that are not normally stored as part of a parameter's definition e.g. 'val' and 'order'. Use 'eval' to store the current eval() in the 'val' attribute. Can also be a string: '*' indicating all properties of the parameter.
 +
:* <code>forceAttrLists</code> - '''(Optional)''' If True, all attributes will be stored in a list with the length of the tuplet
 
<!--PYHEND-->
 
<!--PYHEND-->
  
 
<!--PYHMVK pageToJSONDict-->
 
<!--PYHMVK pageToJSONDict-->
'''<code>pageToJSONDict(page, extraAttrs=None)</code>''' &rarr; '''<code>JSON object</code>'''
+
'''<code>pageToJSONDict(page, extraAttrs=None, forceAttrLists=False)</code>''' &rarr; '''<code>JSON object</code>'''
:Convert a page of parameters to a jsonable python dict. Format: {parameter name: {parameter attributes, ...}, ...}
+
:Convert a custom page of parameters into a JSONable Python dict. Format: {parameter name: {parameter attributes, ...}, ...}
 
:* <code>page</code> - the page to convert.
 
:* <code>page</code> - the page to convert.
:* <code>extraAttrs</code> - '''(Optional)''' a list or tuple of attribute names that are not normally stored as part of a parameter's definition e.g. 'val' and 'order'.
+
:* <code>extraAttrs</code> - '''(Optional)''' a list or tuple of attribute names that are not normally stored as part of a parameter's definition e.g. 'val' and 'order'. Can also be a string: '*' indicating all properties of the parameter.
 +
:* <code>forceAttrLists</code> - '''(Optional)''' If True, all attributes will be stored in a list with the length of the tuplet
 
<!--PYHEND-->
 
<!--PYHEND-->
  
 
<!--PYHMVK opToJSONOp-->
 
<!--PYHMVK opToJSONOp-->
'''<code>opToJSONOp(op, extraAttrs=None)</code>''' &rarr; '''<code>JSON object</code>'''
+
'''<code>opToJSONOp(op, extraAttrs=None, forceAttrLists=False, includeCustomPages=True, includeBuiltInPages=False)</code>''' &rarr; '''<code>JSON object</code>'''
:Convert all custom parameter pages to a jsonable python dict. Format: {page name: {parameter name: {parameter attributes, ...}, ...}, ...}
+
:Convert all custom parameter pages to a JSONable python dict. Format: {page name: {parameter name: {parameter attributes, ...}, ...}, ...}
 
:* <code>op</code> - the OP to convert.
 
:* <code>op</code> - the OP to convert.
:* <code>extraAttrs</code> - '''(Optional)''' a list or tuple of attribute names that are not normally stored as part of a parameter's definition e.g. 'val' and 'order'.
+
:* <code>extraAttrs</code> - '''(Optional)''' a list or tuple of attribute names that are not normally stored as part of a parameter's definition e.g. 'val' and 'order'. Can also be a string: '*' indicating all properties of the parameter.
 +
:* <code>forceAttrLists</code> - '''(Optional)''' If True, all attributes will be stored in a list with the length of the tuplet
 +
:* <code>includeCustomPages</code> - '''(Optional)''' If True, include custom par pages
 +
:* <code>includeBuiltInPages</code> - '''(Optional)''' If True, include builtin pages
 
<!--PYHEND-->
 
<!--PYHEND-->
  
 
<!--PYHMVK addParameterFromJSONDict-->
 
<!--PYHMVK addParameterFromJSONDict-->
'''<code>addParameterFromJSONDict(comp, jsonDict, replace=True, setValues=True, ignoreAttrErrors=False)</code>''' &rarr; '''<code>list of newly created pars</code>'''
+
'''<code>addParameterFromJSONDict(comp, jsonDict, replace=True, setValues=True, ignoreAttrErrors=False, fixParNames=True)</code>''' &rarr; '''<code>list of newly created pars</code>'''
:Add a parameter to <code>comp</code> as defined in a parameter JSON dict.
+
:Add a parameter to <code>comp</code> as defined in a parameter JSON object. To set values, expressions, or bind expressions, provide 'val', 'expr', or 'bindExpr' in JSON.
 
:* <code>comp</code> - the COMP to add parameters to.
 
:* <code>comp</code> - the COMP to add parameters to.
 
:* <code>jsonDict</code> - the parameter JSON dict.
 
:* <code>jsonDict</code> - the parameter JSON dict.
 
:* <code>replace</code> - '''(Optional)''' If False, will cause exception if a parameter already exists.
 
:* <code>replace</code> - '''(Optional)''' If False, will cause exception if a parameter already exists.
:* <code>setValues</code> - '''(Optional)''' If True, values will be set to parameter's defaults, whether parameter already existed or not.
+
:* <code>setValues</code> - '''(Optional)''' If True, values will be set to parameter's defaults if no "val" member is provided.
 
:* <code>ignoreAttrErrors</code> - '''(Optional)''' If True, no exceptions will be raised for invalid attributes in the JSON.
 
:* <code>ignoreAttrErrors</code> - '''(Optional)''' If True, no exceptions will be raised for invalid attributes in the JSON.
 +
:* <code>fixParNames</code> - '''(Optional)''' If True, force correct capitalization.
 
<!--PYHEND-->
 
<!--PYHEND-->
  
 
<!--PYHMVK addParametersFromJSONList-->
 
<!--PYHMVK addParametersFromJSONList-->
'''<code>addParametersFromJSONList(comp, jsonList, replace=True, setValues=True, destroyOthers=False)</code>'''
+
'''<code>addParametersFromJSONList(comp, jsonList, replace=True, setValues=True, destroyOthers=False, newAtEnd=True, fixParNames=True)</code>'''
 
:Add parameters to <code>comp</code> as defined in list of parameter JSON dicts.
 
:Add parameters to <code>comp</code> as defined in list of parameter JSON dicts.
 
:* <code>comp</code> - the COMP to add parameters to.
 
:* <code>comp</code> - the COMP to add parameters to.
Line 80: Line 98:
 
:* <code>setValues</code> - '''(Optional)''' If True, values will be set to parameter's defaults, whether parameter already existed or not.
 
:* <code>setValues</code> - '''(Optional)''' If True, values will be set to parameter's defaults, whether parameter already existed or not.
 
:* <code>destroyOthers</code> - '''(Optional)''' If True, pars and pages not in jsonList will be destroyed
 
:* <code>destroyOthers</code> - '''(Optional)''' If True, pars and pages not in jsonList will be destroyed
 +
:* <code>newAtEnd</code> - '''(Optional)''' If True, new parameters will be sorted to end of page. This should generally be False if you are using 'order' attribute in JSON
 +
:* <code>fixParNames</code> - '''(Optional)''' If True, force correct capitalization.
 
<!--PYHEND-->
 
<!--PYHEND-->
  
 
<!--PYHMVK addParametersFromJSONDict-->
 
<!--PYHMVK addParametersFromJSONDict-->
'''<code>addParametersFromJSONDict(comp, jsonDict, replace=True, setValues=True, destroyOthers=False)</code>'''
+
'''<code>addParametersFromJSONDict(comp, jsonDict, replace=True, setValues=True, destroyOthers=False, newAtEnd=True, fixParNames=True)</code>'''
 
:Add parameters to <code>comp</code> as defined in dict of parameter JSON dicts.
 
:Add parameters to <code>comp</code> as defined in dict of parameter JSON dicts.
 
:* <code>comp</code> - the COMP to add parameters to.
 
:* <code>comp</code> - the COMP to add parameters to.
Line 90: Line 110:
 
:* <code>setValues</code> - '''(Optional)''' If True, values will be set to parameter's defaults, whether parameter already existed or not.
 
:* <code>setValues</code> - '''(Optional)''' If True, values will be set to parameter's defaults, whether parameter already existed or not.
 
:* <code>destroyOthers</code> - '''(Optional)''' If True, pars and pages not in jsonDict will be destroyed
 
:* <code>destroyOthers</code> - '''(Optional)''' If True, pars and pages not in jsonDict will be destroyed
 +
:* <code>newAtEnd</code> - '''(Optional)''' If True, new parameters will be sorted to end of page. This should generally be False if you are using 'order' attribute in JSON
 +
:* <code>fixParNames</code> - '''(Optional)''' If True, force correct capitalization.
 
<!--PYHEND-->
 
<!--PYHEND-->
  
 
<!--PYHMVK addParametersFromJSONOp-->
 
<!--PYHMVK addParametersFromJSONOp-->
'''<code>addParametersFromJSONOp(comp, jsonOp, replace=True, setValues=True, destroyOthers=False)</code>'''
+
'''<code>addParametersFromJSONOp(comp, jsonOp, replace=True, setValues=True, destroyOthers=False, newAtEnd=True, fixParNames=True)</code>'''
 
:Add parameters to <code>comp</code> as defined in dict of page JSON dicts ala <code>opToJSONOp</code>.
 
:Add parameters to <code>comp</code> as defined in dict of page JSON dicts ala <code>opToJSONOp</code>.
 
:* <code>comp</code> - the COMP to add parameters to.
 
:* <code>comp</code> - the COMP to add parameters to.
Line 100: Line 122:
 
:* <code>setValues</code> - '''(Optional)''' If True, values will be set to parameter's defaults, whether parameter already existed or not.
 
:* <code>setValues</code> - '''(Optional)''' If True, values will be set to parameter's defaults, whether parameter already existed or not.
 
:* <code>destroyOthers</code> - '''(Optional)''' If True, pars and pages not in jsonOp will be destroyed
 
:* <code>destroyOthers</code> - '''(Optional)''' If True, pars and pages not in jsonOp will be destroyed
 +
:* <code>newAtEnd</code> - '''(Optional)''' If True, new parameters will be sorted to end of page. This should generally be False if you are using 'order' attribute in JSON
 +
:* <code>fixParNames</code> - '''(Optional)''' If True, force correct capitalization.
 
<!--PYHEND-->
 
<!--PYHEND-->
  

Latest revision as of 19:02, 11 April 2020

Summary[edit]

The TDJSON module provides a variety of Python utility functions for JSON features in TouchDesigner. Most of the functions deal with Custom parameters and Parameter Pages, but some are good for more general use. When the documentation below refers to a "JSON object" it means a JSONable Python object, while "JSON text" is a text representation of such an object.

To use TDJSON put the following line at the top of your Python script:

TDJ = op.TDModules.mod.TDJSON

You can now use any of the following functions by calling:

TDJ.<function name>(...)

See also: JSON, JSON, JSON overview

Functions[edit]

jsonToText(jsonObject, indent='\t')JSON text (from json.dumps)

Return a JSON object as JSON text with tab indents for readability.
  • jsonObject - a JSONable Python object.
  • indent - (Optional) The indent argument to json.dumps. Defaults to '\t' for readability.

Set to None for default json.dumps behavior.

jsonToDat(jsonObject, dat)

Write a JSON object as JSON text into a dat.
  • jsonObject - a JSONable Python object.
  • dat - a DAT to be filled with the JSON text (uses jsonToText). Other text will be overwritten.

textToJSON(text, orderedDict=True, showErrors=False)JSON object or None

Turn JSON text into a JSON Python object. Returns None if conversion fails unless showErrors is True.
  • text - a JSON text string.
  • orderedDict - (Optional) If True, the JSON object returned will be an OrderedDict (from core python module 'collections').
  • showErrors - (Optional) if True, raise an exception for conversion errors, otherwise return None if there is an error.

datToJSON(dat, orderedDict=True, showErrors=False)JSON object or None

Turn JSON text stored in a DAT into a JSON Python object. Returns None if conversion fails unless showErrors is True.
  • dat - a DAT containing a JSON text string.
  • orderedDict - (Optional) if True, the JSON object returned will be an OrderedDict (from core python module 'collections').
  • showErrors - (Optional) if True, raise an exception for conversion errors, otherwise return None if there is an error.

serializeTDData(data, verbose=True)standardized serializable format or repr(data) if not of type listed or int, float, str, long, bool, None

Return a serializable value for a piece of TD data. Standardizes serialized

format for TD types OP, Cell, Channel, Page, Par, ParMode.

  • data - anything
  • verbose - (Optional) if True, provide extra details for Cell, Channel, Page, Par

parameterToJSONPar(p, extraAttrs=None, forceAttrLists=False)JSON object

Convert a custom parameter or tuplet to a JSONable Python dict. NOTE: a parameter that is a member of a multi-value tuplet will create a JSON object for the entire tuplet.
  • p - the parameter to convert.
  • extraAttrs - (Optional) a list or tuple of attribute names that are not normally stored as part of a parameter's definition e.g. 'val' and 'order'. Use 'eval' to store the current eval() in the 'val' attribute. Can also be a string: '*' indicating all properties of the parameter.
  • forceAttrLists - (Optional) If True, all attributes will be stored in a list with the length of the tuplet

pageToJSONDict(page, extraAttrs=None, forceAttrLists=False)JSON object

Convert a custom page of parameters into a JSONable Python dict. Format: {parameter name: {parameter attributes, ...}, ...}
  • page - the page to convert.
  • extraAttrs - (Optional) a list or tuple of attribute names that are not normally stored as part of a parameter's definition e.g. 'val' and 'order'. Can also be a string: '*' indicating all properties of the parameter.
  • forceAttrLists - (Optional) If True, all attributes will be stored in a list with the length of the tuplet

opToJSONOp(op, extraAttrs=None, forceAttrLists=False, includeCustomPages=True, includeBuiltInPages=False)JSON object

Convert all custom parameter pages to a JSONable python dict. Format: {page name: {parameter name: {parameter attributes, ...}, ...}, ...}
  • op - the OP to convert.
  • extraAttrs - (Optional) a list or tuple of attribute names that are not normally stored as part of a parameter's definition e.g. 'val' and 'order'. Can also be a string: '*' indicating all properties of the parameter.
  • forceAttrLists - (Optional) If True, all attributes will be stored in a list with the length of the tuplet
  • includeCustomPages - (Optional) If True, include custom par pages
  • includeBuiltInPages - (Optional) If True, include builtin pages

addParameterFromJSONDict(comp, jsonDict, replace=True, setValues=True, ignoreAttrErrors=False, fixParNames=True)list of newly created pars

Add a parameter to comp as defined in a parameter JSON object. To set values, expressions, or bind expressions, provide 'val', 'expr', or 'bindExpr' in JSON.
  • comp - the COMP to add parameters to.
  • jsonDict - the parameter JSON dict.
  • replace - (Optional) If False, will cause exception if a parameter already exists.
  • setValues - (Optional) If True, values will be set to parameter's defaults if no "val" member is provided.
  • ignoreAttrErrors - (Optional) If True, no exceptions will be raised for invalid attributes in the JSON.
  • fixParNames - (Optional) If True, force correct capitalization.

addParametersFromJSONList(comp, jsonList, replace=True, setValues=True, destroyOthers=False, newAtEnd=True, fixParNames=True)

Add parameters to comp as defined in list of parameter JSON dicts.
  • comp - the COMP to add parameters to.
  • jsonList - the list of par JSON dicts.
  • replace - (Optional) If False, will cause exception if a parameter already exists.
  • setValues - (Optional) If True, values will be set to parameter's defaults, whether parameter already existed or not.
  • destroyOthers - (Optional) If True, pars and pages not in jsonList will be destroyed
  • newAtEnd - (Optional) If True, new parameters will be sorted to end of page. This should generally be False if you are using 'order' attribute in JSON
  • fixParNames - (Optional) If True, force correct capitalization.

addParametersFromJSONDict(comp, jsonDict, replace=True, setValues=True, destroyOthers=False, newAtEnd=True, fixParNames=True)

Add parameters to comp as defined in dict of parameter JSON dicts.
  • comp - the COMP to add parameters to.
  • jsonDict - the dict of par JSON dicts.
  • replace - (Optional) If False, will cause exception if a parameter already exists.
  • setValues - (Optional) If True, values will be set to parameter's defaults, whether parameter already existed or not.
  • destroyOthers - (Optional) If True, pars and pages not in jsonDict will be destroyed
  • newAtEnd - (Optional) If True, new parameters will be sorted to end of page. This should generally be False if you are using 'order' attribute in JSON
  • fixParNames - (Optional) If True, force correct capitalization.

addParametersFromJSONOp(comp, jsonOp, replace=True, setValues=True, destroyOthers=False, newAtEnd=True, fixParNames=True)

Add parameters to comp as defined in dict of page JSON dicts ala opToJSONOp.
  • comp - the COMP to add parameters to.
  • jsonOp - the dict of page JSON dicts.
  • replace - (Optional) If False, will cause exception if a parameter already exists.
  • setValues - (Optional) If True, values will be set to parameter's defaults, whether parameter already existed or not.
  • destroyOthers - (Optional) If True, pars and pages not in jsonOp will be destroyed
  • newAtEnd - (Optional) If True, new parameters will be sorted to end of page. This should generally be False if you are using 'order' attribute in JSON
  • fixParNames - (Optional) If True, force correct capitalization.

destroyOtherPagesAndParameters(comp, pageNames, parNames)

Destroys all pages and parameters on comp that are not found in pageNames or parNames.
  • comp - the COMP to destroy pages and parameters on.
  • pageNames - an iterable of names of pages to keep.
  • parNames - an iterable of names of pars to keep.

An Operator Family that manipulates text strings: multi-line text or tables. Multi-line text is often a command Script, but can be any multi-line text. Tables are rows and columns of cells, each containing a text string.

Any of the procedural data operators. OPs do all the work in TouchDesigner. They "cook" and output data to other OPs, which ultimately result in new images, data and audio being generated. See Node.

A CHOP outputs one or more channels, where a channel is simply a sequence of numbers, representing motion, audio, etc. Channels are passed between CHOPs in TouchDesigner networks. See also Export.

An Operator Family that contains its own Network inside. There are twelve 3D Object Component and eight 2D Panel Component types. See also Network Path.