Payton 1.4.0

3D Graphics Programming Toolkit

Payton 3D SDK

Payton 3D SDK Screencast

![example workflow](https://github.com/sinanislekdemir/p## Examples

Personally, I don't really read long descriptive documentation unless necessary. I prefer things simple and self-explanatory. Therefore, instead of writing lengthy documentation, I create simple examples to demonstrate each feature of Payton without requiring deep dives into the internals.

Examples can be downloaded from the Payton Github Page.

You can either download the entire repository as a zip file or you can simply git clone it.ctions/workflows/pythonpackage.yml/badge.svg)

🎭 Motion Capture Data

Payton includes support for BVH (Biovision Hierarchy) motion capture files. For extensive motion capture datasets, you can find thousands of BVH files from the Bandai Namco Research Motion Dataset. The example BVH files included with Payton are sourced from this dataset.

Payton is a 3D Software Development Kit designed as a general-purpose playground for programming. With Payton, users can quickly kickstart their ideas and create tools for next-level development, including map editors, small animations, algorithms, or artificial intelligence for games. Unlike complex game engines and libraries that can be time-consuming to set up, Payton comes with sensible pre-configured defaults, making it unique and simple to use.

Payton is not intended to be a full-featured game engine or complete 3D environment, as there are already plenty of excellent tools available for those purposes. Instead, it excels at rapid prototyping and tool development, allowing users to easily visualize their concepts and achieve their goals. Users can seamlessly transition from Payton to other platforms when their projects outgrow its scope.

While 2D graphs and charts are useful for reports, many scenarios require visualizing data in 3 or 4 dimensions. Payton enables users to extend their graphics into higher dimensions and process real-time data from sensors, cameras, or any other data source. These sources can include thermometers, random number generators, IoT devices with speed sensors, maps, vehicle diagnostic ports, or even time-based mathematical formulas. Although projects can become complex, Payton is designed to remain accessible to beginners who can follow the tutorials to develop their programming skills.

Contents of this Document:

• Payton 3D SDK
  • Contents of this Document:
  • Features:
  • Install
    • Requirements:
    • Install using Pip:
      • AWP3D Format and Exporter
      • Using Payton with Anaconda
    • Upgrade to the latest version:
  • Getting Started
    • Your first code
  • Controls
  • Examples
  • Example Index
  • Contribution
  • Screenshots and Videos
  • Troubleshooting
  • Some free-thoughts and decisions:

Features:

• 3D Math Library
• Various base geometries:
  • Cube
  • Cylinder
  • Triangular Mesh
  • Plane
  • Lines
  • Particle System
  • Sphere
  • Dynamic Grid
• Clean default scene
• Pre-defined keyboard-mouse and camera controls
• Pre-defined environment
• Clock system for parallel tasks and time-based operations
• Simple collision detection
• Optional Physics Engine
  • Basic support for Bullet Physics (to be extended)
• Extendable controllers
• Pre-defined lighting with shadows
• Material support
• Clickable objects and virtual planes
• Shader support
• Basic GUI Support
  • Window
  • Panel
  • Button
  • EditBox (with multi-line support)
• 3D File formats:
  • AWP3D Animated High-Poly 3D Object
  • Wavefront OBJ
  • Quake 2 MD2 with Animations
• Mesh Generation Tools
  • Extrude Line in 3D
  • Rotate Line around an axis in 3D
  • Fill between lines
• Mesh modifiers:
  • Merge Mesh
  • Subdivide Mesh
• Extensive examples for every feature

Install

Requirements:

• LibSDL2 sudo apt install libsdl2-dev for Debian/Ubuntu-based Linux distributions. For other platforms, please consult your preferred package manager.
• ImageMagick sudo apt install imagemagick for Debian/Ubuntu-based Linux distributions. For other platforms, please consult your preferred package manager.
• Python 3.10+
• A graphics card that supports OpenGL 3.3+

Install using Pip:

From a bash terminal:

pip install payton

This should install all dependencies. If you encounter permission errors, you are likely installing the library system-wide and may be missing some permissions. If you prefer not to use pipenv or virtualenv, you might want to run the above command as sudo pip3 install payton.

Optional Bullet Physics Integration

Payton supports Bullet Physics at a basic level for solid geometries.

pip install pybullet

Once Bullet Physics is successfully installed in the same environment as Payton, it will be automatically activated, and you will be able to use its basic properties. Check out the relevant examples.

Optional GTK3 Integration

Instead of SDL2, you can use GTK3 (along with all nice GTK3 widgets) with Payton.

You need to install Python GTK3 Bindings.

AWP3D Format and Exporter

AWP3D is simply a ZIP file containing every frame as a Wavefront object. To export your animated Blender objects as AWP3D files, you can use the exporter add-on available here:

https://github.com/sinanislekdemir/payton/tree/master/plugins

Using Payton with Anaconda

As of version 0.0.10, Payton is installable on Anaconda. From the Anaconda Prompt:

pip install payton

This is sufficient to install Payton and its dependencies on Anaconda.

Payton will be available for use with Spyder or JupyterLab locally.

Upgrade to the latest version:

Payton is under active maintenance. This means I am spending time fixing bugs and making improvements. Therefore, you might want to upgrade it occasionally.

pip3 install payton --upgrade

This should do the trick!

Getting Started

Your first code

from payton.scene import Scene

scene = Scene()
scene.run()

This will create your first empty scene and show it inside an SDL window.

Controls

Key / Action	Description
Mouse Wheel	Zoom In - Zoom Out
Right Mouse Button Drag	Rotate Scene
Middle Mouse Button Drag	Pan Scene
Escape	Quit Simulation
C	Change Camera Mode (Perspective / Orthographic)
Space	UnPause / Pause Scene Clocks
G	Show / Hide Grid
W	Change Display Mode (Solid / Wireframe / Points)
F2	Previous Camera
F3	Next Camera
H	Open / Close Help Window

Environment variables

Some options can be configured using environment variables.

• SDL_WINDOW_WIDTH: Set window width.
• SDL_WINDOW_HEIGHT: Set window height.
• GL_MULTISAMPLEBUFFERS: Set OpenGL multisample buffer count for antialiasing. (usually 1 or 2)
• GL_MULTISAMPLESAMPLES: Set OpenGL multisample sampling count for antialiasing. (usually 1-16)

Without GL_MULTISAMPLEBUFFERS AND GL_MULTISAMPLESAMPLES, you may notice pixelated graphics. There are no default values set for these because they can vary between graphics cards.

Troubleshooting

On some older systems or where decent graphics drivers are not installed, you can try running Payton code with MESA. It runs fine, though there will be some performance decrease. However, this will not be noticeable for basic applications.

To enforce MESA 3.3, you can run Payton with:

MESA_GL_VERSION_OVERRIDE=3.3 python <path-to-your-payton-code>

Examples

Personally, I don’t really read the long descriptive documentation unless necessary. I like things simple and self-explaining. Therefore, instead of writing long documentations, I write simple examples to use each feature of Payton without digging much into the internals.

Examples can be downloaded from Payton Github Page.

You can either download the whole repository as a zip file or you can just git clone it.

Tested on Windows 10 Paperspace, seems to be working as expected

Supports PyBullet solid geometry physics

Example Index

• Basic Examples
  • Scene
  • Objects
    • Adding a cube
    • Adding multiple cubes
    • Object parent-child relations
    • Cylinder object
    • How to load complex triangular objects
    • Complex meshes
    • Point cloud
    • Particle System
    • Plane Object
    • Line object
    • Better Lines Example
    • Mesh plane
    • Quake 2 Objects
    • Ragdoll Object
  • How to use "clock"
  • Object picking using mouse
  • Load textures
  • Vertex colors
  • Collision Detection
    • Simple example
    • Complex example
  • Physics Engine
    • Cubes example
    • Joint example
  • GTK3 Python OpenGL Payton Integration
  • Rotating Objects
  • Graphical User Interface (GUI)
  • Custom keyboard shortcuts
  • Using multiple cameras
  • Changing background
  • Click plane (get cursor location in world coordinates)
  • Using object motion history
  • Object Oriented Approach
  • Materials
  • Exporting and importing your scene to json
  • Changing time of day
  • Near and Far Planes
  • Spotlight Example
  • Mesh Plane Example
  • AWP3D Example
  • AWP3D Example Ranges
• Mid Level
  • Popping the baloons game
  • Build mesh using heightmap
  • Fetch Instagram Images and build 3D Wall
  • A bit more complex Quake Example
  • Ripple Example (Mesh Grid)
  • RPG-like Controls
  • Custom Shader
• High Level
  • Multiplayer
    • Server backend for a multiplayer game
    • 3D Blocks building game multiplayer

Contribution

• Please keep using type hints in the main library.
• Type hinting can be ignored for examples.
• Example code should be plain and simple.
• Every new feature should include sensible defaults.
  • Nothing should be too verbose to use.
• Make sure that make check passes before pushing your code.
• Running isort . is not mandatory but highly encouraged.
• Every new feature should have example code.
• There is a reason why some methods are longer than they should be and complex.
  • To reduce code jumps and stack switches.
  • To run faster.

Screenshots and Videos

Examples Showcase:

Some free thoughts and decisions:

I've chosen to use List[float] type for Vectors because:

• I needed something mutable. Otherwise, the number of memory copies and swaps would be too much. So, I've ruled out Tuple and NamedTuple.
• dataclass has overhead when converting to C-type floats and arrays in memory.

So, to gain some performance, I have created the main library with the risk of non-strict vector lengths.