{"type":"doc","content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"3"},"outline":{"value":"false"},"type":{"value":"list"},"printable":{"value":"false"}},"macroMetadata":{"macroId":{"value":"07734fc5-e8ef-4208-a8b9-90146bbac7c7"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"2ced2ce4-12be-4c6f-9e1c-4b62f0207d7b"}},{"type":"paragraph"},{"type":"bodiedExtension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"excerpt","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"e6b0f6038f02d5ab40555da0096d1103"},"schemaVersion":{"value":"1"},"title":"Excerpt"}},"localId":"210a95fe-e353-48df-8bb5-bae394e4e929"},"content":[{"type":"paragraph","content":[{"text":"This document describes how to write Python 3 applications using Vortex Studio SDK.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Python Usage and Environment Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"You can use your preferred integrated development environment (IDE) to work with Python.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"The only restriction is that the supported Python version is Python 3.8. The default interpreter currently bundled with Vortex Studio is 3.8.6.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Please note that due to the way the Vortex Python module is generated from C++, automatic completion features of IDEs may not always work with some Vortex Objects.","type":"text"}]},{"type":"paragraph","content":[{"text":"Vortex Content might have been created within the Vortex Studio Editor or by code, be it C++ or even Python","type":"text"}]},{"type":"paragraph","content":[{"text":"To use Vortex SDK in Python, there is only one Python module: ","type":"text"},{"text":"Vortex.py","type":"text","marks":[{"type":"strong"}]},{"text":". ","type":"text"}]},{"type":"paragraph","content":[{"text":"The module is located in C:\\CM Labs\\Vortex Studio #versionnumber\\bin.","type":"text"}]},{"type":"paragraph","content":[{"text":"Once ","type":"text"},{"text":"PYTHONPATH","type":"text","marks":[{"type":"code"}]},{"text":"is updated with the path of Vortex.py, the developer simply needs to import the Vortex library.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Everything is Vortex in Python e.g. C++ ","type":"text"},{"text":"VxContent::Scene","type":"text","marks":[{"type":"code"}]},{"text":" becomes ","type":"text"},{"text":"Vortex.Scene, ","type":"text","marks":[{"type":"code"}]},{"text":"VxMath::Matrix44 becomes","type":"text"},{"text":" Vortex.Matrix44 ","type":"text","marks":[{"type":"code"}]},{"text":"etc...","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The command ","type":"text"},{"text":"dir","type":"text","marks":[{"type":"code"}]},{"text":"() or ","type":"text"},{"text":"dir","type":"text","marks":[{"type":"code"}]},{"text":"(object) will list the module content and the object methods.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Help","type":"text","marks":[{"type":"code"}]},{"text":"(object) will provide more information on one object in particular.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Python HTML doc generation using ","type":"text"},{"text":"pydoc","type":"text","marks":[{"type":"code"}]},{"text":": ","type":"text"},{"text":"python -m pydoc -w Vortex","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Vortex Studio SDK container-like classes support ","type":"text"},{"text":"len()","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"operator[]","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Import Vortex","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"import Vortex\n \ns = Vortex.Scene.create()\n\nm = Vortex.Matrix44() \nr = len(m) # r = 4\nc = len(m[0]) # c = 4","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How to set PythonPath when using Vortex.py","type":"text"}]},{"type":"paragraph","content":[{"text":"PythonPath must be extended with the path pointing to the binaries of Vortex Studio.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following are example on how to set ","type":"text"},{"text":"PYTHONPATH","type":"text","marks":[{"type":"code"}]},{"text":" with Vortex Studio : ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"open a command line and enter ","type":"text"},{"text":"set PYTHONPATH=%VORTEXPATH%\\bin;%PYTHONPATH%","type":"text","marks":[{"type":"code"}]},{"text":" before starting python.exe ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"inside a python terminal, update sys.path ","type":"text"},{"text":"import sys; sys.path.append('VORTEXPATH\\bin')","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"inside VsCode, add the following line to the .env file ","type":"text"},{"text":"PYTHONPATH=VORTEXPATH\\bin","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"paragraph","content":[{"text":"Please refer to the documentation of Python 3 to define the appropriate ","type":"text"},{"text":"PYTHONPATH","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"paragraph","content":[{"text":"When using a VxApplication within a Python process and that application will be loading content that contains Dynamics Script Extension, the Interpreter Directory must be the same as the starting Python process.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"import sys\nimport Vortex\n\nmyApp = Vortex.VxApplication()\n\n# Create a setup \nsetup = Vortex.ApplicationConfig.create()\n\n#Set the interpreterDirectory to the same that launched this script\nsetup.parameterPython3.interpreterDirectory.value = sys.exec_prefix \n\n# add other modules to setup \n...\nsetup.apply(myApp)\n\n","type":"text"}]},{"type":"paragraph"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Vortex SDK - Python specificities","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Property ","type":"text"},{"text":".value","type":"text","marks":[{"type":"code"}]}]},{"type":"paragraph","content":[{"text":"In extensions, the inputs, outputs, and parameters are known as fields. ","type":"text"}]},{"type":"paragraph","content":[{"text":"Fields can be accessed in several ways:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In a generic way, via methods ","type":"text"},{"text":"getInput","type":"text","marks":[{"type":"code"}]},{"text":"/","type":"text"},{"text":"getOutput","type":"text","marks":[{"type":"code"}]},{"text":"/","type":"text"},{"text":"getParameter","type":"text","marks":[{"type":"code"}]},{"text":" of any ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":". e.g. extension.getInput('Int').value","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In a specific way via the interface. e.g part.inputControlType.value","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"In a specific way within a ","type":"text"},{"text":"dynamics script extension","type":"text","marks":[{"type":"em"}]},{"text":", using ","type":"text"},{"text":"extension","type":"text","marks":[{"type":"code"}]},{"text":". e.g. extension.inputs.myInt.value","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The value of a Field can be read or written using the Python property \"","type":"text"},{"text":"value\"","type":"text","marks":[{"type":"code"}]},{"text":", a generic accessor that implicitly performs type conversion, which was added in the Vortex Python API. ","type":"text"}]},{"type":"paragraph","content":[{"text":"If the field is an integer, the property \"","type":"text"},{"text":"value\"","type":"text","marks":[{"type":"code"}]},{"text":" will be an integer. If the field is a reference to an Interface e.g ","type":"text"},{"text":"Field","type":"text","marks":[{"type":"code"}]},{"text":" interface, the property \"","type":"text"},{"text":"value\"","type":"text","marks":[{"type":"code"}]},{"text":" will return that interface e.g. ","type":"text"},{"text":"AssemblyInterface","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":".value Property","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# The input is an int\nextension.getInput('Int').value = 8\n \n# The output is a VxVector3, extract x from VxVector3\nx = extension.getOutput('Vector3').value.x\n \n# The Parameter is an Field\nextension.getParameter('Assembly').value.addPart(part)","type":"text"}]},{"type":"paragraph","content":[{"text":"Section","type":"text"},{"text":" Set/Get Values on Inputs, Outputs, and Parameters of a dynamics script extension","type":"text","marks":[{"type":"em"}]},{"text":" below contains additional examples.","type":"text"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Setting value on vector using accessors","type":"text"}]},{"type":"paragraph","content":[{"text":".value cannot be used in combination with any accessor to assigned a value. E.g., input.value.x = 1 won't work, one should use input.value = VxVector3(1,1,1)","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Object Interfaces","type":"text"}]},{"type":"paragraph","content":[{"text":"The Vortex API exposes each Content Objects in Python using either their base type or their specialized types:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Base Content type objects: ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Scene -> ","type":"text"},{"text":"SceneInterface","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"C","type":"text","marks":[{"type":"code"}]},{"text":"onfiguration ->","type":"text"},{"text":" ConfigurationInterface","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ConnectionContainer->","type":"text"},{"text":" ConnectionContainerInterface","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"VxVHLInterface -> ","type":"text"},{"text":"VxVHLInterfaceInterface","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Mechanism -> ","type":"text"},{"text":"MechanismInterface","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Assembly -> AssemblyInterface","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Part -> ","type":"text"},{"text":"PartInterface","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Constraint -> ","type":"text"},{"text":"ConstraintInterface","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"CollisionGeometry -> ","type":"text"},{"text":"CollisionGeometryInterface","type":"text","marks":[{"type":"code"}]},{"type":"hardBreak"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Specialized Content objects that inherit from one of the base content types: ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"prismatic constraint -> ","type":"text"},{"text":"PrismaticInterface","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"hinge constraint -> ","type":"text"},{"text":"HingeInterface","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"sphere cg -> ","type":"text"},{"text":"SphereInterface","type":"text","marks":[{"type":"code"}]}]}]}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Converting Interfaces","type":"text"}]},{"type":"paragraph","content":[{"text":"Interface conversion is explicit. Base class objects can be converted to specialized objects using the right interface constructor.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Explicit Conversion","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# Getting the HingeInterface from a ConstraintInterface\nhinge = Vortex.HingeInterface(constraint.getExtension()) #constraint is a ConstraintInterface of an hinge.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Base Constraints Interface (or ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":" of constraints) can also be converted to the right Interface using ","type":"text"},{"text":"Constraint.getConstraintInterface(constraint)","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Base Collision Geometry (or ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":" of collision geometry) can also be converted to the right Interface using ","type":"text"},{"text":"CollisionGeometry.getCollisionGeometryInterface(cg)","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"paragraph","content":[{"text":"Most content objects have an interface version in Python. When they are not available, just use the ","type":"text"},{"text":"VxExtensionFactory","type":"text","marks":[{"type":"code"}]},{"text":" and work with the ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":" in a generic way.","type":"text"}]},{"type":"paragraph","content":[{"text":"Custom Interfaces developed by clients will not have Python Interface objects.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"code snippet - creating an object","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"from Vortex import *\n...\n# Create and setup the application\n...\n# using create function from the Part class\npart= Part.create() # part type is PartInterface\npart.setName(partName)\n\n# update partDef\nbox = Box.create() # box type is BoxInterface\n \n# Part.addCollisionGeometry accepts BoxInterfaces\npart.addCollisionGeometry(box) #part.addCollisionGeometry accepts CollisionGeometryInterface as well as all Interface objects\n \n# Contrary to C++, Python VxApplication.add() accepts VxExtension rather than Interfaces. Use getExtension() on the interface object to get it\napplication.add(part.getExtension())\n\n...\n# Working with CGs\n# Part.getCollisionGeometries() returns an array of CollisionGeometryInterface, getting the proper cg type require a conversion\ncg_0 = part.getCollisionGeometries()[0]\n \n# To use the cg_0 as a Box, convert to a BoxInterface with getCollisionGeometryInterface using the VxExtension of the CollisionGeometryInterface\nbox = CollisionGeometry.getCollisionGeometryInterface( cg_0 ) # Since cgs_0 is a box, getCollisionGeometryInterface() returns a BoxInterface\n \n# This is equivalent of doing\n# box = BoxInterface( cg_0.getExtension() ) ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"IMobile and transformation Matrix","type":"text"}]},{"type":"paragraph","content":[{"text":"Content objects that can be moved are derived from the ","type":"text"},{"text":"IMobile","type":"text","marks":[{"type":"code"}]},{"text":" interface. ","type":"text"},{"text":"IMobileInterface","type":"text","marks":[{"type":"code"}]},{"text":" objects can be moved with using method ","type":"text"},{"text":"setLocalTransform","type":"text","marks":[{"type":"code"}]},{"text":", which takes ","type":"text"},{"text":"Vortex.Matrix44","type":"text","marks":[{"type":"code"}]},{"text":" object describing the transformation in terms of scale, rotation and translation.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"IMobile","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# get the output transform from a PartInterface object\noutput_transform = part.outputWorldTransform.value\n \n# get position and orientation of the part as Vortex.VxVector3\nposition = Vortex.getTranslation(output_transform.value)\norientation = Vortex.getRotation(output_transform.value)\n \n# move the part\n# set the input local transform\nnew_position = Vortex.VxVector3(1,1,1)\npart.setLocalTransform( Vortex.translateTo(output_transform.value, new_position) ) # prefer using setLocalTransform over Field inputLocalTransform.value","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"VxMath::Transformation","type":"text","marks":[{"type":"textColor","attrs":{"color":"#707070"}}]}]},{"type":"paragraph","content":[{"text":"A series of global helpers exist at the Vortex level to simplify matrix computation. They are the equivalent of the C++ Global helpers in the namespace","type":"text"},{"text":" VxMath::Transformation.","type":"text","marks":[{"type":"code"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Transformation helpers","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# Scale, Rotation and Translation Matrix Constructor\nm = Vortex.createScale(x,y,z) # Create a scale matrix.\nm = Vortex.createScale(scale) # Create a scale matrix from VxVector3.\nm = Vortex.createRotation(rx, ry, rz) # Creates a rotation matrix. rx, ry and rz are Euler angles given in radian, using the default Euler order\nm = Vortex.createRotation(axis, angle) # Creates a rotation matrix from an axis (VxVector3) and angle (radian).\nm = Vortex.createRotation(quat) # Creates a rotation matrix from a quaternion\nm = Vortex.createRotationFromOuterProduct(v, w) # Creates a rotation matrix from the outer product of two 3 dimensions vectors.\nm = Vortex.createTranslation(tx, ty, tz) # Creates a translation matrix.\nm = Vortex.createTranslation(translation) # Creates a translation matrix from VxVector3.\n\n# Creates a transform matrix with a position sets to the eye and oriented to the center. \n# The first component of the matrix is the forward vector, the second one is the side vector and the third is the up.\nm = Vortex.createObjectLookAt(eye, center, up)\n \n# The first component of the matrix is the side-way vector, the second one is the up vector and the third is pointing backward to the center.\nm = Vortex.createCameraLookAt(eye, center, up)\n\n# Creates an orthographic projection matrix.\nm = Vortex.createOrthographic(left, right, bottom, top, zNear, zFar)\n \n# Creates a non-regular projection frustum.\nm = Vortex.createFrustum(left, right, bottom, top, zNear, zFar)\n \n# Creates a regular perspective projection frustum.\nm = Vortex.createPerspective(fovy, aspectRatio, zNear, zFar)\n\n# Extraction helpers\ns = Vortex.getScale(m) # Get Scale VxVector3 from Matrix44\nr = Vortex.getRotation(m) # Get Rotation VxVector3 from Matrix44\nt = Vortex.getTranslation(m) # Get Translation VxVector3 from Matrix44\n\n# Checks whether this matrix includes a perspective projection.\nb = Vortex.isPerspectiveProjection(m)\n\n# Affine Matrix operation\nmt = Vortex.translateTo(m, translation) # Sets translation VxVector3 on m\nmr = Vortex.rotateTo(m, rotation) # Sets rotation VxVector3 on m\nms = Vortex.scaleTo(m, scale) # Sets scale VxVector3 on m\nm = Vortex.compose(scale, rotation, translation, flip) # Creates a matrix by composition with a VxVector3 scaling, then a VxVector3 rotation and a VxVector3 translation.\nscale, rotation, translation, flip = Vortex.decompose(m) # Decomposes the affine matrix m into a scale, rotation and translation matrix. Rotation are given in the range [-pi, pi] for x, [-pi/2, pi/2] for y, [-pi, pi] for z.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Accessing Application Context","type":"text"}]},{"type":"paragraph","content":[{"text":"To get information relative to the application context, use ","type":"text"},{"text":"getApplicationContext()","type":"text","marks":[{"type":"code"}]},{"text":". The method is available via any ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"extension","type":"text","marks":[{"type":"code"}]},{"text":" in the case of a ","type":"text"},{"text":"dynamics script extension","type":"text","marks":[{"type":"em"}]},{"text":". Application context API is relatively simple and can be used for time/frame-based related logic. Application context methods are also available directly from the ","type":"text"},{"text":"VxApplication","type":"text","marks":[{"type":"code"}]},{"text":" . e.g. .getSimulationFrameRate(), although the context itself can otherwise be accessed from a ","type":"text"},{"text":"VxApplication","type":"text","marks":[{"type":"code"}]},{"text":" using method ","type":"text"},{"text":"getContext()","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".getApplicationContext().getSimulationFrameRate() # Frame rate e.g. 60 means 60 fps","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".getApplicationContext().getSimulationTimeStep() # Time of a step. Is the inverse of frame rate e.g. Frame Rate = 60, Time Step = 1/60 = 0.016666","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".getApplicationContext().getSimulationTime() # Current Time of the simulation. Time increases by Time step every frame.","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".getApplicationContext().getFrame() # Current Frame of the simulation","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".getApplicationContext().getApplicationMode() # Current Simulation mode i.e. KEditingMode, kSimulatingMode or kPlaybackMode","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".getApplicationContext().isPaused() # Indicates if the simulation is paused","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":".getApplicationContext().isSimulationRunning() # Indicates if the Simulation is running i.e. ApplicationMode is kSimulatingMode And isPaused == False","type":"text","marks":[{"type":"subsup","attrs":{"type":"sup"}}]}]}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Application Scripting","type":"text"}]},{"type":"paragraph","content":[{"text":"Python can be used for prototyping, tests (some of Vortex internal tests are written with Python), or a complete Vortex Application. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The concept is no different than what is described in the section ","type":"text"},{"text":"Making a Vortex Application","type":"text","marks":[{"type":"link","attrs":{"href":"https://vortexstudio.atlassian.net/wiki/spaces/VSD2502/pages/3985966977"}}]},{"text":". The difference is that the application is started in Python.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Creating a VxApplication","type":"text"}]},{"type":"paragraph","content":[{"text":"The first step is to create an application and set it up. Use the ","type":"text"},{"text":"Vortex Studio Editor","type":"text","marks":[{"type":"em"}]},{"text":" to create its Application Setup. Then it is simply a matter of loading the setup to apply it.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Setting up an application","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"from Vortex import *\napplication = VxApplication()\nserializer = ApplicationConfigSerializer()\n \nserializer.load('myconfig.vxc')\n\n# Extract the ApplicationConfig\nconfig = serializer.getApplicationConfig()\n \n# Apply it\nconfig.apply(application)\n...\n# Load Content\n...\n# Run the application\n... \n# Unload Content\n...\n# Cleanup\napplication = None","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that like in C++, it is possible to insert and remove modules and extensions manually to the application as well as set up some application parameters.","type":"text"}]},{"type":"paragraph","content":[{"text":"Likewise, it is possible to create an ","type":"text"},{"text":"ApplicationConfig","type":"text","marks":[{"type":"code"}]},{"text":" object in Python. However, not all modules and extensions factory keys and the ","type":"text"},{"text":"VxID","type":"text","marks":[{"type":"code"}]},{"text":" to its parameters are exposed in Python. ","type":"text"},{"type":"hardBreak"},{"text":"Although it is technically possible to create a valid application setup in Python, the user is encouraged to use the ","type":"text"},{"text":"Vortex Studio Editor","type":"text","marks":[{"type":"em"}]},{"text":" to create its Application Setup.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Good Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"When you are done with the application, it is preferable to set it to None before the end of the program.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#333333"}}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Application Modes","type":"text"}]},{"type":"paragraph","content":[{"text":"Application mode is part of the application context and is used by Modules and Extensions to make some decisions. Modules and extensions are aware of what the application is doing and can adapt their behavior.","type":"text"}]},{"type":"paragraph","content":[{"text":"There are 3 application modes in Vortex :","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Editing mode","type":"text","marks":[{"type":"strong"}]},{"text":": The simulation is not computed at every step. That's when a user usually changes an object's parameters, move objects, add or remove objects, activate a configuration, load content, etc.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Simulating mode","type":"text","marks":[{"type":"strong"}]},{"text":": The simulation is computed at every step, objects parameters should not be modified. The simulation can be paused and resumed.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Playback mode","type":"text","marks":[{"type":"strong"}]},{"text":": The simulation is not computed, objects are moved from the playback source so that content is replayed “graphically”.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The Editor starts in editing mode. The user edits his content. When the user hits the play button, it goes in simulating mode. On stops, it goes back to editing. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The Player also starts in editing mode. The user selects his content. When the user hits the play button, it goes in simulating mode. On stop, it goes back to editing. If the user loads a recording, the player goes in playback mode.","type":"text"}]},{"type":"paragraph","content":[{"text":"The default mode for a Vortex Application is simulating, it can be set to editing in the Application Setup.","type":"text"}]},{"type":"paragraph","content":[{"text":"Changing the mode is not instantaneous and usually requires at least 1 application update.","type":"text"}]},{"type":"paragraph","content":[{"text":"To change the mode manually, the best way is to use the vxatp helper","type":"text"},{"text":" VxATPUtils.requestApplicationModeChangeAndWait(application, mode)","type":"text","marks":[{"type":"code"}]},{"text":", where mode is either kModeEditing or kModeSimulating.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Example:Application Mode","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"...\napplication = VxApplication()\n...\n# Setup the application\n...\nvxatp3.VxATPUtils.requestApplicationModeChangeAndWait(self.application, Vortex.kModeEditing)\n\n# Load mechanism file and get the mechanism interface\nself.vxmechanism = self.application.getSimulationFileManager().loadObject(self.content_file)\nself.mechanism = Vortex.MechanismInterface(self.vxmechanism)\n\n# Get the RL Interface VHL\nself.interface = self.mechanism.findExtensionByName('RL Interface')\n\n# Switch to Simulation Mode\nvxatp3.VxATPUtils.requestApplicationModeChangeAndWait(self.application, Vortex.kModeSimulating)","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Pausing the simulation","type":"text"}]},{"type":"paragraph","content":[{"text":"If the mode is set to simulation, the user can pause the simulation by calling ","type":"text"},{"text":"pause()","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Simulation can be resumed be calling ","type":"text"},{"text":"resume()","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Loading Content","type":"text"}]},{"type":"paragraph","content":[{"text":"Loading content created using the ","type":"text"},{"text":"Vortex Studio Editor","type":"text","marks":[{"type":"em"}]},{"text":" should be done with the VxSimulationFileManager provided by the ","type":"text"},{"text":"VxApplication","type":"text","marks":[{"type":"code"}]},{"text":". The object loaded is distributed across the network. Object loaded this way is not meant to be edited, most changes will not be distributed. Content should be loaded while the application is in editing mode.","type":"text"}]},{"type":"paragraph","content":[{"text":"To edit content using Python, see section Content Creation.","type":"text"}]},{"type":"paragraph","content":[{"text":"Content gets unloaded on its own when the application is destroyed, but should you need to remove content, the simulation file manager can also be used to remove content via ","type":"text"},{"text":"unloadObject()","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Example:Loading a scene","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"...\napplication = VxApplication()\n...\n# Setup the application\n...\n# Get the file manager to load content\nfileManager = application.getSimulationFileManager()\n\n# Load the file, the object returned is the root object, in this case, a scene. The Reference should be kept to inspect the content during the simulation\n# The object loaded is already added to the application\nscene = SceneInterface( fileManager.loadObject(\"myScene.vxscene\") )\nif (scene.valid()):\n\t# Work with scene\n\t...\n\t# run application\n\t...\n\t# Done with content\n\tfileManager.unloadObject(\"myScene.vxscene\")\n\t...\n\t# Load new content and continue...","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Good Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"When you are done with content, it should be unloaded using the method ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#333333"}}]},{"text":"unloadObject()","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text","marks":[{"type":"textColor","attrs":{"color":"#333333"}}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Running the Application","type":"text"}]},{"type":"paragraph","content":[{"text":"Once the application has some content loaded or created, it can be updated.","type":"text"}]},{"type":"paragraph","content":[{"text":"If you only need to run the application until it ends, use the function ","type":"text"},{"text":"run()","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"},{"text":"Function ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]},{"text":"run()","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}},{"type":"em"}]},{"text":" on the application is basically a loop that calls ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]},{"text":"update()","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}},{"type":"em"}]},{"text":" continuously. It could be replaced with the code below.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"run()","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"run = True \nwhile(run): \n\trun = application.update() ","type":"text"}]},{"type":"paragraph","content":[{"text":"Depending on the mode, the physics will be simulated or not when there is an update.","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]},{"type":"hardBreak"},{"text":"For example, in the Vortex Editor, the default mode is editing. Once the user clicks on the start button, the application goes to simulating. On clicking the stop buttons, it goes back to editing. There are always calls to ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]},{"text":"update()","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}},{"type":"em"}]},{"text":".","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]},{"type":"hardBreak"}]},{"type":"paragraph","content":[{"text":"Function ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]},{"text":"update()","type":"text","marks":[{"type":"code"}]},{"text":" must be called once per frame, no matter the simulation mode and also when the simulation is paused, as modules require updates no matter the simulation mode or the pause state. The application context is available like in C++ and the mode should be set properly depending on what you are doing, ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]}]},{"type":"paragraph","content":[{"type":"hardBreak"},{"text":"If you need to perform things outside the update, such as inspecting content, or run a specific number of frames, rather than call ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]},{"text":"run()","type":"text","marks":[{"type":"code"}]},{"text":", call ","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]},{"text":"update()","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text","marks":[{"type":"textColor","attrs":{"color":"#222222"}}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"running 100 frames","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"run = True \nstartFrame = application.getContext().getFrame() \ncurrentFrame = startFrame \nwhile(run and (currentFrame - startFrame) < 100): \n\trun = application.update() \n\tcurrentFrame = application.getContext().getFrame()","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Inspecting and updating content","type":"text"}]},{"type":"paragraph","content":[{"text":"To look into content, a user can browse from the ","type":"text"},{"text":"VxObject","type":"text","marks":[{"type":"code"}]},{"text":" returned by the simulation file manager. It is possible to use ","type":"text"},{"text":"Interface","type":"text","marks":[{"type":"code"}]},{"text":" to get to the object of interest, as explained in the Content Creation in Python section above.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following is an example of how to use a hinge constraint retrieved from a scene object in Python:","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Browsing content","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"...\n# Create and setup the application\n...\n#Load content\n# loadObject returns a VxObject type, it needs to be converted to a SceneInterface (C++ equivalent of VxSmartInterface)\nscene = SceneInterface( fileManager.loadObject(\"myScene.vxscene\") )\nif scene.valid():\n\t# Browse to my hinge\n # scene.getMechanisms returns an array of MechanismInterface, no conversion needed\n mechanism = scene.getMechanisms()[0]\n\t# mechanism.getExtensions returns an array of IExtensionInterface\n\tiextension = mechanism.getExtensions()[0]\n\tconnectionContainer = ConnectionContainerInterface(iextension.getExtension())\n \n # mechanism.getAssemblies returns an array of AssemblyInterface, no conversion needed \n\tassembly = mechanism.getAssemblies()[0]\n # assembly.getConstraints() returns an array of ConstraintInterface, getting the proper constraint type require a conversion\n constraint = assembly.getConstraints[0]\n \n # To use the constraint as a hinge, create the HingeInterface using the VxObject of the ContraintInterface\n hinge = ConstraintInterface.getConstraintInterface(constraint) #since contraint is an Hinge, getConstraintInterface() returns an HingeInterface\n\t# this is the equivalent of doing\n\t# hinge = HingeInterface(constraint.getExtension())\n ","type":"text"}]},{"type":"paragraph","content":[{"text":"Once the references to the required objects have been established, the external application basically need to update the inputs, execute an update and read the values from the outputs. Data should not be written into outputs. Parameters value should not change during simulation. In Python, when you have access to the interface API, it is preferable to use it to get access to the fields rather than using function ","type":"text"},{"text":"getInput","type":"text","marks":[{"type":"code"}]},{"text":"()/","type":"text"},{"text":"getOutput","type":"text","marks":[{"type":"code"}]},{"text":"()/","type":"text"},{"text":"getParameter","type":"text","marks":[{"type":"code"}]},{"text":"() on the ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":", as the second option requires knowledge of the field's ","type":"text"},{"text":"VxID","type":"text","marks":[{"type":"code"}]},{"text":" and is less efficient.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Getting data from content","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"...\n# Create and setup the application\n...\n#Load content\n...\n# Set the input Velocity, with is a Field, property value is a VxVector3\npart.inputLinearVelocity.value = Vortex.VxVector3(1,1,1)\n\n# Updates the application's modules\napplication.update()\n\n# Get the mechanism position from an custom extension with a field, using getParameter since the Interface is not available in Python\n# property value is a MechanismInterface\nmechanism = myCustomExtension.getParameter('Mechanism').value\nmechPos = Vortex.getTranslation( mechanism.outputWorldTranform.value )\n...\n ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Using Keyframes to restore the initial positions","type":"text"}]},{"type":"paragraph","content":[{"text":"Keyframes can be used to restore the values of content objects taken at some point in time, e.g. when starting the simulation.","type":"text"}]},{"type":"paragraph","content":[{"text":"The first thing to do is to create a keyframe list and then use it to save and restore keyframes.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following provides an example of saving one keyframe and restoring it later.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Save and Restore Keyframe","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":" # init key frame\n application.update()\n keyFrameList = application.getContext().getKeyFrameManager().createKeyFrameList(\"KeyFrameList\", False)\n application.update()\n key_frames_array = keyFrameList.getKeyFrames()\n # len(key_frames_array) should be 0\n\n # first key frame\n frameId1 = keyFrameList.saveKeyFrame()\n waitForNbKeyFrames(1, application, keyFrameList)\n key_frames_array = keyFrameList.getKeyFrames()\n # len(key_frames_array) should be 1\n # key_frames_array[0] should not be None\n\n # wait a bit, do something...\n counter = 0\n while(self.application.update() and counter < 60):\n counter += 1\n\n # restore first key frame \n keyFrameList.restore(key_frames_array[0])\n self.application.update()","type":"text"}]},{"type":"paragraph","content":[{"text":"In contrary to the C++ implementation, there is no callback implemented to know when a keyframe is ready, therefore a small pull function must be implemented","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"waitForNbKeyFrames","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"def waitForNbKeyFrames(expectedNbKeyFrames, application, keyFrameList):\n maxNbIter = 100\n nbIter = 0\n while len(keyFrameList.getKeyFrames()) != expectedNbKeyFrames and nbIter < maxNbIter:\n if not application.update():\n break\n ++nbIter","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Content Creation","type":"text"}]},{"type":"paragraph","content":[{"text":"Content can also be created, or updated after being loaded.","type":"text"}]},{"type":"paragraph","content":[{"text":"Please read ","type":"text"},{"text":"Creating Content","type":"text","marks":[{"type":"link","attrs":{"href":"https://vortexstudio.atlassian.net/wiki/spaces/VSD2502/pages/3985965435"}}]},{"text":" for the fundamentals of content creation. The concepts described in that section apply in Python as well and will not be repeated here.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"About Extensions and factory keys","type":"text"}]},{"type":"paragraph","content":[{"text":"Not all extensions and module factory keys are exposed directly via the python API, only the most commonly used. Should you need to invoke the extension factory with a specific factory key that you don't know, it is possible to invoke the extension factory to get the list of all the available factory keys. ","type":"text"}]},{"type":"paragraph","content":[{"text":"The following provides an example of how to access the information of a Factory Key from the list fetched.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"code snippet - Extensions factory key with an object","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# loading all plugins, not that is typically not necessay, this is only to fill the Extension Factory\npluginMngr = VxPluginManager.instance()\npluginMngr.loadAllVxp() #loadAllVxp() loads all the plugins, this ensure that all the factory keys will be available\n\n#Access extensions' Factory Key\nFactoryKeyList = VxExtensionFactory.getAvailableTypes()\nfor FactoryKey in FactoryKeyList:\n print(FactoryKey.getUuid())\n print(FactoryKey.getCategoryName())\n print(FactoryKey.getFeatureName())\n print(FactoryKey.getVxpName())\t\t#If available\n...\n\n#copy the desired factory key e.g. Application Joystock extension factory key\nmyKey = VxFactoryKey(VxUuid(\"78E37E89-3FF6-4C58-8EE1-999E02049F3B\"), 'Input Devices', 'Application Joystick', 'VxSimDevicesJoystick')\napplicationJoystick = VxExtensionFactory.create(myKey)\napplication.add(applicationJoystick)\n ","type":"text"}]},{"type":"paragraph"},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Good Practices","type":"text"}]},{"type":"paragraph","content":[{"text":"In normal circumstances, it is not necessary to invoke the plugin manager to load all plugins. Only the plugins you need will be loaded when appropriate, loading all plugins will increase the memory footprint of your python process for no reason. ","type":"text"},{"type":"hardBreak"},{"text":"You should use the code above to find the factory key you need, then copy it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Then in your program, invoke the extension factory with the proper factory key as shown above.","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Working with definitions and instances","type":"text"}]},{"type":"paragraph","content":[{"text":"Use the VxObjectSerializer to load and save your document definition. Children in documents are instances and must be instantiated like in C++.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"code snippet - I/O with an object","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# loading a definition\nserializer = VxObjectSerializer()\nserializer.load(fileName)\nassemblyDef = AssemblyInterface(serializer.getObject()) #getObject() returns a VxObject so the AssemblyInterface must be created\n\n...\n#Modify the definition\n...\n#saving a definition\nserializer = VxObjectSerializer(assemblyDef)\nserializer.save(fileName)\n ","type":"text"}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"Clone, instantiate and sync","type":"text"}]},{"type":"paragraph","content":[{"text":"The C++ global functions to perform those operations are not available in Python. However, all Python Smart Interfaces have additional functions that their C++ counterparts do not have: ","type":"text"},{"text":"clone","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"instantiate ","type":"text","marks":[{"type":"code"}]},{"text":"and ","type":"text"},{"text":"sync","type":"text","marks":[{"type":"code"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"code snippet - sync operations","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"#\nmechanism = Mechanism.create()\n \n# Load an assembly definition, let's say this assembly has a box CG part only.\nserializer = VxObjectSerializer()\nserializer.load(fileName)\nassemblyDef = AssemblyInterface(serializer.getObject()) #getObject() returns a VxObject so the AssemblyInterface must be created\n\n# INSTATIATE - Instantiate a definition\nassemblyInstance = assemblyDef.instantiate()\nmechanism.add(assemblyInstance)\n\n# Add a part to the assembly, which is a sphere and is lighter but otherwise has the same data.\npart0 = assemblyDef.getParts()[0]\n\n# CLONE - Make a clone of the part\npartDefClone = part0.clone()\n\n# add it to assembly definition\nassemblyDef.addPart(partDefClone)\n\n# Modify partDefClone by changing the mass and adding a sphere in place of a box\npartDefClone.parameterMassPropertiesContainer.mass.value = lighter\npartDefClone.removeCollisionGeometry(box)\nsphere = Sphere.create()\npartDefClone.addCollisionGeometry(sphere)\n...\n# SYNC - Sync the assembly to get the definition data i.e. the part cloned\nassemblyInstance.sync()\n# After the sync, the assembly instance has 2 parts","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Content Creation examples","type":"text"}]},{"type":"paragraph","content":[{"text":"These examples reproduce the C++ examples found in ","type":"text"},{"text":"Creating Content","type":"text","marks":[{"type":"link","attrs":{"href":"https://vortexstudio.atlassian.net/wiki/spaces/VSD2502/pages/3985965435"}}]},{"text":". ","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"Python tutorial Content Creation","type":"text","marks":[{"type":"link","attrs":{"href":"https://vortexstudio.atlassian.net/wiki/spaces/VSD2502/pages/3985971801"}}]},{"text":" for additional examples.","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"paragraph","content":[{"text":"The following code snippets are not intended to produce a complete, runnable example when combined as-is.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Collision Geometries","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Collision Geometries","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# create a box\nbox = Vortex.Box.create()\n \n# Set the box dimensions (x,y,z) to (1 meters, 2 meters, 3 meters)\nbox.parameterDimension.value = Vortex.VxVector3(1.0,2.0,3.0)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Parts","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Part","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# create a part\npart = Vortex.Part.create()\n# set the mass\npart.parameterMassPropertiesContainer.mass.value = 1.0\n # Adding a CG\npart.addCollisionGeometry(box)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Assemblies","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Assemblies","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# create an assembly\nassembly = Vortex.Assembly.create()\n\n# create a part for the assembly\npart = part.create()\n\n# Sets Position and Control type\npart .setLocalTransform( Vortex.createTranslation(1.0,2.0,3.0) )\npart .inputControlType.value = Vortex.Part.kControlDynamic\n \n#Add the part to the assembly\nassembly.addPart(part )","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Constraints","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Constraints","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# create an hinge\nhinge = Vortex.Hinge.create()\n \n# set the attachment parts\nhinge.inputAttachment1.part.value = part1\nhinge.inputAttachment1.part.value = part2\n \n# set the attachment positions\nhinge.inputAttachment1.position.value = Vortex.VxVector3(1.0,0.0,0.0)\nhinge.inputAttachment2.position.value = Vortex.VxVector3(1.0,0.0,0.0)\n \n# set the attachment primary axis\nhinge.inputAttachment1.primaryAxis = primaryAxis\nhinge.inputAttachment2.primaryAxis = primaryAxis\n \n# Add the hinge to the assembly\nassembly.addConstraint(hinge)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Attachments","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Attachments","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# create a first attachment point\nattPt1 = Vortex.AttachmentPoint.create()\nattPt1.parameterParentPart.value = part1\nassembly.addAttachmentPoint(attPt1)\n\n# create a second attachment point and add it \nattPt2 = Vortex.AttachmentPoint.create()\nattPt2.parameterParentPart.value = part2\nassembly.addAttachmentPoint(attPt2)\n\n# create an attachment using both attachment points\nattachment = Vortex.Attachment.create()\nattachment.setAttachmentPoints(attPt1, attPt2)\n\n# add the attachment to the assembly\nassembly.addAttachment(attachment)\n \n# attach \nattachment.inputAttach = True","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Mechanisms","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Mechanisms","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# create a mechanism\nmechanism = Vortex.Mechanism.create()\n \n# create an instance from the assembly definition\nassemblyInstance = assembly.instantiate() \n\n# Position\nassemblyInstance.setLocalTransform( Vortex.createTranslation(1.0,2.0,3.0) )\n\n# Add the assembly instance to the mechanism\nmechanism.addAssembly(assemblyInstance)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Scenes","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Scenes","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"scene = Vortex.Scene.create()\n\n# create an instance from the mechanism definition\nmechanismInstance = mechanism.instantiate()\n\n# Position\nmechanismInstance.setLocalTransform( Vortex.createTranslation(1.0,2.0,3.0) )\n\n# Add the mechanism instance to the scene\nscene.addMechanism(mechanismInstance)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"VHL Interface","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"VHL","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# Create the VHL extension\nvhlInterface = Vortex.VxVHLInterface.create()\n\n# Add a hinge control field as input of VHL. Make sure to use the correct hinge extension (i.e. from the assembly instance)\nvhlInterface.addInput('Input Value', hingeFromAssemblyInstance.inputAngularCoordinate.control) \n\n# Add the VHL extension to the mechanism\nmechanism.addExtension(vhlInterface.getExtension()) ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Connection Container","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Connections Container","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# Create the connection container extension\nconnectionContainer = Vortex.ConnectionContainerExtension.create()\n\n# Add a connection between two fields : my custom extension output and a part input control\n# Types have to be compatible for the connection creation to succeed\nconnectionIndex = connectionContainer.create(myCustomExt.getOutput('CustomOutput'), part.inputControlType)\n\n# Add the connection container to the mechanism\nmechanism.addExtension(connectionContainer.getExtension())","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Dynamics Script Extension (Python 3)","type":"text"}]},{"type":"paragraph","content":[{"text":"Python extensions do not have a dedicated interface, so a ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":" is used directly.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Python Extension","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# Create the Python scripting extension\npythonExt = Vortex.VxExtensionFactory.create(Vortex.DynamicsScriptICD.kFactoryKey)\n\n# Add the scripting file as parameter - the script can also be added as a string\npythonExt.getParameter(Vortex.DynamicsScriptICD.kScriptPath).value = '/mypythonscript.py'\n\n# Add a parameter of type Part and set its reference\npythonExt.addParameter('ParamPart', Vortex.Types.Type_Part)\npythonExt.getParameter('ParamPart').value = part\n\n# Add an input of type boolean and set its value\npythonExt.addInput('Switch', Vortex.Types.Type_Bool)\npythonExt.getInput('Switch').value = False\n\n# Add an output of type integer and set its value\npythonExt.addOutput('Control Mode', Vortex.Types.Type_Int)\npythonExt.getOutput('Control Mode').value = 0\n\n# Add the connection container to the mechanism\nmechanism.addExtension(pythonExt)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"Configuration can also be edited in Python, but it is preferable to use the ","type":"text"},{"text":"Vortex Studio Editor","type":"text","marks":[{"type":"em"}]},{"text":", as it is easy to make mistakes in code. Configurations can only be activated while the application is in editing mode,","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Configuration","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"...\n# Add 4 extensions to mechanism\nmyExtension1 = Vortex.VxExtensionFactory.create(MyFactoryKey)\nmyExtension2 = Vortex.VxExtensionFactory.create(MyFactoryKey)\nmyExtension3 = Vortex.VxExtensionFactory.create(MyFactoryKey)\nmyExtension4 = Vortex.VxExtensionFactory.create(MyFactoryKey)\n \n# Sets default value\nmyExtension1.parameterA.value = 1\nmyExtension1.parameterB.value = 2\nmyExtension1.parameterC.value = 3\n\nmyExtension2.parameterA.value = 4\nmyExtension2.parameterB.value = 5\nmyExtension2.parameterC.value = 6\n\nmyExtension3.parameterA.value = 7\nmyExtension3.parameterB.value = 8\nmyExtension3.parameterC.value = 9\n\nmyExtension4.parameterA.value = 10\nmyExtension4.parameterB.value = 11\nmyExtension4.parameterC.value = 12\n\nmechanism.addExtension(myExtension1)\nmechanism.addExtension(myExtension2)\nmechanism.addExtension(myExtension3)\nmechanism.addExtension(myExtension4)\n...\n# Create a configuration\nconfiguration = Vortex.Configuration.create()\nconfiguration.setName('Configuration1')\nmechanism.addExtension(configuration.getExtension())\n \n# Configuration will modify Extension 1, remove extension 2 and add extension 4\nconfiguration.addReference(myExtension1, Vortex.kModify)\nconfiguration.addReference(myExtension2, Vortex.kRemoveOnActivation)\nconfiguration.addReference(myExtension4, Vortex.kAddOnActivation) # Because the flag is AddOnActivation, myExtension4 is immediately removed from the content. It still exist with mechanism but no module will received it.\n \n# Start edition.\nif(configuration.canActivate()[0]): # just to make sure there is no conflict, canActivate has 2 return values, the first being True are False, the second being the conflicts\n{\n\tconfiguration.inputActivate.value = True # Activation will remove myExtension2 and add myExtension4.\n mApplication.update() # activation requires an application update\n \n\tif(configuration.outputActivated.value):\n\t{\n\t\t# Edit the extension 1 and 4\n\t\tmyExtension1.parameterA.value = -1\n\t\tmyExtension1.parameterC.value = -10\n \n\t\tmyExtension4.parameterB.value = 42\n\t\t\n # Done editing\n\t\tmConfiguration.inputActivate.value = False\n\t\tmApplication.update() # deactivation requires an application update\n\t}\n\telse:\n\t{\n\t\t# Handles errors\n\t\terrors = mConfiguration.getRuntimeErrors()\n\t}\n}\n \n... # Continue edition\n \n# Create a scene\nscene = Vortex.Scene.create()\n# instantiate a mechanism\nmechInstance = mechanism.instantiate()\n \n# myExtension1 is in the content, parameterA value is 1, parameterB is 2 and parameterC is 3\n# myExtension2 is in the content, parameterA value is 4, parameterB is 5 and parameterC is 6\n# myExtension3 is in the content, parameterA value is 7, parameterB is 8 and parameterC is 9\n# myExtension4 is NOT in the content\nscene.addMechanism(mechInstance)\n \n# Activate the mechanism configuration in the scene\nconfInstance = Vortex.ConfigurationInterface( mechInstance.getObject().findExtensionByName('configuration1', False) )\nconfInstance.inputActivate.value = True\nmApplication.update() # requires an application update\n \n# myExtension1 is in the content, parameterA value is 11, parameterB is 2 and parameterC is -10\n# myExtension2 is NOT in the content\n# myExtension3 is in the content, parameterA value is 7, parameterB is 8 and parameterC is 9\n# myExtension4 is in the content, parameterA value is 10, parameterB is 42 and parameterC is 12","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Python Tutorials","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"Python Tutorials","type":"text","marks":[{"type":"link","attrs":{"href":"https://vortexstudio.atlassian.net/wiki/spaces/VSD2502/pages/3985979851"}}]},{"text":" for the list of tutorials","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Advanced Python Scripting","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"C++ Smart Interface vs. Python","type":"text"}]},{"type":"paragraph","content":[{"text":"Most of the C++ interfaces have their equivalent in the Vortex Python API.","type":"text"}]},{"type":"paragraph","content":[{"text":"C++ Smart Interfaces are ","type":"text"},{"text":"IExtension's ","type":"text","marks":[{"type":"code"}]},{"text":"implementation with their ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":" underneath, wrapped into a nice template class and is the preferred way of working with Vortex objects, rather than using VxExtension in a generic way, which requires the user to know every fields' Id.","type":"text"}]},{"type":"paragraph","content":[{"text":"In Python, it is still possible to work with VxExtension, like in C++. They can be created via the ","type":"text"},{"text":"VxExtensionFactory","type":"text","marks":[{"type":"code"}]},{"text":" as usual and still requires the knowledge of the field's id.","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to use an equivalent of a C++ smart interface in Python, the Python API has objects named ","type":"text"},{"text":"Interface,","type":"text","marks":[{"type":"code"}]},{"text":" where ","type":"text"},{"text":"","type":"text","marks":[{"type":"code"}]},{"text":" is the name of the C++ interface. e.g. ","type":"text"},{"text":"PartInterface","type":"text","marks":[{"type":"code"}]},{"text":" Python object is the C++ equivalent of ","type":"text"},{"text":"VxSmartInterface","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"To use content objects in Python:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Methods are accessed via","type":"text"},{"text":" Interface.","type":"text","marks":[{"type":"code"}]},{"text":", e.g. ","type":"text"},{"text":"mechanism.getExtensions() where mechanism is a MechanismInterface Python object (C++ equivalent of VxSmartInterface).","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Interface.getObject()","type":"text","marks":[{"type":"code"}]},{"text":" returns a ","type":"text"},{"text":"VxObject","type":"text","marks":[{"type":"code"}]},{"text":" typed instance, ","type":"text"},{"text":"none","type":"text","marks":[{"type":"code"}]},{"text":" is returned if it is not a ","type":"text"},{"text":"VxObject","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Interface.getExtension()","type":"text","marks":[{"type":"code"}]},{"text":" returns the ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":" typed instance","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Can be created by calling ","type":"text"},{"text":"Interface","type":"text","marks":[{"type":"code"}]},{"text":".create(), or by constructing an ","type":"text"},{"text":"Interface","type":"text","marks":[{"type":"code"}]},{"text":" from a ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":". ","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Interface conversion","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"from Vortex import *\n \n# create a VxDynamics::Part\npart = Part.create()\n# This is the equivalent of doing\nextension = VxExtensionFactory.create(PartICD.kFactoryKey)\npart = PartInterface(extension)\n \npart.addCollisionGeometry(cg) # using it has an interface","type":"text"}]},{"type":"paragraph","content":[{"text":"Since all objects are ","type":"text"},{"text":"IExtension","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"IObject","type":"text","marks":[{"type":"code"}]},{"text":", all objects in Python are ","type":"text"},{"text":"IExtensionInterface","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"IObjectInterface","type":"text","marks":[{"type":"code"}]},{"text":". However, passing from one to another, requires an explicit conversion.","type":"text"}]},{"type":"paragraph","content":[{"text":"Given object ","type":"text"},{"text":"a","type":"text","marks":[{"type":"em"}]},{"text":" of type InterfaceA, to get an object ","type":"text"},{"text":"b","type":"text","marks":[{"type":"em"}]},{"text":" of type InterfaceB : ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"b","type":"text","marks":[{"type":"em"}]},{"text":" = InterfaceB ( ","type":"text"},{"text":"a","type":"text","marks":[{"type":"em"}]},{"text":".getExtension() ) e.g., ","type":"text"},{"text":"ConstraintInterface","type":"text","marks":[{"type":"code"}]},{"text":" to ","type":"text"},{"text":"HingeInterface","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"IExtensionInterface","type":"text","marks":[{"type":"code"}]},{"text":" object to ","type":"text"},{"text":"ConnectionContainerInterface","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Interface conversion","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"# mechanism.getExtensions returns an array of IExtensionInterface\niextension_0 = mechanism.getExtensions ()[0]\nconnectionContainer = ConnectionContainerInterface(iextension_0.getExtension())","type":"text"}]},{"type":"paragraph","content":[{"text":"Note that while in C++ many functions (such as ","type":"text"},{"text":"VxApplication::add()","type":"text","marks":[{"type":"code"}]},{"text":" ) that take ","type":"text"},{"text":"VxSmartInterface","type":"text","marks":[{"type":"code"}]},{"text":" in a generic way work, because in C++ the conversion is implicit, it won't work in Python because conversion is explicit. Some of the Python API was extended to accept ","type":"text"},{"text":"VxExtension","type":"text","marks":[{"type":"code"}]},{"text":" to simplify general usage. The user simply needs to call ","type":"text"},{"text":"getExtension()","type":"text","marks":[{"type":"code"}]},{"text":" on the object interface when working in Python.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"getExtension()","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"python"},"content":[{"text":"import Vortex\n \napplication = Vortex.VxApplication() # VxApplication is not a Smart Interface. Just call the constructor\npart = Vortex.Part.create()\n# Contrary to C++, Python VxApplication.add() accepts VxExtension rather than Smart Interface. Use getExtension() on the interface object \napplication.add(part.getExtension())\n \n# addExtension on a VxDynamics::Mechanism was modified to accept VxExtension\nconnectionContainer = ConnectionContainer.create()\nmechanism.addExtension( connectionContainer.getExtension() ) ","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"type":"hardBreak"}]}],"version":1}

Browser not supported