Difference between revisions of "Experimental:TDJSON"

From TouchDesigner Documentation
Jump to: navigation, search
(Created page with "=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...")
 
(Blanked the page)
(Tag: Blanking)
 
Line 1: Line 1:
=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. 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>
 
 
You can now use any of the following functions by calling:
 
 
<code>TDJ.<function name>(...)</code>
 
 
'''See also:''' [http://www.json.org/ JSON], [https://www.makeuseof.com/tag/json-laymans-overview/ JSON overview]
 
=Functions=
 
 
<!--PYHMVK jsonToText-->
 
'''<code>jsonToText(jsonObject)</code>''' &rarr; '''<code>JSON text</code>'''
 
:Return a JSON object as JSON text with tab indents for readability.
 
:* <code>jsonObject</code> - a JSONable Python object.
 
<!--PYHEND-->
 
 
<!--PYHMVK jsonToDat-->
 
'''<code>jsonToDat(jsonObject, dat)</code>'''
 
:Write a JSON object as JSON text into a dat.
 
:* <code>jsonObject</code> - a JSONable Python object.
 
:* <code>dat</code> - a DAT to be filled with the JSON text (uses jsonToText). Other text will be overwritten.
 
<!--PYHEND-->
 
 
<!--PYHMVK textToJSON-->
 
'''<code>textToJSON(text, orderedDict=True, showErrors=False)</code>''' &rarr; '''<code>JSON object or None</code>'''
 
: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>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.
 
<!--PYHEND-->
 
 
<!--PYHMVK datToJSON-->
 
'''<code>datToJSON(dat, orderedDict=True, showErrors=False)</code>''' &rarr; '''<code>JSON object or None</code>'''
 
: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>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.
 
<!--PYHEND-->
 
 
<!--PYHMVK parameterToJSONPar-->
 
'''<code>parameterToJSONPar(p, extraAttrs=None, forceAttrLists=False)</code>''' &rarr; '''<code>JSON object</code>'''
 
: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>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>forceAttrLists</code> - '''(Optional)''' If True, all attributes will be stored in a list with the length of the tuplet
 
<!--PYHEND-->
 
 
<!--PYHMVK pageToJSONDict-->
 
'''<code>pageToJSONDict(page, extraAttrs=None, forceAttrLists=False)</code>''' &rarr; '''<code>JSON object</code>'''
 
:Convert a custom page of parameters into a JSONable Python dict. Format: {parameter name: {parameter attributes, ...}, ...}
 
:* <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>forceAttrLists</code> - '''(Optional)''' If True, all attributes will be stored in a list with the length of the tuplet
 
<!--PYHEND-->
 
 
<!--PYHMVK opToJSONOp-->
 
'''<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, ...}, ...}, ...}
 
:* <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>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-->
 
 
<!--PYHMVK addParameterFromJSONDict-->
 
'''<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 object.
 
:* <code>comp</code> - the COMP to add parameters to.
 
:* <code>jsonDict</code> - the parameter JSON dict.
 
:* <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>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-->
 
 
<!--PYHMVK addParametersFromJSONList-->
 
'''<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.
 
:* <code>comp</code> - the COMP to add parameters to.
 
:* <code>jsonList</code> - the list of par JSON dicts.
 
:* <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>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-->
 
 
<!--PYHMVK addParametersFromJSONDict-->
 
'''<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.
 
:* <code>comp</code> - the COMP to add parameters to.
 
:* <code>jsonDict</code> - the dict of par JSON dicts.
 
:* <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>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-->
 
 
<!--PYHMVK addParametersFromJSONOp-->
 
'''<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>.
 
:* <code>comp</code> - the COMP to add parameters to.
 
:* <code>jsonOp</code> - the dict of page JSON dicts.
 
:* <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>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-->
 
 
<!--PYHMVK destroyOtherPagesAndParameters-->
 
'''<code>destroyOtherPagesAndParameters(comp, pageNames, parNames)</code>'''
 
:Destroys all pages and parameters on <code>comp</code> that are not found in <code>pageNames</code> or <code>parNames</code>.
 
:* <code>comp</code> - the COMP to destroy pages and parameters on.
 
:* <code>pageNames</code> - an iterable of names of pages to keep.
 
:* <code>parNames</code> - an iterable of names of pars to keep.
 
<!--PYHEND-->
 
 
<noinclude>[[Category:TD Python Modules]]</noinclude>
 
[[Category:TDPages]]
 
[[Category: Python‏‎]]
 

Latest revision as of 01:18, 20 November 2019