Matterport SDK Tutorial

Matterport

What is matterport  ?

Matterport is a software as a service platform we you can create 3D models of any physical space using 360° photos 

What is SDK ?

SDK stands for Software Development Kit which contain a set development tools and packages through other developer can create there own application for a specific platform 


Application Using Matterport SDK:

Mattertag editor 



Here we are gonna create a web application using Matterport SDK to edit the the mattertag in the matterport showcase 
matterport  contains two types of  SDK
  1. SDK for Embed
  2. SDK bundle

SDK for Embed 

With this SDK developer can control the 3D showcase of matterport in there web application.
for example : we can add tags in the space , change their appearance etc

SDK Bundle

With this SDK developer get direct access to the 3D engine , renderers,scene graph and much more
for example : we can add custom 3D objects in the space 


Mattertag Editor has been made using SDK for Embed , the whole SDK has written in javascript language , So here i will show you the step by step work flow this application to understand it better

before embeding the matterport showcase in your web app we need the two important things 

  1. SDK key
  2. Model SID
SDK key can be access from the developers option in your matterport account and the model SID is unique Id given every 3d space created in matterport which can be access through spaces option 


1) Basic HTML Template 


This html container basic structure of our web app ,which will display our matterport showcase , Space SId , table containing the information about the mattertag and all the editing options .
If you observe the line no : 6 , this is a script which contains SDK for Embed source code imported using CDN (content delivery network ) method 

2) Creating a custom server for development purpose

As we know that SDK is written in Javascript so we will express framework to create a server for our we app for testing and debugging the code 
    

  • first creating a folder named Matterport on which we store all the folders 

  • after that we install express framework into this directory using NPM which is a package manager for javascript

  •   after this step we will create the a server.js file which will use to run the server 

  • We will save all the necessary file in a public folder

  • Now come the most important step is to create the app.js file where we use SDK . I will break down all the steps of the code to get the clear understanding 
    1. First we initialize all the variable which is being used throughout the code

        code in  line 13 is used to check the user's browser is firefox or not  because firefox has some issue in rendering the matterport showcase .

            2. Then we will connect all the variables with html elements so that we can alter them using javascript


        3. Then we will load the matterport showcase using html iframe element in the web app , when the web app loads first time we will load the default modelSID initialized eariler but we can change space using the input of modelSID from Space SID section of html


     4. when iframe start loading then we will connect it through matterport SDK using showcaseload() function


this function is asynchronous type of function which will return a promise that it will wait until the sdk connect , then execute further codes

        5. After that we will execute loadedShowcaseHandler() function which contains multiple other function within it , first we fetch the mattertag data associated to the model using mpsdk.Matterport.getData() function from the SDK.



   This we run two function 
  • populateTags()
  • setupFunctionality()
    populateTags function will populate all the tags information into tables 


    setupFunctionality function will create a row from each tags 


populateTags will call addToTable() function will create a structure for row to feed the data in (label , description , colour, gotolink,delete) columns 

 setupFunctionality() will call addTagListener function for every tag , it will activate the eventListener when we click on that area to make changes


Here we have used SDK function (mpsdk.Mattertag.navigateToTag()) which when activated will move the sweep to the tag location instantly .
when addEventListener get activated then it will call ChangeInfo function 


First the function will take the input from the user and set the change variable to focus() and wait until the user hit the enter key , once the user hit the enter the change variable convert to blur() and call the clickAway() function 


this function will first remove blur function from the change variable and check whether user has given any input in each cell of the table or not using ternary operator , if the user have given the valid input then it will call updataTag function with label and description and input , but if they click again on the cell they it will call back to changeInfo function  


this function will first create a empty dictionary for label and description and make the changes permanent in cell of table using the SDK function (mpsdk.Mattertag.editBillBoard())


As we know earlier that we have created a variable (isFireFox) which checks whether the user's browser in firefox or not, So if we get to know the it other than Firefox than we initiate focus detect function 

this function will first create a variable called eventListener which will track the movement of the mouse in window and check if the  users click to place the tag in space then it will check whether the clicked area is iframe or not , if the condition get fullfilled then it nagvigate the user to that new tag using placetag function 



In the Web App We have created four Editing Options 
  1. Place new tag
  2. Import tags
  3. Remove all tags
  4. Export tags
lets start with place new tag and see how it works , when the user click this button then addTagBtn variable get activated 

 we use SDK function (mpsdk.mattertag.add) function to initiate the adding tag procedure which will set the default label , description , location information to that tag and give that tag a SID no 


and using mpsdk.Mattertag.getData function will we provide the tag a necessary parameter for further use.


after getting those data we will follow the same procedure to put it inside the table using allToTable and addTagListener function , but before updating the the coordinates of the new tag in the space first it will the check the browser , if it is found to be Firefox then we call a special function called as overlayDetect () for further task  


here we use  the sdk function (mpsdk.Renderer.getWorldPositionData) which convert the screen position into 3d world position , actually it mean basically it convert 2D coordinates to 3D coordinates ,
and then call the updateTagPos with 3d coordinate position as input 


This function will use sdk function (mpsdk.mattertag.editPosition) to update the x,y,z coordinates of the tag.
There is another SDK function (mpsdk.Pointer.intersection.subscribe) which is use to check whether the 3d coordinate are in the model or sweep area , if yes then only initiate the updataTagPos function for updation

Ok now lets move on to import button and disscuss about its workflow, so when the user click on import button then "importBtn" variable get initiated 

  
this function first create input element in html , when user type the file name then it calls  importFile function to import it from the local system 

this function first reads the file type , if it is  JSON format then it proceed further and call replaceShowcaseTag function to replace all the sid no of old tags with new one  using  "mpsdk.Mattertag.remove" function and populate the new tags in the space using populateTag function  . It also update the parameters the tags like mattertag.media which is used to add media files like photo and videos


Now Its time for Remove button , after clicking this button "removeBtn" variable get initiated which call removeAllTags function 


here we use "mpsdk.Mattertag.remove"function to remove all the tag from the model database. and also update the html tables  

and the final one "Export Button", we use exportBtn variable to call exportTags function which convert the data of tags into JSON format further call download function which download the json file into local system

And this is how we complete the Mattertag Editor Application using Matterport SDK. 😉


Here are the list of SDK functions which are being used in this project :

  1. mpsdk.Matterport.getData()
  2. mpsdk.Mattertag.remove()
  3. mpsdk.Mattertag.navigateToTag()
  4. mpsdk.Mattertag.editBillBoard()
  5. mpsdk.Mattertag.add()
  6. mpsdk.Renderer.getWorldPositionData()
  7. mpsdk.Mattertag.editPosition()
  8. mpsdk.Pointer.intersection.subscribe()
  9. mpsdk.Mattertag.remove()

For full documentation for Matterport sdk visit to this site : Matterport SDK

 Here is the full code of app.js file of this project :

Comments

Post a Comment