docs(arena): update usage for cli-args

content/python/scenes.md

@@ -8,32 +8,125 @@ parent: Python Library
 # Scenes in arena-py
 
 Scenes give arena-py programs access to an ARENA scene. It provides an interface to add/update objects, run animations, and many more!
+There are 3 main ways to define which server, scene name, and other arguments you wish to use:
+
+1. [Python Object Args](#python-object-args)
+1. [Environment Variable Args](#environment-variable-argsn)
+1. [Command Line Args](#command-line-args)
+
+## Python Object Args
 
-## Scene Access
 To get access to a scene in the ARENA, create a `Scene` object. Make sure you have proper permissions to access it!
+
 ```python
 scene = Scene(host="arenaxr.org", scene="example")
 # scene = Arena(host="arenaxr.org", scene="example") works too
 ```
 
-## Arguments
-`host`: Base ARENA URL.
+### Scene Object Arguments
 
-`realm`: ARENA realm name.
+See [Scene API Spec](/content/python-api/scene).
 
-`scene`: ARENA scene name.
+- `host`: Base ARENA URL.
+- `realm`: ARENA realm name.
+- `scene`: ARENA scene name.
+- `namespace`: ARENA namespace. Default value is ARENA username.
+- `video`: If true, request permissions for video conference. Default = False.
+- `debug`: If true, print a log of all publish messages from this client. Default = False.
+- `cli_args`: If true, several [standardized parameters](#command-line-args) are available. Default = False.
+- `debug`: If True, print authentication debug information and every published message. Ignore this parameter.
+- `network_latency_interval`: Interval (in ms) to run network graph latency update. Default value is 10000 (10 secs). Ignore this parameter.
 
-`namespace`: ARENA namespace. Default value is ARENA username.
+### Scene Object Callbacks
 
-`debug`: If True, print authentication debug information and every published message. Ignore this parameter.
+See [Scene Callbacks](callbacks.md).
 
-`network_latency_interval`: Interval (in ms) to run network graph latency update. Default value is 10000 (10 secs). Ignore this parameter.
+- `on_msg_callback`: See [Scene Callbacks](callbacks#on_msg_callback)
+- `new_obj_callback`: See [Scene Callbacks](callbacks#new_obj_callback)
+- `user_join_callback`: See [Scene Callbacks](callbacks#user_join_callback)
+- `user_left_callback`: See [Scene Callbacks](callbacks#user_left_callback)
+- `delete_obj_callback`: See [Scene Callbacks](callbacks#delete_obj_callback)
+- `end_program_callback`: See [Scene Callbacks](callbacks#end_program_callback)
 
-## Callbacks
-See [Scene Callbacks](callbacks.md).
+## Environment Variable Args
+
+It is also possible to override these args un `Scene()` using environmental variables at the command line as shown below. This allows a simple way to re-target applications for your own environment without having to change the parameters manually in the code.
+
+```shell
+export MQTTH=arenaxr.org # ARENA webserver main host
+export SCENE=scene
+export NAMESPACE=namespace
+python3 program.py
+```
+
+Definitions of other [environment variables](/content/python-api/env) are available.
+
+## Command Line Args
+
+The `cli_args` parameter can be used to avoid defining many of these parameters in the `Scene()` object, and expect the user to supply them on the command line. Several have been standardized, and we make it simple to include custom args for your program.
+
+### Simple CLI
+
+If you have scene-dependant settings, like position, rogation, scale, which might change with each scene name change, you can supply them on the command line. Usage:
+
+```shell
+python program.py -s example -p -10 0 10 -r 0 45 0 -c 0.5 0.5 0.5
+```
+
+Then you can consume them in your program:
+
+```python
+scene = Scene(cli_args=True)
+scene.add_object(Object(
+    object_id="my-parent-object-name",
+    position=scene.args["position"],
+    rotation=scene.args["rotation"],
+    scale=scene.args["scale"],
+))
+```
+
+This is a list of the most common options available in this mode, (`python3 program.py -h` to view):
+
+```
+-h, --help            show this help message and exit
+-mh HOST, --host HOST
+                        ARENA webserver main host to connect to
+-n NAMESPACE, --namespace NAMESPACE
+                        Namespace of scene
+-s SCENE, --scene SCENE
+                        Scene to publish and listen to
+-d DEVICE, --device DEVICE
+                        Device to publish and listen to
+-p POSITION POSITION POSITION, --position POSITION POSITION POSITION
+                        App position as cartesian.x cartesian.y cartesian.z
+-r ROTATION ROTATION ROTATION, --rotation ROTATION ROTATION ROTATION
+                        App rotation as euler.x euler.y euler.z
+-c SCALE SCALE SCALE, --scale SCALE SCALE SCALE
+                        App scale as cartesian.x cartesian.y cartesian.z
+-D, --debug           Debug mode.
+```
+
+### Advanced CLI
+
+You can add arbitrary arguments to any arena program.
+
+```shell
+python program.py -s example --config ./configuration.json
+```
+
+You can specify the dictionary of help text, used in usage help, and the `config` will at least be `None` if unused.
+Simply set `cli_args` to true, use `--config` on the CLI, and then reference, but it's a little unsafe if unused.
+
+```python
+scene = Scene(cli_args={"config": "The location of the config file to load."})
+# scene = Scene(cli_args=True)  # works too!
+file = open(scene.args["config"])
+```
 
 ## Access to Persisted Objects
+
 To get access to Objects in the persist database, you can use `get_persisted_obj`.
+
 ```python
 @scene.run_once
 def main():
@@ -42,6 +135,7 @@ def main():
 ```
 
 You can also just do:
+
 ```python
 @scene.run_once
 def main():

content/tools/authoring.md

@@ -14,7 +14,7 @@ An AR/VR capable editing tool to create/manipulate/delete ARENA objects. See top
 1. Clone our Python repo [https://github.com/arenaxr/arena-py](https://github.com/arenaxr/arena-py).
 1. Usage: `arb` takes at minimum one argument, the first one, a scene name (`hello` in this example).
    ```shell
-   python3 tools/arb/arb.py hello
+   python3 tools/arb/arb.py -s hello
    ```
 1. Interact with the tool at https://arenaxr.org/[your username]/hello
 
@@ -27,26 +27,29 @@ An AR/VR capable editing tool to create/manipulate/delete ARENA objects. See top
 ## Usage
 
 ```
-usage: arb.py [-h] [-n NAMESPACE] [-b BROKER] [-p PORT] [-r REALM] [-m MODELS] [-d] scene
+usage: arb.py [-h] [-mh HOST] [-n NAMESPACE] [-s SCENE] [-d DEVICE] [-p POSITION POSITION POSITION] [-r ROTATION ROTATION ROTATION]
+              [-c SCALE SCALE SCALE] [-D]
 
-ARENA AR Builder.
-
-positional arguments:
-  scene                 ARENA scene name
+arena-py Application CLI
 
 optional arguments:
   -h, --help            show this help message and exit
+  -mh HOST, --host HOST
+                        ARENA webserver main host to connect to
   -n NAMESPACE, --namespace NAMESPACE
-                        ARENA namespace
-  -b BROKER, --broker BROKER
-                        MQTT message broker hostname
-  -p PORT, --port PORT  MQTT message broker port
-  -r REALM, --realm REALM
-                        ARENA realm name
-  -m MODELS, --models MODELS
-                        JSON GLTF manifest
-  -d, --debug           Debug mode.
-```
+                        Namespace of scene
+  -s SCENE, --scene SCENE
+                        Scene to publish and listen to
+  -d DEVICE, --device DEVICE
+                        Device to publish and listen to
+  -p POSITION POSITION POSITION, --position POSITION POSITION POSITION
+                        App position as cartesian.x cartesian.y cartesian.z
+  -r ROTATION ROTATION ROTATION, --rotation ROTATION ROTATION ROTATION
+                        App rotation as euler.x euler.y euler.z
+  -c SCALE SCALE SCALE, --scale SCALE SCALE SCALE
+                        App scale as cartesian.x cartesian.y cartesian.z
+  -D, --debug           Debug mode.
+  ```
 
 ## EDIT Button
 The `edit` button will update all objects in the scene with click-listeners, allowing you to target ARB commands to any object. Toggling the `edit` button **on**, updates the scene `scene-options` object and will remind you to reload the page for edit mode to fully activate. You may see an <span style="color: orange;">orange warning</span> in the upper left that [Events Publish Behavior is too high](/content/troubleshooting.html#warning-events-publish-behavior-is-too-high), which is expected and a reminder to toggle the `edit` button **off**, when finished editing the scene with ARB.
@@ -108,7 +111,7 @@ There is a small temporary object resting on position 0,0,0 in the shape of a co
 You can import a json-formatted manifest of GLTF models using the command argument **-m** to use on the **model** control panel option. You can write your own, or use the example, [arb-manifest.json](https://github.com/arenaxr/arena-py/blob/master/tools/arb/arb-manifest.json).
 
 ```shell
-python3 tools/arb/arb.py hello -m arb-manifest.json
+python3 tools/arb/arb.py -s hello --manifest arb-manifest.json
 ```
 
 Scale varies widely between individual models, so experiment with the best scale to start with.
@@ -151,19 +154,3 @@ Scale varies widely between individual models, so experiment with the best scale
   ]
 }
 ```
-
-### MQTT Host and Realm
-
-By default all `arb` MQTT messages are published to the default message broker and topic (realm and scene you specify) using this scheme:
-
-- _default broker_: `oz.andrew.cmu.edu`
-- _default topic_: `realm/s/[your namespace]/hello`
-
-To use your own MQTT message broker (**-b**) and/or realm (**-r**):
-
-- _custom broker_: `arena-west1.conix.io`
-- _custom topic_: `foo/s/[your namespace]/hello`
-
-```shell
-python tools/arb/arb.py hello -b arena-west1.conix.io -r foo
-```