PyCG Framework

A framework for rendering 3D computer graphics with Python.

Try It · Report Bug · Request Feature

Table of Contents

1. About the Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. License
5. Contact
6. References

About The Project

This 3D CG graphics framework was created using Python for the purposes of teaching Computer Graphics and Software Engineering through the object-oriented design and application of a CG rendering library. The framework is largely inspired by the one developed by Lee Stemkoski and Michael Pascale (see References) with a focus on cross-compatibility, object-oriented software design principles, and the use of pythonic conventions over the ones commonly used with OpenGL.

For more information on the course and the companion material that uses this framework, see the Software Engineering Lab website and the posts there.

( back to top )

Built With

• 
• 
• 

( back to top )

Getting Started

The following instructions describe how to create a local copy of the framework and configure it to run in a virtual environment.

Prerequisites

This project requires Python 3.8+ and it is recommended to use a virtual environment for installing all the dependencies. Either venv or Pipenv work fine.

• Python
• venv
• Pipenv

Installation

1. Clone the repo.

   git clone https://github.com/rsonger/pycg-framework.git

2. Create a virtual environment.
   venv

   python -m venv .venv

   Pipenv

   pipenv install

3. Activate the virtual environment.
   venv

   # Windows
   source .venv/Scripts/activate
   # MacOS
   source .venv/bin/activate

   Pipenv

   pipenv shell

4. In venv, the packages need to be installed after activating the environment.

   pip install -r requirements.txt

5. On MacOS, a discrepency in the OpenGL package may result in an ImportError. You can test this by running the following command in the terminal:

   python -c "import OpenGL.GL"

   If you see the error, look at the Traceback and find the location of the site-packages\OpenGL\platform directory inside your Python library. Open the ctypesloader.py file from that directory and find the line that has:

   fullName = util.find_library( name )

   Then change the line to:

   fullName = f"/System/Library/Frameworks/{name}.framework/{name}"

( back to top )

Usage

The WindowApp class in the graphics.core.app module contains all the basic logic for setting up a rendering context inside a windowed application. It implements the typical lifecycle of an interactive rendering application as shown in the flowchart below. An application using the framework should extend the WindowApp class and implement its startup and update methods as exemplified by the program in demo.py.

Run the demo app with python demo.py to see the scene depicted in the screenshot from above. The demo also makes use of CameraRig from graphics.extras.camera_rig which allows the user to move through the scene and look. The keys WASD move the camera forward, left, back, and right while Q and E move it down and up. The keys IJKL rotate the camera to look up, left, down, and right.

( back to top )

Roadmap

• Window context
  • Input handler
  • Keyboard inputs
• OpenGL interfaces
  • GPU program compiler
  • VAOs (vertex array objects)
  • Uniform variables
• Time-keeping for animations
• Matrices for geometric transformations
• Scene graph
  • 3D Objects
  • Vertex geometry
    • Parametric Geometries
  • Shader materials
  • Camera object
  • Renderer
  • Extra components
    • Axes helper
    • Grid helper
    • Camera rig
• Texture Mapping
  • Basic texture shader
  • Procedurally generated textures
  • Generating textures from text
  • 2D Sprites
• Heads-Up Display
  • Orthogonal projection
• TV textures as render targets
• Postprocessing
• Lighting
  • Ambient, directional, and point sources
  • Normal vectors for vertices
  • Shader attributes and uniforms
  • Rendering lights
  • Light source helpers
  • Bump mapping
  • Bloom and glow effects
  • Shadows

( back to top )

License

Distributed under the Academic Free License. See LICENSE.txt for more information.

( back to top )

Contact

Rob Songer

Project Link: https://github.com/rsonger/pycg-framework

( back to top )

References

• Lee Stemkoski and Michael Pascale (2021). Developing Graphics Frameworks with Python and OpenGL. CRC Press, in print and online. DOI: 10.1201/9781003181378

( back to top )