Metadata-Version: 2.4
Name: soup3D
Version: 5.2.0
Summary: A 3D engine based on OpenGL and pygame for beginners
Author: OrangeSoup
Author-email: deanliusy@163.com
Keywords: 3D,OpenGL,pygame,graphics,game development
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyOpenGL
Requires-Dist: pyglm
Requires-Dist: numpy
Requires-Dist: imageio
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# soup3D

[English](README.md) | [简体中文](README_zh.md)

A 3D engine based on `OpenGL` and `pygame` that is easy for beginners to learn, and can be used for 3D game development, data visualization, 3D graphics rendering, and other development tasks.

## Installation

If your `python` environment includes `pip`, you can install it using the following command:

```bash
pip install soup3D
```

## Quick Start

After installation, you can try this code:

```python
import soup3D  # 3D rendering library
import pygame  # pygame window library for displaying soup3D rendered images

if __name__ == '__main__':
    pygame.init()                                                            # Initialize pygame
    pygame.display.set_caption("soup3D")                                     # Set pygame window title
    pygame.display.set_mode((1920, 1080), pygame.DOUBLEBUF | pygame.OPENGL)  # Configure window mode
    soup3D.init(bg_color=(1, 1, 1), width=1920, height=1080)                 # Initialize soup3D

    soup3D.light.ambient(1, 1, 1)  # Set ambient light to maximum

    surface = soup3D.shader.AutoSP(soup3D.shader.MixChannel((1, 1), 1, 0.5, 0))  # Create orange surface shader
    face = soup3D.Face(  # Create a right triangle
        soup3D.TRIANGLE_L,
        surface,
        (
            (0, 0, 0, 0, 0),  # (x, y, z, u, v)
            (1, 0, 0, 0, 0),
            (0, 1, 0, 0, 0)
        )
    )
    model = soup3D.Model(0, 0, -5, face)  # Add triangle to model
    model.show()  # Display model

    running = True  # Running status
    while running:  # Main loop
        soup3D.update()  # Update soup3D
        pygame.display.flip()  # Refresh pygame screen
        for event in pygame.event.get():  # Iterate through all events
            if event.type == pygame.QUIT:  # Detect window closing event
                pygame.quit()  # Close window
                running = False  # End loop

```

If the environment is properly configured, you will see an orange triangle in the window after running this code.

## Contributing

Due to limited individual development capabilities, we welcome like-minded people to develop this project together. But for better code management, please first understand our development goals and code standards.

- **Development Goals**
  
  The purpose of developing this project is to create a 3D rendering engine that is easy to use while also having professional capabilities. We want Python developers to be able to develop 3D applications in a way that suits their habits.
  
- **Code Standards**
  
  Following these standards will increase the likelihood of your code being accepted:
  
  1. All functions, classes, and class methods must have `reStructuredText` format comments
    
  2. Test your code before submitting a PR. Please refer to the `Function Testing` section below for testing methods
    
  3. Confirm requirements with the author before developing any module
  
  4. New features should not affect the calling methods of existing features
    
  5. Do not import modules anywhere except at the beginning of files
    
  6. Do not nest function definitions. All functions except class member functions must be defined in the global scope of their files
    
  7. Class member variables can be accessed from outside the class, but do not modify them externally. If modification is needed, add class member functions instead
    
- **Function Testing**
  
  After development, you can test functionality in the following way:
  
  1. Create a test environment with the following structure   
     ![Directory Structure](readmepic0.png)
  
  2. Edit test code in `.../project/test.py` to test the functions you've written
  
  3. Run `.../project/test.py`. If it runs successfully, the test is successful

## More Information

This library has many more methods for you to use. For more information, please refer to the [Help Document](./docs/README_zh.md)

## License

This project is licensed under the **MIT License**, see the [LICENSE file](LICENSE) for details.
