-
Notifications
You must be signed in to change notification settings - Fork 22
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- docs: split documentation in multiple files to keep it shorter
- docs: added documentation of HTML generation
- Loading branch information
Showing
4 changed files
with
203 additions
and
159 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| ## Marker | ||
|
|
||
| This module can generate both barcode and pattern markers. | ||
|
|
||
| **MarkerModule.getBarcodeMarkerSVGDataURI(matrixTypeId, value)** | ||
|
|
||
| This method is used to create a barcode image from a value. | ||
| Accepts a matrix type (see exported `MATRIX_*` constants) and a value and returns a data URI string, | ||
| representing an SVG of the barcode marker. | ||
|
|
||
| Supported matrix types (values start from 0): | ||
|
|
||
| | Matrix type | Max value | | ||
| | ----------------- | ----------- | | ||
| | `3x3_hamming_6_3` | 7 | | ||
| | `3x3_parity_6_5` | 31 | | ||
| | `4x4_bch_13_5_5` | 31 | | ||
| | `4x4_bch_13_9_3` | 511 | | ||
| | `5x5_bch_22_7_7` | 128 | | ||
| | `5x5_bch_22_12_5` | 4095 | | ||
|
|
||
| **MarkerModule.getMarkerPattern(dataURI)** | ||
|
|
||
| This method is used to create a `.patt` file from an image. | ||
| Accepts an image as a data URI string and returns a string for the `.patt` file. | ||
|
|
||
| **MarkerModule.getFullMarkerImage(dataURI, ratio, size, color)** | ||
|
|
||
| This method is used to create the marker image with border from an image. | ||
| Accepts an image as a data URI string, size, ratio and border color for the marker and returns | ||
| a data URI string representing the final marker image. | ||
|
|
||
| **Example** | ||
|
|
||
| ```js | ||
| const { MarkerModule, MATRIX_3X3_HAMMING_63 } = ARjsStudioBackend; | ||
|
|
||
| // generate an SVG data URI for the value '8' | ||
| const barcodeMarkerSVG = MarkerModule.getBarcodeMarkerSVGDataURI(MATRIX_3X3_HAMMING_63, 7); | ||
|
|
||
| const barcodeImage = new Image(); | ||
| barcodeImage.src = barcodeMarkerSVG; // use the image 'load' event to know when image is ready | ||
|
|
||
| // ---- | ||
|
|
||
| // draw the image on an off-screen canvas and use `.toDataURL()` to get a data URI | ||
| const fullMarker = await MarkerModule.getFullMarkerImage(imageDataURI, 1.0, 100, 'black'); | ||
| const pattFile = await MarkerModule.getMarkerPattern(imageDataURI); | ||
|
|
||
| const patternImage = new Image(); | ||
| patternImage.src = fullMarker; | ||
| // use the image 'load' event to know when image is ready | ||
| patternImage.addEventListener('load', () => { | ||
| document.body.appendChild(patternImage); | ||
| }) | ||
|
|
||
| const pattFileDownload = document.createElement('a'); | ||
| pattFileDownload.href = `data:text/plain;charset=utf-8,${pattFile}`; | ||
| pattFileDownload.download = 'marker.patt'; // filename | ||
| pattFileDownload.click(); // trigger download | ||
| ``` | ||
|
|
||
| ## Location (TBI) | ||
|
|
||
| ## NFT (TBI) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| ## GitHub Pages | ||
|
|
||
| **new GithubProvider(config)** | ||
|
|
||
| Accepts the following configuration: | ||
|
|
||
| ```js | ||
| new GithubProvider({ | ||
| token: 'authorization token', // required, can be a PAT or OAuth token | ||
| owner: 'username', // automatically retrieved by default | ||
| repo: 'name of the repository', // defaults to 'arjs-studio-NUMBERS' | ||
| branch: 'gh-pages' // automatically deploy to Pages by default | ||
| }); | ||
| ``` | ||
|
|
||
| **addFile(path, content, encoding)** | ||
|
|
||
| To add a file you need to provide its path in the repository, content and encoding. | ||
| Accepted encodings are `utf-8` for textual files and `base64` for encoded images (see exported `ENC_*` constants). | ||
|
|
||
| **serveFiles(config)** | ||
|
|
||
| Commits files to the user's repository and returns a `Promise` that resolves to the URL | ||
| of the deployed Pages. | ||
|
|
||
| ```js | ||
| provider.serveFiles({ | ||
| message: 'custom commit message', | ||
| owner: 'custom owner', | ||
| repo: 'custom repo', | ||
| branch: 'custom branch' | ||
| }); | ||
| ``` | ||
|
|
||
| **Example** | ||
|
|
||
| First, create a Personal Access Token from [GitHub Developer Settings](https://github.com/settings/tokens) | ||
| with scope `repo:publis_repo`. | ||
|
|
||
| Then use it to serve the project: | ||
|
|
||
| ```js | ||
| const { GithubProvider, ENC_BASE64 } = ARjsStudioBackend; | ||
|
|
||
| const github = new GithubProvider({ | ||
| token: 'YOUR-TOKEN' | ||
| }); | ||
| github.addFile('index.html', 'Hello World!'); | ||
| github.addFile('img/example.jpg', 'base64 encoded image ...', ENC_BASE64); | ||
| const pagesUrl = await github.serveFiles({ | ||
| message: 'my awesome AR experience' | ||
| }); | ||
| const branchName = github.branch; // store this | ||
| ``` | ||
|
|
||
| The provider will use the PAT to create repo, branch, set up Pages, commit all the files and trigger | ||
| a Pages build. | ||
|
|
||
| ## Zip file | ||
|
|
||
| **new ZipProvider()** | ||
|
|
||
| The constructor, no configuration is needed. | ||
|
|
||
| **addFile(path, content, encoding)** | ||
|
|
||
| To add a file you need to provider its path in the ZIP, content and encoding. | ||
| Accepted encodings are `utf-8` for textual files, `base64` for encoded images and `binary` if data | ||
| should be treated as raw content (see exported `ENC_*` constants). | ||
|
|
||
| **serveFiles(config)** | ||
|
|
||
| Generates the ZIP file returning a `Promise` that resolves to the requested format. | ||
|
|
||
| ```js | ||
| provider.serveFiles({ | ||
| type: 'output format', // see ZIP_* constants, defaults to base64 | ||
| compress: 6 // set to 0 to disable compression, defaults to 0 | ||
| }); | ||
| ``` | ||
|
|
||
| **Example** | ||
|
|
||
| ```js | ||
| const image = 'base64 encoded image'; | ||
| const { | ||
| ZipProvider, | ||
| ENC_BASE64 | ||
| } = ARjsStudioBackend; | ||
|
|
||
| const zip = new ZipProvider(); | ||
| zip.addFile('readme.txt', 'Hello world!'); | ||
| zip.addFile('images/img.jpg', image, ENC_BASE64); | ||
| const base64 = await zip.serveFiles({ compress: 9 }); | ||
| // trigger download | ||
| window.location = `data:application/zip;base64,${base64}` | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| ## Marker applications | ||
|
|
||
| **MarkerModule.generatePattern3dHtml(pattSrc, modelSrc)** | ||
|
|
||
| Generates the `index.html` contents for an AR.js application using a marker pattern and 3d model as AR asset. | ||
| Parameters are the relative paths for `.patt` and `.gltf` files. | ||
|
|
||
| **MarkerModule.generatePatternImageHtml(pattSrc, imageSrc)** | ||
|
|
||
| Generates the `index.html` contents for an AR.js application using a marker pattern and an image as AR asset. | ||
| Parameters are the relative paths for `.patt` file and the image. | ||
|
|
||
| **MarkerModule.generatePatternAudioHtml(pattSrc, audioSrc)** | ||
|
|
||
| Generates the `index.html` contents for an AR.js application using a marker pattern and an audio file as AR asset. | ||
| Parameters are the relative paths for `.patt` file and the audio. | ||
|
|
||
| **MarkerModule.generatePatternVideoHtml(pattSrc, videoSrc)** | ||
|
|
||
| Generates the `index.html` contents for an AR.js application using a marker pattern and a video file as AR asset. | ||
| Parameters are the relative paths for `.patt` file and the video. | ||
|
|
||
| **Example** | ||
|
|
||
| ```js | ||
| const { MarkerModule } = ARjsStudioBackend; | ||
|
|
||
| // generate the index.html for an AR application that uses marker pattern and an audio file as AR asset | ||
| const content = MarkerModule.generatePatternAudioTemplate('/marker.patt', '/assets/audio.mp3'); | ||
| ``` |