diff --git a/README.md b/README.md index 5af71f7..eceef95 100644 --- a/README.md +++ b/README.md @@ -16,15 +16,15 @@ The following static methods are available for the frontend side: - [x] Pattern Marker Generator (marker image + .patt file), given input image and custom parameters -- [ ] Creation and Output for `a-scene` element of Marker Based app, with default parameters +- [x] Creation and Output for `a-scene` element of Marker Based app, with default parameters -- [ ] Creation and Output for `a-scene` element of Location Based app, with default parameters +- [x] Creation and Output for `a-scene` element of Location Based app, with default parameters - [ ] Creation and Output for `a-scene` element of NFT Based app, with default parameters -- [ ] Creation and Output of `a-marker` element, with custom parameters (pattern, barcode markers) +- [x] Creation and Output of `a-marker` element, with custom parameters (pattern, barcode markers) -- [ ] Creation and Output of `gps-entity-place` element, with custom parameters +- [x] Creation and Output of `gps-entity-place` element, with custom parameters - [ ] Creation and Output of `a-nft` element, with custom parameters @@ -54,7 +54,7 @@ Alternatively, you can use a CDN service like GitHack (replace `vX.Y.Z` with an Modules are used to generate assets like marker and `.patt` files. -See [modules docs](docs/modules.md) for detailed documentation and examples. +See [modules docs](docs/modules.md) for a detailed documentation and examples. ## Providers @@ -62,13 +62,20 @@ 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. -See [providers docs](docs/providers.md) for detailed documentation and examples. +See [providers docs](docs/providers.md) for a detailed documentation and examples. ## HTML generation Modules also provide static functions to generate the content of `index.html` files for all kinds of AR.js applications. -See [templates docs](docs/templates.md) for detailed documentation and examples. +See [templates docs](docs/templates.md) for a detailed documentation and examples. + +## Package + +This class is a helper for generating the application package for the user. It provides an easy interface for the whole +process, wrapping all modules/providers. + +See [package docs](docs/package.md) for a detailed documentation and examples. ## TODO diff --git a/docs/modules.md b/docs/modules.md index 76a7ede..0c17303 100644 --- a/docs/modules.md +++ b/docs/modules.md @@ -4,7 +4,7 @@ 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. +Use this method 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. @@ -21,16 +21,16 @@ Supported matrix types (values start from 0): **MarkerModule.getMarkerPattern(dataURI)** -This method is used to create a `.patt` file from an image. +Use this method 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. +Use this method 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** +### Example ```js const { MarkerModule, MATRIX_3X3_HAMMING_63 } = ARjsStudioBackend; diff --git a/docs/package.md b/docs/package.md new file mode 100644 index 0000000..4db8411 --- /dev/null +++ b/docs/package.md @@ -0,0 +1,108 @@ +## Package + +**new Package(config)** + +Accepts the following configuration: + +```js +new Package({ + arType: 'pattern', // see exported AR_* constants + assetType: '3d', // see exported ASSET_* constants + assetFile: yourAssetFile, // read details after this code block + assetName: 'model.gltf', // the AR asset filename, including the file extension + assetParam: { + isValid: true, // whether the scale/size parameters are correct or not (if you don't know what this is, set to true) + scale: 1.0, // scale of the asset + size: { // sizes of the asset, unused + width: 1.0, + height: 1.0, + depth: 1.0 + }, + latitude: 12.345678, // required for location based AR + longitude: 12.345678 // required for location based AR + }, + markerPatt: '...', // the content of the generated .patt file, as a string (required for pattern/location based AR) + matrixType: '...', // see exported MATRIX_* constants (required for barcode based AR) + markerValue: 7, // barcode value (required for barcode based AR) +}); +``` + +The `assetFile` parameter must be: +- a base64 encoded string (use `FileReader.readAsDataURL()` and strip the initial `data:*/*;base64,` string) for 3d/image assets +- a `Blob` for audio/video assets when using Zip provider +- an `ArrayBuffer` for audio/video when using GitHub provider + +**serve(config)** + +Deploys the package, based on the chosen provider. Accepts the following configuration: + +```js +package.serve({ + packageType: 'zip', // see exported PACKAGE_* constants + config: {...} // see either serveFiles() documentation for your chosen provider +}); +``` + +### Example + +```js +const { + AR_PATTERN, + ASSET_3D, + PACKAGE_GITHUB, + PACKAGE_ZIP, + MarkerModule +} = ARjsStudioBackend; + +// helper function -- promisify file reading +const reader = new FileReader(); +const waitRead = () => { + return new Promise(resolve => { + reader.addEventListener('load', () => { + resolve(reader.result); + }); + }) +}; + +// read marker image +const markerFile = document.querySelector('#marker-image').files[0]; +reader.readAsDataURL(markerFile); +const originalMarker = await waitRead(); + +// generate .patt file +const textPatt = await MarkerModule.getMarkerPattern(originalMarker); + +// read asset file +const assetFile = document.querySelector('#asset-file-selector').files[0]; +reader.readAsDataURL(assetFile); +const base64Asset = await waitRead(); + +// create the package +const package = new Package({ + arType: AR_PATTERN, + assetType: ASSET_3D, + assetFile: base64Asset, + assetName: file.name, + assetParam: { + isValid: true, + scale: 1.0 + }, + markerPatt: textPatt +}); + +// deploy to github... +const pagesURL = await package.serve({ + packageType: PACKAGE_GITHUB, + token: 'user github token', + repo: 'arjs-awesome-repo-84265' +}); +console.log(`navigate to ${pagesURL} to see your project`); + +// ...or generate a zip file (or both!) +const zipFile = await package.serve({ + packageType: PACKAGE_ZIP, + compress: 9 +}); +// trigger download +window.location = `data:application/zip;base64,${zipFile}`; +``` diff --git a/docs/providers.md b/docs/providers.md index d5818cb..194efbf 100644 --- a/docs/providers.md +++ b/docs/providers.md @@ -24,12 +24,12 @@ provider.serveFiles({ }); ``` -**Example** +### Example First, create a Personal Access Token from [GitHub Developer Settings](https://github.com/settings/tokens) with scope `repo:public_repo`. -In production you'll need to implement GitHub's OAuth Web Application flow ([see here](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow)) +In production, you'll need to implement GitHub's OAuth Web Application flow ([see here](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow)) to obtain a token from your users. Then use it to serve the project: @@ -44,10 +44,10 @@ const pagesUrl = await github.serveFiles({ token: 'YOUR-TOKEN', message: 'my awesome AR experience' }); -const branchName = github.branch; // store this +const repoName = github.repo; // store this ``` -The provider will use the PAT to create repo, branch, set up Pages, commit all the files and trigger +The provider will use the PAT to create the repository, branch, set up Pages, commit all the files and trigger a Pages build. ## Zip file @@ -73,7 +73,7 @@ provider.serveFiles({ }); ``` -**Example** +### Example ```js const image = 'base64 encoded image'; @@ -87,5 +87,5 @@ 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}` +window.location = `data:application/zip;base64,${base64}`; ``` diff --git a/docs/templates.md b/docs/templates.md index 934bf64..c7f9a61 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -5,7 +5,7 @@ Generate the `index.html` contents for AR.js applications using marker pattern. Accepts an asset type (see exported `ASSET_*` constants) and relative paths for `.patt` and asset files. -**Example** +### Example ```js const { MarkerModule, ASSET_AUDIO } = ARjsStudioBackend; @@ -22,7 +22,7 @@ Generate the `index.html` contents for AR.js applications using marker barcode. Accepts a matrix type (see exported `MATRIX_*` constants), the barcode value represented by the marker and asset file. -**Example** +### Example ```js const { MarkerModule, MATRIX_3X3_HAMMING_63 } = ARjsStudioBackend; diff --git a/src/index.js b/src/index.js index 5f10836..6910eeb 100644 --- a/src/index.js +++ b/src/index.js @@ -12,6 +12,8 @@ import { AR_PATTERN, AR_LOCATION, AR_NTF, + PACKAGE_GITHUB, + PACKAGE_ZIP, } from './modules/package/Package'; import { MATRIX_3X3_HAMMING_63, @@ -54,6 +56,8 @@ export { AR_PATTERN, AR_LOCATION, AR_NTF, + PACKAGE_GITHUB, + PACKAGE_ZIP, Package, NFTModule, ENC_BASE64, diff --git a/src/modules/package/Package.js b/src/modules/package/Package.js index fdd3a53..14cad5c 100644 --- a/src/modules/package/Package.js +++ b/src/modules/package/Package.js @@ -18,6 +18,9 @@ export const AR_PATTERN = 'pattern'; export const AR_LOCATION = 'location'; export const AR_NTF = 'ntf'; +export const PACKAGE_ZIP = 'zip'; +export const PACKAGE_GITHUB = 'github'; + /** * @typedef AssetParam * @property {boolean} isValid @@ -40,11 +43,11 @@ export class Package { /** * @param {Object} config * @param {string} config.arType - one of barcode, pattern, location or ntf (see exported constants) - * @param {string} config.assetType - one of 3d, image, audio or video (see {@link MarkerModule} exported constants) + * @param {string} config.assetType - one of 3d, image, audio or video (see exported constants) * @param {string|Blob} config.assetFile - the file to be show in AR * @param {string} config.assetName - the file name, to be included in HTML template * @param {AssetParam} [config.assetParam] - scale and position of AR asset - * @param {string} [config.markerPatt] - the marker image patt file (required for pattern AR type) + * @param {string} [config.markerPatt] - the marker image patt file (required for pattern and location AR type) * @param {string} [config.matrixType] - the barcode matrix type (see {@link BarcodeMarkerGenerator} exported constants, required for barcode AR type) * @param {number} [config.markerValue] - the barcode value of the marker (required for barcode AR type) */ @@ -117,11 +120,11 @@ export class Package { // init provider switch (packageType) { - case 'zip': + case PACKAGE_ZIP: provider = new ZipProvider(); break; - case 'github': + case PACKAGE_GITHUB: provider = new GithubProvider(); break;