Python X3D Package x3d.py |
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."
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:
pip install x3d
python -m pip install x3d
PythonX3dSmokeTests.py provides thorough example source code. Corresponding self-test output: build.examples.log.txt with screenshot using IDLE.
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.
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.
class
to class_
(all nodes)global
to global_
(DirectionalLight,
Inline,
PointLight,
SpotLight,
TextureProjector,
TextureProjectorParallel)
type
to type_
(BiquadFilter,
field,
NavigationInfo,
PeriodicWave,
ProjectionVolumeStyle,
ShaderPart,
ShaderProgram)
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.
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:
isValidSFBool(value)
, isValidSFVec3f(value)
, isValidMFRotation(value)
, etc.
assertValidSFBool(value)
, assertValidSFVec3f(value)
, assertValidMFRotation(value)
, etc.
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.
x3d.py
package
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.
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.
x3d.py
package for deployment to PyPI
x3d.py project
.
x3d.py
development tasks.
x3d.py
package.
pylint
static testing of the x3d.py
package.
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:
x3d.py
module (Windows 10 example):
PYTHONPATH=C:\Users\brutzman\AppData\Local\Programs\Python\Python39\Lib\site-packages\x3d;
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.
The
x3d.py
project is published on the
Python Packaging Index (PyPI).
Development was configured by following the
PyPI packaging-projects tutorial.
build.package.x3d.py
,
package.prepare
,
and
pylint
.
x3d.py
is completely autogenerated from X3DUOM via the
X3duomToX3dPythonPackage.xslt
XSLT conversion stylesheet.
x3d.py
python package
produced by
X3duomToX3dPythonPackage.xslt
.x3d
models to .py
source
x3d.py
package.
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.
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. # ####################################################################################################
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.
x3d.py
is built.
Corresponding self-test output:
build.examples.log.txt
with
screenshot using IDLE.
insertPackagePrefix=true
.
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.
Mission statement: "Project Jupyter exists to develop open-source software, open-standards, and services for interactive computing across dozens of programming languages."
x3d.py
capabilities live in a Web browser.
Python puts a high value on clarity, strict style and effective documentation.
Lots! Much progress continues. For a release-summary log, please see history log for this page.
x3d.py
package from pip
and not PYTHONPATH
.
field
and fieldValue
initializations.pylint
development tool is applied prior to each release to support strict code quality. See
build.pylint.log.txt
for current output results.
XML()
export
sourceCode
support for embedded Script and shader CDATA source code.
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: 15 January 2025