quick3d 0.2.0

A powerful Python library for 3D visualization of geometry

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:

pip install numpy matplotlib

Quick Start

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:

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:

python -m quick3d.examples.basic_example

License

Quick3D is released under the MIT License.