refactored parameters, log functions

Author: matt-manuel

README.md

@@ -2,17 +2,13 @@
 
 This repo contains a shell script (bash) for uploading scene files to the Cognitive3D platform.
 
-## Scene Upload Script
-
-This script uploads a set of 3D scene files to the Cognitive3D API.
+## Requirements
 
-### Requirements
-
-* Bash (macOS/Linux)
+* Bash (macOS / Linux / Windows Subsystem for Linux (WSL))
 * `curl`
 * `jq`
 
-### Installation
+### Installation of required dependencies
 
 Make sure the following tools are installed:
 
@@ -22,59 +18,60 @@ sudo apt install jq curl     # Ubuntu/Debian
 dnf install jq curl          # Fedora/RHEL
 ```
 
-### Usage
+### Environment Variables
+
+You must set your Cognitive3D Developer API key as an environment variable:
 
 ```bash
-./scene-upload.sh <scene_directory> [environment] [scene_id]
+export C3D_DEVELOPER_API_KEY="your_api_key"
 ```
 
-#### Parameters
-
-* `<scene_directory>` (required): Path to a folder containing:
-
-  * `scene.bin`
-  * `scene.gltf`
-  * `screenshot.png`
-  * `settings.json`
+You can get your developer API key from the Cognitive3D web dashboard. Look for the "Manage developer key" option in the settings (gear icon) menu.
 
-* `[environment]` (optional): Either `prod` (default) or `dev`
+> Note: We strongly recommend you _do not_ store your developer API key in version control.
 
-* `[scene_id]` (optional): Scene ID to append to the API endpoint to upload a new version of an existing scene
+## Scene Upload Script
 
-#### Environment Variables
+This script uploads a set of 3D scene files to the Cognitive3D platform using our API.
 
-You must set your Cognitive3D developer API key as an environment variable:
+### Usage
 
 ```bash
-export C3D_DEVELOPER_API_KEY="your_api_key"
+./upload-scene.sh --scene_dir <scene_directory> [--env <prod|dev>] [--scene_id <scene_id_from_dashboard>]
 ```
 
-You can get your developer API key from the Cognitive3D web dashboard. Look for the "Manage developer key" option in the settings (gear icon) menu.
+#### Parameters
 
-> Note: We strongly recommend you _do not_ store your developer API key in version control.
+* `--scene_dir <scene_directory>` (required): Path to a folder containing:
+  * `scene.bin`
+  * `scene.gltf`
+  * `screenshot.png`
+  * `settings.json`
+* `[--env <prod/dev>]` (optional): Either `prod` (default) or `dev`
+* `[--scene_id <scene_id_from_dashboard>]` (optional): Scene ID to append to the API endpoint to upload a new version of an existing scene
 
 ### Example
 
 For the first time you upload your scene you won't have a scene ID, so we don't pass that parameter. The first time you run this script, without a scene ID, it creates the scene and returns the new scene ID (output to the console at the end of the script.)
 
 ```bash
-export C3D_DEVELOPER_API_KEY="abc123xyz"
-./scene-upload.sh ./TestScene prod
+export C3D_DEVELOPER_API_KEY=<abc123xyz>
+./upload-scene.sh --scene_dir ./TestScene --env prod
 ```
 
 For subsequent (new) versions of the same scene, pass in your scene ID as the third parameter to the script. This will upload the scene assets again and the platform will auto-increment the scene version.
 
 You can find the scene ID on the Cognitive3D dashboard on the Scenes page. Look for the "information" icon (letter 'i' in a circle) and hover over it.
 
 ```bash
-export C3D_DEVELOPER_API_KEY="abc123xyz"
-./scene-upload.sh ./TestScene prod my-scene-id
+export C3D_DEVELOPER_API_KEY=<abc123xyz>
+./upload-scene.sh --scene_dir ./TestScene --env prod --scene_id my_scene_id
 ```
 
 ### Behavior
 
 * Reads the SDK version from `sdk-version.txt` in the same directory as the script.
-* Replaces the `sdkVersion` field inside `settings.json` using `jq`.
+* Replaces the `sdkVersion` field inside `settings.json` file in the scene directory using `jq`.
 * Uploads the four files to the correct API endpoint.
 * Verifies API response and prints success or error.
 
@@ -83,23 +80,19 @@ export C3D_DEVELOPER_API_KEY="abc123xyz"
 To see usage information:
 
 ```bash
-./scene-upload.sh --help
+./upload-scene.sh --help
 ```
 
 ## Dynamic object uploader script
 
 This Bash script uploads dynamic 3D object assets to the Cognitive3D platform, supporting GLTF + BIN files, optional textures, and thumbnail metadata. It supports both development and production environments.
 
-### Dynamic object uploader requirements
-
-* Bash 4+
-* `curl`
-* A Cognitive3D Developer API key (set as an environment variable)
+Uploading a scene to the platform is required before you can upload any dynamic object models. The scene_id is a required parameter.
 
 ### Dynamic object uploader usage
 
 ```bash
-./upload-dynamic-object.sh \
+./upload-object.sh \
   --scene_id <scene-uuid> \
   --object_filename <object-name> \
   --object_dir <path-to-object-directory> \
@@ -114,10 +107,10 @@ This Bash script uploads dynamic 3D object assets to the Cognitive3D platform, s
 * `--scene_id`: The Scene ID UUID where the object will be uploaded.
 * `--object_filename`: The base filename (no extension) of the object, used to find `.gltf` and `.bin` files.
 * `--object_dir`: The directory containing the object files.
-* `--object_id`: If specified, uploads as a new version of an existing object.
 
 #### Optional Parameters
 
+* `--object_id`: If specified, uploads as a new version of an existing object.
 * `--env`: Target environment (`prod` or `dev`). Defaults to `prod`.
 * `--verbose`: Enables detailed logging.
 * `--dry_run`: Prints the constructed `curl` command but skips execution.
@@ -132,16 +125,16 @@ The following files must exist in the `--object_dir`:
 
 * `<object_filename>.gltf`
 * `<object_filename>.bin`
-* (Optional, recommended) `cvr_object_thumbnail.png`
+* (Optional, recommended) `cvr_object_thumbnail.png`, a representative screenshot of the object; used by the dashboard
 * (Optional) Any additional `.png` textures used by the model
 
 ### Dynamic object uploader example
 
 ```bash
-export C3D_DEVELOPER_API_KEY="your-api-key"
+export C3D_DEVELOPER_API_KEY=<your-api-key>
 
-./object-upload.sh \
-  --scene_id scene_id_goes_here \
+./upload-object.sh \
+  --scene_id <scene_id_goes_here> \
   --object_filename cube \
   --object_dir object-test \
   --env prod \
@@ -161,13 +154,53 @@ export C3D_DEVELOPER_API_KEY="your-api-key"
 * `--dry_run` shows the `curl` command without executing it
 * Colored output highlights info, warnings, errors, and debug details
 
-### Examples
+### Uploading the object manifest
+
+After uploading the dynamic object asset files (mesh, textures) you must upload the dynamic object manifest file to display the objects on the Cognitive3D dashboard for your project and scene.
+
+### Dynamic object manifest uploader usage
+
+The dynamic object manifest for your scene and object is created automatically after successfully uploading the dynamic object assets. It will be in a file named `<scene_id>_object_manifest.json`.
 
 ```bash
-./object-upload.sh \
-  --scene_id fea64809-2a44-4b0c-acc1-a66f371521a8 \
-  --env dev \
-  --object_dir lantern-test \
-  --object_filename Lantern \
-  --object_id Lantern
+./upload-object-manifest.sh \
+  --scene_id <scene-uuid> \
+  [--env dev|prod] \
+  [--verbose] \
 ```
+
+#### Dynamic object manifest uploader required parameters
+
+* `--scene_id`: The Scene ID UUID where the object will be uploaded.
+
+#### Object manifest uploader optional parameters
+
+* `--object_id`: If specified, uploads as a new version of an existing object.
+* `--env`: Target environment (`prod` or `dev`). Defaults to `prod`.
+* `--verbose`: Enables detailed logging.
+* `--dry_run`: Prints the constructed `curl` command but skips execution.
+
+### Dynamic object manifest uploader environment variables
+
+* `C3D_DEVELOPER_API_KEY`: Your Cognitive3D Developer API key (required).
+
+### Dynamic object manifest uploader file requirements
+
+The following files must exist in the same directory where you are calling the script from:
+
+* `<scene_id>_object_manifest.json`, which is automatically created after successfully uploading your dynamic object meshes
+
+### Dynamic object manifest uploader example
+
+```bash
+export C3D_DEVELOPER_API_KEY=<your-api-key>
+
+./upload-object-manifest.sh \
+  --scene_id <scene_id_goes_here> \
+  --env prod \
+  --verbose
+```
+
+The reason we don't automatically upload the manifest after uploading the object assets is to allow you to modify the manifest JSON before uploading.
+
+If you have any questions or problems using these scripts contact our customer support team using the Intercom button (public circle) on any Cognitive3D web page.

list-objects.sh

@@ -24,7 +24,7 @@ debug() {
 }
 
 usage() {
-  echo "Usage: $0 --sceneId <scene_id> --env <prod|dev> [--verbose] [--debug]"
+  echo "Usage: $0 --scene_id <scene_id> --env <prod|dev> [--verbose] [--debug]"
   exit 1
 }
 
@@ -43,7 +43,7 @@ fi
 while [[ $# -gt 0 ]]; do
   key="$1"
   case $key in
-    --sceneId)
+    --scene_id)
       SCENE_ID="$2"
       shift; shift
       ;;

scene-test/settings.json

@@ -1,5 +1,5 @@
 {
   "scale": 1,
-  "sceneName": "Test scene 1",
-  "sdkVersion": "0.1.1"
+  "sceneName": "Test scene 5",
+  "sdkVersion": "0.1.3"
 }

sdk-version.txt

@@ -1 +1 @@
-0.1.2
+0.1.3

test-all.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+# usage: test-all.sh <scene_id> <env>
+# This script runs a series of upload and list commands for a given scene and environment.
+
+# Required: Run `./upload-scene.sh` script with no scene_id first; use that scene_id for this script.
+
+# get SCENE_ID from the first argument
+SCENE_ID="$1"
+
+# get ENV from the second argument
+ENV="$2"
+
+echo "Running tests for scene ID: $SCENE_ID in environment: $ENV"
+## wait for enter key
+read -p "Press Enter to continue..."
+
+./upload-scene.sh --scene_id $SCENE_ID --scene_dir scene-test --env $ENV --verbose
+
+./upload-object.sh --scene_id $SCENE_ID --object_filename cube --object_id cube --object_dir object-test --env $ENV --verbose
+
+./upload-object-manifest.sh --scene_id $SCENE_ID --env $ENV --verbose
+
+./upload-object.sh --scene_id $SCENE_ID --object_filename Lantern --object_id Lantern --object_dir lantern-test --env $ENV --verbose
+
+./upload-object-manifest.sh --scene_id $SCENE_ID --env $ENV --verbose
+
+./list-objects.sh --scene_id $SCENE_ID --env $ENV --verbose