DHARTAPI.ViewAnalysis.ViewAnalysis Class Reference

Functions for analyzing the view of an observer in an environment at human scale. More...

Static Public Member Functions
static ManagedFloatArray	ViewAnalysisAggregate (EmbreeBVH bvh, IEnumerable< Vector3D > nodes, int ray_count, float upward_fov=50.0f, float downward_fov=70.0f, float height=1.7f, ViewAggregateType type=ViewAggregateType.AVERAGE)
	Conduct view analysis and aggregate the results for each node. More...
static ResultArray	ViewAnalysisStandard (EmbreeBVH bvh, IEnumerable< Vector3D > nodes, int ray_count, float upward_fov=50.0f, float downward_fov=70.0f, float height=1.7f)
	Conduct View Analysis and access the results of every ray casted for every node. More...
static DirectionArray	SphericallyDistributeRays (int num_rays, float upward_fov=50f, float downward_fov=70f)
	Distribute a set of points equally on a unit sphere. More...

Detailed Description

Functions for analyzing the view of an observer in an environment at human scale.

Note

All of these functions internally use a raytracer, so a DHARTAPI.RayTracing.EmbreeBVH is required.

Member Function Documentation

SphericallyDistributeRays()

static DirectionArray DHARTAPI.ViewAnalysis.ViewAnalysis.SphericallyDistributeRays ( int  num_rays, float  upward_fov = 50f, float  downward_fov = 70f  )

static

Distribute a set of points equally on a unit sphere.

Parameters

num_rays	The number of points to distribute.
upward_fov	Maximum angle above the sphere to generate points in degrees,
downward_fov	Maximum angle in degrees downwards to generate.

Returns

An array of equally distributed points on a unit sphere.

Warning

The number of rays casted may not exactly match ray_count depending on the provided field of view restrictions.

Note

This is the same function used internally by view analysis to equally distribute ray directions.

Example

 
            // Equally distribute 10 rays
            var results = DHARTAPI.ViewAnalysis.ViewAnalysis.SphericallyDistributeRays(10);
 
            // Print results
            Debug.WriteLine(results);
 

[0, -1, 0, -0.2650034, -0.8181818, . . . -0.7649929, 0.4396428, 0.8181818, 0.3705303]

ViewAnalysisAggregate()

static ManagedFloatArray DHARTAPI.ViewAnalysis.ViewAnalysis.ViewAnalysisAggregate ( EmbreeBVH  bvh, IEnumerable< Vector3D >  nodes, int  ray_count, float  upward_fov = 50.0f, float  downward_fov = 70.0f, float  height = 1.7f, ViewAggregateType  type = ViewAggregateType.AVERAGE  )

static

Conduct view analysis and aggregate the results for each node.

Parameters

bvh	the Geometry to intersect with.
nodes	Observer locations to perform view analysis from.
ray_count	Number of rays to cast. Higher values provide more accurate analysis, but increase the runtime of this function
upward_fov	Maximum angle in degrees above the viewer's eye level that is considered.
downward_fov	Maximum angle in degrees below the viewer's eye level that is considered.
height	Height of the observer. Nodes are offset this distance from the ground before the analysis is performed.
type	How the distances for all hits should be aggregated. See ViewAggregateType for a list of all aggregation methods.

Returns

An ordered array of floats corresponding to the aggregated score for each node in nodes.

The rays for each node will be casted in parallel using all available cores on the host's machine.

Remarks

This function is much lighter in memory than ViewAnalysisStandard since all operations are done in place on single floats. Use this as a faster alternative if the scores of nodes are all that's needed.

Examples

            // Load the plane .obj from example models, and rotate it from y-up to z-up
            string mesh_path = "ExampleModels/plane.obj";
            MeshInfo OBJ = OBJLoader.LoadOBJ(mesh_path, CommonRotations.Zup_To_Yup);
 
            // Create a BVH from the plane
            EmbreeBVH bvh = new EmbreeBVH(OBJ);
 
            Vector3D Point = new Vector3D(0, 0, 0);
            Vector3D[] nodes = { Point };
            int num_rays = 1000;
 

 
            // Define the nodes to evaluate
            Vector3D[] nodes = {
                new Vector3D(0,0,1),
                new Vector3D(0,0,2),
                new Vector3D(0,0,3)
            };
 
            // Set maximum number of rays, then conduct analysis
            int num_rays = 1000;
            ManagedFloatArray results = DHARTAPI.ViewAnalysis.ViewAnalysis.ViewAnalysisAggregate(
                bvh,
                nodes,
                num_rays,
                type:ViewAggregateType.COUNT
            );
 
            // Print results. The number of rays should get lower with each element, since each node
            // is further away from the plane than the last
            Debug.WriteLine(results);
 

[480, 451, 428]

Referenced by StringToEdgeCost.Main().

ViewAnalysisStandard()

static ResultArray DHARTAPI.ViewAnalysis.ViewAnalysis.ViewAnalysisStandard ( EmbreeBVH  bvh, IEnumerable< Vector3D >  nodes, int  ray_count, float  upward_fov = 50.0f, float  downward_fov = 70.0f, float  height = 1.7f  )

static

Conduct View Analysis and access the results of every ray casted for every node.

Parameters

bvh	Geometry to intersect with.
nodes	Observer locations to perform view analysis from.
ray_count	Number of rays to cast.Higher values provide more accurate analysis, but increase the runtime and memory consumption of this function.
upward_fov	Maximum angle in degrees above the viewer's eye level that is considered.
downward_fov	Maximum angle in degrees below the viewer's eye level that is considered.
height	Height of the observer. Nodes are offset this distance from the ground before the analysis is performed.

Returns

A nodes.Count() by num_rays 2 dimensional array of results for each node and each ray casted. For example, every ray for node one is located at row 1, and the results for every ray casted from node 2 are located at row 2.

The rays for each node will be casted in parallel using all available cores on the host's machine.

Warning

The number of rays casted may not exactly match ray_count depending on the provided field of view restrictions.

Note

The hitpoints for each ray in the returned array can be determined using the directions SphericallyDistributeRays() with the same fov and ray_count parameters. Failures to intersect geometry will return -1.

Example

            // Load the plane .obj from example models, and rotate it from y-up to z-up
            string mesh_path = "ExampleModels/plane.obj";
            MeshInfo OBJ = OBJLoader.LoadOBJ(mesh_path, CommonRotations.Zup_To_Yup);
 
            // Create a BVH from the plane
            EmbreeBVH bvh = new EmbreeBVH(OBJ);
 
            Vector3D Point = new Vector3D(0, 0, 0);
            Vector3D[] nodes = { Point };
            int num_rays = 1000;
 

            // Define the nodes to evaluate
            Vector3D[] nodes = {
                new Vector3D(0,0,1),
                new Vector3D(1,1,1),
                new Vector3D(0,0,3)
            };
 
            // Set maximum number of rays, then conduct analysis
            int num_rays = 10;
 
            // Conduct view analysis and get all the results
            var results = DHARTAPI.ViewAnalysis.ViewAnalysis.ViewAnalysisStandard(bvh, nodes, num_rays);
 
            // Iterate through every node and print the results
            for (int node_index = 0; node_index < nodes.Length; node_index++)
            {
                var node = nodes[node_index];
                string print = node.ToString() + ": (";
                for (int ray_index = 0; ray_index < num_rays; ray_index++)
                {
                    // Get the result for the current node at the current ray
                    var result = results[node_index][ray_index];
                    print += result.ToString();
 
                    // Add a comma if it isn't the last element
                    if (ray_index != num_rays - 1)
                        print += ", ";
                    else
                        print += ")";
                }
                // Print the line
                Debug.WriteLine(print);
                    
            }
 

(0, 0, 1): ([-1, -1], [5.292, 0], [-1, -1], [-1, -1], [3.098, 0], [5.407, 0], [13.07, 0], [-1, -1], [3.529, 0], [-1, -1])
(1, 1, 1): ([-1, -1], [5.292, 0], [-1, -1], [-1, -1], [3.098, 0], [5.407, 0], [13.07, 0], [-1, -1], [3.529, 0], [-1, -1])
(0, 0, 3): ([-1, -1], [9.211, 0], [-1, -1], [-1, -1], [5.394, 0], [9.413, 0], [-1, -1], [-1, -1], [6.144, 0], [-1, -1])

---

The documentation for this class was generated from the following file:

• src/Csharp/packages/viewanalysis/src/ViewAnalysis.cs