Description
VG_GraspEditor is a public script that provides a tutorial on the minimal VG API functions for accessing grasps existing in the VG grasp database as well as using the labeling interface.
A VG_GraspEditor Prefab that uses this script (as shown in above image) is added in VirtualGrasp\Resources\GraspEditor. This prefab can be added into any unity scene and allows runtime adding, deleting and reviewing primary grasps (see Jump Primary Grasp).
Important: Please do all grasp editing in the Unity Editor in order to modify the grasp database. When using VG_GraspEditor on Android, the grasp database is not modified to prevent users from accidentally modifying an application.
Editing Grasps
Using VG_GraspEditor you can add dynamically synthesized grasps as primary grasps into the grasp DB in runtime.
- The VG_GraspEditor Prefab shows up as an “editing pad” with a number of buttons to allow adding, deleting, deleting all, stepping through primary grasps and experimenting with the Jump Primary Grasp interactions on the object.
- This editing pad is also an interactable object so that it can be grasped and moved close to any object(s) on which grasp editing is needed.
- The grasp editing will be performed on the object currently grasped in one hand. If no object is grasped by any hand, all buttons (currently the text next to it) are grayed out to show there is no valid action on this button.
- Once an object is grasped by a hand, the relevant grasp editing buttons are enabled by showing up the button text (in black).
- When an object’s current interaction type is Trigger Grasp, Jump Grasp or Preview Grasp, the grasps are dynamically synthesized. Therefore the Add grasp button is enabled to add the current grasp into the grasp db.
- VG_GraspEditor GUI has an option Editing Interaction Type to allow developers to choose the main interaction type to use when adding primary grasps. The first time pushing Toggle button will switch the grasped object to the selected editing interaction type, and later the Toggle button will toggle between this type and Jump Primary Grasp for adding and reviewing added primary grasps respectively. This allows developer to choose most convenient Editing Interaction Type for adding grasps without interfering with the desired project setting for the objects.
- If you want to immediately delete a just added grasp, click the Delete grasp button without re-grasping the object.
- If you want to delete all grasps added on this object with this hand, click the Delete all grasps button.
- If you want to experiment with Jump Primary Grasp interaction with the primary grasps, click Toggle interaction button to toggle to Jump Primary Grasp interaction type. When you then re-grasp this object, the primary grasp closest to the current wrist pose will be applied.
- When the current interaction is Jump Primary Grasp, you can also step through to review all the primary grasps by clicking the Step grasp button.
- By stepping through grasps, you can also click the Delete grasp button to delete unwanted grasps.
- Remember to add primary grasps for both left and right hands for a given object, otherwise when the object is set to jump primary grasp interaction type, the hand without primary grasps added will not be able to grasp the object.
- There is no need to press any button to save grasps, simply close the application, and the added grasps will be saved into StreamingAssets/VG_Grasps/grasps.db in your project folder.
Important: Note that during the grasp editing, only edited grasps are saved to the database. The toggled interaction type is not saved in the scene and will not overwrite your project settings for the object.
Using Grasps in Runtime
To use primary grasps for an object, you need to set the object’s interaction type to be Jump Primary Grasp. To do that you can
- either add a VG_Interactable component to the object and to specify for this object locally,
- or specify in Global Grasp Interaction Settings if you want all objects to be only grasped using added primary grasps,
- or use the API function SetInteractionTypeForObject to change this object to use primary grasp in runtime,
- or use the API function SetGlobalInteractionType to change all the objects to use primary grasps in runtime.
Important: Once an object uses Jump Primary Grasp as the interaction type, it assumes the hand that want to grasp it has added primary grasps for the object. So if you only added primary grasps on one hand, then the other hand will not be able to grasp the object. The primary grasps added in one hand currently can not be mirrored directly to the other hand side because mirroring of grasps is not as simple as mirroring just hand gesture since it involves accurately detecting the object symmetry as well.
Important Note on the Files
The information on added grasps will be stored in the grasp .db file which you will find in each project’s StreamingAssets/VG_Grasps/ folder by default.
The VirtualGrasp plugin will automatically load this file at initialization (e.g. start the game), and save it at releasing (e.g. stop the game).
By this follows that:
- All scenes will use the same added grasps, since the .db file is saved in and loaded from the project.
- If you you are using a version control system and want to share the data with others, you have to commit the .db file to the repository.