SyPy: A Python API/SDK for SynthEyes
SynthEyes Pro includes an API* and SDK** package called SyPy ("sigh-pie") that enables you to write Python programs to control a SynthEyes application instance. You can write new user assistance tools, or integrate with 3rd party applications that also offer python capability, such as 3ds max, maya, Cinema 4D, Hiero, Shotgun, etc. You can use SyPy with user-interface packages such as PySide or PyQT, and write and debug code using your favorite Python IDE***.
SyPy uses an advanced "bring your own python" architecture. It is installed into the python of your choice and communicates with a SynthEyes application to do your bidding. Technically, this is a client-server architecture like a browser and web-server, or like an X11 application and its windowing server. The setup details are handled automatically within SyPy.
The SyPy architecture tremendously simplifies integrating SynthEyes with other applications, since SyPy effectively executes within the 3rd party application. In a typical integration of other software tools that don't use SyPy's approach, a custom communication channel must be set up, or two matching tools developed, one for each application, that share a file formatwith substantial effort for each.
With SyPy, one python acts as if it is embedded in both applications. The programmer can easily access information from both SynthEyes and the 3rd party application, intermingling calls to the respective APIs. It's a very powerful approach.
SynthEyes Functionality Exposed by SyPy
SyPy offers extensive access to functionality within SynthEyes; including:
- open a new or existing SynthEyes, create new scenes, open shots, save the SNI file, close the application;
- set export type and file, export, render image sequences from the image preprocessor;
- operate the user interface, set playback rate and range, start and stop playback;
- access shots, cameras, moving objects, trackers, meshes, etc in SynthEyes as objects within python, with their Sizzle-script parameters accessible;
- control and access the SynthEyes undo system;
- examine and set the SynthEyes preferences;
- click items on the main menu or right-click menus of viewports;
- make well-chosen additions to the main menu;
- access the main, popup, or floating windows, and locate sub-windows recursively by name, class, or ID;
- examine windows and perform window-specific operations for buttons, combos, spinners, etc;
- use a python class to manipulate SynthEyes-format transform matrices;
- utilize the high-performance builtin OBJ importer.
And of course all that functionality can be combined with the functionality inherent to python, including user interfaces built with Tkinter, PySide, PyQT, or other similar packages.
What Is Included?
The following items are included in SyPy:
- SyPy python code
- SyPy documentation
Script programming requires a substantial degree of expertise and is not covered by our normal support. We can't debug your code nor write code for you. We reserve the right to charge an additional technical support fee to cover scripting.
Show Me Something!
Here's a small example that converts a camera track to an object tracka typical fix-it task. Notice the first line: it gives the title that this script appears under, on the SynthEyes Script menu.
# ; Quick convert camera-track to object-track import SyPy hlev = SyPy.SyLevel() hlev.OpenExisting() # Go to the solver panel and reset the camera hlev.SetRoom("Solver") bid = hlev.ActionID("Solve/Clear") hlev.Main().ByID(bid).ClickAndWait() # it's on the Summary panel # Start our undo block for low-level changes hlev.Begin() # Make a new moving object on the active camera mob = hlev.CreateNew("OBJ") # Move all the trackers to the new object cam = hlev.Active().cam # active cam for sure for t in cam.Trackers(): t.obj = mob # Make the camera disabled, and the new object active cam.mode = "Disabled" hlev.SetActive(mob) hlev.ReloadAll() hlev.Accept("Convert to moving object") # All done... could re-solve here if desired.
Frequently Asked Questions
Why isn't python "built in" to SynthEyes? Python is free open-source software with many different versions available. There's no reason for us to pick a particular one that might not fit your needs. You can download and use whichever python you prefer, including python from other applications or IDEs. Since you're writing python code against the SyPy API in any case, what we do behind the curtain is largely irrelevant, except that in this case, our approach is vastly more flexible and gives you great new possibilities.
What versions of Python are supported? We've run SyPy on python 2.6 and 2.7. If you have a need for Python 3, please contact us; we've done some planning so that it shouldn't be a big deal.
How do I install SyPy into (the Python of) another application? SyPy is written in python; it is a standard python "package." To install it, just copy SyPy into the "site-packages" folder of the python installation that you want to run SyPy in. For example, for Cinema 4D, copy SyPy to C:\Program Files\MAXON\CINEMA 4D R12\resource\modules\python\res\Python.win64.framework\Lib\site-packages.
Can I use python on one computer to control SynthEyes on a different computer? No, that's neither possible nor permitted by the license.
Do you offer any languages other than python? We currently offer only a python version of the API/SDK, but the underlying technology is language-independent. An API and SDK for another language would require only porting the portion written in Python, which consists of rather shallow stubs.
SyPy is offered in the Pro version only, solely for the purpose of enabling customers to enhance the user-interface and workflow of their tracking artists (not eliminate them!) by enabling better integration with the customer's own tools. The license agreement contains limitations on the usage of the scripting technologies; SyPy applications
- must not create electronic systems that process disproportionate numbers of shots without artist direction,
- must not create replacement user interfaces that allow a SynthEyes license to be remoted, virtualized, or otherwise shared between users, and
- must not create services that process shots submitted by third parties.
*: API stands for Application Programming Interface. The python programmer writes code that calls functions listed in the API. The calls are implemented by the SyPy SDK.
**: SDK stands for Software Development Kit. The SyPy SDK is a python package that contains the code required to actually perform the operations the programmer requests using the SyPy API.
***: IDE stands for Integrated Development Environment. An IDE allows you to edit and run your code within the same program, which typically offers python-specific features such as code coloring and code auto-completion operations.