- feat: added constants for package type

- docs: added docs for Package class

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,21 +54,28 @@ 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
 
 Providers are used to gather together the project assets and serve them in different formats.
 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
 

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;

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}`;
+```

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}`;
 ```

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;

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,

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;