Command Line Usage

Submission dialogs can be launched from ArtistView's "Submit" pulldown menu or directly from the command line. When launched from the command line, the UI can be populated with values based on command line options. This is the method employed by our in-app submission UIs.

Basic usage

Next to the executable for qubeArtistView exists an executable called qubeSubmission[_console.exe]. Based on the OS, the default path is:

Windows:C:\Program Files\pfx\qube\qubeArtistView\qubeSubmission_console.exe
OS X:/Applications/pfx/qube/qubeArtistView.app/Contents/MacOS/qubeSubmission
Linux: /usr/local/pfx/qube/qubeArtistView/qubeSubmission

Windows only

Icon

On Windows' terminal or in batch files, qubeSubmission_console.exe must be used so that the app is run in the foreground, and the standard out/err messages are properly output to the terminal.

To launch an empty submission dialog, you must let the executable know which submission dialog to display. This is done through the --submitType command line option:

qubeSubmission --submitType maya_jobtype

You can query the executable for a list of available submitTypes. Before jumping into the query, let's look at qubeSubmission's help screen by running qubeSubmission --help...

Overview of command line options

QubeSubmission's help screen can be seen by running qubeSubmission --help.

$ ./qubeSubmission --help
Usage: 
qubeSubmission [options]
Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  Startup Actions:
    -d, --debug         Run in debug mode.
    -q                  Only display warning and error messages.
    -l, --list          List available submit script types and exit.
    --fields            List available fields for the given submitType and
                        exit. SubmitType must be supplied
  Configuration Overrides:
    --stdout=STDOUT     Redirect stdout to the given file.
    --stderr=STDERR     Redirect stderr to the given file.
    --supervisor=SUPE   Use the given supe instead of the one specified in
                        qb.conf.
  Job Submission:
    --submitType=SUBMITTYPE
                        Type of submission dialog to display. This will bring
                        up a blank submission dialog of the given type.  It is
                        not necessary to use this option when supplying any
                        other submit* option, as they will contain the
                        submit_type in their argument.
    --submitDict=SUBMITDICT
                        String representation of a Python dictionary that
                        represents the job to be submitted.
    --submitPkl=PICKLE_FILE
                        Pickled [python] dictionary that represents the job to
                        be submitted.
    --submitJSON=JSON_FILE
                        JSON object that represents the job to be submitted.
    --submitFile=DICT_FILE
                        A file that contains the string representation of a
                        Python dictionary or qb.Job that represents the job to
                        be submitted.
    --submitArchive=QUBE_JOB_ARCHIVE
                        Use the given job archive (*.qja or *.xja) to create
                        the submission dialog.

Getting a list of available submission dialogs

To launch a submission dialog from the command line, one must know the submission type. A list of submission types can be seen as follows:

$ ./qubeSubmission --list
INFO: Running in normal logging mode
INFO: Load submit scripts...
+--------------------------+------------------------------------------+
| Name                     | Display name                             |
+--------------------------+------------------------------------------+
| aftereffects_appFinder   | AfterEffects Cross-platform BatchRender  |
| aftereffects_cmdline     | AfterEffects BatchRender                 |
| cinema4d_appFinder       | Cinema 4D Cross-Platform BatchRender     |
| cinema4d_osx             | Cinema 4D OSX workers BatchRender        |
| cinema4d_win             | Cinema 4D Windows workers BatchRender    |
| cmdline                  | Command-line (single)                    |
| cmdrange                 | Generic Batch                            |
| harmony_stage_network    | Harmomy Network BatchRender              |
| harmony_stage_standalone | Harmomy Standalone BatchRender           |
| maya_batch_MR            | Maya Mental Ray BatchRender              |
| maya_batch_SW            | Maya Software BatchRender                |
| maya_batch_VRAY          | Maya V-RAY BatchRender                   |
| maya_jobtype             | Maya Jobtype Render                      |
| pyCmdline                | Python controlled Command-line (single)  |
| pyCmdrange               | Generic Python Batch                     |
| skeleton                 | Skeleton Submission UI                   |
| vred_sequencer_frames    | VRED Sequencer Jobtype FrameRange Render |
| vred_sequencer_stills    | VRED Sequencer Jobtype Stills Render     |
+--------------------------+------------------------------------------+

To launch a submission UI, use the submission UI's "name" as the argument to --submitType. For example, to launch an empty "Cinema 4D Cross-Platform BatchRender" submission dialog, you would run:

qubeSubmission --submitType cinema4d_appFinder

Pre-populating a submission dialog with values

Values can be pre-populated into any field via command line options. When bringing up a pre-populated submission dialog, submitType will be encoded into the key-value pairs, therefore --submitType need not be used. qubeSubmission accepts key-value pairs through the following options:

--submitDict: string representation of a Python dictionary
--submitPkl: path to a temporary Python pickle file. Note that the file will be deleted after successful submission
--submitJSON: path to a temporary JSON file. Note that the file will be deleted after successful submission
--submitDictFile: path to a temporary text file that contains the string representation of a python dictionary. Note that the file will be deleted after successful submission

Note that any of the above options can be used multiple times in the same command. Doing so would present a submission dialog for each --submit*.

Finding the keys

To determine which keys apply to which fields in which submission types, use the --fields option:

$ ./qubeSubmission --submitType maya_jobtype --fields
INFO: Running in normal logging mode
INFO: Load submit scripts...
 -- maya_jobtype --
Common Qube parameters (not all are guaranteed to be in the submit dialog):
+------------------------+------------------------+-----------+----------+-----------------------------+
| Parameter name         | Field name             | Field Arg | opttype  | destination                 |
+------------------------+------------------------+-----------+----------+-----------------------------+
| account                | account                |           | string   | job                         |
| agenda_postflights     | agenda_postflights     |           | string   | job                         |
| agenda_preflights      | agenda_preflights      |           | string   | job                         |
| range                  | range                  |           | string   | job.package                 |
...
| requirements           | requirements           |           | string   | job                         |
| reservations           | reservations           |           | string   | job                         |
| restrictions           | restrictions           |           | string   | job                         |
| retries                | retrywork              |           | int      | job                         |
| retries                | retrywork_delay        |           | int      | job                         |
| threading              | threads_all            |           | bool     | job.package                 |
| threading              | threads_specific       |           | int      | job.package                 |
| timeout                | timeout                |           | int      | job                         |
| validate_fileMinSize   | validate_fileMinSize   |           | int      | job.package                 |
| win_env                | win_env                |           | table    |                             |
+------------------------+------------------------+-----------+----------+-----------------------------+
 
Application specific parameters:
+------------------------+------------------------+-----------------------------------------+---------+-------------+
| Parameter name         | Field name             | Field Arg                               | opttype | destination |
+------------------------+------------------------+-----------------------------------------+---------+-------------+
| DR                     | DR                     |                                         | combo   | job.package |
| cameras                | cameras                |                                         | string  | job.package |
| default_light          | enableDefaultLight     | defaultRenderGlobals.enableDefaultLight | combo   | job.package |
...
| renderer               | currentRenderer        | defaultRenderGlobals.currentRenderer    | combo   | job.package |
| renumber_byframe       | byExtension            | defaultRenderGlobals.byExtension        | string  | job.package |
| renumber_startframe    | startExtension         | defaultRenderGlobals.startExtension     | string  | job.package |
| scenefile              | scenefile              |                                         | path    | job.package |
| threads                | renderThreads          | -threads                                | int     | job.package |
+------------------------+------------------------+-----------------------------------------+---------+-------------+

"Field Arg" should be used as the key when available. If there is no field arg, then "Field Name" is used. The value given, then, will be used to populate the field in the UI (assuming that the value has not been mandated by preferences) that matches the field arg or field name.

For example, to launch a maya_jobtype submission dialog, pre-populated with a frame range of 1-100, a retry count of 5, a scene file of /path/to/scenefile.mb, and to explicitly set the renderer to Mental Ray, you would use the key/value pairs:

{'retrywork': 5,
 'package': {'range': '1-100',
             'scenefile': '/path/to/scenefile/mb',
             'defaultRenderGlobals.currentRenderer': 'mentalRay',
            }
}

Note that for the last setting, 'defaultRenderGlobals.currentRenderer', we are using the field arg rather than the field name. When a field arg is available, it must be used; but if it is not, as is the case with 'retrywork', 'range', and 'scenefile', then the field name is used.

Note that 'retrywork' is the only item in the root of the dictionary, while 'range', 'scenefile', and 'defaultRenderGlobals.currentRenderer' are in the dictionary's 'package'. To determine which keys go into the root and which go into 'package', look at the "Destination" column in the output of fields. If the destination is "job," then the associated key is used in the root of the dictionary. If the destination is "job.package," then the associated key is used in the dictionary's 'package'. When in doubt, use the dictionary's package.

Using key/value pairs on the command line

Now that we know which key/value pairs to use, and where they should be within the submission dictionary, we need to get that dictionary to the submission UI. This can be done using one of the following command-line option arguments:

submitDict: as a string representation of a Python dictionary
submitPkl: as a Python dictionary pickled to a file
submitJSON: as a JSON dictionary saved to a file
submitDictFile: as the string representation of a Python dictionary written to a text file

In the following examples, we will be using a maya_jobtype submission dialog with the name, instances(cpus), frame range, and scene file fields populated from the command line.

submitDict Example

submitDict uses the string representation of a Python dictionary directly on the command line. One must be mindful of quotes - being a command line argument, the dictionary must be a single, quoted string, so any quotes within the string must be escaped. This can become especially difficult when the command is being generated by a program (i.e. Maya) where both the quotes and the quotes' escape characters must be escaped.

./qubeSubmission --submitDict

"{'name': 'Maya job submitted from command line', 'cpus': 5, 'package': {'submitType':'maya_jobtype', 'range': '1-100', 'scenefile': '/path/to/scenefile.mb'}}"

Note that we're using two different types of quotes - double quotes for the argument and single quotes within the argument. Were we to use the same quotes throughout, we would need to escape those within the argument:

./qubeSubmission --submitDict

"{\"name\": \"Maya job submitted from command line\", \"cpus\": 5, \"package\": {\"submitType\":\"maya_jobtype\", \"range\": \"1-100\", \"scenefile\": \"/path/to/scenefile.mb\"}}"

submitDictFile example

For applications that do not provide a Python or JSON interface but can write text, there exists a submitDictFile option which will evaluate the contents of a passed in file as Python dictionary. One might find this advantageous over --submitDict being that there won't be the same quoting issues due to the fact that there is no command-line evaluation. In this example, we'll use Python to create the text file, but any application that can write text to a file would suffice.

$ python
>>> job_dict = {'name': 'Maya job submitted from command line', 'cpus': 5, 'package': {'submitType':'maya_jobtype', 'range': '1-100', 'scenefile': '/path/to/scenefile.mb'}}
>>> fp = open("/tmp/dict_file.txt","w")
>>> fp.write(str(job_dict))
>>> fp.close()
>>> exit()
 
 
$ ./qubeSubmission --submitJSON /tmp/dict_file.txt

submitPkl example

Assuming one can launch the submission dialog from a Python interpreter, submitPkl is a more powerful/useful option.

$ python
>>> import pickle
>>> fp = open("/tmp/job_dict.pkl","wb")
>>> job_dict = {'name': 'Maya job submitted from command line', 'cpus': 5, 'package': {'submitType':'maya_jobtype', 'range': '1-100', 'scenefile': '/path/to/scenefile.mb'}}
>>> pickle.dump(job_dict, fp)
>>> fp.close()
>>> exit()
 
 
$ ./qubeSubmission --submitPkl /tmp/job_dict.pkl

submitJSON example

For applications that do not provide a python interface and/or applications that can write JSON, there exists a submitJSON option which will ingest JSON files. In this example, we'll use Python to create the JSON file, but any application that can write JSON would suffice

$ python
>>> import json
>>> job_dict = {'name': 'Maya job submitted from command line', 'cpus': 5, 'package': {'submitType':'maya_jobtype', 'range': '1-100', 'scenefile': '/path/to/scenefile.mb'}}
>>> fp = open("/tmp/job_dict.json","w")
>>> json.dump(job_dict, fp)
>>> fp.close()
>>> exit()
 
 
$ ./qubeSubmission --submitJSON /tmp/job_dict.json