Python Users: Ceetron Python Modules [CPM]

Setting up the environment

Prerequisites

You will need Python 3.6 or 3.7 to be installed on your system. There is a version for each of these python packages. You will also need to install the requests module, eg. pip install requests. On Windows you will also need Visual C++ 2015 runtimes (see Deployment section below) which are usually already installed.

License

To use Ceetron Python Modules [CPM] you will need a license. You can get a free evaluation license by contacting suppo.nosp@m.rt@c.nosp@m.eetro.nosp@m.n.co.nosp@m.m. When you receive your license, please update the license keys A&B in the cee/licence.py file.

You can also configure the license codes with environment variables:

CEETRON_DESKTOP_COMPONENTS_LICENSE_KEY_A = 0x12345678
CEETRON_DESKTOP_COMPONENTS_LICENSE_KEY_B = 0x87654321

Finally, you can also do initialization of CPM manually and provide you license to the cee.core.CoreComponent.initialize method. See Examples/minimal_core.py for an example on how to do this.

1 import cee.core
2 comp_instance = cee.core.CoreComponent.initialize(my_license_key_a, my_license_key_b)

Configure your installation

The only thing you need to configure to run the examples is the license as described above.

The examples scripts use the helpers/setup_environment.py to configure the PYTHONPATH and on Windows the PATH. You can choose to use this helper or in any other way setup the PYTHONPATH (and optionally PATH) for CPM to work. PYTHONPATH should point to the root of the CPM installation.

Running example scripts

Minimal test example

This example creates a simple geometry with the cee.geo module and exports the model to a PNG image. Run this to verify that the CPM installation is ok and that the off-screen rendering using OSMesa works as expected. The script will create an image called script_outputs/minimalImage.png

To run the example:

  • go to the ./Examples folder
  • using the terminal do:

    python minimal_osmesa.py

Tutorial

This example shows how to use CPM to extract information from the CAE file. It is also an introduction to the CAE object model of CPM.

To run the example:

  • go to the ./Examples folder
  • using the terminal do:

    python tutorial.py

Run the export examples

The Export Examples is a collection of examples showing how to use CPM to export to the Ceetron free viewers using VTFx, export to a cloud streaming database (CUG) and upload to Ceetron Cloud for remote visualization in a browser.

To run the example:

  • go to the ./Examples/ExportExamples folder
  • using the terminal do:

    python test_examples.py

If all works well, this will run a number of tests on provided example models located in ./Examples/DemoFiles : Ansys, Fluent, openFOAM and VTK-VTM

Tested functions, all with custom display model configuration:

  • Export to CUG
  • Export to VTFx
  • Send model to Ceetron Cloud account
  • Addition of a custom result to example Ansys model
  • Export of the example Ansys model to a custom format, producing myFile.txt which is opened automatically

All result output is stored in "example_test_results" which can be deleted afterwards.

Take a look at custom_vtfx_export.py

The other custom modules (custom_cug_export and custom_send_to_cloud) follow the same pattern : arguments are parsed and verified. A model is then opened, configured and exported to a VTFx file, or CUG folder or sent to cloud.

Note that the configuration of the model is passed as an argument : the user specifies the name of the configuration function and its parameters. For example, the following command line calls the configuration function "setLastStateAndScalar" with parameter "XX Stress*"

python custom_vtfx_export.py ../DemoFiles/example_ansys.rst example_ansys_xx_stress.vtfx setLastStateAndScalar "XX Stress*"

The same can be achieved within a Python file:

1 import custom_vtx_export
2 custom_vtfx_export.run("../DemoFiles/example_ansys.rst", "example_test_results/example_ansys_xx_stress.vtfx", "setLastStateAndScalar", "XX Stress*")

Please note that if multiple files need to be opened to get a full model, they need to be specified as the first argument using a "," as a separator. For example, this command line operates on a Fluent model using two files : example_fluent.cas (geometry) and example_fluent.dat (results)

custom_vtfx_export.run("../DemoFiles/example_fluent.cas,../DemoFiles/example_fluent.dat",   "example_test_results/example_fluent_all_velocity.vtfx",    "setLastStateAndScalar",    "All Vel*")

Use for your own needs

The customizable part of all these export and shares (VTFx, CUG, SendToCloud) is thus isolated as a configuration function in the configure model. This is where you would write your own display model configuration functions, which can then be invoked by name on the command line as seen above. The functions rely on CDC programming, please refer to the documentation or contact Ceetron for an introductory training to get you up to speed.

Documentation

Ceetron Python Modules offers all of the features from Ceetron Desktop Components (CDC). CDC is written in C++ and CPM is provided as a wrapper layer on top of this. Because of this, all documentation and tutorial snippets are provided in C++ only. However, we believe that reading class/function descriptions and code examples in the C++ generated documentation will be straightforward for a Python programmer.

The Python wrapping targets Python 3.6 and is also available for Python 3.7.

You may wish to consider using Anaconda 4.3.1 (Python 3.6 version), which is a friendly Python distribution including a large variety of packages used in the engineering community.

Modules

Ceetron Python Modules is provided as a Python module named cee, which contains one submodule per C++ namespace.

Python module Ceetron Desktop Components C++ namespace
cee.core CeeCore cee
cee.vis CeeVisualization cee::vis
cee.geo CeeGeometry cee::geo
cee.ug CeeUnstructGrid cee::ug
cee.plt CeePlot2d cee::plt
cee.rep CeeReport cee::rep
cee.exp CeeExport cee::exp
cee.imp CeeImportCae cee::imp
cee.osmesa CeeOSMesa cee::osmesa

Getting started with Ceetron Python Modules

Once the python components are all set you can verify your installation by launching the script minimal_osmesa.py within the Examples/ folder. The documentation for each C++ namespace translated into Python Modules are found in the main C++ documentation.

Please read a list of topics before starting. This will help you understand the main concepts of Ceetron Components, license, CloudIds and others (see Topics). The Ceetron Components overview are found in (Components Overview).

From C++ documentation to actual Python code

The C++ namespace are translated into Python Modules.

1 # C++
2 using namespace cee::app
3 
4 # Python
5 import cee.app

walking through the library

1 # C++
2 cee::Str fileName = "path/to/my/file";
3 cee::ug::Error error;
4 
5 cee::ug::Model* model = cee::app::Models.open(filename, &error);
6 
7 
8 
9 # Python
10 from cee.app import models
11 fileName = "path/to/my/file"
12 
13 model = models.open(fileName)

Accesing methods by pointers in C++ become dot in Python.

For instance, the visibility for an object is typically accessed using visible()/setVisible() in C++.

1 # C++
2 # class cee::ug::PartSettings
3 int partId = 1;
4 size_t globalGeometryIndex = 1;
5 cee::ug::PartSettings* settings = model->partSettings(globalGeometryIndex, partId);
6 settings()->setVisible(false); // request to hide part on the view
7 
8 # Python
9 partId = 1
10 globalGeometryIndex = 1
11 
12 settings = model.partSettings(globalGeometryIndex, partId)
13 settings.setVisible(False)

As you can see, the translation is very straight forward. Please check the tutorials in Tutorials and Examples and come back to this section to help you translate the C++ code into python.

Inheritance

Due to limitations in the Python wrapper layer, there is a special handling of inheritance in the Python version of Ceetron Desktop Components. The problem is downcasting objects that are fetched from within Ceetron Desktop Components.

For instance:

1 myGeo = GeometryModel()
2 myView.addModel(myGeo)
3 
4 model = myView.model(0) # Get myGeo as a Model from the cee.vis.View instance.
5 geometryModel = GeometryModel.castFromBaseClass(model) # Cast to a GeometryModel using the provided method
6 markupModel = MarkupModel.castFromBaseClass(model) # This results in markupModel being None

In this scenario, in order to obtain an instance of GeometryModel when getting a Model from the view, we have provided casting methods for all such classes. Using the static castFromBaseClass will always give you a correct cast. For an invalid cast, the returned value will be null.

Identity operator

Due to the wrapping mechanism of underlying C++ objects, the Python "is" operator does not provide the expected behavior when objects are passed on to C++, for example to be stored in C++ pointer collections. In these cases, if identity needs to be tested, a specific operator named |swigis| has been implemented in the cee.core module.

1 ...
2 
3 from cee.core import swigis
4 
5 ...
6 
7 resources = ImageResources()
8 
9 image1 = Image()
10 res.addImageResource("image 1", image1) # object image1 will be stored in a C++ object collection
11 
12 image2 = res.imageResource("image 1") # retrieving the same object
13 
14 print(image2 is image1) # unexpectedly False (Python objects wrapping the C++ are different)
15 print(image2 |swigis| image1) # allows to compare underlying C++ objects

Deployment

For Ceetron Desktop Components, the development language is C++, which means that any product developed using one of our toolkits must distribute Visual C++ redistributables. To deploy redistributable Visual C++ files, you can use the Visual C++ Redistributable Package (VCRedist_x64.exe) that are included in Visual Studio or use redistributable merge modules, or you can directly install redistributable Visual C++ DLLs in the application local folder, which is the folder that contains the executable application file.

The latest Visual C++ Redistributable Packages for all Visual Studio versions can be downloaded from: https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads

If you just deploy with the redistributable DLLs in the application folder, you will need "C Runtime Library (CRT) for native code" and "Standard C++ Library for native code".