Quick3D

3D Visualization Made Easy

An abstract Python class for visible geometries in a custom 3D visualization scene built on top of Matplotlib's mplot3d toolkit.

Quick3D Logo

Key Features

Easy to Use

A base class that allows you to create your 3D geometries to be manipulated in the same 3D scene.

Highly Visible

Extensive styling options available to make unique a geometry, such as colors, line widths, and more.

Interactive Scenes

A 3D scene to walk around your geometries with its interactive controls.

Examples

Interactive 3D Scene

All Quick3D objects will be managed by a 3D scene that can add objects, adjust the view angle, and customize their appearance.

Controls

Add Geometries

Python Codes

3D Coordinate System

Basic Coordinate System

Create a basic 3D coordinate system with XYZ axes. 

from quick3d import Scene3D

# Create a new 3D scene
scene = Scene3D()

# Display the scene
scene.show()

3D Cubes

Create and customize 3D cubes with different styles. 

from quick3d import Scene3D, Cube3D

# Create a new scene
scene = Scene3D()

# Add a cube with default style
cube1 = Cube3D(center=(-2, 0, 0), size=1)
scene.add_object(cube1)

# Add a cube with custom style
cube2 = Cube3D(center=(0, 0, 0), size=1)
custom_style = {
    'facecolor': 'lightgreen',
    'edgecolor': 'darkgreen',
    'linewidth': 2.0,
    'alpha': 0.8
}
scene.add_object(cube2, style=custom_style)

# Add a larger cube with transparent style
cube3 = Cube3D(center=(2, 0, 0), size=1.5)
transparent_style = {
    'facecolor': 'lightblue',
    'edgecolor': 'navy',
    'linewidth': 1.0,
    'alpha': 0.3,
    'linestyle': '--'
}
scene.add_object(cube3, style=transparent_style)

# Display the scene
scene.show()

Customized Axes

Customize the coordinate system axes and lighting.

from quick3d import Scene3D, Cube3D # Create a new scene scene = Scene3D() # Set light source direction and intensity scene.set_light_direction((1.5, 1.0, 0.5)) # Light direction vector scene.set_ambient_light(0.4) # Ambient light intensity (0-1) # Add a cube cube = Cube3D() scene.add_object(cube) # Customize the coordinate axes axes_style = { 'length': 1.5, 'x_color': 'darkred', 'y_color': 'darkgreen', 'z_color': 'darkblue', 'linewidth': 2.5, 'label_fontsize': 14, 'grid_size': 0.5, # Grid cell size 'grid_limits': 10, # Grid density 'grid_color': 'gray', # Grid color 'grid_linewidth': 0.8 # Grid line width } scene.set_custom_axes_style(axes_style) # Display the scene with custom view parameters scene.show( elev=30, # Elevation angle in degrees azim=45, # Azimuth angle in degrees axes='custom' # Use custom axes mode )

Getting Started

Installation

$ pip install quick3d

Quick3D requires Python 3.6 or higher, and depends on matplotlib, numpy, and mpl_toolkits.

API Reference

Classes

Methods

Quick3D

Base class for all 3D objects in the Quick3D library. Provides basic functionality for styling and rendering 3D objects with light response.

Constructor

Quick3D()

Instance Attributes

  • facecolor - Color of the object's face (default: 'lightblue')
  • edgecolor - Color of the object's edges (default: 'navy')
  • linewidth - Width of the object's lines (default: 1.0)
  • alpha - Transparency of the object (default: 0.7)
  • linestyle - Style of the object's lines (default: '-')
  • light_intensity - Highlight intensity (default: 0.8)
  • shadow_color - Shadow color (default: 'darkgray')
  • highlight_edges - Highlight edges on bright faces (default: True)

Methods

get_instance()

Returns a reference to the object instance. 

def get_instance(self) -> Quick3D
plot(style, ax,** kwargs)

Abstract method to plot the 3D object with the specified style. Must be implemented by subclasses. 

def plot(self, style: dict, ax: Axes3D, **kwargs)
  • style - Style dictionary
  • ax - 3D axes to render on
  • **kwargs - Additional keyword arguments including light parameters
set_style(style)

Sets visual style properties from a dictionary. 

def set_style(self, style: dict)
  • style - Dictionary containing style properties
get_style()

Returns current style properties as a dictionary. 

def get_style(self) -> dict
reset_default_style()

Resets style properties to default values. 

def reset_default_style(self)
get_domain()

Abstract method to get the bounding box of the object. Must be implemented by subclasses. 

def get_domain(self) -> np.ndarray
get_centroid()

Abstract method to get the centroid of the object. Must be implemented by subclasses. 

def get_centroid(self) -> np.ndarray

Scene3D

Class for creating and managing 3D scenes with unified light source management.

Constructor

Scene3D(*args, **kwargs)

Instance Attributes

  • objects - List of 3D objects in the scene
  • styles - List of style dictionaries for the objects
  • fig - Matplotlib figure object
  • ax - 3D axes object
  • _custom_axes - CustomAxes object for coordinate system
  • light_direction - Light direction vector (default: (1, 1, 1))
  • ambient_light - Ambient light intensity (0-1, default: 0.3)

Methods

add_object(obj, style=None)

Adds a Quick3D object to the scene. 

def add_object(self, obj: Quick3D, style: dict = None)
  • obj - Quick3D object to add
  • style - Style dictionary for the object (optional)
show(elev=20, azim=-80, **kwargs)

Displays the 3D scene with support for different axes modes. 

def show(self, elev: float = 20, azim: float = -80,** kwargs)
  • elev - Elevation angle in degrees (default: 20)
  • azim - Azimuth angle in degrees (default: -80)
  • **kwargs - Additional keyword arguments including:
    • axes - Axes mode: 'custom' (default), True, False
set_light_direction(direction)

Sets the light direction for the scene. 

def set_light_direction(self, direction: Tuple[float, float, float])
  • direction - Light direction vector (x, y, z)
set_ambient_light(intensity)

Sets the ambient light intensity for the scene. 

def set_ambient_light(self, intensity: float)
  • intensity - Ambient light intensity (0-1)
create_custom_axes(style=None, **kwargs)

Creates and returns a CustomAxes object for the scene. 

def create_custom_axes(self, style=None, **kwargs) -> CustomAxes
  • style - Style dictionary for the axes (optional)
  • **kwargs - Additional keyword arguments for CustomAxes
remove_custom_axes()

Removes the CustomAxes object from the scene. 

def remove_custom_axes(self)
set_custom_axes_style(style)

Sets the style of the CustomAxes object. 

def set_custom_axes_style(self, style: dict)
  • style - Style dictionary for the axes
get_custom_axes_style()

Returns the current style of the CustomAxes object. 

def get_custom_axes_style(self) -> dict

CustomAxes

Class for drawing customizable coordinate axes in 3D scenes.

Constructor

CustomAxes(length: float = 1.0, 
           origin: Tuple[float, float, float] = (0, 0, 0),
           **kwargs)
  • length - Length of the axes (default: 1.0)
  • origin - Origin coordinates (default: (0, 0, 0))
  • **kwargs - Additional keyword arguments for grid configuration:
    • grid_size - Grid cell size (default: 1.0)
    • grid_limits - Grid density (default: 8)
    • grid_color - Grid color (default: 'gray')
    • grid_linewidth - Grid line width (default: 0.6)
    • grid_alpha - Grid transparency (default: 0.8)
    • top_margin_ratio - Top margin ratio (default: 0.1)
    • show_xy_plane - Show XY plane (default: True)
    • show_xz_plane - Show XZ plane (default: False)
    • show_yz_plane - Show YZ plane (default: False)
    • plane_color - Coordinate plane color (default: 'gray')
    • plane_alpha - Coordinate plane transparency (default: 0.2)

Instance Attributes

  • length - Length of the axes (default: 1.0)
  • origin - Origin coordinates (default: (0, 0, 0))
  • x_color - Color of the X axis (default: 'red')
  • y_color - Color of the Y axis (default: 'green')
  • z_color - Color of the Z axis (default: 'blue')
  • linewidth - Width of the axes lines (default: 2.0)
  • label_fontsize - Font size for axis labels (default: 12)
  • grid_size - Grid cell size (default: 1.0)
  • grid_limits - Grid density (default: 8)
  • grid_color - Grid color (default: 'gray')
  • grid_linewidth - Grid line width (default: 0.6)
  • grid_alpha - Grid transparency (default: 0.8)
  • top_margin_ratio - Top margin ratio (default: 0.1)
  • show_xy_plane - Show XY plane (default: True)
  • show_xz_plane - Show XZ plane (default: False)
  • show_yz_plane - Show YZ plane (default: False)
  • plane_color - Coordinate plane color (default: 'gray')
  • plane_alpha - Coordinate plane transparency (default: 0.2)

Methods

plot(style, ax,** kwargs)

Draws the custom axes and grid on the given 3D axes. 

def plot(self, style: dict, ax: Axes3D, **kwargs)
  • style - Style dictionary
  • ax - The 3D axes to draw on
  • **kwargs - Additional keyword arguments including axes='custom'
set_style(style)

Sets visual style properties from a dictionary. 

def set_style(self, style: dict)
  • style - Dictionary containing style properties
get_style()

Returns current style properties as a dictionary. 

def get_style(self) -> dict
get_domain()

Returns the domain range of the axes. 

def get_domain(self) -> np.ndarray
get_centroid()

Returns the centroid of the axes. 

def get_centroid(self) -> np.ndarray

Cube3D

A 3D cube object with light response. Inherits from Quick3D.

Constructor

Cube3D(center: Tuple[float, float, float] = (0, 0, 0), size: float = 1.0)
  • center - Center coordinates of the cube (default: (0, 0, 0))
  • size - Edge length of the cube (default: 1.0)

Instance Attributes

  • center - Center coordinates of the cube
  • size - Edge length of the cube
  • face_normals - Normal vectors of the 6 faces

Methods

plot(style, ax, **kwargs)

Plots the 3D cube with the specified style and light response. 

def plot(self, style: dict, ax: Axes3D, **kwargs)
  • style - Style dictionary
  • ax - 3D axes to render on
  • **kwargs - Additional keyword arguments including light parameters
get_domain()

Returns the bounding box of the cube. 

def get_domain(self) -> np.ndarray
get_centroid()

Returns the centroid of the cube. 

def get_centroid(self) -> np.ndarray

Cuboid3D

A 3D cuboid (rectangular prism) object with light response. Inherits from Quick3D.

Constructor

Cuboid3D(origin: Tuple[float, float, float] = (0, 0, 0),
         length: float = 2.0,  # x方向长度
         width: float = 1.0,   # y方向宽度
         height: float = 1.5,  # z方向高度
         origin_location: str = 'center')
  • origin - Origin coordinates (default: (0, 0, 0))
  • length - Length in x direction (default: 2.0)
  • width - Width in y direction (default: 1.0)
  • height - Height in z direction (default: 1.5)
  • origin_location - Origin position relative to the cuboid:
    • 'center' - Center point (default)
    • 'x_min_y_min_z_min' - Minimum x, y, z vertex
    • 'x_max_y_min_z_min' - Maximum x, minimum y, z vertex
    • 'x_min_y_max_z_min' - Minimum x, maximum y, z vertex
    • 'x_max_y_max_z_min' - Maximum x, y, minimum z vertex
    • 'x_min_y_min_z_max' - Minimum x, y, maximum z vertex
    • 'x_max_y_min_z_max' - Maximum x, minimum y, z vertex
    • 'x_min_y_max_z_max' - Minimum x, maximum y, z vertex
    • 'x_max_y_max_z_max' - Maximum x, y, z vertex

Instance Attributes

  • origin - Origin coordinates
  • length - Length in x direction
  • width - Width in y direction
  • height - Height in z direction
  • origin_location - Origin position relative to the cuboid
  • center - Geometric center of the cuboid
  • face_normals - Normal vectors of the 6 faces

Methods

plot(style, ax, **kwargs)

Plots the 3D cuboid with the specified style and light response. 

def plot(self, style: dict, ax: Axes3D, **kwargs)
  • style - Style dictionary
  • ax - 3D axes to render on
  • **kwargs - Additional keyword arguments including light parameters
get_domain()

Returns the bounding box of the cuboid. 

def get_domain(self) -> np.ndarray
get_centroid()

Returns the centroid of the cuboid. 

def get_centroid(self) -> np.ndarray

Cylinder3D

A 3D cylinder object with light response. Inherits from Quick3D.

Constructor

Cylinder3D(center: Tuple[float, float, float] = (0, 0, 0), radius: float = 1.0, height: float = 2.0, slices: int = 32)
  • center - Center coordinates of the cylinder (default: (0, 0, 0))
  • radius - Base radius of the cylinder (default: 1.0)
  • height - Height of the cylinder (along Z-axis, default: 2.0)
  • slices - Number of side segments (more = smoother, default: 32)

Instance Attributes

  • center - Center coordinates of the cylinder
  • radius - Base radius of the cylinder
  • height - Height of the cylinder
  • slices - Number of side segments

Methods

plot(style, ax, **kwargs)

Plots the 3D cylinder with the specified style and light response. 

def plot(self, style: dict, ax: Axes3D, **kwargs)
  • style - Style dictionary
  • ax - 3D axes to render on
  • **kwargs - Additional keyword arguments including light parameters
get_domain()

Returns the bounding box of the cylinder. 

def get_domain(self) -> np.ndarray
get_centroid()

Returns the centroid of the cylinder. 

def get_centroid(self) -> np.ndarray

Sphere3D

A 3D sphere object with light response. Inherits from Quick3D.

Constructor

Sphere3D(center: Tuple[float, float, float] = (0, 0, 0), radius: float = 1.0, rings: int = 20, sectors: int = 32)
  • center - Center coordinates of the sphere (default: (0, 0, 0))
  • radius - Radius of the sphere (default: 1.0)
  • rings - Number of latitude lines (more = smoother, default: 20)
  • sectors - Number of longitude lines (more = smoother, default: 32)

Instance Attributes

  • center - Center coordinates of the sphere
  • radius - Radius of the sphere
  • rings - Number of latitude lines
  • sectors - Number of longitude lines

Methods

plot(style, ax, **kwargs)

Plots the 3D sphere with the specified style and light response. 

def plot(self, style: dict, ax: Axes3D, **kwargs)
  • style - Style dictionary
  • ax - 3D axes to render on
  • **kwargs - Additional keyword arguments including light parameters
get_domain()

Returns the bounding box of the sphere. 

def get_domain(self) -> np.ndarray
get_centroid()

Returns the centroid of the sphere. 

def get_centroid(self) -> np.ndarray