{"type":"doc","content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"bodiedExtension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"excerpt","parameters":{"macroParams":{"atlassian-macro-output-type":{"value":"INLINE"}},"macroMetadata":{"macroId":{"value":"c4c513e3-5320-405a-a9cd-6c46ec980cda"},"schemaVersion":{"value":"1"},"title":"Excerpt"}},"localId":"52a97946-fcec-43fa-9209-dbf9b5c78972"},"content":[{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"780acf27-889e-4b8d-aab1-6ea7b30b0200"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"259803c1-71ac-4ffd-828c-82e817f0b026"}}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Content Creation","type":"text"}]},{"type":"paragraph","content":[{"text":"The main tool for content creation is of course the Vortex Studio Editor. The Editor manages for you all the dependencies between the documents, for example, it ensures that a change in a mechanism document is reflected in the scene where that mechanism is being used.","type":"text"},{"type":"hardBreak"},{"text":"However, a user could want to create content automatically in code, in C++ or Python, but some key concepts must be understood for that content to be compatible with Vortex Studio. The reader is expected to understand what are extensions, smart interfaces, and fields, see ","type":"text"},{"text":"Vortex Studio SDK - Customizing Vortex","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD237/pages/3324812074"}}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Using an application","type":"text"}]},{"type":"paragraph","content":[{"text":"Vortex Studio SDK is using internally its own concepts. Content classes are VxSim::IObject. While some content classes can be created and manipulated without a Vortex Application, many features (e.g. VxContent::Configurations) will not work without a ","type":"text"},{"text":"VxSim::VxApplication","type":"text","marks":[{"type":"strong"}]},{"text":". The Vortex Studio Editor is a VxSim::VxApplication, working in Editing mode when content is created. It is recommended to create or edit content using a VxSim::VxApplication. Objects being edited should be added to the application before editing them.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Definitions and instances","type":"text"}]},{"type":"paragraph","content":[{"text":"The Vortex Studio Editor allows you to create five types of content documents: Assembly, Gallery, Mechanism, Scene, and Control Interface. When a user creates a Mechanism (or any other content object), it creates a definition. When a user inserts that Mechanism into a Scene, it uses a special copy of that definition: an instance.","type":"text"}]},{"type":"panel","attrs":{"panelType":"info"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Other Definitions","type":"text"}]},{"type":"paragraph","content":[{"text":"Control Presets, Simulators, and Application Setups (i.e class ApplicationConfig) are also definitions, but they are not content files and work slightly differently. They are not covered in this section.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"A definition consists of a main IObject (the parent) and some associated instances of IObject and IExtension (the children) saved into a file.","type":"text"},{"type":"hardBreak"},{"text":"An instance is a copy of a definition that remembers the definition it came from. To put a definition object into another, it must be instantiated.","type":"text"}]},{"type":"paragraph","content":[{"text":"Since an instance remembers its definition, when that definition changes, the instance can receive the changes via the synchronization operation called ","type":"text"},{"text":"sync","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"},{"type":"hardBreak"},{"text":"The ","type":"text"},{"text":"sync","type":"text","marks":[{"type":"em"}]},{"text":" operation only brings the ","type":"text"},{"text":"definition data","type":"text","marks":[{"type":"underline"}]},{"text":" to the instance. Definition data are the parameters of an object, as well as all the data of its children. The presence and order of the children are also definition data.","type":"text"},{"type":"hardBreak"},{"text":"To complement the definition data that is common to all instances of the same object there are ","type":"text"},{"text":"instance data","type":"text","marks":[{"type":"underline"}]},{"text":". Instance data are the inputs/outputs distinct in each instance and are saved within the parent's definition.","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"align-start","width":31.0},"content":[{"type":"media","attrs":{"width":798,"id":"6aac2276-f18a-4f18-8b74-558c5ac19fa0","collection":"contentId-3324814404","type":"file","height":756}}]},{"type":"paragraph","content":[{"text":"There are 2 exceptions to this rule:","type":"text"}]},{"type":"orderedList","attrs":{"order":1},"content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The inputs and outputs values of a VHL interface extension, which can be a child of a Mechanism or a Scene, are instance data. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The field ","type":"text"},{"text":"inputActivate ","type":"text","marks":[{"type":"code"}]},{"text":"of a Configuration is instance data. A configuration in a mechanism is usually activated at the scene level.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The Vortex Editor handles definitions and instances; it synchronizes them properly without manual intervention. For example, to get the changes in the number of Parts in a scene, the Assembly instance of the Mechanism definition using it must be synchronized, then the Mechanism instances must be synced in the Scene definition. It is a manual process.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Vortex Studio Editor only knows 7 types of Definitions: Assembly, Gallery, Mechanism, Scene, Control Interface, Equipment, and Exercise list, corresponding to the documents it can create. While the concept of definition can be generalized, the editor wouldn't know what to do with custom definitions.","type":"text"}]},{"type":"paragraph","content":[{"text":"A setup is also a definition, but they are not instantiated.","type":"text"}]},{"type":"paragraph","content":[{"text":"A simulator should not need to perform those operations, these are edition concepts.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Definitions and instances: Example","type":"text"}]},{"type":"paragraph","content":[{"text":" Adding an Assembly to a Mechanism. ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The Mechanism is a definition (saved in a .vxmechanism file), and an inserted Assembly in that Mechanism is an instance of an Assembly definition (that was saved in a .vxassembly file). ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Within the Mechanism document, the Assembly instance can be positioned using the inputLocalTransform field, the field is an input, and that field is instance data that belongs to the definition data of the assembly.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If the Assembly is opened in its own document in the editor, it is the definition data is being edited, such as part mass and collision geometries.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Any changes to the Assembly's parameters and children will be synchronized to the Assembly instance when going back to the Mechanism document in the editor. However, the position of the Assembly instance will remain the same.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It works the same going up in the mechanism and scene.","type":"text"}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Working with definitions and instances","type":"text"}]},{"type":"paragraph","content":[{"text":"Objects can be saved with the VxSim::VxObjectSerializer. Only definitions can be saved to a file. Object ","type":"text"}]},{"type":"paragraph","content":[{"text":"The serializer can be used to load objects as well. Object loaded is thus a definition. When a definition containing instances is loaded, all the definitions of the instance will be loaded as well.","type":"text"},{"type":"hardBreak"},{"text":"All the instances are automatically synchronized after a load. ","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"How to create and save a Mechanism with an Assembly instance in code","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"// create the assembly definition\nauto assemblyDefinition = VxSim::VxSmartInterface::create();\n\n// Create a part and add it to the assembly definition\nauto part = VxSim::VxSmartInterface::create();\nassemblyDefinition->add(part);\n\n// Edit the part\npart->parameterMassPropertiesContainer.mass = heavy;\nauto sphere = VxSim::VxSmartInterface::create();\npart->addCollisionGeometry(sphere);\n\n// Saving the assembly file\nVxSim::VxObjectSerializer serializerA(assemblyDefinition ); \nserializerA.save(\"MyAssembly.vxassembly\");\n\n// Create a mechanism definition\nauto mechanismDefinition = VxSim::VxSmartInterface::create();\n\n// create an instance of the assembly\nauto assemblyInstance = VxSim::instantiate(assemblyDefinition);\nmechanismDefinition->add(assemblyInstance);\n\n// save the mechanism file\nVxSim::VxObjectSerializer serializerM(mechanismDefinition ); \nserializerM.save(\"MyMechanism.vxmechanism\");\n\n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"How to load a Mechanism with an Assembly instance in code","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"// load the mechanism file \nVxSim::VxObjectSerializer serializer; \nserializer.load(\"MyMechanism.vxmechanism\");\n\n// get the mechanism definition\nVxSim::VxSmartInteface mechanism= serializer.getObject();\n\n// get the Assembly instance and its part\nauto assemblyInstance = mechanism->getAssemblies()[0];\nauto part = assemblyInstance->getParts()[0];\n\n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"paragraph","content":[{"text":"In a simulator, ","type":"text"},{"text":"VxSim::VxSimulationFileManager","type":"text","marks":[{"type":"strong"}]},{"text":" can be used to load content. However, VxSim::VxSimulationFileManager::load(filename) returns an instance. The object returned is an instance and it is already added to the current VxApplication.","type":"text"}]},{"type":"paragraph","content":[{"text":"For content creation, it is recommended to use a VxSim::VxObjectSerializer, since you will need to work with definition. ","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Cloning","type":"text"}]},{"type":"paragraph","content":[{"text":"Cloning is an operation to copy an object. A clone is independent of its source.","type":"text"},{"type":"hardBreak"},{"text":"Cloning a definition makes a definition. Cloning an instance makes an instance, linked to the same definition.","type":"text"}]},{"type":"paragraph","content":[{"text":"To clone, simple call function ","type":"text"},{"text":"clone()","type":"text","marks":[{"type":"code"}]},{"text":", available in namespace VxSim by including file ","type":"text"},{"text":"VxObjectHelpers.h","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Clone","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include \n...\n// Clone the part since I need a part with a sphere CG, but lighter\nauto part2 = VxSim::clone(part);\npart2->parameterMassPropertiesContainer.mass= lighter;\n\nassemblyDefintion->add(part2); // the two parts are independant","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Instantiate","type":"text"}]},{"type":"paragraph","content":[{"text":"Instantiating","type":"text","marks":[{"type":"em"}]},{"text":" creates a copy of a definition, the resulting object is an instance but a link is kept to its definition. You cannot create an instance of an object that is not a definition. As mentioned before, an instance cannot be saved on its own into a file, but instance data are saved with their parent definition. ","type":"text"}]},{"type":"paragraph","content":[{"text":"To instantiate, simple call function ","type":"text"},{"text":"instantiate()","type":"text","marks":[{"type":"code"}]},{"text":", available in namespace VxSim by including file ","type":"text"},{"text":"VxObjectHelpers.h","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Instantiate","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include \n...\n// create a mechanism\nauto mechanism = VxSim::VxSmartInteface::create();\n\n// Load a definition\nVxSim::VxObjectSerializer objSerializer(); \nobjSerializer.load(\"MyAssemby.vxassembly\");\n\nVxSim::VxSmartInterface assemblyDefinition = objSerializer.getObject();\n\n// Instantiate a definition\nauto assemblyInstance = VxSim::instantiate(assemblyDefinition);\nmechanism->add(assemblyInstance);\n\n// move the instance\nassemblyInstance->setLocalTransform(transform); //Instance data\n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"panel","attrs":{"panelType":"error"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Bad Instances","type":"text"}]},{"type":"paragraph","content":[{"text":"There exists other IObject that are not meant to be definitions, something other than an Assembly, Gallery, Mechanism, Scene, and Control Interface e.g. a Terrain, a Human, or an Ocean. Attempting to instantiate such an object leads to undefined behavior and the file using the instance could be unusable by the Vortex applications.","type":"text"}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Synchronization","type":"text"}]},{"type":"paragraph","content":[{"text":"The synchronize operation consists of updating an instance's definition data to match its definition while keeping the instance data. Once done, the children of the object are fully updated to match the children of the definition object.","type":"text"}]},{"type":"paragraph","content":[{"text":"To ","type":"text"},{"text":"synchronize","type":"text","marks":[{"type":"em"}]},{"text":", simple call function ","type":"text"},{"text":"sync()","type":"text","marks":[{"type":"code"}]},{"text":", available in namespace VxSim by including file ","type":"text"},{"text":"VxObjectHelpers.h","type":"text","marks":[{"type":"em"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Sync","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":" #include \n\n[...]\n\n// Modify the assembly definition by changing adding a third part\nauto part3 = VxSim::VxSmartInterface::create();\npart3->parameterMassPropertiesContainer.mass = heavier; // Definition data\npart3->inputControlType = VxDynamics::Part::kControlStatic; \npart3->addCollisionGeometry(box);\nassemblyDefinition->add(part3)\n\n[...]\n\n// Sync to get the definition data\nVxSim::sync(assemblyInstance);\n// After the sync, the new part in the assembly definition has been added to the assembly instance\n ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Creating Content in C++","type":"text"}]},{"type":"paragraph","content":[{"text":"All Vortex objects are extensions. Extensions are plugins and as such an object can be created using the ","type":"text"},{"text":"VxSim::VxExtensionFactory ","type":"text","marks":[{"type":"strong"}]},{"text":"with the proper ","type":"text"},{"text":"VxSim::VxFactoryKey","type":"text","marks":[{"type":"strong"}]},{"text":". However, the recommended way of using Vortex Object is by using ","type":"text"},{"text":"VxSim::VxSmartInterface::create() ","type":"text","marks":[{"type":"strong"}]},{"text":"to create an extension of type T. ","type":"text"}]},{"type":"panel","attrs":{"panelType":"warning"},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Note:","type":"text"}]},{"type":"paragraph","content":[{"text":"The following code snippets are not intended to produce a complete, runnable example when combined as-is.","type":"text"}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - creating objects","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"// The following code creates an object of type MyExtension\n// 1) Using the VxSmartInterface API and factory key\nauto myExt = VxSim::VxSmartInterface::create(MyExtensionFactoryKey);\n \n// 2) Using the VxSmartInterface API, which requires the class MyExtension to have a \n// properly set static memmber : static VxSim::VxFactoryKey MyExtension::kFactoryKey\nauto myExt = VxSim::VxSmartInterface::create(); \n\n// 3) Using the extension factory\nVxSim::VxSmartInterface myExt = VxSim::VxExtensionFactory::create(MyExtensionFactoryKey);","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Dynamics Objects","type":"text"}]},{"type":"paragraph","content":[{"text":"Most content objects are dynamics. These are your Mechanisms, Assemblies, Constraints, Attachment, Attachment Points, Parts, and Collision Geometries.","type":"text"},{"type":"hardBreak"},{"text":"These Dynamics objects are represented by interfaces in the code (e.g. Part, Box), while the implementation is actually a dynamics extension provided by the dynamics plugin (","type":"text"},{"text":"VxDynamics.vxp","type":"text","marks":[{"type":"em"}]},{"text":").","type":"text"}]},{"type":"paragraph","content":[{"text":"A header file describes the interface that should be used by the developer (e.g. ","type":"text"},{"text":"VxDynamics/Part.h","type":"text","marks":[{"type":"em"}]},{"text":").","type":"text"},{"type":"hardBreak"},{"text":"The header file gives access to everything the user needs to make it work: the factory key and fields to each input, output, and parameter. Some utility functions are also provided.","type":"text"},{"type":"hardBreak"},{"text":"An ICD header file describes the name of each input, outputs and parameters should a user needs to access them in a generic fashion from a VxExtension.","type":"text"}]},{"type":"paragraph","content":[{"text":"Dynamics objects Assembly and Mechanism can be loaded and saved to disk.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Moving Dynamics Objects well","type":"text"}]},{"type":"paragraph","content":[{"text":"Every dynamics object that can be moved implements the ","type":"text"},{"text":"VxSim::IMobile ","type":"text","marks":[{"type":"strong"}]},{"text":"interface. The position of a IMobile is set by the input ","type":"text"},{"text":"inputLocalTransform","type":"text","marks":[{"type":"code"}]},{"text":" and the actual position of an object is given by the output ","type":"text"},{"text":"outputWorldTransform","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"},{"type":"hardBreak"},{"text":"To move an object, rather than setting the value of the ","type":"text"},{"text":"inputLocalTransform","type":"text","marks":[{"type":"code"}]},{"text":" field is recommended to use function ","type":"text"},{"text":"setLocalTransform","type":"text","marks":[{"type":"code"}]},{"text":"().","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Collision Geometries","type":"text"}]},{"type":"paragraph","content":[{"text":"The following code gives an example of using a box collision geometry extension.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - collision geometry","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include \n\n// create a box\nauto box = VxSim::VxSmartInterface::create();\n\n// Set the box dimensions (x,y,z) to (1 meters, 2 meters, 3 meters)\nbox->parameterDimension = VxVector3(1.0,2.0,3.0);","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Parts","type":"text"}]},{"type":"paragraph","content":[{"text":"The following code gives an example of creating a part:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - part","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include \n\n// create a part\nauto part = VxSim::VxSmartInterface::create();\n\n// set the mass\npart->parameterMassPropertiesContainer.mass = 1.0\n \n// Adding a CG\npart->addCollisionGeometry(box);\n\n","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Assemblies","type":"text"}]},{"type":"paragraph","content":[{"text":"The following code gives an example of creating an assembly:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - assembly","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include \n\n// create an assembly\nauto assembly = VxSim::VxSmartInterface::create();\n\n// Position and Control type of a child part\nauto part = VxSim::VxSmartInterface::create();\npart->setLocalTransform( VxMath::Transformation::createTranslation(1.0,2.0,3.0) );\npart->inputControlType = VxDynamics::VxPart::kControlDynamic;\n\n// Add the part to the assembly\nassembly->add(part);","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Constraints","type":"text"}]},{"type":"paragraph","content":[{"text":"The following code gives an example of creating an hinge constraint with the minimal inputs:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - hinge constraint","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include \n\n// create an hinge\nauto hinge = VxSim::VxSmartInterface::create();\n\n// set the attachment parts\nhinge->inputAttachment1.part = part1;\nhinge->inputAttachment1.part = part2;\n\n// set the attachment positions\nhinge->inputAttachment1.position = VxMath::Vector3(1.0,0.0,0.0);\nhinge->inputAttachment2.position = VxMath::Vector3(1.0,0.0,0.0);\n\n// set the attachment primary axis\nauto primaryAxis = Vx::VxTransform(hinge->inputAttachment1.part->inputLocalTransform.getValue()).axis(0)\nhinge->inputAttachment1.primaryAxis = primaryAxis;\nhinge->inputAttachment2.primaryAxis = primaryAxis;\n \n// Add the hinge to the assembly\nassembly->addConstraint(hinge);\n\n","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Attachments","type":"text"}]},{"type":"paragraph","content":[{"text":"The following code gives an example of creating an attachment with two attachment points, each referencing a different part. The example attaches part together by adding an attachment to the assembly.","type":"text"},{"type":"hardBreak"},{"text":"Attachments can be added to a mechanism or a scene to attach assemblies or mechanisms, respectively.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - attachments","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include \n#include \n\n\n// create a first attachment point\nauto attPt1 = VxSim::VxSmartInterface::create();\nattPt1->parameterParentPart= part1;\nassembly->addAttachmentPoint(attPt1);\n\n// create a second attachment point and add it \nauto attPt2 = VxSim::VxSmartInterface::create();\nattPt2->parameterParentPart= part2;\nassembly->addAttachmentPoint(attPt2);\n\n// create an attachment using both attachment points\nauto attachment = VxSmartInterface::create();\nattachment->setAttachmentPoints(attPt1, attPt2);\n\n// add the attachment to the assembly\nassembly->addAttachment(attachment);\n \n// attach \nattachment->attach();\n","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Mechanisms","type":"text"}]},{"type":"paragraph","content":[{"text":"The following code gives an example of creating a mechanism:","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - mechanism","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include \n\n// create a mechanism\nauto mechanism = VxSim::VxSmartInterface::create();\n \n// create an instance from the assembly definition\nauto assemblyInstance = VxSim::instantiate(assembly); \n\n// Position\nassemblyInstance->setLocalTransform(VxMath::Transformation::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":"Other content extensions","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Scenes","type":"text"}]},{"type":"paragraph","content":[{"text":"Scenes are where you put all your mechanisms and some assemblies if necessary for your simulation.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - scene","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include \n\n// create a scene\nauto scene = VxSim::VxSmartInterface::create();\n\n// create an instance from the mechanism definition\nauto mechanismInstance = VxSim::instantiate(mechanism);\n\n// Position\nmechanismInstance->setLocalTransform( VxMath::Transformation::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":4},"content":[{"text":"VHL Interface","type":"text"}]},{"type":"paragraph","content":[{"text":"VHL Interfaces are extensions that give direct access to its children's field by mapping it to a VHL field. VHL Interface can be added to a mechanism or a scene.","type":"text"},{"type":"hardBreak"},{"text":"Adding inputs, outputs or parameters is available through the interface.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - VHL Interface in mechanism","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"// Create the VHL extension\nauto vhlInterface = VxSim::VxSmartInterface::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);\n","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Connection Container","type":"text"}]},{"type":"paragraph","content":[{"text":"Connection containers are extensions that will contain connections between fields. Fields that can be connected must be children of the connection container's parent, typically a mechanism, ","type":"text"},{"type":"hardBreak"},{"text":"Adding connections is available through the interface.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - connection container","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"// Create the connection container extension\nauto connectionContainer = VxSim::VxSmartInterface::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\nint connectionIndex = connectionContainer->create(myCustomExt->getProxy()->getOutput(\"MyOutput\"), &part->inputControlType); \n\n// Add the connection container to the mechanism\nmechanism->addExtension(connectionContainer);\n","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Python Scripting Extension","type":"text"}]},{"type":"paragraph","content":[{"text":"Python scripting extensions are standard extensions to control an aspect of the simulation in code. There are handled by the dynamics module and are added to a mechanism or a scene.","type":"text"},{"type":"hardBreak"},{"text":"The script file parameter refers to the .py file to execute. It is also possible to set the python code to execute as a string into the code parameter, but it is less convenient for edition.","type":"text"}]},{"type":"paragraph","content":[{"text":"The script extension can be edited to dynamically add inputs, outputs, and parameters that can be used by the Python script.","type":"text"}]},{"type":"paragraph","content":[{"text":"The added fields can be referred to by the script using self.inputs., self.outputs ., self.parameters ., where is the name of the field with invalid characters replaced by an underscore. The value is available from the ","type":"text"},{"text":"value","type":"text","marks":[{"type":"em"}]},{"text":" property of the Python field.","type":"text"}]},{"type":"paragraph","content":[{"text":"Python extension does not have a dedicated interface, VxSmartInterface of IExtension should be used.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - python scripting extension","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"// Create the python scripting extension\nVxSim::VxSmartInterface pythonExt = VxSim::VxExtensionFactory::create(VxSimPython::DynamicsICD::kFactoryKey);\n\n// Add the scripting file as parameter - the script can also be added as a string\npythonExt->getProxy()->getParameter(VxSimPython::DynamicsICD::kScriptFile)->setValue(std::string(\"/mypythonscript.py\"));\n\n// Add a parameter of type Part and set its reference\nVx::VxID kParamPart(\"Part\");\npythonExt->getProxy()->addParameter(kParamPart, VxData::Types::Type_Part);\npythonExt->getProxy()->getParameter(kParamPart)->setValue(part.getExtension()); // \"Part\" extension can be read in the script using self.parameters.Part.value\n\n// Add an input of type boolean and set its value\nVx::VxID kInputSwitch(\"Switch\");\npythonExt->getProxy()->addInput(kInputSwitch, VxData::Types::Type_Bool);\npythonExt->getProxy()->getInput(kInputSwitch)->setValue(false); // \"Switch\" boolean can be read in the script using self.inputs.Switch.value\n\n// Add an output of type integer and set its value\nVx::VxID kOutputControl(\"Control Mode\");\npythonExt->getProxy()->addOutput(kOutputControl, VxData::Types::Type_Int);\npythonExt->getProxy()->getOutput(kOutputControl)->setValue(0); // \"Control Mode\" int can be written in the script using self.outputs.Control_Mode.value \n\n// Add the connection container to the mechanism\nmechanism->addExtension(pythonExt);\n","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"Configurations are extensions used by mechanisms and scenes to ","type":"text"},{"text":"configure","type":"text","marks":[{"type":"em"}]},{"text":" them. By this, we mean that a configure is a set of modifications to the content that can be applied or not. The main goal is to make the mechanism or scene more reusable. Rather than having multiple copies of the object which is just a small number of differences, the configuration allows you to keep one base object and as many distinct configurations as you want.","type":"text"},{"type":"hardBreak"},{"text":"Configurations are set when the application is in editing mode before the simulation is run. They cannot be changed in simulation mode.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Basics","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When added to an object (a mechanism or a scene), the ","type":"text"},{"text":"VxContent::Configuration","type":"text","marks":[{"type":"code"}]},{"text":" can reference other extensions in the same object, allowing to modify inputs and parameters of referenced extensions or remove them from the content.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A configuration does not create extensions, the extensions must be in the object without configuration.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"An object can have multiple configurations.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Configuration is only a set of modifications to be applied to one or many referenced extensions. The type of modification is called Action.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The actions are applied to the referenced extensions when activated.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Multiple configurations can be activated at the same time, but a Configuration cannot be activated if there is a conflict between changes.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Activation can only happen while the application is in editing mode.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Configuration Actions","type":"text"}]},{"type":"paragraph","content":[{"text":"A configuration can do one of the following actions, given by enum eConfigurationAction, on a given referenced extension:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Modify (","type":"text"},{"text":"kModify","type":"text","marks":[{"type":"code"}]},{"text":") : ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When configuration is activated, selected inputs/parameters values are modified in the referenced extension; The referenced extension will be sent to the modules normally.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When a configuration is not activated, all inputs/parameters values are untouched in the referenced extension; The referenced extension will be sent to the modules normally.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"This is the default action.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Remove (","type":"text"},{"text":"kRemoveOnActivation","type":"text","marks":[{"type":"code"}]},{"text":") : ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When a configuration is activated, the referenced extension will not be sent to the modules.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When a configuration is not activated, the referenced extension will be sent to the modules normally; All inputs/parameters values are untouched in the referenced extension. ","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Add (","type":"text"},{"text":"kAddOnActivation","type":"text","marks":[{"type":"code"}]},{"text":"):","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When a configuration is activated, the referenced extension will be sent to the modules normally; Selected inputs/parameters values are modified in the referenced extension. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When a configuration is not activated, the referenced extension will not be sent to the modules.","type":"text"}]}]}]}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Configuration Conflicts","type":"text"}]},{"type":"paragraph","content":[{"text":"Two configurations will be in conflict if:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They are modifying values in the ","type":"text"},{"text":"same","type":"text","marks":[{"type":"strong"}]},{"text":" extensions.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"One configuration modifies values and the other wants to remove the extension.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"One configuration wants to add an extension, and the other wants to modify or remove the same extension.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"How it works","type":"text"}]},{"type":"paragraph","content":[{"text":"The configuration extensions are handled by the Configuration Module. The module is part of a VxApplication and does not need to be added by the application setup.","type":"text"}]},{"type":"paragraph","content":[{"text":"The activation of a configuration is not instantaneous, it requires an update so that it can be treated by the Configuration Module and propagated properly across the network.","type":"text"}]},{"type":"paragraph","content":[{"text":"The field ","type":"text"},{"text":"inputActivate","type":"text","marks":[{"type":"code"}]},{"text":" is instance data, activating a configuration in a mechanism definition won't affect which configuration is activated in the scene. An activated configuration in the definition only affects which configurations will be activated when the instance is created.","type":"text"}]},{"type":"paragraph","content":[{"text":"A Configuration in a Scene can refer to a Configuration in a mechanism instance, allowing to use of the Configuration of a scene to configure a mechanism.","type":"text"}]},{"type":"paragraph","content":[{"text":"Activating or editing a configuration must be done in editing mode. Adding references should be done when the extension is not activated. In order to have a different set of input or parameter values for a reference extension, it must be added to a configuration (with action kModify or kAddOnActivation), then the configuration must be activated. When a user edits the values of a referenced extension, the changed values will only be in effect when the configuration is activated if the configuration is activated. The code sample below shows an example.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Using the Configuration API","type":"text"}]},{"type":"paragraph","content":[{"text":"The Configuration API offers several functions to ease the edition. ","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Function ","type":"text"},{"text":"addReference()","type":"text","marks":[{"type":"code"}]},{"text":" allows you to reference an extension in a configuration, with one of the following action: ","type":"text"},{"text":"kModify","type":"text","marks":[{"type":"code"}]},{"text":", ","type":"text"},{"text":"kRemoveOnActivation","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"kAddOnActivation","type":"text","marks":[{"type":"code"}]}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The function will return a ConfigurationErrors container. If it is not empty, it is possible to inspect each configuration error to find out the problem.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Function ","type":"text"},{"text":"canAddReference()","type":"text","marks":[{"type":"code"}]},{"text":" will help you figure out if you can add a reference to an extension in a configuration.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Function ","type":"text"},{"text":"removeReference()","type":"text","marks":[{"type":"code"}]},{"text":" allows you to remove a reference to an extension in a configuration. The returned object can be kept to revert the removed extension with all of its modifications.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"To activate the Configuration, the field ","type":"text"},{"text":"inputActivate","type":"text","marks":[{"type":"code"}]},{"text":" should be set to true. It requires an update to be propagated.","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"If there is a conflict, a configuration will not be activated but will stay in that state. If the conflict gets resolved, it will activate on its own.","type":"text"}]}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use field ","type":"text"},{"text":"outputActivated","type":"text","marks":[{"type":"code"}]},{"text":" to determine activation success.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Use the function ","type":"text"},{"text":"getRuntimeErrors()","type":"text","marks":[{"type":"code"}]},{"text":" to find out a conflict in activation. ","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Function ","type":"text"},{"text":"canActivate()","type":"text","marks":[{"type":"code"}]},{"text":" should be called before setting ","type":"text"},{"text":"inputActivate","type":"text","marks":[{"type":"code"}]},{"text":" to true, to know what will be the result of the activation.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Function ","type":"text"},{"text":"restoreReference()","type":"text","marks":[{"type":"code"}]},{"text":" allows restoring a removed extension with its set of modifications.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Function ","type":"text"},{"text":"getReferencedExtensions()","type":"text","marks":[{"type":"code"}]},{"text":" allows consulting the referenced extensions with their associated actions within a configuration.","type":"text"},{"type":"hardBreak"},{"type":"hardBreak"}]}]}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"code snippet - configuring a mechanism","type":"text","marks":[{"type":"strong"}]}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"...\n// Add 4 extensions to mechanism\nmyExtension1 = VxExtensionFactory::create(MyExtension::kFactoryKey);\nmyExtension2 = VxExtensionFactory::create(MyExtension::kFactoryKey);\nmyExtension3 = VxExtensionFactory::create(MyExtension::kFactoryKey);\nmyExtension4 = VxExtensionFactory::create(MyExtension::kFactoryKey);\n \n// Sets default value\nmyExtension1->parameterA = 1;\nmyExtension1->parameterB = 2;\nmyExtension1->parameterC = 3;\n\nmyExtension2->parameterA = 4;\nmyExtension2->parameterB = 5;\nmyExtension2->parameterC = 6;\n\nmyExtension3->parameterA = 7;\nmyExtension3->parameterB = 8;\nmyExtension3->parameterC = 9;\n\nmyExtension4->parameterA = 10;\nmyExtension4->parameterB = 11;\nmyExtension4->parameterC = 12;\n\nmMechanism->addExtension(myExtension1);\nmMechanism->addExtension(myExtension2);\nmMechanism->addExtension(myExtension3);\nmMechanism->addExtension(myExtension4);\n...\n// Create a configuration\nmConfiguration = VxSmartInterface::create();\nmConfiguration ->setName(\"Configuration1\");\nmMechanism->addExtension(mConfiguration );\n \n// Configuration will modify Extension 1, remove extension 2 and add extension 4\nmConfiguration->addReference(myExtension1, VxContent::kModify);\nmConfiguration->addReference(myExtension2, VxContent::kRemoveOnActivation);\nmConfiguration->addReference(myExtension4, VxContent::kAddOnActivation); // Because the flag is AddOnActivation, myExtension4 is immediately removed from the content. It still exist with mMechanism but no module will received it.\n \n// Start edition.\nif(mConfiguration->canActivate()) // just to make sure there is no conflict\n{\n\tmConfiguration->inputActivate = true; // This removes myExtension2 and adds myExtension4.\n mApplication->update(); // requires an application update\n \n\tif(mConfiguration->outputActivated.getValue())\n\t{\n\t\t// Edit the extension 1 and 4\n\t\tmyExtension1->parameterA = -1;\n\t\tmyExtension1->parameterC = -10;\n \n\t\tmyExtension4->parameterB = 42;\n\t\t\n // Done editing\n\t\tmConfiguration->inputActivate = false;\n\t\tmApplication->update(); // requires an application update\n\t}\n\telse\n\t{\n\t\t// Handles errors\n\t\tauto& errors = mConfiguration->getRuntimeErrors();\n\t}\n}\n \n... continue edition, create a scene\nVxSmartInterface scene = VxSmartInterface::create();\n//instantiate a mechanism\nmMechInstance = VxSim::Instantiate(mMechanism);\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\nmScene->addMechanism(mMechInstance);\n \n// Activate the mechanism configuration in the scene\nVxSim::VxSmartInterface confInstance = mMechInstance.getObject()->findExtensionByName(\"Configuration1\");\nconfInstance->inputActivate = 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\n","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Graphics Objects","type":"text"}]},{"type":"paragraph","content":[{"text":"The creation of graphics objects (including Terrain) in code is a complex subject out of the scope of this guide. Please use the Vortex Editor to manipulate Gallery and its sub-objects.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Content Creation in Python","type":"text"}]},{"type":"paragraph","content":[{"text":"Content can be created in Python as well, see ","type":"text"},{"text":"Integrating Vortex Studio using Python 3","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD237/pages/3324808465"}}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Content Creation Tutorials","type":"text"}]},{"type":"paragraph","content":[{"text":"See the following C++ and Python tutorials for example on content creation and manipulation.","type":"text"}]},{"type":"paragraph","content":[{"text":"Content Creation Tutorial","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD237/pages/3324806892"}}]}]},{"type":"paragraph","content":[{"text":"Content Parsing Tutorial","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD237/pages/3324815282"}}]}]},{"type":"paragraph","content":[{"text":"Content Update Tutorial","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD237/pages/3324816339"}}]}]},{"type":"paragraph","content":[{"text":"Content Creation Tutorial (Python 3)","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD237/pages/3324814971"}}]}]},{"type":"paragraph","content":[{"text":"Content Parsing Tutorial (Python 3)","type":"text","marks":[{"type":"link","attrs":{"href":"/wiki/spaces/VSD237/pages/3324817204"}}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}],"version":1}

Browser not supported