From ed4a951d46d3454ef074c0c6d5616ee4a64d0bd9 Mon Sep 17 00:00:00 2001 From: adachille Date: Mon, 8 May 2017 09:38:16 -0400 Subject: [PATCH] Added part 7 Twine documentation --- _twine/part2.md | 3 +- _twine/part3.md | 10 ++-- _twine/part4.md | 8 +-- _twine/part5.md | 10 ++-- _twine/part6.md | 26 ++++++--- _twine/part7.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 176 insertions(+), 22 deletions(-) create mode 100644 _twine/part7.md diff --git a/_twine/part2.md b/_twine/part2.md index 227decb..5d65ba7 100644 --- a/_twine/part2.md +++ b/_twine/part2.md @@ -15,8 +15,7 @@ To run the example, follow the steps below: At this point, the 3D models and text associated with the story image should appear on your phone. -**NOTE:** -Alternatively, instead of printing the story images for step 1, you can simply point your phone at the images on your computer screen. However, the 3D models may be rotated in an unpredictable way, so it is recommended you print the images. +>**NOTE:** Alternatively, instead of printing the story images for step 1, you can simply point your phone at the images on your computer screen. However, the 3D models may be rotated in an unpredictable way, so it is recommended you print the images. The source code for this example can be found in this [GitHub directory](https://github.com/argonjs/understanding-argon-twine). diff --git a/_twine/part3.md b/_twine/part3.md index 75d59c4..131eab5 100644 --- a/_twine/part3.md +++ b/_twine/part3.md @@ -3,7 +3,7 @@ layout: page title: 'Part 3: Writing a simple Argon-Twine experience' --- -> This lesson uses the first [example](https://github.com/blairmacintyre/oldfashioned/tree/master/examples/) from github.
Import the text file into Twine to open the project. +> This lesson uses the first [example](https://github.com/blairmacintyre/oldfashioned/tree/master/examples/) from GitHub.
Import the text file into Twine to open the project. ## Creating a Story in Twine @@ -14,7 +14,7 @@ After creating a new project, you will be directed to the Twine editing page. At It is important to note that an Argon-Twine project is separated into three different components, the passages (written in the OldFashioned format), a story CSS stylesheet, and a JavaScript component. ## Writing the JavaScript Component -Let's begin by opening up the JavaScript component for editing. In any Argon-Twine project, you should begin by doing a "passage-cleanup", which removes any passage entities. For simple projects the following code will suffice. +Let's begin by opening the JavaScript component for editing. In any Argon-Twine project, you should begin by doing a "passage-cleanup", which removes any passage entities. For simple projects the following code will suffice. ```javascript @@ -86,7 +86,7 @@ Macro.add(['append3d', 'replace3d'], { ## The "Start" and "StoryInit" passages Now we move to the simpler part: the passages component. Navigate to the grid view of the project. You should see an untitled passage. Open the editor for the passage and name it `Start`. This passage will be the beginning of any AR experience you create with Twine. -**NOTE:** The first passage we create must be the `Start` passage. +> **NOTE:** The first passage we create must be the `Start` passage. But before we begin editing this passage, let's create a new passage and name it `StoryInit`. `StoryInit` is a special passage that is used to make any preparations that must be done before beginning the AR experience. Among other actions, it can be used to initialize story entities. In the passage editor for `StoryInit`, we will add a story-entity consisting of two 3D objects, a box and a sphere. We will call this entity, quite simply, `box-and-sphere`. Add the following code to the `StoryInit` passage. @@ -101,7 +101,7 @@ But before we begin editing this passage, let's create a new passage and name it Notice that the attributes of these 3D objects are readily customizable. Another important point is that attributes like `radius`, `width`, `height`, and `depth` are in units of meters. ## Adding Passage Entities -Now we can finally get into the core of the creation process. We will open up the editor for the `Start` passage again and add some basic text that will be overlayed onto the screen when we run the project. We will also add a passage-entity consisting of a simple green sphere. Add the following code to the `Start` passage. +Now we can finally get into the core of the creation process. We will open the editor for the `Start` passage again and add some basic text that will be overlayed onto the screen when we run the project. We will also add a passage-entity consisting of a simple green sphere. Add the following code to the `Start` passage. ```html @@ -139,6 +139,6 @@ This is a third AR scene. Click [[second|second]] to go to the second scene, or ``` ## Exporting the Project -Now let's export and use our experience! From the Twine dashboard, click the cog icon in the upper right corner of your AR project and click the "Publish to File" button, which will create an html file that will hold your AR experience. To view this example, you need to serve it to the Argon browser running on an iOS device. If you view it in a regular browser, you will simply see a white background, because the background video reality can only be provided by Argon.Simply find a way to store this file on the Internet, for example, through GitHub pages, and then navigate to the file using the Argon4 application. +Now let's export and use our experience! From the Twine dashboard, click the cog icon in the upper right corner of your AR project and click the "Publish to File" button, which will create an html file that will hold your AR experience. To view this example, you need to serve it to the Argon browser running on an iOS device. If you view it in a regular browser, you will simply see a white background, because the background video reality can only be provided by Argon. Simply find a way to store this file on the Internet, for example, through GitHub pages, and then navigate to the file using the Argon4 application. Congratulations, you now have the tools to create simple AR experiences with Twine! Next, we will take a look at CSS styling in Twine. \ No newline at end of file diff --git a/_twine/part4.md b/_twine/part4.md index 5b0c324..9e273c6 100644 --- a/_twine/part4.md +++ b/_twine/part4.md @@ -3,13 +3,13 @@ layout: page title: 'Part 4: CSS Styling in Twine' --- -> This lesson uses the first [example](https://github.com/blairmacintyre/oldfashioned/tree/master/examples/) from github.
Import the text file into Twine to open the project. +> This lesson uses the first [example](https://github.com/blairmacintyre/oldfashioned/tree/master/examples/) from GitHub.
Import the text file into Twine to open the project. ## Utilizing CSS Styling -You can utilize CSS for styling an Argon experience's layout, font, and presentation. We will be adding some CSS styling to the Twine expererience we created in the last lesson. +You can utilize CSS for styling an Argon experience's layout, font, and presentation. We will be adding some CSS styling to the Twine experience we created in the last lesson. -To create storywide styling, you must reference the story's id: `story`. We can style our story in a multitude of different ways. For example, we can specify "pointer events", which allow you to control when a graphic element becomes the target of mouse elements. "Auto" applies to all events. Other possible styling we can do includes choosing our font families, specifying background color, positioning our CSS elements, etc.. +To create storywide styling, you must reference the story's id: `story`. We can style our story in a multitude of different ways. For example, we can specify "pointer events", which allow you to control when a graphic element becomes the target of mouse elements. "Auto" applies to all events. Other possible styling we can do includes choosing our font families, specifying background color, positioning our CSS elements, etc. ```css @@ -25,7 +25,7 @@ To create storywide styling, you must reference the story's id: `story`. We can ``` -Using CSS styling, we can also influence how Argon treats obejcts that are in focus and those that are out of focus. To style elements that are in focus, simply style the `argon-focus` class, and for those that are out of focus, use the `argon-no-focus` class. +Using CSS styling, we can also influence how Argon treats objects that are in focus and those that are out of focus. To style elements that are in focus, simply style the `argon-focus` class, and for those that are out of focus, use the `argon-no-focus` class. Add the code below and notice how in this example we make objects that are not focused notably more transparent. diff --git a/_twine/part5.md b/_twine/part5.md index 77c3b56..7f0e20a 100644 --- a/_twine/part5.md +++ b/_twine/part5.md @@ -3,13 +3,13 @@ layout: page title: 'Part 5: Panoramas' --- -> This lesson uses the second [example](https://github.com/blairmacintyre/oldfashioned/tree/master/examples/) from github.
Import the text file into Twine to open the project. +> This lesson uses the second [example](https://GitHub.com/blairmacintyre/oldfashioned/tree/master/examples/) from github.
Import the text file into Twine to open the project. ## Argon Panoramas The default background for Argon is the view offered by the live video camera on the phone or tablet. Instead of the video, you can substitute a 360-degree panoramic image as the background. Panoramas offer a number of compelling design options. If the user cannot get to a specific location, such as a museum or historic site, the panorama can convey what the site looks like. The AR experience can play over the panorama. -To display a panoramic backgroud, Argon needs an image in a special format called an ‘equirectangular projection.” You can make such a photo yourself using a relatively inexpensive panoramic camera such as the [Ricoh Theta S](https://theta360.com/en/about/theta/s.html). You can also take multiple images with a DLSR camera and stitch them into an equirectangular projection using a stitcher program such as [PTGui](https://www.ptgui.com). The resulting image should have an aspect ratio (width to height) of 2-1. 5000x2500 pixels is a good size. If the image is too large, it may fail to load. Once you have the equirectangular image as a .jpg or .png file, then you can create the panorama in Argon. +To display a panoramic background, Argon needs an image in a special format called an ‘equirectangular projection.” You can make such a photo yourself using a relatively inexpensive panoramic camera such as the [Ricoh Theta S](https://theta360.com/en/about/theta/s.html). You can also take multiple images with a DLSR camera and stitch them into an equirectangular projection using a "stitcher" program such as [PTGui](https://www.ptgui.com). The resulting image should have an aspect ratio (width to height) of 2-1. 5000x2500 pixels is a good size. If the image is too large, it may fail to load. Once you have the equirectangular image as a .jpg or .png file, then you can create the panorama in Argon. ## Adding the Panorama Macros Let's begin by creating a new Twine story and entering the JavaScript editor. Remember that the first code you must add to any AR Twine experience is the "passage-cleanup". For this experience, the same code as the previous example will suffice. @@ -20,7 +20,7 @@ The first macro we must define is `createPanorama`. This macro will be called in the `StoryInit` passage and be used to initialize panoramas that we may later use in our Twine passages. It takes in three arguments, a name, a dataset url, and a string containing the latitude, longitude, and altitude, of the location of the panorama. -We will also be creating a short helper function for our createPanorama macro. Add the code below. +We will also be creating a short helper function for our `createPanorama` macro. Add the code below. ```javascript @@ -121,9 +121,9 @@ Click [[next|second]] to see how 3D objects look when placed on a panorama. Note that `aquarium` should be replaced with the name corresponding to the panorama image you wish to show in the scene. ## Overlaying 3D Objects onto Panoramas -With our next passage, let's try to overlay our panorama with some 3D objects. Think back to tutorial 3. How did we add 3D objects to a scene? +With our next passage, let's try to overlay our panorama with some 3D objects. Think back to [part 3]({{ site.baseurl }}/_twinet/part3). How did we add 3D objects to a scene? -Remember, we first have to add the append3d (and optionally the replace3d) macro into the JavaScript component before we can begin placing 3D objects into our scene. Go ahead and add those in. After that's done, we can start adding 3D objects, and your second passage can look something like this: +Remember, we have to first add the append3d (and optionally the replace3d) macro into the JavaScript component before we can begin placing 3D objects into our scene. Go ahead and add those in. After that's done, we can start adding 3D objects, and your second passage can look something like this: ```html Here is our second panorama, and as you can see (you might have to look around), we have added some 3D objects to it! Click [[here|Start]] to go back to the 'Start' scene. diff --git a/_twine/part6.md b/_twine/part6.md index 47a6dc2..38500fa 100644 --- a/_twine/part6.md +++ b/_twine/part6.md @@ -1,6 +1,6 @@ --- layout: page -title: 'Part 6: Incorporating Vuforia in Your Twine Experience' +title: 'Part 6: Creating an Image Database for Twine Experiences' --- @@ -8,18 +8,25 @@ title: 'Part 6: Incorporating Vuforia in Your Twine Experience' The Argon browser includes a computer-vision tracking system called [Vuforia](http://www.vuforia.com). Vuforia is a platform-native SDK that can find and precisely track where images and objects are relative to the camera. argon.js can represent these tracked *targets* as frames of reference expressed relative to the camera on the device (which is what we also use as the location of the user). This means that anything tracked by Vuforia can have its position computed relative to any other frame of reference Argon knows about, and attaching content to objects tracked by Vuforia is done in exactly the same way that content was attached to the world in the first parts of this tutorial. ## Obtaining a Vuforia License Key -To begin using Vuforia with your Twine story, you should have access to hosting on an online server. For more information on how to do that, click [here](http://www.webhostingsecretrevealed.net/web-hosting-beginner-guide/). - -The next step is to obtain a Vuforia license key. First, you must [register](https://developer.vuforia.com) for a Vuforia developer account. After creating an account, you can generate a license key. Navigate to the "Develop" page and add a licence key (you can choose the "Development" type for this example). Your license key will look something like this: +To begin using Vuforia with your Twine story, you will need to obtain a Vuforia license key. First, you must [register](https://developer.vuforia.com) for a Vuforia developer account. After creating an account, you can generate a license key. Navigate to the "Develop" page and add a licencse key (you can choose the "Development" type for this example). Your license key will look something like this: 
 AYVDMl7/////AAAAGUNYbWe+HkCjrn65cBM7Lm0Z6OHGozSF6sPHjCvjp3LhFIlirezFjpIqp0Xtg0ObkDmyTdJj1Yqb8VB9zeFu29cUBWe1fEBAHT//B74Urf2vcDCjyk7l92MUcwCq1xMRruzTVyXkIiQO8XrPTfjGA0KCCJjeBMj9HLvsH+POXBuKPOpnAEkptjZ/qNa4lEpSmZnr43Vg8wJZsQtzFBL8KDT8RGxzSZbuIh800dLzWmJOOjUDlac2qmnBWia7F7QymO1ig5WXgbDGb3CoOsFAZOgUsqXqk2ycrmV9BnebjesdVWmYKazrreiH021fq4rT1EmW5zgo4jR5pfLnjlXhofobPnCsq3zJZda6N13zpabc
-**Warning:** you should not share your key with others because you are only alloted so many "recos" before you are charged. A "reco" occurs when your app recognizes an image in a cloud database. +> **Warning:** you should not share your key with others because you are only allotted so many "recos" before you are charged. A "reco" occurs when your app recognizes an image in a cloud database. To use Vuforia, the native library must be initialized with a valid license key. The Argon browser requires each web app to provide this key in an encrypted format, so that programmers are not making their license key visible to others. This also means that only the users of your applications can access Vuforia functionality that is tied to your key, especially services that cost money to use. -To obtain this encrypted version of your license key, navigate to the [Vuforia PGP Encryptor](http://docs.argonjs.io/start/vuforia-pgp-encryptor/) page. Paste your key in the box titled "Vuforia Key." Read the instructions below, and then type in your server address with this format: "?(*.)yourwebsitehere.com**". Copy the new encrypted key under the "License Data (encrypted)" box. The entire output is the encrypted version of the license key. +To obtain this encrypted version of your license key, navigate to the [Vuforia PGP Encryptor]({{ site.baseurl }}/start/vuforia-pgp-encryptor) page. The first box is for your Vuforia license key, which you should paste in exactly as it appears on the Vuforia website without adding any extra spaces or line breaks. + +In the second box, you should enter a list of domains and URL patterns specifying what URLs this license key and corresponding tracking database can be used from. Make sure to read the instructions thoroughly because the domains you enter must be correctly formatted. Now enter the URL patterns into the first box below "Allowed Origins". It should look something like this: + +``` +?(*.)example.com/**, www.myothersite.com/demo/** + +``` + +Copy the new encrypted key from the "License Data (encrypted)" box. The entire output is the encrypted version of the license key. Store this key in a text file. > If you are using a public computer, you should empty the browser cache after using the Vuforia-PGP-encryptor page, to ensure your license key is not available after you are done. @@ -27,3 +34,10 @@ To obtain this encrypted version of your license key, navigate to the [Vuforia P ## Adding Vuforia Targets +With your new Vuforia key, you are now ready to create a Vuforia database and add targets to that database. Navigate to the Vuforia Target Manager page and add a database. After the database has been created, you can begin adding targets, which can be 2D images or 3D objects. For the sake of simplicity, we will be using 2D images as our targets for this example, which you can download from [here](#). Alternatively, you can use your own jpg or png images. + +> When adding targets, pay attention to the sizes you enter, as argonjs will use these sizes as if they are expressed in meters. + +After adding your target(s), download the database, selecting whichever SDK option you prefer. You should receive two files with the name of the database, one with a `.dat` extension and the other with a `.xml` extension. + +When creating AR experiences that utilize this database, make sure to keep the `xml` and `dat` files in the same directory. In the next lesson we will teach you how to incorporate your new image database into your Twine AR experiences. \ No newline at end of file diff --git a/_twine/part7.md b/_twine/part7.md new file mode 100644 index 0000000..77fc233 --- /dev/null +++ b/_twine/part7.md @@ -0,0 +1,141 @@ +--- +layout: page +title: 'Part 7: Using Vuforia in Twine' +--- + +> This lesson uses the third [example](https://github.com/blairmacintyre/oldfashioned/tree/master/examples/) from GitHub.
Import the text file into Twine to open the project. + + +## Adding the Vuforia Macros +In this tutorial you will learn how to utilize your Vuforia database within Twine to make AR experiences that can precisely track where images and objects are relative to the camera. We will begin by creating a new Twine project and adding the standard "passage-cleanup" code as well as the `append3d` and `replace3d` macros discussed in [part 3]({{ site.baseurl }}/_twinet/part3) of this tutorial. + +There are three essential macros you will need to add to use Vuforia targets. The first two, `initVuforia` and `vuforiaDataset`, are used to initialize Vuforia using your encrypted license key and any Vuforia target datasets you will be using. The `initVuforia` macro will need one parameter, the url of the text file containing the encrypted Vuforia key. Argon will use this file to initialize Vuforia. + +We call the collection of targets in a Vuforia database a **dataset**. Our second important macro, `vuforiaDataset`, will retrieve a dataset using the xml file that was automatically generated when we downloaded our Vuforia database in [part 6]({{ site.baseurl }}/_twinet/part6), granting us access to any target in that database. The macro will take in two parameters: a `datasetID`, which will act as a name for our dataset, and a `datasetURL`, which is the URL of the xml file associated with the database we want to use. The macros will look like this: + +```javascript + +/* <> */ +Macro.add(["initVuforia"], { + handler () { + if (this.args.length < 1) { + return this.error('parameter missing: key file url'); + } + + var keyElem = document.createElement('a-asset-item'); + var $keyElem = jQuery(keyElem); + $keyElem.attr({ + "id" : "vuforiakey", + "src" : this.args[0] + }); + + keyElem.addEventListener('loaded', function(evt) { + $('#argon-aframe').attr("vuforiakey", "#vuforiakey"); + }); + $('#argon-aframe').prepend($keyElem); + } +}); + +/* <> */ +Macro.add(["vuforiaDataset"], { + handler () { + if (this.args.length < 2) { + return this.error('parameters are {id, dataset url}'); + } + console.log("dataset: " + this.args[1]); + $('#argon-aframe').attr("vuforiadataset__" + this.args[0], "src:url(" + this.args[1] + ");"); + } +}); + + +``` + +The final macro you will need is `createReferenceFrameEntity`. This macro will create an entity that relies on a specified frame of reference. We will use this macro in conjunction with the `append3d` macro to create an object that uses a specified frame of reference for positioning. `createReferenceFrameEntity` will take in three parameters: an `entityID`, which will be used to refer to this entity, a string that will determine whether the entity is a story or passage entity, and a `"parent frame"` which the entity will use as a point of reference. Add the code below and read through the comments. + +```javascript + +// <> +Macro.add(['createReferenceFrameEntity'], { + handler() { + if (this.args.length < 3) { + return this.error('need selector, name and parent frame name'); + } + + var targetId = this.args[0]; + + /* Determines whether this is a story or passage entity */ + var $container; + if (this.args[1] === "story") { + $container = $("#story-entities"); + } else if (this.args[1] === "passage") { + $container = $("#passage-entities"); + } else { + return this.error('3D content type must be "story" or "passage": "' + this.args[1] + '" invalid'); + } + + /* If an entity with the same id has already been added, an error is thrown */ + var $targets = $container.find("#" + targetId); + if ($targets.length > 0) { + return this.error('passage "' + targetId + '" already exists.'); + } + + /* Adds the entity to the appropriate entity container (story or passage) */ + $targets = jQuery(document.createElement('ar-frame')); + $targets.attr({ + "id": targetId, + "parent": this.args[2] + }); + + for (var i = 3; i> +<> + +``` + +With Vuforia and our dataset initialized, we can create an entity that uses one of our dataset's targets as a frame of reference. To do that, we use the `createReferenceFrameEntity` followed by the name of the entity we want to add, the type of entity we want it to be (story or passage), and the parent entity that we want to use as a frame of reference. For this example, we want to use a target that we added to our Vuforia database as the parent entity. + +``` + +<> + +<> + +<> + +``` + +This segment of code will create a 3D box called `boxOnTarget` that will remain hidden until the user points their camera towards a picture of the target inside `myDataset` called `target`. Because we made `boxOnTarget` a story entity, anytime the camera points to this picture, our `boxOnTarget` object will become visible and be positioned using the `target` as a frame of reference. + +It is also important to note that we can use the user's camera (which we just refer to as the "user") as a frame of reference for entities. In fact, the user *is* the default frame of reference. Go to the Start passage and add the following code: + +``` + +Any entity can act as a parent (frame of reference) for another Argon entity, a Vuforia target, a normal 3D object that we append to the screen, or even the user. + +<> + +<> + +<> + +``` + +> **NOTE:** the most important concept to grasp from this lesson is that any Argon entity with *known* position can act as a frame of reference. However, Vuforia gives you the added ability of using custom images and 3D objects as frames of reference with high precision using computer vision. + +You should spend some time practicing using reference frames and Vuforia targets as they are some of the most powerful tools that Argon has to offer and will greatly extend the power and flexibility of your augmented reality experiences! \ No newline at end of file