to X3D Resources
               

Python X3D Package x3d.py

               
to Web3D home page

X3D Python Scene Access Interface Library (X3DPSAIL)

Download and Installation | Design Features and Data Types | Development | Examples | Jupyter Notebook | PyPI for x3d.py | 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.

"Pythonic is a word because Python programming is... different, in many excellent ways."


🔖 Download and Installation to top

Direct link: x3d.py can be included in your projects (typically somewhere on PYTHONPATH).

(PyPI troubleshooting continues.) Python Package Installer (PyPI) x3d.py project and upgrade options:

PythonX3dSmokeTests.py provides thorough example source code. Corresponding self-test output: build.examples.log.txt with screenshot using IDLE.


🔖 Design Features to top

The current implementation strives to follow first principles of python package design, being as "pythonic" as possible. Creating a native-Python implementation for X3D data structures appears to provide the greatest possible portability.

Python is exceedingly rigorous regarding design and implementation, demands crisp readability, and often leads to a single best approach for each programming task. These are valuable features that lead to ease of programming and greatly reduced debugging. A single well-constructed open-source Python X3D implementation has the potential to serve all Python distributions and programmers well.

X3DPSAIL x3d.py design is similarly rigorous and based on the X3D Unified Object Model (X3DUOM), which formally defines a full set of object-oriented interfaces for all nodes, fields and statements in the X3D Architecture Specification. An XSLT stylesheet processes the X3DUOM and autogenerates the entire x3d.py package, ensuring that it is always up-to-date with the latest X3D Architecture. The resulting codebase tracks with the latest draft specification for X3Dv4, also providing backwards compatibility for X3D versions 3.0 through 3.3.

Naming

X3D field names and x3d.py field names are usually eponymous (identical). In accordance with PEP 8 – Style Guide for Python Code: Naming Styles some renaming of fields has occurred. Adding a single trailing underscore avoids name collisions with Python keywords.

History

Prior implementation efforts tried to build a Python language package for X3D by converting a Java codebase, but encountered great difficulty. Nevertheless this effort helped with the regularization of x3d.py package design. 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.


🔖 Data Types to top

An important aspect of Python ease of programming is duck typing: If it looks like a duck and walks like a duck and quacks like a duck, then it must be a duck.

Python duck typing describes how well-designed code improves its flexibility by allowing polymorphic substitution (i.e. parametric polymorphism).

X3D has strictly defined field types for every field of every node in the standard. This means that all values can be statically checked when defining a model, leading to high-quality model files. Further it is an error to provide an incorrectly typed value at run time, i.e. an SFString cannot be directly used as a numeric value. This approach precludes a wide range of errors that can occur in other languages. Details on each possible X3D type can be found at X3D Tooltips: types.

Strict typing checks are included when building X3D classes and assigning values to fields, for all X3D types. This strictness for input data prevents Garbage in, garbage out pathologies when creating X3D models.

X3D regular expression (regex) checking is applied to result values. Each type class includes string constants for REGEX_PYTHON and REGEX_PYTHON patterns.

Python authors can confirm data validity and take further advantage of available type-checking methods, such as the following:

The x3d.py python package strives to support duck typing of unambiguous values while preserving strict X3D validation of all inputs. Example tests for each case can be found in examples/PythonX3dSmokeTests.py with corresponding output examples shown in great detail at build.examples.log.txt.

Current work is looking at whether utility conversion of large numpy arrays might be further supported. We are working towards X3D as Web-based 3D presentation layer for Big Data.


🔖 Development of x3d.py package to top

Package designers: Don Brutzman and Loren Peitso. We gratefully acknowledge important contributions by Masaki Aono, John Carlson, Hans Moritz Günther, Myeong Won Lee, and Vince Marchetti.

Build assets

Most x3d.py package development work is performed using Netbeans and Ant. The Savage Developers Guide provides further details on current compilation configuration settings. Package-development references follow.

  1. PythonX3dDevelopmentArchive.zip provides a convenient collection of key development assets.
  2. pyproject.toml is a package configuration file supports creation of x3d.py package for deployment to PyPI x3d.py project.
  3. build.xml for Ant is primary tool for x3d.py development tasks.
  4. build.configuration.log.txt shows an administrator console for installing/upgrading python developer module dependencies.
  5. build.package.log.txt shows creation and testing of the x3d.py package.
  6. build.examples.log.txt shows testing of example models.
  7. build.pylint.log.txt shows pylint static testing of the x3d.py package.
  8. build.deploy.log.txt shows administrator deployment to PyPI.
  9. build.uninstall.log.txt is a debugging console for 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:

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 x3d.py project is published on the Python Packaging Index (PyPI). Development was configured by following the PyPI packaging-projects tutorial.

🔖 Source code autogeneration assets

🔖 Version control

All work is maintained under a non-viral Web3D Consortium open-source license (text) and maintained using subversion at Sourceforge version control.

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 to top

Conversion and Creation

Perhaps the easiest way to get going with an X3D python program is to pip install x3d and edit source code however you please.

Here is the header block that appears on each of the converted programs created using the X3dToPython.xslt conversion stylesheet.

####################################################################################################
#
# Now available: developmental python x3d.py package on PyPI for import.
#   This approach simplifies Python X3D deployment and use.
#   https://pypi.org/project/x3d
#
# Installation:
#       pip install x3d
# or
#       python -m pip install x3d
#
# Developer options for loading x3d package:
#
#    from x3d import *  # preferred approach, terser source that avoids x3d.* class prefixes
#
# or
#    import x3d         # traditional way to subclass x3d package, all classes require x3d.* prefix,
#                       # but python source is very verbose, for example x3d.Material x3d.Shape etc.
#                       # X3dToPython.xslt stylesheet insertPackagePrefix=true supports this option.
#
####################################################################################################

Example X3D models

The following model conversions and test programs are performed as part of each build release for the x3d.py project. Conversions are typically performed by the X3dToPython.xslt conversion stylesheet.

See build.examples.log.txt for test results from each of the preceding examples. This log is produced by running ant examples in the python directory of the full distribution.

But wait, there's more... 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."


🔖 References to top

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

Books

Python


🔖 TODO to top

Lots! Much progress continues. For a release-summary log, please see history log for this page.


🔖 Contact to top

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: 17 October 2023