Represents a single face of a 4-planar, orthogonal layout. More...

#include <faces.h>

Collaboration diagram for dialect::Face:

Public Member Functions
	Face (Graph_SP &G)
	Standard constructor. More...

void	initWithEdgeSeq (const std::vector< IdPair > &edges)
	A method to build the Face, based on the clockwise sequence of "edges" of which it is made up; here an "edge" is a mere IdPair.

Nodes	getNodeSeq (void)
	Access the sequence (vector) of Nodes belonging to the Face, in clockwise order.

Sides	getSides (void)
	Get a copy of the vector of Sides.

NexesById	getNexusLookup (void)
	Get a copy of the Nexus lookup.

bool	containsNodeIdSeq (std::vector< id_type > idSeq) const
	Utility method, to test whether the Face contains a given sequence of Node IDs, in clockwise cyclic order.

Graph_SP	getGraph (void)
	Access the underlying Graph.

id_type	id (void) const
	Access the unique ID of a given instance. More...

bool	isExternal (void) const
	Check whether this is the external face or not.

std::string	toString (void) const
	Get a string representation.

std::map< id_type, std::vector< std::pair< Node_SP, Node_SP > > >	getNbrPairs (void)
	Access the neighbour pairs.

Sides	getRelevantSidesForPlacement (TreePlacement_SP tp) const
	Get a vector of all Sides that are relevant to a given TreePlacement.

void	listAllPossibleTreePlacements (TreePlacements &tps, Tree_SP tree, Node_SP root, HolaOpts opts)
	Compute all the possible ways of placing a given Tree into this Faces, at a given root Node belonging to this Face. More...

CompassDirs	inwardDirsAvailable (Node_SP node)
	List the compass directions in which an edge could point if it were anchored at the given Node, and pointed inward, into the Face. More...

void	insertTreeNode (TreePlacement_SP tp, double padding=0)
	To be used after the face has been expanded to make room for the tree. This method adds a large node to the graph, representing the bounding box of the tree, with padding. The treenode is constrained to lie beside its root node. More...

ProjSeq_SP	computeCollateralProjSeq (TreePlacement_SP tp, double padding=0)
	Compute a projection sequence to remove/prevent overlaps between the given TreePlacement's tree box, and any existing tree boxes or ordinary perimeter Nodes on relevant Sides of this Face. More...

bool	applyProjSeq (ProjSeq &ps)
	Convenience function for applying a ProjSeq with all the appropriate options. More...

ProjSeq_SP	doCollateralExpansion (TreePlacement_SP tp, double padding=-1)
	Perform collateral expansion for a given TreePlacement. This means pushing Nodes and tree boxes on relevant Sides out of the way, to make room for the new tree box. More...

void	buildBdrySegsFacingOneDir (CardinalDir facingDir, LineSegments &closedSegs, LineSegments &openSegs, TreePlacement_SP ignoreTP=nullptr)
	Build LineSegments to represent all those segments of the internal boundary of this Face that face in a given direction. These segments can represent aligned Edges, or parts of boundaries of Nodes or tree boxes. More...

ProjSeq_SP	buildBestProjSeq (TreePlacement_SP tp, double padding=0, bool doCostlierDimensionFirst=false, ExpansionEstimateMethod estimateMethod=ExpansionEstimateMethod::CONSTRAINTS)
	Build the best projection sequence for a given tree placement. More...

Sides	getAllSidesOppositeSegment (LineSegment &seg, bool openInterval=false) const
	Get all the Sides of this Face that lie opposite a given LineSegment. More...

TreePlacements	getAllTreePlacements (void) const
	Get all TreePlacements that have been added to this Face. More...

std::set< TreePlacement_SP >	getSetOfAllTreePlacements (void) const
	Get the set of all TreePlacements that have been added to this Face. More...

void	getAllTreePlacements (TreePlacements &tps) const
	Get all TreePlacements that have been added to this Face. More...

void	getNumTreesByGrowthDir (std::map< CardinalDir, size_t > &counts, bool scaleBySize=false) const
	After tree placements have been chosen and performed, get a count of trees by growth direction. More...

Detailed Description

Represents a single face of a 4-planar, orthogonal layout.

Constructor & Destructor Documentation

◆ Face()

dialect::Face::Face ( Graph_SP & G )

inline

Standard constructor.

Parameters

[in] G The Graph to which the Face belongs.

Member Function Documentation

◆ applyProjSeq()

bool Face::applyProjSeq ( ProjSeq & ps )

Convenience function for applying a ProjSeq with all the appropriate options.

Parameters

[in] ps The ProjSeq to be applied.

Returns: boolean, saying whether all the projections were successful.

References dialect::ColaOptions::preventOverlaps, and dialect::ColaOptions::solidifyAlignedEdges.

Referenced by doCollateralExpansion().

Here is the caller graph for this function:

◆ buildBdrySegsFacingOneDir()

void Face::buildBdrySegsFacingOneDir	(	CardinalDir	facingDir,
		LineSegments &	closedSegs,
		LineSegments &	openSegs,
		TreePlacement_SP	ignoreTP = `nullptr`
	)

Build LineSegments to represent all those segments of the internal boundary of this Face that face in a given direction. These segments can represent aligned Edges, or parts of boundaries of Nodes or tree boxes.

Parameters

[in]	facingDir	CardinalDir telling which side the segments should face.
[out]	closedSegs	Vector in which to store all constructed closed segments.
[out]	openSegs	Vector in which to store all constructed open segments.
[in]	ignoreTP	Optional TreePlacement whose collateral tree boxes should be ignored.

Note: Whether a boundary segment is closed or open means whether one crosses the interior boundary of the face at the endpoints (yes for closed, no for open).

For example, if facingDir is SOUTH, then closedSegs will get one LineSegment for every horizontal Edge in the Face, while openSegs will get a LineSegment representing the southern boundary of (a) each Node in the Face, and (b) each Tree box in the Face.

References dialect::BoundingBox::buildSideSegment(), getRelevantSidesForPlacement(), Avoid::Point::id, Avoid::Point::x, and Avoid::Point::y.

Here is the call graph for this function:

◆ buildBestProjSeq()

ProjSeq_SP Face::buildBestProjSeq	(	TreePlacement_SP	tp,
		double	padding = `0`,
		bool	doCostlierDimensionFirst = `false`,
		ExpansionEstimateMethod	estimateMethod = `ExpansionEstimateMethod::CONSTRAINTS`
	)

Build the best projection sequence for a given tree placement.

Parameters

[in]	tp	The TreePlacement to be added to this Face.
[in]	padding	Optional padding for the new tree box.
[in]	doCostlierDimensionFirst	See TreePlacement::buildBestProjSeq.
[in]	estimateMethod	See defn of ExpansionEstimateMethod enum class.

Returns: A ProjSeq representing the computed projection sequence.

References doCollateralExpansion(), and vpsc::XDIM.

Here is the call graph for this function:

◆ computeCollateralProjSeq()

ProjSeq_SP Face::computeCollateralProjSeq	(	TreePlacement_SP	tp,
		double	padding = `0`
	)

Compute a projection sequence to remove/prevent overlaps between the given TreePlacement's tree box, and any existing tree boxes or ordinary perimeter Nodes on relevant Sides of this Face.

Parameters

[in]	tp	The TreePlacement to be added to this Face.
[in]	padding	Optional padding for the new tree box.

Returns: A ProjSeq representing the computed projection sequence.

Note: In the case where tp's root lies on two sides of the face, these two sides must be aligned in complementary dimensions (i.e. one in x, and one in y), so the sepcos generated here are always independent.

That is, if each side has an existing treenode that must be pushed away, the sepco for one tree will never achieve the push for the other, since these pushes /must/ be done in complementary dimensions.

Therefore there is no need to wait until after the first removal has been actually performed to compute the sepco for the second removal; it cannot be affected by the first one. This means we can safely compute them simultaneously.

References getRelevantSidesForPlacement().

Referenced by doCollateralExpansion().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ doCollateralExpansion()

ProjSeq_SP Face::doCollateralExpansion	(	TreePlacement_SP	tp,
		double	padding = `-1`
	)

Perform collateral expansion for a given TreePlacement. This means pushing Nodes and tree boxes on relevant Sides out of the way, to make room for the new tree box.

Parameters

[in]	tp	The TreePlacement requiring space.
[in]	padding	Optional padding to be added to the new tree box. Leave negative if you want padding equal to iel/4 to be automatically applied, where iel is the underlying graph's current ideal edge length.

Returns: The ProjSeq that was used to achieve the required expansion. This ProjSeq will have been already evaluated and applied when returned.

Exceptions

Runtime exception if any of the collateral expansion projections are infeasible. In theory this should never happen.

References applyProjSeq(), and computeCollateralProjSeq().

Referenced by buildBestProjSeq().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getAllSidesOppositeSegment()

Sides Face::getAllSidesOppositeSegment	(	LineSegment &	seg,
		bool	openInterval = `false`
	)		const

Get all the Sides of this Face that lie opposite a given LineSegment.

Parameters

[in]	seg	The LineSegment in question.
[in]	openInterval	Set true if you want to consider the overlap with the LineSegment's open interval instead of closed (the default).

Returns: Vector of Sides.

◆ getAllTreePlacements() [1/2]

TreePlacements Face::getAllTreePlacements ( void ) const

Get all TreePlacements that have been added to this Face.

Returns: Vector of TreePlacements.

Referenced by getNumTreesByGrowthDir().

Here is the caller graph for this function:

◆ getAllTreePlacements() [2/2]

void Face::getAllTreePlacements ( TreePlacements & tps ) const

Get all TreePlacements that have been added to this Face.

Parameters

[out] tps Vector of TreePlacements to which those belonging to this Face should be added.

◆ getNumTreesByGrowthDir()

void Face::getNumTreesByGrowthDir	(	std::map< CardinalDir, size_t > &	counts,
		bool	scaleBySize = `false`
	)		const

After tree placements have been chosen and performed, get a count of trees by growth direction.

Parameters

[out]	counts	Map into which the counts should be added.
[in]	scaleBySize	Set true if for each tree you actually want to count its number of nodes. In other words, the final counts you get actually indicate the number of nodes in trees that grow in the given directions.

References getAllTreePlacements().

Here is the call graph for this function:

◆ getSetOfAllTreePlacements()

std::set< TreePlacement_SP > Face::getSetOfAllTreePlacements ( void ) const

Get the set of all TreePlacements that have been added to this Face.

Returns: Set of TreePlacements.

◆ id()

id_type dialect::Face::id ( void ) const

inline

Access the unique ID of a given instance.

Returns: The ID.

◆ insertTreeNode()

void Face::insertTreeNode	(	TreePlacement_SP	tp,
		double	padding = `0`
	)

To be used after the face has been expanded to make room for the tree. This method adds a large node to the graph, representing the bounding box of the tree, with padding. The treenode is constrained to lie beside its root node.

Parameters

[in]	tp	A TreePlacement representing the Tree to be placed.
[in]	padding	Optional padding to be added to the tree box.

See also: TreePlacement::getTreeBox for interpretation of the padding.

References getRelevantSidesForPlacement(), Avoid::Point::x, and Avoid::Point::y.

Referenced by dialect::TreePlacement::insertTreeNode().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ inwardDirsAvailable()

CompassDirs Face::inwardDirsAvailable ( Node_SP node )

List the compass directions in which an edge could point if it were anchored at the given Node, and pointed inward, into the Face.

Because of the way the faces are traced out, swinging from the previous node to the next one sweeps out an area of the /inside/ of this face when you go /anticlockwise/.

Therefore if d0 is the compass direction from node to prev, and if d1 is that from node to next, then the available directions are all those strictly between d0 and d1 /in the anticlockwise direction/.

For example, if node –> prev points South while node –> next points West, then both East and North are available. But if node –> prev points East while node –> next points North, then only NE is available.

Referenced by listAllPossibleTreePlacements().

Here is the caller graph for this function:

◆ listAllPossibleTreePlacements()

void Face::listAllPossibleTreePlacements	(	TreePlacements &	tps,
		Tree_SP	tree,
		Node_SP	root,
		HolaOpts	opts
	)

Compute all the possible ways of placing a given Tree into this Faces, at a given root Node belonging to this Face.

Parameters

[out]	tps	A vector of TreePlacements to which all those allocated by this method are to be added.
[in]	tree	The Tree to be placed.
[in]	root	The Node, belonging to this Face, where the Tree is to attach.
[in]	opts	Options to control which kinds of placements are defined.

Note: If opts.treePlacement_favourCardinal == true, then we will report ordinal placement options if and only if there are no possible cardinal placement options. For example, if {NE, E, SE} were available, we would construct a TreePlacement only on the E placement direction; however if only {NE, SE} were available, we would construct a TreePlacement for each of these ordinal directions.

References inwardDirsAvailable().

Here is the call graph for this function:

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

libdialect/faces.h
libdialect/faces.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Face()

Member Function Documentation

◆ applyProjSeq()

◆ buildBdrySegsFacingOneDir()

◆ buildBestProjSeq()

◆ computeCollateralProjSeq()

◆ doCollateralExpansion()

◆ getAllSidesOppositeSegment()

◆ getAllTreePlacements() [1/2]

◆ getAllTreePlacements() [2/2]

◆ getNumTreesByGrowthDir()

◆ getSetOfAllTreePlacements()

◆ id()

◆ insertTreeNode()

◆ inwardDirsAvailable()

◆ listAllPossibleTreePlacements()