Conventions

Conventions that have been applied to the example code to enable relationships between 3D models and Oracle application data. The following conventions can be inferred from the code as needed. A few that are of note:

Authentication / Authorization
  • This is a demo app to illustrate the art-of-the-possible. It requires credentials to integrate with OIC, but those credentials are single-user based. Do not use this convention for anything other than demos. You must implement a proper sign-in process if you intend to implement components of this app in a real-world solution.

  • The project uses an #error tag in files that implement the username/password management for demonstration. You can remove this tag to get the app to compile. But you should implement a proper authentication and authorization scheme in a real-world application.

3D Model — Use the included 3D model as a reference to these comments.
  • The app expects a relatively simple node hierarchy in the scenekit file. The root node is usually a shell of the model. That shell can be dragged to set the placement of all of the subnodes under it. The root node also acts as an encapsulation when gauges or generated content apply to a particular object.

    • A hierarchal node placement also ensures that you don’t “tap through” the outside of the 3D model into unseen nodes that may exist on the inside of the model.

  • The node name matters! The node name is used to identify the part that the user has selected. In turn, that name is then used when searching for metadata such as specifications or other knowledge from external data sources. Names do not need to be unique, but there could be repercussions from giving more than one node the same name. This also applies to the procedure animations definitions; node names are how the procedures know what nodes to act upon.
  • Nodes act in a hierarchy. If you apply a change to a parent node, it will usually affect all of the child nodes in the structure.
  • The parent node’s origin affects the placement of the digital twin. The AR application is configured to expect that the 3D object is sitting on the horizontal plane. Therefore, the zero point for the Y origin should be the bottom of the model. The X and Z axis should align to the middle of the model on their respective planes.

  • Nodes are expected to have two materials: 1) a default material that supplies the normal look and feel for a node, and 2) a highlight material that the node will change to when it is long-pressed. The naming convention is always DefaultMaterial and HighlightMaterial.

Data
  • The objective of this app is to pull as much information from appropriate Oracle applications when possible. This includes information about the selected node, IoT data about the device, and even the procedures that are demonstrated to service the device. Therefore, there are data conventions that have been created as models which can be decoded from JSON data and dictate the actions of the application. For instance, an ARContextNode object can be decoded from JSON to provide the specifications and procedures for any node selected.

    • The ARContextNode object supplies the following for each node that is tapped. None of the items are required; it is possible for each node in a model to implement some or all of what the ARContextNode supplies.

      • Name — the node name used to map data and the name of the node in the 3D model.

      • Description — A string that can be used for describing what the node is.

      • Specifications — A set of objects that define the rows that will be appear in the specifications section of the context table of the UI.

      • Action Animations — The animation or set of animations that will play when a node is tapped with three fingers.

      • Sensors — An array of sensor objects that supply the key that matches an IoT data payload, placement of the sensor, and an image to supply as the background of the sensor.

      • Procedures — An array of procedures that will walk the user through interacting with the model in a step-by-step manner that includes text and animation.

  • An offline data mode is built in to the app for two purposes: 1) to enable functionality when Internet connectivity is not available, and 2) to demonstrate how to configure potential data sources to supply information to the application. Files in the Application/Models/Simulator folder mimic API responses that can arrive from real APIs. These files can help with understanding what data is supplied to the app.
Note: These are not real-world API calls to Oracle apps and have been updated to enable local data use. Do not use them for anything more than example reference.

The next section discusses the app user interface.