Job Files

Sometimes you need more than just render a single static frame. You might need an animation or batch render scene with multiple artwork set and so on, and here Boxshot job files could help.

What is a Job File?

A job file is a file that links Boxshot project, some settings and the output image. It basically tells Boxshot how to render a project and how many times to do that.

A job file can define a turn–table animation by linking to a base project and having a number of rendering instructions for each camera position.

A job file can define batch rendering set by telling Boxshot to render the project with this artwork, then with that artwork etc.

Boxshot Job Manager internally uses job files. All the animations and batch rendering tools use job files, too. If you double–click the job in the Job Manager window and have a closer look to the folder that opens, you’ll notice the job file next to the project and artwork there.

The good news is that you too can make job files and Boxshot will render them exactly as it renders its own!

Job File Format

Job files use XML format and look something like this:

<boxshot-job version="1" name="some job" scene="/path/to/scene.boxshot5">
	<task name="task 1" width="..." height="..." 
		  passes="..." renderer="..." output="/path/to/folder/file.png">
		<camera rotation-h="..." rotation-v="..." 
				center-x="..." center-y="..." center-z="..." 
				distance="..." aspect="..." fov="..."/>
		<script>
		<![CDATA[
				scene.root.children[0].visible = false;
		]]>
		</script>
	</task>
	<task .....>
		...
	</task>
</boxshot-job>

The root tag “boxshot-job” defines job file version, its name and a path to the scene. You can leave the scene attribute empty if you generate the whole scene using scripts.

The children “task” tags define rendering tasks. Each task has name, width, height, number of passes to render or rendering time, and output fields that are pretty straightforward. You may provide just width or height, or even none of them if you’d like to use default values from the scene. One more attribute is “renderer”, which defines a rendering engine to use for the task. You can get more information about these parameters in the command line rendering tutorial.

Each task node may have a child node “camera” which controls camera’s parameters. The attribute names are self-descriptive, just put the right values there.

Finally, you can add a “script” node with CDATA block where you provide some Javascript commands to customize the scene. Note that Boxshot reloads the scene after each task that has script commands, so the changes are not preserved between tasks.

Job files have “boxshotJob” extension.

Learn by Example

As Boxshot uses job files itself, it is a good idea to have a look inside. Make a simple turntable animation job, double–click it in the job manager and see the job file in your code editor to see the camera positioning technique. Do the same for a batch rendering job to see how the artwork is applied to objects, and so on.

Boxshot actively uses scripting in job files, so having a look at our scripting tutorials might help a lot.

Rendering With Job Manager

Once the job file is ready and has a proper “boxshotJob” extension, you can simply double–click it and Boxshot will open the user interface for rendering the job.

Click the Render button as you do with your “render later” jobs, wait a bit and get the result.

Rendering From Command Line

Of course, the command line job rendering is also supported. The syntax is pretty similar to the command line project rendering, but as job files already contain almost all the information, you just need to point Boxshot to the job file itself.

Here is the command line syntax for Windows:

"C:\Program Files\Appsforlife\Boxshot 5\Boxshot.exe" --render test.boxshotJob

Here is the same for Mac:

/Applications/Boxshot\ 5.app/Contents/MacOS/Boxshot --render test.boxshotJob

So basically you need to specify the --render parameter and provide the name of the job file. Boxshot will do the rest without popping up any user interface.