tinygfx.g3d package

Submodules

tinygfx.g3d.csg module

class tinygfx.g3d.csg.CSGSurface(l_child, r_child, operation, *args, **kwargs)

Bases: tinygfx.g3d.world_objects.Intersectable

Parameters
intersect(rays)
invert_normals()
reset_normals()
property surface_ids

Returns a tuple of surface ids and surface that make up the intersectable object, used for calculating intersections.

class tinygfx.g3d.csg.Operation(value)

Bases: enum.Enum

An enumeration.

DIFFERENCE = 3
INTERSECT = 2
UNION = 1
tinygfx.g3d.csg.array_csg(array1, array2, operation, sort_output=True)

Given two arrays and an operation, returns a new array which is the CSG operation acting on the array. If the array is thought of as intersection points between a ray and a two objects being combined with a CSG operation, the returned is the valid hits for the resulting object. Function assumes both arrays are sorted and have an even number of axis=0 elements

Parameters
Returns

tinygfx.g3d.csg.difference(s0, s1)
Parameters
Return type

tinygfx.g3d.csg.CSGSurface

tinygfx.g3d.csg.intersect(s0, s1)
Parameters
Return type

tinygfx.g3d.csg.CSGSurface

tinygfx.g3d.csg.union(s0, s1)
Parameters
Return type

tinygfx.g3d.csg.CSGSurface

tinygfx.g3d.operations module

tinygfx.g3d.operations.binomial_root(a, b, c, disc=None)

finds the 2nd order polynomial roots given the equations a*x^2 + b*x + c = 0

Parameters

  • a – coefficients for the second order of the polynomial

  • b – coefficients for the first order of the polynomial

  • c – coefficients for the zeroth order of the polynomial

  • disc – the precalculated Discriminant array, if provided the discriminant won’t be recalculated

Returns

an array of length n with the smallest positive root for the array

tinygfx.g3d.operations.element_wise_dot(mat_1, mat_2, axis=0)

calculates the row-wise/column-wise dot product two nxm matrices

Parameters

  • mat_1 – the first matrix for the dot product

  • mat_2 – the second matrix for the dot product

  • axis – axis to perform the dot product along, 0 or 1

Returns

a 1D array of length m for axis 0 and n for axis 1

tinygfx.g3d.operations.reflect(vectors, normals)

reflects an array of vectors by a normal vector.

Parameters

  • vectors – a mxn array of vectors, where each column corresponds to one vector

  • normals – a mxn array of unit-normal vectors or a 4x0 single normal vector. If only one normal is provided, every vector is reflected across that normal

Returns

an mxn array of reflected vector

tinygfx.g3d.operations.refract(vectors, normals, n1, n2, n_global=1)
calculates the refracted vector at an interface with index mismatch of n1 and n2. If the angle between the normal

and the vector is <90 degrees, the vector is exiting the medium, and the global refractive index value is used instead. this is analygous to a ray exiting a glass interface and entering air

Parameters

  • vectors – the ray transmission vectors in the current medium

  • normals – the normals to the surface at the point of intersection with the ray

  • n1 – refractive index of the medium the ray is currently transmitting through

  • n2 – refractive index of the medium the ray is entering

  • n_global – the world refractive index to use if the ray is exiting the medium

Returns

a 4xn array of homogeneous vectors representing the new transmission direction of the vectors after the medium

tinygfx.g3d.operations.smallest_positive_root(a, b, c)

finds the 2nd order polynomial roots given the equations a*x^2 + b*x + c = 0, returns the smallest root > 0, and np.inf if a root does not satisfy that condition. Note that if a has a value of zero, it will be cast as 1 to avoid a divide by zero error. it’s up the user to filter out these results before/after execution (using np.where etc.).

Parameters

  • a – coefficients for the second order of the polynomial

  • b – coefficients for the first order of the polynomial

  • c – coefficients for the zeroth order of the polynomial

Returns

an array of length n with the smallest positive root for the array

tinygfx.g3d.primitives module

class tinygfx.g3d.primitives.Cube(min_corner=(- 1, - 1, - 1), max_corner=(1, 1, 1), *args, **kwargs)

Bases: tinygfx.g3d.primitives.SurfacePrimitive

a axis aligned cube fully defined by its corners

intersect(rays)
calculates the intersection of an array of rays with the surface, returning a 1-D array with the hit distance

for each ray. Rays are represented by the vector equation x(t) = o + t*v, where o is the point-origin, and v is the vector direction.

Parameters

rays – a 2x4xn numpy array where n is the number of rays being projected. For each slice of rays the first row is the ray’s origin, and the second row is the direction. Both should be represented as homogeneous coordinates

Returns

an array of the parameter t from the ray equation where the ray intersects the object.

Return type

1-D numpy array of float

normal(intersections)
calculates the normal of a sphere at each point in an array of coordinates. It is assumed that the points lie

on the surface of the object, as this is not verified during calculation.

Parameters

intersections (4xn numpy of float) – a 4xn array of homogeneous points representing a point on the sphere.

Returns

an array of vectors representing the unit normal at each point in intersection

Return type

4xn numpy array of float

class tinygfx.g3d.primitives.Cylinder(radius=1, min_height=- 1, max_height=1, capped=True, *args, **kwargs)

Bases: tinygfx.g3d.primitives.SurfacePrimitive

A cylinder with a radius of 1 in the XY plane, extending from -1 to 1

get_radius()
Get the sphere’s radius in object space. The apparent radius in world space may be different due to object

transforms

Returns

the sphere’s object space radius

Return type

float

intersect(rays)
For Cylinder intersections first find the intersection point with an infinite cylinder, than check if

the caps are intersected before or after the cylinder

normal(intersections)
calculates the normal of a sphere at each point in an array of coordinates. It is assumed that the points lie

on the surface of the object, as this is not verified during calculation.

Parameters

intersections (4xn numpy of float) – a 4xn array of homogeneous points representing a point on the sphere.

Returns

an array of vectors representing the unit normal at each point in intersection

Return type

4xn numpy array of float

class tinygfx.g3d.primitives.Disk(radius=1.0, *args, **kwargs)

Bases: tinygfx.g3d.primitives.Shape2D

Return type

None

classmethod from_diameter(diameter)

Creates a disk object from the diameter :param diameter: :return:

Parameters

diameter (float) –

Return type

tinygfx.g3d.primitives.Disk

point_in_shape(points)

Calculates if the points are in :param points: :return:

Parameters

points (numpy.ndarray) –

Return type

numpy.ndarray

class tinygfx.g3d.primitives.HomogeneousCoordinate(*args, **kwargs)

Bases: numpy.ndarray

normalize()
property w
property x
property y
property z
class tinygfx.g3d.primitives.Paraboloid(focus=1, height=1, *args, **kwargs)

Bases: tinygfx.g3d.primitives.SurfacePrimitive

A Spherical parabola with focus at point (0,0,f). The directrix plane is the XY plane

get_focus()
intersect(rays)
calculates the intersection of an array of rays with the surface, returning a 1-D array with the hit distance

for each ray. Rays are represented by the vector equation x(t) = o + t*v, where o is the point-origin, and v is the vector direction.

Parameters

rays – a 2x4xn numpy array where n is the number of rays being projected. For each slice of rays the first row is the ray’s origin, and the second row is the direction. Both should be represented as homogeneous coordinates

Returns

an array of the parameter t from the ray equation where the ray intersects the object.

Return type

1-D numpy array of float

normal(intersections)
calculates the normal of a sphere at each point in an array of coordinates. It is assumed that the points lie

on the surface of the object, as this is not verified during calculation.

Parameters

intersections (4xn numpy of float) – a 4xn array of homogeneous points representing a point on the sphere.

Returns

an array of vectors representing the unit normal at each point in intersection

Return type

4xn numpy array of float

class tinygfx.g3d.primitives.Plane(width=2, length=2, *args, **kwargs)

Bases: tinygfx.g3d.primitives.SurfacePrimitive

An XY-Plane defined at z=0

intersect(rays)

a plane can have at most one intersection with a ray, but for the case of CSG we’ll return a double hit at that coordinate

Parameters

rays –

Returns

normal(intersections)
calculates the normal of a sphere at each point in an array of coordinates. It is assumed that the points lie

on the surface of the object, as this is not verified during calculation.

Parameters

intersections (4xn numpy of float) – a 4xn array of homogeneous points representing a point on the sphere.

Returns

an array of vectors representing the unit normal at each point in intersection

Return type

4xn numpy array of float

class tinygfx.g3d.primitives.Point(*args, **kwargs)

Bases: tinygfx.g3d.primitives.HomogeneousCoordinate

class tinygfx.g3d.primitives.Ray(*args, **kwargs)

Bases: numpy.ndarray

property direction
property origin
class tinygfx.g3d.primitives.Rectangle(x_length=2, y_length=2, *args, **kwargs)

Bases: tinygfx.g3d.primitives.Shape2D

Return type

None

point_in_shape(points)

Calculates if the points are in :param points: :return:

Parameters

points (numpy.ndarray) –

Return type

numpy.ndarray

class tinygfx.g3d.primitives.Shape2D

Bases: abc.ABC

A 2D shape that exist in the XY Plane :param object: :return:

abstract point_in_shape(points)

Calculates if the points are in :param points: :return:

Parameters

points (numpy.ndarray) –

Return type

numpy.ndarray

class tinygfx.g3d.primitives.Sphere(radius=1, *args, **kwargs)

Bases: tinygfx.g3d.primitives.SurfacePrimitive

get_radius()
Get the sphere’s radius in object space. The apparent radius in world space may be different due to object

transforms

Returns

the sphere’s object space radius

Return type

float

intersect(rays)
calculates the intersection of an array of rays with the surface, returning a 1-D array with the hit distance

for each ray. Rays are represented by the vector equation x(t) = o + t*v, where o is the point-origin, and v is the vector direction.

Parameters

rays – a 2x4xn numpy array where n is the number of rays being projected. For each slice of rays the first row is the ray’s origin, and the second row is the direction. Both should be represented as homogeneous coordinates

Returns

an array of the parameter t from the ray equation where the ray intersects the object.

Return type

1-D numpy array of float

normal(intersections)
calculates the normal of a sphere at each point in an array of coordinates. It is assumed that the points lie

on the surface of the object, as this is not verified during calculation.

Parameters

intersections (4xn numpy of float) – a 4xn array of homogeneous points representing a point on the sphere.

Returns

an array of vectors representing the unit normal at each point in intersection

Return type

4xn numpy array of float

class tinygfx.g3d.primitives.SurfacePrimitive(*args, **kwargs)

Bases: abc.ABC

SurfacePrimitive classes have abstract functions to calculate ray-object intersections and normals

abstract intersect(rays)
calculates the intersection of an array of rays with the surface, returning a 1-D array with the hit distance

for each ray. Rays are represented by the vector equation x(t) = o + t*v, where o is the point-origin, and v is the vector direction.

Parameters

rays – a 2x4xn numpy array where n is the number of rays being projected. For each slice of rays the first row is the ray’s origin, and the second row is the direction. Both should be represented as homogeneous coordinates

Returns

an array of the parameter t from the ray equation where the ray intersects the object.

Return type

1-D numpy array of float

abstract normal(intersections)
calculates the normal of a sphere at each point in an array of coordinates. It is assumed that the points lie

on the surface of the object, as this is not verified during calculation.

Parameters

intersections (4xn numpy of float) – a 4xn array of homogeneous points representing a point on the sphere.

Returns

an array of vectors representing the unit normal at each point in intersection

Return type

4xn numpy array of float

class tinygfx.g3d.primitives.Vector(*args, **kwargs)

Bases: tinygfx.g3d.primitives.HomogeneousCoordinate

tinygfx.g3d.primitives.bundle_of_rays(n_rays)

returns a 2x4xn_rays array of ray objects where rays[0] are 4xn_ray homogoneous points(0,0,0), and rays[1] are 4xn_ray homogeneous vectors(0,0,0)

Parameters

n_rays –

Returns

tinygfx.g3d.primitives.bundle_rays(rays)
tinygfx.g3d.primitives.overlap(arr1, arr2)
Parameters

  • arr1 (numpy.ndarray) –

  • arr2 (numpy.ndarray) –

tinygfx.g3d.renderers module

class tinygfx.g3d.renderers.EdgeRender(camera, surfaces)

Bases: object

Parameters
class States(value)

Bases: enum.Enum

An enumeration.

FINISH = 3
IDLE = 4
INITIALIZE = 5
INTERACT = 2
PROPAGATE = 1
TRIM = 6
get_results()

Returns a dataframe of the Ray Trace Results

Returns

pandas dataframe

ray_offset_value = 1e-06
render()
reset()
class tinygfx.g3d.renderers.ShadedRenderer(camera, shapes, light_position)

Bases: object

Parameters
class States(value)

Bases: enum.Enum

An enumeration.

FINISH = 3
IDLE = 4
INITIALIZE = 5
INTERACT = 2
PROPAGATE = 1
TRIM = 6
render()
reset()
tinygfx.g3d.renderers.draw(surfaces, view='xy', axis=None, shaded=True, bounds=None, resolution=640)
Parameters

surfaces (List[tinygfx.g3d.world_objects.TracerSurface]) –

tinygfx.g3d.world_objects module

class tinygfx.g3d.world_objects.CountedObject(*args, **kwargs)

Bases: object

get_id()

Gets the class specific object ID number for this instance.

Returns

the unique class id of the object instance

Return type

int

class tinygfx.g3d.world_objects.Cuboid(l_corner=(- 1, - 1, - 1), r_corner=(1, 1, 1), material=GoochMaterial(base_color=RGBAColor([0., 0., 0., 1.]), warm_color=RGBAColor([1., 0.5, 0., 1.]), cool_color=RGBAColor([0., 0., 1., 1.]), alpha=0.3, beta=0.3), *args, **kwargs)

Bases: tinygfx.g3d.world_objects.TracerSurface

classmethod from_length(length, **kwargs)
classmethod from_sides(x=1, y=1, z=1, **kwargs)
surface

alias of tinygfx.g3d.primitives.Cube

class tinygfx.g3d.world_objects.Cylinder(radius=1, min_height=- 1, max_height=1, material=GoochMaterial(base_color=RGBAColor([0., 0., 0., 1.]), warm_color=RGBAColor([1., 0.5, 0., 1.]), cool_color=RGBAColor([0., 0., 1., 1.]), alpha=0.3, beta=0.3), *args, **kwargs)

Bases: tinygfx.g3d.world_objects.TracerSurface

surface

alias of tinygfx.g3d.primitives.Cylinder

class tinygfx.g3d.world_objects.Intersectable(*args, **kwargs)

Bases: tinygfx.g3d.world_objects.WorldObject, abc.ABC

Base class for a renderable object

attach_to(parent_object)
Parameters

parent_object (tinygfx.g3d.world_objects.WorldObject) –

Return type

None

property bounding_box
property bounding_volume
abstract intersect(rays)
invert_normals()
reset_normals()
property surface_ids

Returns a tuple of surface ids and surface that make up the intersectable object, used for calculating intersections.

class tinygfx.g3d.world_objects.ObjectGroup(*args, **kwargs)

Bases: tinygfx.g3d.world_objects.WorldObject, collections.UserList

class tinygfx.g3d.world_objects.OrthographicCamera(h_pixel_count, h_width, aspect_ratio, *args, **kwargs)

Bases: tinygfx.g3d.world_objects.WorldObject

A camera oriented along the z-axis pointing along the x-axis

Parameters

  • h_pixel_count (int) –

  • h_width (float) –

  • aspect_ratio (float) –

Return type

None

generate_rays()
Return type

numpy.ndarray

get_resolution()
get_span()
class tinygfx.g3d.world_objects.Paraboloid(focus=1, height=1, material=GoochMaterial(base_color=RGBAColor([0., 0., 0., 1.]), warm_color=RGBAColor([1., 0.5, 0., 1.]), cool_color=RGBAColor([0., 0., 1., 1.]), alpha=0.3, beta=0.3), *args, **kwargs)

Bases: tinygfx.g3d.world_objects.TracerSurface

surface

alias of tinygfx.g3d.primitives.Paraboloid

class tinygfx.g3d.world_objects.Sphere(radius, material=GoochMaterial(base_color=RGBAColor([0., 0., 0., 1.]), warm_color=RGBAColor([1., 0.5, 0., 1.]), cool_color=RGBAColor([0., 0., 1., 1.]), alpha=0.3, beta=0.3), *args, **kwargs)

Bases: tinygfx.g3d.world_objects.TracerSurface

surface

alias of tinygfx.g3d.primitives.Sphere

class tinygfx.g3d.world_objects.TracerSurface(surface_args, material=GoochMaterial(base_color=RGBAColor([0., 0., 0., 1.]), warm_color=RGBAColor([1., 0.5, 0., 1.]), cool_color=RGBAColor([0., 0., 1., 1.]), alpha=0.3, beta=0.3), *args, **kwargs)

Bases: tinygfx.g3d.world_objects.Intersectable, abc.ABC

get_world_normals(positions)

returns the normal vectors of the surface for the given positions

Parameters

positions – a 4xn array of homogeneous point coordinates.

Returns

a 4xn array of unit vectors representing the surface’s normal vector at the corresponding input position

intersect(rays)

Intersect the set of rays with the surface, returns a 1d array of euclidean distances between the ray and surface. if the surface does not intersect -1 is returned instead :param rays: :return:

property primitive
shade(rays, distances, **kwargs)

propagates a set of rays incident on the surface. returns a new set of rays and refractive indices representing the rays after transmitting/reflecting off the surface.

Parameters

  • rays (numpy.ndarray) –

  • distances (numpy.ndarray) –

Return type

numpy.ndarray

surface: tinygfx.g3d.primitives.SurfacePrimitive
class tinygfx.g3d.world_objects.WorldObject(*args, **kwargs)

Bases: tinygfx.g3d.world_objects.CountedObject

a world object represents an object in 3D space, it has an origin and a direction, as well as a transform matrices to convert to/from world space

get_object_transform()

returns the 4x4 matrix that translates the world coordinates into object space. the returned matrix is a copy of the internal object and can be modified without changing the object’s state.

Returns

a 4x4 numpy array of float

get_orientation()
get_position()
get_quaternion()
get_world_transform()

returns the 4x4 matrix that translates the object into world coordinate space. the returned matrix is a copy of the internal object and can be modified without changing the object’s state.

Returns

a 4x4 matrix of type float representing the object transform

move(x=0, y=0, z=0)
move_x(movement)
move_y(movement)
move_z(movement)
rotate_x(angle, units='deg')
rotate_y(angle, units='deg')
rotate_z(angle, units='deg')
scale(x=1, y=1, z=1)
scale_all(scale_val)
scale_x(scale_val)
scale_y(scale_val)
scale_z(scale_val)
to_object_coordinates(coordinates)
to_world_coordinates(coordinates)
transform(transform_matrix)

applies the transform matrix to the object. Can contain rotation, translation, scale, and sheer operations. Can be chained with other transform operations.

Parameters

transform_matrix –

Returns

self

class tinygfx.g3d.world_objects.XYPlane(width=2, length=2, material=GoochMaterial(base_color=RGBAColor([0., 0., 0., 1.]), warm_color=RGBAColor([1., 0.5, 0., 1.]), cool_color=RGBAColor([0., 0., 1., 1.]), alpha=0.3, beta=0.3), *args, **kwargs)

Bases: tinygfx.g3d.world_objects.TracerSurface

surface

alias of tinygfx.g3d.primitives.Plane

tinygfx.g3d.world_objects.bounding_box(point_set)

Returns an axis oriented bounding box that fully contains the point set :param point_set: :return:

Module contents