architwin 1.0.32 → 1.0.33

package/README.md

@@ -24,11 +24,13 @@ ArchiTwin Library
   - [Loading and Interacting with 3D/2D Objects](#loading-and-interacting-with-3d2d-objects)
     - [What is an Object?](#what-is-an-object)
     - [Loading Objects](#loading-objects)
+    - [Accessing List of Rendered Objects and Object Structure](#accessing-list-of-rendered-objects-and-object-structure)
     - [Transforming Objects](#transforming-objects)
       - [Transforming Object by clicking it](#transforming-object-by-clicking-it)
-      - [METHOD 2: Programmatically transforming objects](#method-2-programmatically-transforming-objects)
+      - [Programmatically transforming objects](#programmatically-transforming-objects)
     - [Undoing and Redoing Transformation Changes](#undoing-and-redoing-transformation-changes)
     - [Adding Objects To Your Space](#adding-objects-to-your-space)
+      - [Programmatically Add Objects](#programmatically-add-objects)
     - [Creating a Customizable Media Screen](#creating-a-customizable-media-screen)
       - [Adding a Media Screen](#adding-a-media-screen)
       - [Media Screen Parameter Reference](#media-screen-parameter-reference)
@@ -639,6 +641,85 @@ import * as atwin from 'architwin'
 
 atwin.nearbyObjects //Gets updated everytime the User camera moves
 ```
+
+### Accessing List of Rendered Objects and Object Structure
+
+Objects that have been loaded and **rendered** into the 3D space are stored in an array called _3DXObjects which you can access by doing calling it this way
+
+```typescript
+atwin._3DXObjects
+```
+
+All the elements in this array implement the `IObjectData` interface. Each element in the array contains all the data you would need manipulate the object.
+
+*interface used* (TS)
+```typescript
+interface IObjectData {
+  collider?: any
+  object: IShowcaseObject
+  component: Scene.IComponent
+  node: Scene.INode
+  type?: string
+}
+```
+
+Each object element inside `atwin._3DXObjects` contains the value keys:
+
+**collider:** Collider components define the shape of an 3D/2D object for the purposes of physical collisions. A collider, which is invisible, does not need to be the exact same shape as the GameObject’s mesh.
+
+**object:** The object key is an object that implements the `IShowcaseObject` interface. This is one of the most important values as the object contains all the information about an object such as its id,name,position,rotation,scale,amazon_uri link, and etc. You can look at the interface below to view the full makeup of the object key.
+
+*interface used* (TS)
+```typescript
+export interface IShowcaseObject {
+  id: number;
+  showcase_id: number;
+  object_id: number;
+  user_id: number;
+  object_position: {
+    x: number;
+    y: number;
+    z: number;
+  };
+  object_rotation: {
+    x: number;
+    y: number;
+    z: number;
+  };
+  object_scale: {
+    x: number;
+    y: number;
+    z: number;
+  };
+  autoplay: boolean;
+  autoplay_distance: number;
+  offset_position: number;
+  offset_rotation: number;
+  position_unit: string;
+  showcase_object_name: string;
+  is_deleted: boolean;
+  is_read: boolean;
+  is_new: boolean;
+  object_data: I3DObject;
+}
+```
+
+**component:** This objects contains functions and variables responsible for intializing, updating, and destroying a rendered objects mesh, texture, etc. This object also contains the three.js instance. Since the 3D space is rendered with Three.js under the hood. You can use this instance to invoke methods made available by three.js. This gives you a lot of flexibility and control provided you know how to use it. This documentation will not cover Three.js specific methods. Visit their [official website](https://threejs.org/) if you want to learn more about it.
+
+**node:** The node is responsible for managing the lifecycle of a 3D/2D objects. The node can be used to `start()` and `stop()` a rendered model. Invoking `start()` will render the model into the scene while `stop()` will destroy it and remove it from the scene. 
+
+**type:** A string that states the file or object type of a 3D/2D object. The file type could be any of the following
+
+**Valid Types**
+
+| type | context | description | 
+| :----: | :----: | :---: |
+| GLB | 3D model | A 3D model with or without animation |
+| FBX | 3D model | A 3D model with or without animation |
+| FRAME | Media Screen | A customizable [media screen](#creating-a-customizable-media-screen) |
+| ZIP | slideshow | A zip file rendered as a image slideshow |
+
+The `atwin.selectedObject` variable is an example of a variable that implements this interfacea and contains this data.
 ### Transforming Objects
 
 Transformation such as translate, scale, and rotate are actions used to manipulate objects in a 3D space. These transformations allow you to change an object's position, size, and orientation respectively. 
@@ -670,7 +751,7 @@ If you wish the to access the object data of the object that has been clicked on
 console.log("Selected object data",atwin.selectedObject)
 ```
 
-#### METHOD 2: Programmatically transforming objects
+#### Programmatically transforming objects
 
 If you need to transform the position,rotation, and scale of one or more objects without having to use the mouse then the 
 `setObjectTransformation()` method will allow you to do so. The method accepts the following parameters 
@@ -688,10 +769,10 @@ The **transform** object contains the following key-value pairs. These values wh
 | object_rotation | Vector3 | yes | none | Valid x,y,z coordinates|
 | object_scale | Vector3 | yes | none | Valid x,y,z coordinates|
 
-In this example, we will get a random 3D model from the array of rendered objects stored in `atwin._3DXObject` and manipulate it using the method. The object we will be manipulating in this example is a 3D model with a file type of GLB (You can also transform other object types such as a media screen). This will return a javascript object that contains the rendered object's data which implement the `IObjectData` interface. You can know more about that by going to this section
+In this example, we will get a random 3D model from the array of rendered objects stored in `atwin._3DXObjects` and manipulate it using the method. The object we will be manipulating in this example is a 3D model with a file type of GLB (You can also transform other object types such as a media screen). This will return a javascript object that contains the rendered object's data which implement the `IObjectData` interface. You can know more about that by going to this section
 
 ```typescript
-const targetObject = atwin._3DXObject.find(obj => obj.object.object_data.object_type == 'GLB')
+const targetObject = atwin._3DXObjects.find(obj => obj.object.object_data.object_type == 'GLB')
 
 const transform = {
   object_position: {
@@ -742,8 +823,14 @@ In order to add an object, you may use the `addObjectToScene()` method.
 
 | parameter | type | required | values |
 | :----: | :----: | :---: | :---: |
-| object | I3DObject | yes | object |
-| option | object | no | object |
+| object | I3DObject | yes | object payload |
+| option | ObjectConfig | no | valid config object |
+
+There are two ways you can use the `addObjectToScene()` method. We will go through each one 
+
+#### Programmatically Add Objects
+
+If you wish to add new object to your space to a pre-defined position, you can use the `addObjectToScene()` method an pass the object data along 
 
 ```typescript
 atwin.addObjectToScene(object:I3DObject, option:object)
@@ -776,7 +863,7 @@ The **transform** object is an object that contains the following key-value pair
 
 By default, your media screen will show a blank white canvas if you set the mediaUrl parameter of the `addMediaScreen()` method as an empty string or `undefined`.
 
-**IMPORTANT:** The link to your media you provide to the mediaUrl **MUST** be publicly accessible and have the appropriate CORS headers, otherwise, you media will not load into the media screen.
+**IMPORTANT:** The link to your media you provide to the mediaUrl **MUST** be publicly accessible and have the appropriate CORS headers, otherwise, your media will not load into the media screen.
 
 There are many ways you can use this method to add a media screen to your 3D space. Let's go through each one.
 
@@ -806,9 +893,9 @@ atwin.addMediaScreen('',transform)
 
 If done correctly, you should be able to see your media screen in your intended position. This method is useful if you already the have position,rotation, and scale values stored in a database or possibly in a local array
 
-**Method 2: Adding with click method with getTargetPosition**
+**Method 2: Adding with click method using getTargetPosition**
 
-The library has several helper methods that provide a range of commmon functionalities to help you achieve certain actions easier. If for example, you do not have your inteneded position coordinates stored in the database or in a local area and wish to click a specific area of the 3D space and get that the coordinates of the area you clicked, you may do some by using the `getTargetPosition()` helper method in tangent with the `addMediaScreen()` method to do so. You can [click here](#getting-the-coordinates-of-a-clicked-area-in-the-3d-space) to know more about the `getTargetPosition()` method
+The library has several helper methods that provide a range of commmon functionalities to help you achieve certain actions easier. If for example, you do not have your intended position coordinates stored in the database or in a local area and wish to click a specific area of the 3D space and get that the coordinates of the area you clicked, you may do some by using the `getTargetPosition()` helper method in tangent with the `addMediaScreen()` method to do so. You can [click here](#getting-the-coordinates-of-a-clicked-area-in-the-3d-space) to know more about the `getTargetPosition()` method
 
 Here is an example of how you can use the two methods together. This is just one example, it is up to you on how you wish to combine different methods provided by the library
 
@@ -831,7 +918,7 @@ atwin.getTargetPosition(myCallbackFunction)
 ```
 
 #### Attaching an image or video to a Media Screen
-You can think of a media screen as a blank canvas whose content is totally up to you. If you wish to set the property media screen content, you may use the `attachMediaScreenContent()` method.
+You can think of a media screen as a blank canvas whose content is totally up to you. If you wish to set the content of the media screen, you may use the `attachMediaScreenContent()` method.
 
 **Attach Media Screen Parameters**
 
@@ -841,9 +928,9 @@ You can think of a media screen as a blank canvas whose content is totally up to
 | mediaUrl | string | yes | none | valid public url to the media|
 | mediaType | string | no | image | 'image' or 'video' |
 
-**IMPORTANT:** The link to your media you provide to the mediaUrl **MUST** be publicly accessible and have the appropriate CORS headers, otherwise, you media will not load into the media screen.
+**IMPORTANT:** The link to your media you provide to the mediaUrl **MUST** be publicly accessible and have the appropriate CORS headers, otherwise, your media will not load into the media screen.
 
-In this example, we are using a link pointing to the media stored in an s3 bucket as the mediaUrl and a random media screen id. You will have to substitute the id with an actual id of a rendered media screen.
+In this example, we are using a link pointing to the media stored in an s3 bucket as the mediaUrl and a random media screen id. You will have to substitute the id with an actual id of a **rendered** media screen.
 
 Example with image:
 ```typescript
@@ -863,10 +950,10 @@ atwin.attachMediaScreenContent(targetMediaScreenId,validUrl,'video')
 
 When setting a video as the media screen content. You can use the `setVideoPlayback()` method to programmatically play,pause,mute,and unmute a video. You can navigate to the [playback controls section](#setting-video-playback-in-the-space) to learn more about the method. Here is an example on how to use it. 
 
-In this example, we are getting a random media screen from the `atwin._3DXObject` array which contains all the objects rendered in the space. Media screens whose media type is a video will have a variable called `planeElement` inside the object's `component` which contains an HTML video element that we can manipulate using the `setVideoPlayback()` method. Please take note that this variable is not acessible if the media type of the media screen content is an image.
+In this example, we are getting a random media screen from the `atwin._3DXObjects` array which contains all the objects rendered in the space. Media screens whose media type is a video will have a variable called `planeElement` inside the object's `component` which contains an HTML video element that we can manipulate using the `setVideoPlayback()` method. Please take note that this variable is not accessible if the media type of the media screen content is an image.
 
 
-*Interface used*
+*Interface used* (TS)
 ```typescript
 export interface IObjectData {
   collider?: any
@@ -879,7 +966,7 @@ export interface IObjectData {
 
 *Example*
 ```typescript
-const randomMediaScreen:IObjectData = atwin._3DXObject.find(obj => obj.object.object_data.object_type == 'FRAME')
+const randomMediaScreen:IObjectData = atwin._3DXObjects.find(obj => obj.object.object_data.object_type == 'FRAME')
 
 setVideoPlayback('play',randomMediaScreen.component.planeElement)
 ```
@@ -888,7 +975,7 @@ You can use the [transform controls](#transforming-objects) to change the positi
 
 ### Getting the coordinates of a clicked area in the 3D space
 
-The 3D space you walk around is a three dimensional mesh under the hood. Every point in this space has an x,y,z coordinates. These are coordinates are important since it allows us to anchor objects into the 3D space and navigate around it. You may at times need the ability to get the coordinates of an area in the space. You can do this by utilizing the `getTargetPosition()` method. 
+The 3D space you walk around in is a three dimensional mesh under the hood. Every point in this space has an x,y,z coordinate. These coordinates are important since it allows us to anchor objects into the 3D space and navigate around it. You may at times need the ability to get the coordinates of an area in the space. You can do this by utilizing the `getTargetPosition()` method. 
 
 **Parameter Reference**
 | parameter | type | required | default | values |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "architwin",
-  "version": "1.0.32",
+  "version": "1.0.33",
   "description": "ArchiTwin Library for Matterport",
   "main": "./lib/architwin.min.js",
   "types": "./lib/architwin.d.ts",
@@ -29,7 +29,6 @@
   "dependencies": {
     "@superviz/matterport-plugin": "^0.8.7",
     "@superviz/sdk": "^4.10.0",
-    "architwin": "^1.0.25",
     "aws-sdk": "^2.1385.0",
     "axios": "^1.4.0",
     "jszip": "^3.10.1",