diff --git a/README.md b/README.md index 33328b9..5af71f7 100644 --- a/README.md +++ b/README.md @@ -44,75 +44,17 @@ For browser usage, download the library from the `dist` directory and import in ``` -## Modules - -Modules are used to generate assets like marker files. - -### 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. +Alternatively, you can use a CDN service like GitHack (replace `vX.Y.Z` with an actual version): -**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 +```html + ``` -### Location (TBI) +## Modules + +Modules are used to generate assets like marker and `.patt` files. -### NFT (TBI) +See [modules docs](docs/modules.md) for detailed documentation and examples. ## Providers @@ -120,103 +62,13 @@ Providers are used to gather together the project assets and serve them in diffe A base `Provider` class can be found in `src/providers/Provider.js`, you can extend directly from it or use others this library provides. -### GitHub Pages - -**new GithubProvider(config)** +See [providers docs](docs/providers.md) for detailed documentation and examples. -Accepts the following configuration: +## HTML generation -```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 -}); -``` +Modules also provide static functions to generate the content of `index.html` files for all kinds of AR.js applications. -**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. - -**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}` -``` +See [templates docs](docs/templates.md) for detailed documentation and examples. ## TODO diff --git a/docs/modules.md b/docs/modules.md new file mode 100644 index 0000000..280919a --- /dev/null +++ b/docs/modules.md @@ -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) diff --git a/docs/providers.md b/docs/providers.md new file mode 100644 index 0000000..2573eff --- /dev/null +++ b/docs/providers.md @@ -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}` +``` diff --git a/docs/templates.md b/docs/templates.md new file mode 100644 index 0000000..e000952 --- /dev/null +++ b/docs/templates.md @@ -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'); +```