Command Line Rendering

Boxshot supports command line rendering of projects which can be useful when the built–in batch rendering tool is not enough. You can render an existing project with the parameters you need from the command line and this tutorial will show how.

Simple Rendering

Make sure you have a Boxshot license, as command line rendering doesn’t work in the demo mode. Start Boxshot, make a simple scene say with a book and save it to the Desktop, naming the file “project”. You should end up with having a file “project.boxshot5” on your desktop.

You can use a different folder and project name, but then make sure you updated the code below to match your specific.

Now let’s render the project. Run your terminal/console application and navigate to your desktop folder. There you can do something like this on Windows:

"C:\Program Files\Appsforlife\Boxshot 5\Boxshot.exe" --render --passes=100 --output=result.png project.boxshot5

Mac users need to do this:

/Applications/Boxshot\ 5.app/Contents/MacOS/Boxshot --render --passes=100 --output=result.png project.boxshot5

Type the line above and press enter. You should see Boxshot running in command line mode, printing some information and rendering the scene. In a few seconds you should get the file named “result.png” next to the project you created. Done!

If you don’t see Boxshot running — make sure you typed the path to the application executable without mistakes and didn’t miss any quotes, slashes or spaces. If Boxshot runs, but display errors — read them to get a better understanding of the issue. You most likely run it from a different folder and it cannot find the project file.

Note that Boxshot will not render a scene if the output file already exists. Remove it, if you want to re–render the scene.

Rendering Options

As you have probably already noticed, Boxshot supports command line parameters for fine–tuning the rendering process. Here is the full list:

• --render — a mandatory parameter that tells Boxshot to run in command–line rendering mode;
• --output=xxx — another mandatory parameter that defines the output file name and format;
• --passes=NNN — configures the number of rendering passes to make;
• --time=NNN — configures the time (in minutes) to perform the rendering;
• --width=NNN — the width of the output image;
• --height=NNN — the height of the output image;
• --engine=xxx — lets you select the rendering engine (see below).

The width and height parameters are optional and if not provided, Boxshot will use the ones saved in the project. If you provide just width or height, Boxshot will compute the other parameter using the camera aspect of the project. If you provide both, Boxshot will override the camera aspect with the new one made of the width and height parameters you provided.

You can configure the rendering quality by either provide the number of passes to render, or the desired rendering time. If you provide both, Boxshot will stop once it reaches one of the limits: either the number of rendering passes are made, or if the provided time is over. Use 50–200 passes for fast and draft preview and 1000 and more for production rendering.

The --engine parameter can be one of those:

• renderer.raytracer3 — the default CPU renderer (used by default);
• renderer.metal — Metal renderer (Mac–only option).

Advanced Rendering Ideas

There is no much sense in rendering existing projects using command line, unless you do a hot–folder automation. It is easier to render them from the user interface or using the job manager, so here is an idea of batch rendering of multiple artwork with the same project.

When Boxshot saves a project, it doesn’t collect all the artwork it uses. Instead, Boxshot stores relative or absolute paths to the artwork and loads it from its original location. There is a Collect Resources… command in the File menu that lets you collect all the artwork when saving project.

Make a test project with, say, a book and apply some custom artwork to its front, side or back side. Whatever you are going to batch–render. Once done, click File → Collect Resources… in the menu and when asked for saving file name, point it to the folder “test” you created on your desktop and name the output file “project”, as we did above.

If you come to that folder, you’ll see the Boxshot project will all the artwork nearby, including the custom one you assigned. From there it should start making sense: you can replace the artwork with your own, render the project, put another artwork, rendering it again and so on.

We’ll not go into the implementation details, as job files do this easier, but if you need a very custom workflow — this “low level” approach could help.

More Batch Rendering Tutorials

• Turntable Animation — render fly–around animations;
• Transition Animation — render transition from one snapshot to another;
• Oscillation Animation — render camera oscillation animations;
• Batch Rendering — render the same scene with multiple artwork;
• Command Line Rendering — render projects from command line;
• Job Files — make and render batch jobs with code.