Quick Start Guide

This guide will get you up and running with PicoGL in just a few minutes. We’ll create a simple colored cube that you can rotate and interact with.

Prerequisites

Before starting, make sure you have:

Python 3.7 or higher
PicoGL installed (see Installation)
A system with OpenGL support

Your First PicoGL Program

Let’s create a simple program that displays a colored cube:

from picogl.renderer import MeshData
from picogl.ui.backend.glut.window.object import RenderWindow
import numpy as np

def main():
    # Define cube vertices (8 corners of a cube)
    vertices = np.array([
        # Front face
        [-1, -1,  1], [ 1, -1,  1], [ 1,  1,  1], [-1,  1,  1],
        # Back face
        [-1, -1, -1], [-1,  1, -1], [ 1,  1, -1], [ 1, -1, -1],
        # Top face
        [-1,  1, -1], [-1,  1,  1], [ 1,  1,  1], [ 1,  1, -1],
        # Bottom face
        [-1, -1, -1], [ 1, -1, -1], [ 1, -1,  1], [-1, -1,  1],
        # Right face
        [ 1, -1, -1], [ 1,  1, -1], [ 1,  1,  1], [ 1, -1,  1],
        # Left face
        [-1, -1, -1], [-1, -1,  1], [-1,  1,  1], [-1,  1, -1]
    ], dtype=np.float32)

    # Define colors for each vertex
    colors = np.array([
        # Front face (red)
        [1, 0, 0], [1, 0, 0], [1, 0, 0], [1, 0, 0],
        # Back face (green)
        [0, 1, 0], [0, 1, 0], [0, 1, 0], [0, 1, 0],
        # Top face (blue)
        [0, 0, 1], [0, 0, 1], [0, 0, 1], [0, 0, 1],
        # Bottom face (yellow)
        [1, 1, 0], [1, 1, 0], [1, 1, 0], [1, 1, 0],
        # Right face (magenta)
        [1, 0, 1], [1, 0, 1], [1, 0, 1], [1, 0, 1],
        # Left face (cyan)
        [0, 1, 1], [0, 1, 1], [0, 1, 1], [0, 1, 1]
    ], dtype=np.float32)

    # Create mesh data
    data = MeshData.from_raw(vertices=vertices, colors=colors)

    # Create render window
    window = RenderWindow(
        width=800,
        height=600,
        title="My First PicoGL Cube",
        data=data
    )

    # Initialize and run
    window.initialize()
    window.run()

if __name__ == "__main__":
    main()

Save this code as my_first_cube.py and run it:

python my_first_cube.py

You should see a window with a colorful cube that you can rotate with your mouse!

Understanding the Code

Let’s break down what this code does:

Import PicoGL modules: - MeshData: Container for vertex and color data - RenderWindow: Window for displaying 3D content
Define vertices: 24 vertices defining 6 faces of a cube
Define colors: One color per vertex
Create mesh data: Combine vertices and colors into a mesh
Create window: Set up the display window
Run: Start the interactive display

Key Concepts

MeshData

MeshData is the core data structure in PicoGL. It holds all the information needed to render a 3D object:

data = MeshData.from_raw(
    vertices=vertices,    # 3D positions
    colors=colors,        # RGB colors
    normals=normals,      # Surface normals (optional)
    uvs=uvs              # Texture coordinates (optional)
)

RenderWindow

RenderWindow provides the display interface. It handles:

OpenGL context creation
Window management
User input (mouse, keyboard)
Rendering loop

window = RenderWindow(
    width=800,           # Window width
    height=600,          # Window height
    title="My App",      # Window title
    data=mesh_data       # Mesh to display
)

Interactive Controls

The default controls are:

Mouse drag: Rotate the view
Mouse wheel: Zoom in/out
R key: Reset rotation
W key: Toggle wireframe mode
ESC key: Exit

Adding More Features

Textures

To add textures to your cube:

# Load texture data
from picogl.utils.loader.texture import TextureLoader

texture_loader = TextureLoader("path/to/texture.png")
texture = texture_loader.load()

# Create mesh with UV coordinates
data = MeshData.from_raw(
    vertices=vertices,
    colors=colors,
    uvs=uv_coordinates  # Texture coordinates
)

# Create textured render window
window = TextureWindow(
    width=800,
    height=600,
    title="Textured Cube",
    data=data,
    use_texture=True,
    texture_file="texture.png"
)

Lighting

To add lighting effects:

# Create mesh with normals
data = MeshData.from_raw(
    vertices=vertices,
    colors=colors,
    normals=normals  # Surface normals for lighting
)

Multiple Objects

To render multiple objects:

# Create multiple mesh data objects
cube_data = MeshData.from_raw(vertices=cube_vertices, colors=cube_colors)
sphere_data = MeshData.from_raw(vertices=sphere_vertices, colors=sphere_colors)

# Create separate renderers for each object
cube_renderer = ObjectRenderer(context=context, data=cube_data)
sphere_renderer = ObjectRenderer(context=context, data=sphere_data)

Legacy Compatibility

If you’re having issues with modern OpenGL, try the legacy examples:

# Use legacy cube renderer
from examples.legacy_cube_minimal import MinimalCubeRenderer

renderer = MinimalCubeRenderer(width=800, height=600)
renderer.run()

Common Issues

Black screen or no rendering

Check if OpenGL is supported on your system
Try the legacy examples for better compatibility

Import errors

Make sure PicoGL is installed: pip install picogl
Check that all dependencies are installed

Window doesn’t appear

Run from Terminal.app (macOS) or command prompt (Windows)
Check display environment variables

Performance issues

Reduce the number of vertices
Use simpler shaders
Try the legacy rendering mode

Next Steps

Now that you have a basic understanding of PicoGL:

Explore the examples in the examples/ directory
Read the API documentation to learn about all available classes
Try the legacy examples if you have compatibility issues
Check out the molecular visualization examples for more complex use cases

Examples to Try

examples/cube.py - Basic colored cube
examples/teapot.py - 3D teapot model
examples/legacy_cube_minimal.py - Legacy-compatible cube
examples/molecular_viewer.py - Molecular visualization

For more advanced examples, see the Examples section.

Troubleshooting

If you run into problems:

Check the installation guide for platform-specific issues
Try the legacy examples for better compatibility
Check the troubleshooting guide for common solutions
Report issues on GitHub with system information

Happy coding with PicoGL! 🎉