ContextCapture® | Getting Started with the SDK

Introduction

The ContextCapture API enables the script based creation, processing and monitoring of
ContextCapture projects. This can be very useful for automating the production workflow in part or
whole, customising the workflow for a particular use case or integrating ContextCapture processing
within a broader production process.

The API is made available as a Python module and provides the majority of Master’s functionality in
script form. Note it is not a GUI automation SDK, ie. the script is not executed within Master but run by
a Python interpreter without a user interface. More on this later.

As of update 15 the API is available in both Center and Desktop editions.

This guide is intended to get you up and running quickly using the API and overcome some typical
hurdles in getting started. It is not a comprehensive guide to the API features and functions, for this
please consult the documentation in the sdk folder of your ContextCapture installation.

Python

When installing ContextCapture you will be given the option to install Python 3.6. Don’t worry if you
didn’t do this during installation.

Python is a widely used scripting language that is easy to learn yet extremely. One of Python’s powerful
features is the way it is highly modular. There is a Python module for almost anything you might want to
do. This means you spend a lot more time focusing on developing the overall functionality of your
program and far less on peripheral or supporting functions. For example if you were developing a
program to catalogue photos by location you would use a module to read the jpg metadata, another to
geolocate the GPS coordinates of the image, and yet another database module to store the results and
form an index.

Installing modules is very easy and this process can even be scripted to ensure you can move your
development between machines and have exactly the same environment with the same versions of
each module.

ContextCapture provides such a module. Although unlike most of the other modules you will use it is
not public and freely available rather it is distributed in the ContextCapture installation.

The Quick Start

The nice developers in the ContextCapture team have provided a script that will perform a lot of the
setup needed to get up and running quickly with the SDK. This is in the sdk folder, though as with
everything else in that folder it is better copied or moved to a location outside of the Program Files
folder to avoid issues with admin rights.

The script will check if Python is installed, install a virtual environment for you and install the
ContextCapture package in the environment. Read on if you want to understand those steps in more

ContextCapture® | Getting started with the SDK. 2020 Page 3 www.Bentley.com

detail and do it yourself, otherwise you can skip the next section.
To get started quickly simply run cc_py_cmd.bat in the sdk folder.

Note that in early builds of update 15 this script contained a bug that may cause it to fail on a fresh
installation of Python. If this is the case update your ContextCapture installation or install the
environment manually as described in the following steps.

Virtual Environments

A lot of applications use Python so you may have multiple Python installations on your machine already.
Each application or script might require a different Python version, different sets of modules, each with
its own version. In the past this scenario was commonly faced by programmers and many of them lost
their hair over it as the resulting mess caused many failures. Luckily Python has an effective way of
ensuring the hygiene needed and avoiding the ‘dll hell’ of the past. This is through what is known as
virtual environments.

A virtual environment is like having multiple desktops on your machine. Each desktop, or environment is
like a clean slate and you can add which ever modules you require for your project/s. You can create as
many environments as you want and switch between them as needed. The environments are
completely isolated from each other. Unlike a desktop however there is nothing visual about an
environment – instead you give each environment a name.

It is strongly recommended to use a virtual environment for working with the API through strictly
speaking it is not necessary if there is no other Python use on the machine.

There are 2 main options for doing this, Virtual Environment (virtualenv) and Conda (or Miniconda).
Both do essentially the same thing but in different ways. virtualenv keeps central store of every module
and version of Python you use in each environment but does not duplicate them. virtualenv is actually a
python module and so works within Python which needs to be installed first. When an environment is
made the active environment it sets it up with the required modules. Conda on the other hand keeps
the environments completely separate even if they contain duplicate modules and Python versions. It is
outside of Python and so contains Python itself and you can setup an environment from scratch
including the Python installation very easily.

Either solution will work but we’ll use virtualenv for getting started as it is more commonly used. If
you’re tempted to use Conda for any reason then it is recommended to use Miniconda which is a leaner
version. The full Conda is somewhat bloated including many packages for scientific computing which are
not needed for ContextCapture use. Conda is an excellent solution for managing environments and in
some ways organises cleaner than using virtualeenv.

Setting up Python and the Virtual Environment

The ContextCapture module must be used with Python 3.6x. Older or newer versions of Python will not
work. If you didn’t install Python during the ContextCapture installation visit you can download it from
https://www.python.org/ftp/python/3.6.4/python-3.6.4-amd64.exe

To check it’s installed and available enter a commandline session (Windows+R, type cmd then enter)
and type python + enter. You should see the version of Python and some information displayed. If you
are not seeing the version of Python you installed this means you already have another Python version
installed which is acting as the default. In this case type exit(). On the command line go to the folder
in which you installed version 3.6.x and try typing python again. This time you should see the correct

ContextCapture® | Getting started with the SDK. 2020 Page 4 www.Bentley.com

version of Python displayed. Type exit() to exit Python.

We are now going to install Virtualenv using the package manager with the following command:

python -m pip install vitualenv

You should see some activity, the module is actually being downloaded and installed. Pip is the module
used to install or remove Python modules.

Now we will create the environment we will use for ContextCapture. Decide where you are going to
place the new environment, it’s just a few folders and files that will be created. The folder does not
have to exist, it will be created when the environment is created. To do this type:

virtualenv <path to you new environment folder>

To activate the virtual environment (VE) we need to run the activation script. This is named activate.bat
and is located in the Scripts sub-folder of the new virtual environment folder. Run this file to activate
the environment.

Finally we need to install the ContextCapture module into this new environment. This is contained in a
wheels package located in the sdk/dist folder of the ContextCapture program folder. Due to rights
issues it might be easier to copy this file somewhere else where admin permissions are not required.
Note that it is like an install package, so once installed you script will not access this again.

python -m pip install <full file path to ccmasterkernel-4.4.15.2008-

cp36-cp36m-win_amd64.whl>

You can drag and drop the whl file into the commandline window and its path should appear on the
commandline, easier than typing it out.

You’re all done installing Python, a VE and the ContextCapture module.

Running a script

Let’s take this little setup for a ride. There’s a script in the samples folder called automaster.py. It runs
through project creation, processing and output. It’s better to move the script from this location to
somewhere outside of Program Files folder to avoid running into problems with Admin rights.
Open this file in any text editor and change the photosDirPath and projectDirPath on lines 25 and 26 to
a location you have some photos to process and a folder to store the ContextCapture project file. Be
careful to use forward slashes (/) in the path rather than the more usual backslashes (\) since
backslashes are interpreted differently in code (as escape characters). Now save and close this file,
we’re going to come back to it later.
First let’s check everything is installed as expected. We can do this by simply attempting to import the
ContextCapture module. In a console window, type:

python to start a python console

import ccmasterkernel to attempt to load the module

If you didn’t get an error doing this then congratulations, you’re all set up and ready to run a script.
Type exit()to leave Python. Now let’s run a script to perform some processing, type:

python <path to the automaster.py script>

ContextCapture® | Getting started with the SDK. 2020 Page 5 www.Bentley.com

As before you can drag and drop the script file into the console window to extract its path.
You’ll see the images listed and that the process is waiting on the Engine (unless you have the Engine
running already). Start ContextCapture Engine and the process should run to completion providing
feedback on progress along the way.

Working with an IDE

This is all you need to develop ContextCapture scripts in Python, but in practice it’s very useful and
often quicker if you work within an Integrated Development Environment or IDE for short. This is just an
application that combines the development tools in a single environment. It’ll do nice things like color-
code the script to make it easier to read and even check errors as you type.

There are two freely available tools to consider, Microsoft’s Code and JetBrains PyCharm Community
Edition.

MS Code is a lightweight IDE that is better suited to someone with more experience as setting it up can
be tricky if you want to run the script through it, debug etc..This is because most setup is done through
json based settings files. The editor is excellent however. PyCharm is suited to both beginner and pro
and powerful enough for our needs, we’ll run with that.

You can download the Community Edition of PyCharm from https://www.jetbrains.com/pycharm/.

Once installed we’ll need to do a little configuring to get it working with our setup.
Mostly we just need to tell PyCharm which Python and Virtual Environment you are using for your
project.

Configuring PyCharm

Open PyCharm and start a new project. Drop down the Project interpreter (1) options to set up the
virtual environment.

Choose Existing interpreter (2) as we’ll be using the VE we setup earlier.

ContextCapture® | Getting started with the SDK. 2020 Page 6 www.Bentley.com

2

Use the ‘…’ button (3) to choose the VE and on the next dialog use the ‘…’ button to pick the python.exe
you will be using. This will be located in your VE folder under the Scripts folder. If you used the
cc_py_cmd batch file to set everything up automatically then the environment will be located in
C:\Users\<Your Account>\AppData\ContextCaptureSDK_CCCenter\4.4.15.2008\ otherwise it will be
where you created it.

The next time you create a project the Interpreter should already be listed so this process will be a lot
quicker.

Create a folder for your project and copy automaster.py there (you may have done this already when
we ran this earlier). Note that multiple projects can share the same VE so it’s not best to choose the VE
folder for your project, though you can. Select this folder as your project folder and you will get a
warning that the folder is not empty. That’s ok, choose to use the contents of the folder for the project.
To run the script go to the Run / Run ‘automaster.py’ menu option. This will run the script as before, but
now through the IDE.

There’s a lot you can do with an IDE such as run through the code line by line or force the execution of
the script to stop in a location to examine what’s going on. This makes developing and debugging scripts
a whole lot easier.

Using the API documentation

Fortunately you’re not left guessing how the ccmasterkernel API works and what the functions are.
These are all well documented. You can find the documentation under the sdk/doc folder. This is really
an API reference rather than a user guide. The best way to learn how to use the API is to examine the
example code and start writing your own.

Working with the Automaster Example

The automaster example creates a ContextCapture project, creates the input blocks from the photo set
and then sets up the aerotriangulation and reconstruction. As the processes are executed it provides
feedback by monitoring the updates the engine is providing. As with the Master, the API does not
perform any processing itself, it merely creates the tasks or jobs to be performed.

The code has been written to be easy to read and understand – the code is largely ‘self-documenting’
The concepts closely mirror those in Master so the flow of events should make sense. A good way to
learn how to use the API is to make changes to the code and try to run it. For example you can change

ContextCapture® | Getting started with the SDK. 2020 Page 7 www.Bentley.com

the code to output a different format or change positioning mode. Make a copy of the file before you
do this so you can always go back. You will find the API reference useful as you progress as it describes
each class (type of object) and what it can do.

ContextCapture® | Getting started with the SDK. 2020 Page 8 www.Bentley.com