Quick Start

(1) Make sure that following runtime library has already been installed in your conputer.

Microsoft Visual C++ 2017 Redistributable (x86)

Note that it must be "x86" (i.e. for 32 bit) even if your OS is 64 bit. You can download and install it from Microsoft's site. If a file, ucrtbase.dll, has already been installed in the directory Windows\SysWOW64\ or Windwos\System32\ of your computer, the installation of the runtime may not be unnecessary. You can also check that by right-clicking Windows "Start" - "Programs and Features" (or "Control Panel" - "Programs and Features").

(2) Unzip the downloaded zip files (xxxx_Main_xxxx.zip, xxxx_tSxx_xxxx.zip, and pythonxxxxx.zip) to any folder you like. You get all or a part of the following files.

To check the version of each ptsxpy DLL file, right click the file, select "Property", select "Details" tab. You need to rename *.tsx to *.dll before you do that.

If you want to check the Python DLL files are genuine, please read "About the Python DLL" in License" page.

(3) Using Windows Explorer, locate to the directory where tS was installed. (If you forgot it, right click your trueSpace icon and select "Open file location")

(4) Find "tsx" (or "Tsx") folder and locate in it.

For example, you may be in:  c:\xxxxxxx\trueSpace761\tS\tsx\

(5) Make a folder in the "tsx" folder, rename it to "ptsx3py" (or "ptsx2py") or any name you like, and move the downloaded and unzipped files to the folder. You need not unzip the python.37.zip.

2. Uninstall and partial update 

If you would like to uninstall the ptsxpy, just delete the "ptsx3py" (or "ptsx2py") folder that you made at the installation precess. This plugin does not write any Windows registory on its installation.

If you would like to update to newly released version, just replace the files. Before you run your script, you should unload the old ptsxpy3 (or ptsxpy2) icon using Shift drag to trashcan icon, and then load the .tsx file to trueSpace.

3. Load ptsxpy to trueSpace

(1) Start your trueSpace.

(2) Find "Install new trueSpace extension" button ("plug" icon) and click it. A file selection dialog appears.

If you use tS4.3, a place holder with eight buttons appeares when you click the plugin button. Click unused one of eight.

(3) Locate to the "ptsx3py" (or "ptsx2py") folder, double-click "ptsx3py.tsx" (or "ptsx2py.tsx") or select it and hit Enter key.

(4) The "ptsxpy3" (or "ptsxpy2") icon appears next to the "plug" icon. The Screen shot below is of tS7.6 (Model side)

, orfor tS4.3

If you would like to unload the plugin, Shift drag the icon to the trashcan. You can clone the icon by dropping any othre place.

You may load both ptsxpy3 and ptsxpy2 on a tS at the same time and can run script with each Python. However please note that the console window and the tS resources are common for both. You must avoid conflict of them.

4.  Run a Python script file

(1) Prepare your script file. For example, create a text file, open it using a text editor, copy following code, save and rename it like "test1.py".

In Python language, the indentation level (i.e. blank preceding to each line) is significant. Please check the documents distributed by python.org: "PEP 8 -- Style Guide for Python Code" )

#------------------------------
# Crete and move some cubes.
#------------------------------
import ptsxpy as p
import ptsxgp
import math

x = 0.

for i in range( 5 ):
    print( "i=", i )
    cb1 = p.CreateCube( 2 , 1., 1., 1. )
    p.SceneAddObject( cb1, e_tsxFALSE )
    loc = Vec3f( x, 0., 0. )
    print( "loc=", loc.prt() )
    p.GNodeSetLocation( cb1, loc.p )
    x += 2.

p.SceneDraw()

 In the example above, p.CreateCube() calls the correcponding C++ side tSxAPI function tsxCreateCube(). You can get information from tSxAPIxx.doc in SDK for each trueSpace version. The module "ptsxgp" and "math" are imported but not used in this example. They are necessary only if you use methods of these module. The "math" is a satandard module of Python and the "ptsxgp" has general purpose functions for user script and "ptsxpydef1.py".  The "ptsxpydef1.py" is always imported automatically to user script (please read also the section below).

(2) Click the "ptsxpython" button.

(3) A file selection dialog and a console window (with black background) appear. tS may hide the console window. you can bring it forward later using holding-Alt key and a few times of Tab key.

(4) Locate to the directory where a script you would like to run exists. Double-click your script file (or select and Enter key)  to start it.

(5) A message "...ended" comes to the console window when the scripts ended.

Note: it's highly recommended that you manage the combination ofthe Python major version  (2 or 3) and ptsxpy major.minor version (x.y in x.y.z), because the specifications and the implementations of ptsxpy may change in the future. In addition, if you attach the script to a post to the Uesr Forum, etc., you should clearly describe on which tS version the script can run.

5. Syntax of functions, predefined classes and constants

In the above sample code, the script is calling some tsxAPI functions like: p.XXXXX( ---- ). The "p" here is an alias of a module "ptsxpy" defined at the beginning of the script. The "XXXXX" here is the part of the name of each tsxAPI function, tsxXXXXX(). If you have the SDK (Software Development Kit) distributed by Caligari corporation for your trueSpace version, you can know the syntax and behavior of them from tsxAPIxx.doc and .h files. The SDK may be found via the net.

The plugin automatically imports a plain text, "ptsxpydef1.py", while it initializes Python. It defines some classes (e.g. Vec3f) and constants (e.g. sizeof_CtsxVector3f). Please don't modify the file. You can add your original classes and constants in each script file or in your file. In the sample script, an instance of Vec3f class is assigned to  the variable "loc". The "loc.p" means the pointer to the three float values. The function GNodeSetLocation() receives it as the 2nd parameter, and sets the location of the cube object given to the 1st parameter. The "e_tsxFALSE" is defined in the "ptsxpydef1.py". You need not to write like "ptsxpydef1.e_tsxFALSE" and can omit the module name because the module is imported like "from ptsxpydef1 import *" by the plugin. The "ptsxgp" is a module of general purpose auxiliary functions.There are some ptsxpygp functions used in "ptsxpydef1.py".

Please read also HELP pages and visit FORUM where you can get sample scripts, read tutorials, report bugs, request features, discuss with members, or ask questions. Registration required before submitting your first post.