Internal API Documentation

API Overview

The API differs from the general code reference as it is only internal methods used for communicating between the core .dll and the python interface.

Nothing here should be called by a user. This is only for developer reference.

Native Functions to C Interface

Main Module

dhart.common_native_functions.ConvertPointsToArray(points: Tuple[float, float, float] | Iterable[Tuple[float, float, float]]) → c_float

Convert a list of floats to a flat c-style array

dhart.common_native_functions.GetStringPtr(string: str) → c_char_p

A quick and consistent way to convert strings into c-strings for C++

dhart.common_native_functions.convert_strings_to_array(strings: List[str]) → c_char_p

Convert a list of strings to an array of char arrays

Parameters:

strings (List[str]) – Strings to convert

Returns:

A list of char arrays equal in length to the input list of strings

Return type:

c_char_p

dhart.common_native_functions.getDLLHandle() → CDLL

Get a reference to the C++ DLL

Exceptions

exception dhart.Exceptions.FileNotFoundException(message='')

The file at the given path given file was not found

exception dhart.Exceptions.HFException(message)

Generic DHARTAPIException

exception dhart.Exceptions.InvalidCostOperation(message='')

Tried to add an edge to a cost that didn’t already exist in the default cost set

exception dhart.Exceptions.InvalidOBJException(message='')

The provided An invalid OBJ file was specified.

This can be raised if the given filepath leads to a file that is not an OBJ file, the file is a malformed obj file.

exception dhart.Exceptions.LogicError(message='')

A class was used improperly.

exception dhart.Exceptions.MissingDependencyException(message='')

One or more of the required dependencies for this operation were unable to be found

exception dhart.Exceptions.OutOfRangeException(message='')

The requested datapoint was out of the bounds of the given structure

class dhart.Exceptions.HF_STATUS(value)

Error codes to be returned from C++

Numpy Interface

class dhart.native_numpy_like.NativeNumpyLike(vector_ptr: c_void_p, data_ptr: c_void_p, size: int | Tuple)

A wrapper for a native C++ vector that maps to a numpy array

Upon garbage collection, the memory allocated in C++ is automatically freed. Not intended to be instantiated on its own

array

A numpy array that can be used to access the underlying C++ vector’s data.

GetPointers() → Tuple[c_void_p, c_void_p]

Return the underlying vector and data pointers.

Returns:

vector pointer and data pointer respectively

Return type:

Tuple[c_void_p, c_void_p]

__init__(vector_ptr: c_void_p, data_ptr: c_void_p, size: int | Tuple)

Create a new numpy like instance

Parameters:

• vector_ptr – A pointer to the C++ vector holding the information

• data_ptr – A pointer to the underlying data of the vector. This is what is used for the numpy buffer.

• size – The shape of the array. I.E. 100 would be a flat 100 element array, (100, 200) would be a 2dimensional array, etc.

Graph Generator

dhart.graphgenerator.graph_generator_native_functions.GenerateGraph(rt_ptr: c_void_p, start_point, spacing, max_nodes: int, up_step: float, up_slope: float, down_step: float, down_slope: float, max_step_connections: int, min_connections: int, cores: int = -1, obstacle_geometry: List[int] = [], walkable_geometry: List[int] = []) → c_void_p | None

Generate the graph in C++ with a raytracer from CreateRaytracer

Returns:

If the graph creation was successful, return a pointer to the graph. Otherwise, return None.

Geometry

dhart.geometry.meshinfo_native_functions.C_GetMeshID(mesh_ptr: c_void_p) → int

Get the ID of an instance of meshinfo in C++

Parameters:

mesh_ptr (c_void_p) – Pointer to the mesh to get the ID from in C++

Returns:

[description]

Return type:

int

dhart.geometry.meshinfo_native_functions.C_GetMeshName(mesh_ptr: c_void_p) → str

Get the nme of a mesh from C++

Parameters:

mesh_ptr (c_void_p) – A pointer to the meshinfo tor read from in native code

Returns:

The name of the mesh in C++

Return type:

str

dhart.geometry.meshinfo_native_functions.C_GetMeshVertsAndTris(mesh_ptr: c_void_p) → Tuple[c_void_p, int, c_void_p, int]

Get pointers to the vertex and triangle arrays of a meshinfo object

Parameters:

• mesh_ptr (c_void_p) – A pointer to the instance of meshinfo to get the vertex

• of. (and triangle arrays) –

Returns:

A pointer to the mesh’s index array, the number of indicies contained within the mesh, a pointer to the vertex array of the mesh, and the number of vertices contained in the mesh respectively

Return type:

Tuple[c_void_p, int, c_void_p, int]

dhart.geometry.meshinfo_native_functions.CreateMesh(indices: List[int], vertices: List[float], name: str, id: int) → c_void_p

Pass mesh data to C++ as a list of indices and vertices

Parameters:

• indices – A list of indices with each 3 representing a triangle. Must be a multiple of 3

• vertices – A list of vertices, with each 3 floats representing a unique vertex

• name – The name of the mesh internally

• id – The mesh’s ID

Returns:

A pointer to a valid MeshInfo object in c++

dhart.geometry.meshinfo_native_functions.CreateOBJ(obj_file_path: str, group_type: int = 0, rotation: Tuple[float, float, float] = (0, 0, 0)) → c_void_p | List[c_void_p]

Read an OBJ from a file on disk.

Parameters:

• obj_file_path (str) – Path to the obj file on dik

• group_type (int, optional) – Method of dividing the OBJ into submeshes.

• rotation (Tuple[float, float, float], optional) – Magnitude to rotate the mesh on the x,y,z axis

Raises:

• InvalidOBJException – OBJ fails to load from the given filepath

• FileNotFoundException – No file exists at the given filepat

Returns:

A pointer to one isntance of meshinfo if only one was created, or a list of pointers for each submesh in the OBJ at path

Return type:

Union[c_void_p, List[c_void_p]]

dhart.geometry.meshinfo_native_functions.DestroyMeshInfo(mesh_info_ptr: c_void_p)

Call the destructor for MeshInfo

Path Finding

dhart.pathfinding.pathfinder_native_functions.C_DestroyPath(path_ptr: c_void_p) → None

Delete a path in C++

dhart.pathfinding.pathfinder_native_functions.C_FindAllPaths(graph_ptr: c_void_p, num_nodes: int, cost_type: str) → List[Tuple[c_void_p, c_void_p, int] | None]

Find a path between every node in the graph

Parameters:

• graph_ptr – A pointer to a valid graph

• num_nodes – The number of nodes in the graph

• cost_type – The type of cost to use from the graph. If left blank, will use the cost that the graph was generated with.

Returns:

Pointer to the Path object in C++ c_void_p: Pointer to the Path’s data in C++ int: The size of the generated path OR None: If there was no path between A and B

Return type:

c_void_p

Raises:

KeyError – cost_type didn’t exist already in the graph

dhart.pathfinding.pathfinder_native_functions.C_FindPath(graph_ptr: c_void_p, start: int, end: int, cost_type: str = '') → Tuple[c_void_p, c_void_p, int] | None

Find a path in C++ from start to end

Parameters:

• graph_ptr – A pointer to a valid graph

• start – starting node id

• end – ending node id

Returns:

Pointer to the Path object in C++ c_void_p: Pointer to the Path’s data in C++ int: The size of the generated path OR None: If there was no path between A and B

Return type:

c_void_p

Raises:

OutOfRangeException – Start or End did not exist in the given graph.

dhart.pathfinding.pathfinder_native_functions.C_FindPaths(graph_ptr: c_void_p, start: List[int], end: List[int], cost_type: str = '') → List[Tuple[c_void_p, c_void_p, int]]

Find multiple paths in C++ from start to end

Parameters:

• graph_ptr – A pointer to a valid graph

• start – starting node id

• end – ending node id

• cost_type – The type of cost to use from the graph. If left blank, will use the cost that the graph was generated with.

Returns:

Pointer to the Path object in C++ c_void_p: Pointer to the Path’s data in C++ int: The size of the generated path OR None: If there was no path between A and B

Return type:

c_void_p

Raises:

KeyError – cost_type didn’t exist already in the graph

dhart.pathfinding.pathfinder_native_functions.c_calculate_distance_and_predecessor(graph_ptr: c_void_p, cost_type: str) → Tuple[c_void_p, c_void_p, c_void_p, c_void_p]

Calculate Distance and Predecessor arrays for a graph in C++

Parameters:

• graph_ptr – Graph to generate predecessor/distance matricies from

• cost_type – Type of cost to use to generate distance and predecessor matricies. Default if left blank.

Raises:

KeyError – cost_type wasn’t left blank, and didn’t already exist in the graph.

Returns:

In order, distance matrix’s vector and data pointers, predecessor matrix’s data vector and data pointers. All returned arrays will be of length equal to the number of nodes in g squared.

Raytracer

dhart.raytracer.raytracer_native_functions.C_AddMeshes(bvh_ptr: c_void_p, mesh_ptrs: List[c_void_p])

Add meshes to a bvh in C++

Parameters:

• bvh_ptr (c_void_p) – Pointer to the raytracer to add meshes to

• mesh_ptrs (List[c_void_p]) – Pointers to MeshInfos to add to the bvh

dhart.raytracer.raytracer_native_functions.C_PreciseIntersection(bvh_ptr: c_void_p, origin: Tuple[float, float, float], direction: Tuple[float, float, float]) → float

Cast a ray in C++ and get the distance back with double precision

Parameters:

• bvh_ptr (c_void_p) – Pointer to a bvh in C++

• origin (Tuple[float,float,float]) – Origin of the ray

• direction (Tuple[float, float, float]) – Direction to cast the ray in

Returns:

A double precision float containing the distance from the ray to it’s point of intersection

Return type:

float

dhart.raytracer.raytracer_native_functions.CastMultipleOriginsOneDirection(rt_ptr: c_void_p, origin: List[Tuple[float, float, float]], direction: Tuple[float, float, float], max_distance: float) → List[Tuple[float, float, float] | None]

Cast multiple rays in the same direction

dhart.raytracer.raytracer_native_functions.CastMultipleRays(rt_ptr: c_void_p, origin: List[Tuple[float, float, float]], direction: List[Tuple[float, float, float]], max_distance: float) → List[Tuple[float, float, float] | None]

Shoot rays for multiple direction/origin pairs.

Returns:

an ordered list of results containing None for misses and hitpoints for hits

Return type:

List

dhart.raytracer.raytracer_native_functions.CastMultipleRaysDistance(bvh_ptr: c_void_p, origins: Tuple[float, float, float] | List[Tuple[float, float, float]], directions: Tuple[float, float, float] | List[Tuple[float, float, float]], max_distance: float = -1) → Tuple[c_void_p, c_void_p]

Returns:

Pointer to the vector containing the ray results c_void_p: Pointer to the vector’s underlying data

Return type:

c_void_p

dhart.raytracer.raytracer_native_functions.CastOcclusionRays(rt_ptr: c_void_p, origin: Tuple[float, float, float] | List[Tuple[float, float, float]], direction: Tuple[float, float, float] | List[Tuple[float, float, float]], max_distance: float) → List[bool]

Cast one or more Occlusion Rays

dhart.raytracer.raytracer_native_functions.CastOneOriginMultipleDirections(rt_ptr: c_void_p, origin: Tuple[float, float, float], direction: List[Tuple[float, float, float]], max_distance: float) → List[Tuple[float, float, float] | None]

Cast multiple rays from a single origin.

Returns:

an ordered list of hitspoints or None

Return type:

List

dhart.raytracer.raytracer_native_functions.CastRay(rt_ptr: c_void_p, origin: Tuple[float, float, float], direction: Tuple[float, float, float], max_distance: float = -1.0) → Tuple[float, float, float] | None

Cast a single ray, get a point in return

dhart.raytracer.raytracer_native_functions.CreateRayTracer(mesh_info_ptr: c_void_p | List[c_void_p], use_precise: bool) → c_void_p

Create a raytracer from a pointer to valid meshinfo previously created by CreateOBJ

Parameters:

• mesh_info_ptr (Union[c_void_p, List[c_void_p]]) – One or more pointers to MeshInfo objects to construct the BVH fromn

• use_precise (bool) – Use a slower but more accurate ray intersection method where applicable

Raises:

MissingDependencyException – Embree.dll or tbb.dll could not be loaded.

Returns:

A pointer to the newly created BVH

Return type:

c_void_p

dhart.raytracer.raytracer_native_functions.DestroyRayTracer(rt_ptr: c_void_p)

Call the destructor for a raytracer

Spatial Structures

dhart.spatialstructures.spatial_structures_native_functions.C_AddEdgeFromNodeIDs(graph_ptr: c_void_p, parent_id: int, child_id: int, score: float, cost_type: str) → None

Adds edge to graph from a node ID

Returns:

None

dhart.spatialstructures.spatial_structures_native_functions.C_AddEdgeFromNodes(graph_ptr: c_void_p, parent: Tuple[float, float, float], child: Tuple[float, float, float], score: float, cost_type: str) → None

Add a new edge to the graph

dhart.spatialstructures.spatial_structures_native_functions.C_AggregateEdgeCosts(graph_ptr: c_void_p, aggregate_type: int, directed: bool, cost_type: str) → c_void_p

Aggregates edge costs

Notes

Calls C_INTERFACE AggregateCosts

dhart.spatialstructures.spatial_structures_native_functions.C_AttrsToCosts(graph_ptr: c_void_p, attribute_string: str, cost_string: str, direction: int)

Generate a cost set based on a set of node parameters

Parameters:

• graph_ptr (c_void_p) – Pointer to the graph to modify

• attribute_string (str) – Attribute to create a new cost set from.]

• cost_string (str) – Key for the newly generated cost set.direction (Direction): Direction to use for calculating the cost of any edge. example INCOMING will use the cost of the node being traveled to by the edge.

Raises:

KeyError – attribute_string was not the key of any node attribute in the graph

dhart.spatialstructures.spatial_structures_native_functions.C_ClearGraph(graph_ptr: c_void_p, cost_type: str = '') → None

Clear graph of a given cost type

dhart.spatialstructures.spatial_structures_native_functions.C_CreateGraph(nodes: List[Tuple[float, float, float]] | None) → c_void_p

Create a new graph in C++

Parameters:

nodes – A list of nodes to pre-insert into the graph or nothing

Returns:

A pointer to the underlying graph object in C++

Return type:

c_void_p

dhart.spatialstructures.spatial_structures_native_functions.C_GetCSRPtrs(graph_ptr: c_void_p, cost_type: str) → Tuple[int, int, int, c_void_p, c_void_p, c_void_p]

Get the information necessary to map a numpy CSR to the C++ graph

Parameters:

graph_ptrc_void_p

a pointer to the graph object

cost_typec_char_p

The cost type to use for constructing the CSR.

Returns:

Number of non-zeros for the csr int: Number of rows in the graph int: Number of columns in the graph c_void_p: Pointer to the data of the graph c_void_p: Pointer to the inner_indices of the graph c_void_p: Pointer to the outer_indices of the graph

Return type:

int

dhart.spatialstructures.spatial_structures_native_functions.C_GetEdgeCost(graph_ptr: c_void_p, parent: int, child: int, cost_type: str)

Get the cost of an edge in the graph

Parameters:

• graph_ptr – pointer to the graph to get the cost from

• parent – parent of the edge

• child – child of the edge

• cost_type – cost type to get the edge cost from. If left as the empty string, use the graph’s default cost type.

Returns:

The cost from parent to child if the cost exists, otherwise returns -1 if the cost doesn’t exist.

dhart.spatialstructures.spatial_structures_native_functions.C_GetNodeID(graph_ptr: c_void_p, node: Tuple[float, float, float]) → int

Get the id of node for the graph at graph_ptr

dhart.spatialstructures.spatial_structures_native_functions.C_NumNodes(graph_ptr: c_void_p) → int

Get the number of nodes in the graph

dhart.spatialstructures.spatial_structures_native_functions.DestroyGraph(graph_ptr: c_void_p)

Call the destructor for a list of nodes

dhart.spatialstructures.spatial_structures_native_functions.DestroyNodes(node_list_ptr: c_void_p)

Call the destructor for a list of nodes

dhart.spatialstructures.spatial_structures_native_functions.GetEdgesForNode(graph_ptr: c_void_p, node_ptr: c_void_p) → Tuple[c_void_p, c_void_p]

* UNIMPLEMENTED *

Get a list of nodes from a graph that belong to the specified node

dhart.spatialstructures.spatial_structures_native_functions.GetNodesFromGraph(graph_ptr: c_void_p) → Tuple[c_void_p, c_void_p]

Get a list of nodes from from the graph pointed to by graph_ptr

Returns:

a pointer to a vector of nodes then a pointer to

said vector’s underlying data.

Return type:

Tuple[c_void_p, c_void_p]

dhart.spatialstructures.spatial_structures_native_functions.SizeOfNodeVector(node_vector_ptr: c_void_p) → int

Get the size of a node vector

dhart.spatialstructures.spatial_structures_native_functions.c_add_node_attributes(graph_ptr: c_void_p, attr: str, ids: List[int], scores: List[str]) → None

Assign or update scores for nodes for a specific attribute

Parameters:

• graph_ptr – Pointer to the graph to add scores to

• attr – Unique key of the attribute to add scores to. If this an

• created. (attribute with this keydoesn't exist then it will be) –

• ids – An array of ids of nodes to assign scores to

• scores – An ordered array of scores where each score is to be assigned

• index. (to the id in ids at the same) –

dhart.spatialstructures.spatial_structures_native_functions.c_clear_node_attribute(graph_ptr: c_void_p, attr: str) → None

Clear a node attribute and all of its scores from a graphj

Parameters:

• graph_ptr – Graph to clear the attribute from.

• attr – Attribute to clear from the graph

dhart.spatialstructures.spatial_structures_native_functions.c_get_node_attributes(graph_ptr: c_void_p, attr: str, num_nodes: int) → List[str] | List[None]

Get node attributes from a grpah in C++

Parameters:

• graph_ptr – Pointer to the graph to get attributes from.

• attr – Unique key of the attribute to get

• num_nodes – number of nodes in the graph

Returns:

A list of strings containing the score for every node in the graph ordered by ID. If the attribute could not be found in the graph, an empty list will be returned instead

View Analysis

dhart.viewanalysis.viewanalysis_native_functions.C_SphericalViewAnalysis(bvh: c_void_p, nodes: c_void_p, node_count: int, ray_count: int, height: float, upper_fov=50, lower_fov=70) → Tuple[c_void_p, c_void_p]

Perform view analysis and get the result of each raycast individually

This function casts node_count * ray_count rays

Returns:

Points to a ViewAnalysisResult vector. c_void_p: Points to the vector’s underlying data. The vector is laid out contiguously with shape (node_count, ray_count). Within each element in this array is a float for distance, and an int for meshid

Return type:

c_void_p

Raises:

HF.Exceptions.OutOfMemoryException – The number of rays/nodes was too large to fit in a C++ vector

dhart.viewanalysis.viewanalysis_native_functions.C_SphericalViewAnalysisAggregate(bvh: c_void_p, nodes: c_void_p, node_count: int, ray_count: int, height: float, agg_type: int, upper_fov=50, lower_fov=70) → Tuple[int, c_void_p, c_void_p]

Conduct view analysis in C++

Returns:

Size of the vector created c_void_p: Pointer to the score vector itself c_void_p: Pointer to the data of the pointer

Return type:

int

Visibility Graph

dhart.visibilitygraph.visibility_graph_native_functions.C_VisibilityGraphAllToAll(bvh: c_void_p, nodes: Tuple[float, float, float], height: float) → c_void_p

Create a directed visibility graph in C++

dhart.visibilitygraph.visibility_graph_native_functions.C_VisibilityGraphAlltoAllUndirected(bvh: c_void_p, nodes: Tuple[float, float, float], height: float, cores: int = 0) → c_void_p

Create an Undirected Visbility graph in C++

Unlike the standard visibility graph algorithm, the Undirected visibility graph is able to be parallelized, and has a much lower memory footprint making it better suited to larger datasets.

Parameters:

• bvh – the pointer to a valid embree bvh

• nodes – a list of nodes as (x,y,z) tuples

• height – height to evaluate the visibility graph from

• cores – number of cores to use in the evaluation. 0 will not be parallelized

Returns:

a pointer to the visibility graph in C++

Return type:

c_void_p

dhart.visibilitygraph.visibility_graph_native_functions.C_VisibilityGraphGroupToGroup(bvh: c_void_p, nodes_a: Tuple[float, float, float], nodes_b: Tuple[float, float, float], height: float, cores: int = 0) → c_void_p | None

Create an Undirected Visbility graph in C++

Returns none if no edges were produced