Python X3D Package x3d.py

X3D Python Scene Access Interface Library (X3DPSAIL)

Installation | Design Features | Development | Examples | Jupyter Notebook | References | TODO | Contact

The x3d.py Python X3D Package supports programmers with Python interfaces and objects for standards-based X3D programming, all as open source.
The presentation Python X3D Package Implementation provides an overview and shows examples.

🔖 Installation

Download and install Python on your system.

Python x3d.py package installation and update options:

• pip install x3d
  or
• python -m pip install x3d

That should be all that is needed for most Python X3D programmers! Here is an example screenshot for PythonX3dSmokeTests.py using IDLE.

🔖 Design Features

The current implementation strives to follow first principles of python package design, being as "pythonic" as possible.

X3D Unified Object Model (X3DUOM) defines a full set of object-oriented interfaces for all nodes, fields and statements in the X3D Architecture Specification. The X3DUOM is used to autogenerate the entire x3d.py package, ensuring that it is always up-to-date with the latest X3D Architecture. This codebase tracks with the latest draft specification for X3Dv4 (also supporting X3D versions 3.0 through 3.3).

Python is exceedingly rigorous regarding design and implementation, demands crisp readability, and often leads to a single best approach for each programming task. A single well-constructed open-source Python X3D implementation might serve all Python distributions and programmers well.

Several extensive design efforts previously tried to build a Python language package for X3D with difficulty. The original X3D Python Package Design whiteboard diagram illustrates the many relationships for strict typing and an object-oriented scene graph that are being supported.

Creating a native-Python implementation for X3D data structures appears to provide the greatest possible portability.

🔖 Development

Package designers: Don Brutzman, Loren Peitso, John Carlson, Masaki Aono, and Myeong Won Lee.

Build assets

Most development work is performed using Netbeans and Ant.

1. PythonX3dDevelopmentArchive.zip provides a convenient asset of key development assets.
2. build.xml for Ant is primary tool for x3d.py development tasks.
3. build.configuration.log.txt shows an administrator console for installing/upgrading python developer module dependencies.
4. build.package.log.txt shows creation and testing of the x3d.py package.
5. build.examples.log.txt shows testing of example models.
6. build.pylint.log.txt shows pylint static testing of the x3d.py package.
7. build.deploy.log.txt shows administrator deployment to PyPi.
8. build.uninstall.log.txt is a debugging console showing difficulties uninstalling and reconfiguring python.

🔖 Configuration

To run python programs from command line, the PATH environment variable must point to PYTHONHOME or installation location. The PYTHONPATH environment variable may also need to be set to one of the following:

• User's local pip installation of x3d.py module (Windows 10 example):
  PYTHONPATH=C:\Users\username\AppData\Local\Programs\Python\Python38\Lib\site-packages\x3d;
• Developer's build location for x3d.py module:
  PYTHONPATH=C:\x3d-code\www.web3d.org\x3d\stylesheets\python\x3d;

Now working: testing confirms that deployment is exposing x3d.py package properly for program execution.
Workaround: if needed for development, simply download x3d.py package source and place it in same directory as your python program.

🔖 Packaging

The Python X3D project is published on the Python Packaging Index (PyPi). Development was configured by following the PyPi packaging-projects tutorial.

🔖 Source code autogeneration assets

• X3DUOM definition file X3dUnifiedObjectModel-4.0.xml is primary input for all codebase production.
• Ant build.xml targets: build.package.x3d.py, package.prepare, and pylint.
• X3D stylesheet descriptions are included in the X3D Resources, online at X3D Resources: Stylesheets
• x3d.py is completely autogenerated from X3DUOM via the X3duomToX3dPythonPackage.xslt XSLT stylesheet.

🔖 Version control

• x3d.py python package produced by X3duomToX3dPythonPackage.xslt
• stylesheets directory and python subdirectory
• Translation stylesheet X3dToPython.xslt for converting .x3d models to .py source
• README.md description file for x3d.py package.
• build.python.log.txt shows compilation and smoke-testing results for x3d.py package.

Consistent support for all X3D Specifications Relationships includes multiple file formats (XML, JSON, ClassicVRML, binary) and programming languages (JavaScript, Java, Python, C, C#, C++) with fully interoperable expressive power for each.

🔖 Examples

Example X3D models

• HelloWorld.py is produced from HelloWorld.x3d by the X3dToPython.xslt stylesheet.
• HelloWorldPrefixed.py is produced from HelloWorld.x3d by the X3dToPython.xslt stylesheet with invocation parameter insertPackagePrefix=true.
• PythonX3dSmokeTests.py performs "smoke tests" of package functionality every time x3d.py is built.

Running ant examples in the python directory produces results shown in build.examples.log.txt for the preceding project models.

X3D Resources: Examples includes over 3900 models converted from .x3d to .py Python source. See build.python.all.log.txt for the entire set of unit-testing results.

🔖 Jupyter notebook

Mission statement: "Project Jupyter exists to develop open-source software, open-standards, and services for interactive computing across dozens of programming languages."

• Jupyter Notebook installation console log for a pip install jupyter session.
• Jupyter Notebook Initial Test by Masaki Aono is a session log that shows x3d.py capabilities live in a Web browser.
• HelloJupyterNotebook0.ipynb test, shown in pdf and also viewable on jupyter nbviewer.

🔖 References

Python puts a high value on clarity, strict style and effective documentation.

Books

• Mark Lutz, Learning Python, fifth edition, O'Reilly and Associates, Sebastopol California, 2013. https://learning-python.com
• Mark Lutz, Programming Python, O'Reilly and Associates, Sebastopol California, 2011. https://learning-python.com
• David Beazley and Brian K. Jones, Python Cookbook, O'Reilly and Associates, Sebastopol California, 2013.
• Deepak Sarda, Python for the Busy Java Developer: the Language, Syntax and Ecosystem, aPress Media, Springer, 2017. Online via antrix.net
• Brett Slatkin, Effective Python: 59 Specific Ways to Write Better Python, Addison Wesley, Pearson Education, 2015. effectivePython.com

Python

• PyVRML97 2.3.0b1 (launchpad) is an earlier, unrelated project that provides VRML97 scene-graph modeling objects for Python. PyVRML97 is part of OpenGLContext. a Learning Environment for PyOpenGL.

🔖 TODO

Lots! For starters, in progress:

• Confirmation testing in progress: Fix deployment on end-user machines so that the python usage demonstrated for all examples only requires installing the x3d.py package from pip and not PYTHONPATH.
• Nearly complete: debug conversions of all X3D Resources: Examples as shown in build.python.all.log.txt
  • Proper tuple-ization of MF fields that are lists of tuples.
  • Class and interface inheritance for each node, then content model for all contained nodes
  • Type-aware validation of values for field and fieldValue initializations.
  • Extend type checking with fully strict validation of field values: min/max value restrictions (complete), allowed enumeration strings, allowed parent-child node relationships, etc.
• Development tool: use pylint for strict code quality. See build.pylint.log.txt for current output results.
• Add support for serialization output to XML (.x3d), ClassicVRML, VRML97, X3DOM and X_ITE, others. Include round-trip validation of XML outputs in build scripts for satisfactory Quality Assurance (QA).
• Round-trip diff testing of XML() export using package x3d.py
• Strict type checking of initialized field and fieldValue content.
• Add support for contained Script and shader CDATA source code.
• Distribution support for Jupyter Notebook (initial example works), Apache Zeppelin notebook, Anaconda distribution of Python, and other data-science platforms.
• We need a "Getting Started" tutorial on this page. This is a good opportunity... who wants to help?!

🔖 Contact

Questions, suggestions, additions and comments about this Python X3D Package page are welcome. Please send them to Don Brutzman and Loren Peitso (email brutzman,lepeitso at nps.edu).

Master version of this Python X3D Package page is available online at
https://www.web3d.org/x3d/stylesheets/python/python.html and available in Sourceforge version control.

Updated: 20 October 2020