quick3d 0.2.0
A powerful Python library for 3D visualization of geometry
Requires Python: >=3.6

# Quick3D

A simple and intuitive 3D visualization library for Python that makes it easy to create, manipulate, and visualize 3D shapes without the complexity of learning low-level plotting APIs.

## Features

- **Easy-to-use API**: Create 3D scenes with just a few lines of code
- **Multiple 3D objects**: Cube, Cuboid (with flexible origin positions), Cylinder, and Sphere
- **Customizable axes**: With grid lines and adjustable parameters
- **Lighting effects**: Support for light direction and ambient light
- **Style customization**: Customize colors, transparency, line widths, and more
- **Responsive design**: Automatic axis adjustment based on scene content

## Installation

Quick3D requires the following dependencies:
- numpy
- matplotlib
- mpl_toolkits.mplot3d

You can install the dependencies using pip:

```bash
pip install numpy matplotlib
```

## Quick Start

```python
from quick3d import Scene3D, Cube3D

# Create a scene
scene = Scene3D()

# Add a cube
cube = Cube3D(center=(0, 0, 0), size=1.0)
scene.add_object(cube, style={
    'facecolor': 'lightblue',
    'edgecolor': 'navy',
    'alpha': 0.7
})

# Show the scene
scene.show(elev=30, azim=45, axes='custom')
```

## Documentation

### Core Classes

#### `Scene3D`
The main scene management class that handles all 3D objects, lighting, and rendering.

**Methods**:
- `__init__()`: Create a new scene
- `set_light_direction(direction: Tuple[float, float, float])`: Set the direction of the light source
- `set_ambient_light(intensity: float)`: Set the ambient light intensity (0-1)
- `add_object(obj: Quick3D, style: Optional[Dict[str, Any]] = None)`: Add a 3D object to the scene
- `show(elev: float = 20, azim: float = -80, **kwargs)`: Display the scene
- `create_custom_axes(style=None, **kwargs)`: Create custom axes for the scene
- `set_custom_axes_style(style)`: Set the style of the custom axes

#### `Quick3D`
The base class for all 3D objects.

**Methods**:
- `set_style(style: Dict[str, Any])`: Set the style of the object
- `get_style() -> Dict[str, Any]`: Get the current style of the object
- `reset_default_style()`: Reset the style to default values
- `get_domain() -> np.ndarray`: Get the bounding box of the object
- `get_centroid() -> np.ndarray`: Get the geometric center of the object

### 3D Objects

#### `Cube3D`
A cube with equal dimensions in all directions.

**Parameters**:
- `center: Tuple[float, float, float] = (0, 0, 0)`: The center of the cube
- `size: float = 1.0`: The size (edge length) of the cube

#### `Cuboid3D`
A rectangular prism with different dimensions in x, y, and z directions.

**Parameters**:
- `origin: Tuple[float, float, float] = (0, 0, 0)`: The origin point
- `length: float = 2.0`: The length in the x direction
- `width: float = 1.0`: The width in the y direction
- `height: float = 1.5`: The height in the z direction
- `origin_location: str = 'center'`: The location of the origin relative to the cuboid

**Origin Locations**:
- `'center'`: Origin is at the geometric center (default)
- `'x_min_y_min_z_min'`: Origin is at the minimum x, minimum y, minimum z vertex
- `'x_max_y_min_z_min'`: Origin is at the maximum x, minimum y, minimum z vertex
- `'x_min_y_max_z_min'`: Origin is at the minimum x, maximum y, minimum z vertex
- `'x_max_y_max_z_min'`: Origin is at the maximum x, maximum y, minimum z vertex
- `'x_min_y_min_z_max'`: Origin is at the minimum x, minimum y, maximum z vertex
- `'x_max_y_min_z_max'`: Origin is at the maximum x, minimum y, maximum z vertex
- `'x_min_y_max_z_max'`: Origin is at the minimum x, maximum y, maximum z vertex
- `'x_max_y_max_z_max'`: Origin is at the maximum x, maximum y, maximum z vertex

#### `Cylinder3D`
A cylinder with a circular base.

**Parameters**:
- `center: Tuple[float, float, float] = (0, 0, 0)`: The center of the cylinder
- `radius: float = 1.0`: The radius of the base
- `height: float = 2.0`: The height of the cylinder
- `slices: int = 32`: The number of slices (segments) for the circular base

#### `Sphere3D`
A sphere.

**Parameters**:
- `center: Tuple[float, float, float] = (0, 0, 0)`: The center of the sphere
- `radius: float = 1.0`: The radius of the sphere
- `rings: int = 20`: The number of rings (latitudinal segments)
- `sectors: int = 32`: The number of sectors (longitudinal segments)

### Custom Axes

The `CustomAxes` class provides customizable axes with grid lines and coordinate planes.

**Parameters**:
- `length: float = 1.0`: The length of the z-axis
- `origin: Tuple[float, float, float] = (0, 0, 0)`: The origin point
- `grid_size: float = 1.0`: The size of each grid cell
- `grid_limits: int = 8`: The maximum number of grid lines
- `grid_color: str = 'gray'`: The color of the grid lines
- `grid_linewidth: float = 0.6`: The width of the grid lines
- `grid_alpha: float = 0.8`: The transparency of the grid lines
- `top_margin_ratio: float = 0.1`: The ratio of top margin for the grid
- `show_xy_plane: bool = True`: Whether to show the XY plane (horizontal plane)
- `show_xz_plane: bool = False`: Whether to show the XZ plane
- `show_yz_plane: bool = False`: Whether to show the YZ plane
- `xy_plane_color: str = '#e0e0e0'`: Color of the XY plane (light gray)
- `xz_plane_color: str = '#e0f0e0'`: Color of the XZ plane (light green)
- `yz_plane_color: str = '#e0e0f0'`: Color of the YZ plane (light blue)
- `plane_alpha: float = 0.7`: Transparency of the coordinate planes

### Coordinate Planes

Quick3D supports displaying three coordinate planes (XY, XZ, YZ) that can help visualize the 3D space. The XY plane is the horizontal plane by default.

**Example**:
```python
from quick3d import Scene3D

scene = Scene3D()

# Enable all coordinate planes with custom styles
axes_style = {
    'show_xy_plane': True,
    'show_xz_plane': True,
    'show_yz_plane': True,
    'xy_plane_color': '#e0e0e0',  # Light gray
    'xz_plane_color': '#e0f0e0',  # Light green
    'yz_plane_color': '#e0e0f0',  # Light blue
    'plane_alpha': 0.7
}
scene.set_custom_axes_style(axes_style)
```

## Examples

Quick3D includes several example scripts in the `examples` directory:

1. `basic_example.py`: Basic usage of Quick3D with a cube
2. `all_objects_example.py`: Demonstrates all 3D objects
3. `cuboid_origin_example.py`: Shows different origin positions for Cuboid3D
4. `coordinate_planes_example.py`: Demonstrates the coordinate planes feature

To run an example:

```bash
python -m quick3d.examples.basic_example
```

## License

Quick3D is released under the MIT License.