estar::Facade Class Reference

#include <Facade.hpp>

Inheritance diagram for estar::Facade:

Inheritance graph
[legend]
List of all members.

Detailed Description

High-level interface for E-star approach to smooth dynamic navigation functions.

Hides the semantics for accessing the underlying Algorithm, Grid, Kernel, and associated objects. The Facade is specialized for grid-based environment representations.

The recommended way to create and initialize a new Facade is to use one of the factory methods Create() or CreateDefault(). You can also allocate and initialize separate Algorithm, Grid, and Kernel objects and wrap a Facade around them.

Note:
We are using multiple inheritance on two completely abstract base classes, so we do not risk too many of the pitfalls involved in multiple inheritance.


Public Types

typedef FacadeReadInterface::node_status_t node_status_t
 
Note:
This typedef keeps code intact that was written before the FacadeWriteInterface/FacadeReadInterface split.


Public Member Functions

 Facade (boost::shared_ptr< Algorithm > algo, boost::shared_ptr< Grid > grid, boost::shared_ptr< Kernel > kernel)
 Create a Facade from existing instances of Algorithm, Grid, and Kernel.
virtual double GetScale () const
 Implements FacadeReadInterface::GetScale().
virtual double GetFreespaceMeta () const
 Implements FacadeReadInterface::GetFreespaceMeta().
virtual double GetObstacleMeta () const
 Implements FacadeReadInterface::GetObstacleMeta().
virtual double GetValue (ssize_t ix, ssize_t iy) const
 Implements FacadeReadInterface::GetValue().
virtual double GetMeta (ssize_t ix, ssize_t iy) const
 Implements FacadeReadInterface::GetMeta().
virtual bool SetMeta (ssize_t ix, ssize_t iy, double meta)
 Implements FacadeWriteInterface::SetMeta().
virtual bool AddGoal (ssize_t ix, ssize_t iy, double value)
 Implements FacadeWriteInterface::AddGoal().
void AddGoal (const Region &goal)
 An alternative to AddGoal(ssize_t, ssize_t, double) which ignores obstacles [vertices with meta equal to GetObstacleMeta()] and doesn't tell us if it encountered any invalid indices.
void RemoveGoal (ssize_t ix, ssize_t iy)
 Revert a goal cell to normal status.
void RemoveGoal (const Region &goal)
 Revert all cells in a goal region to normal status.
virtual void RemoveAllGoals ()
 Implements FacadeWriteInterface::RemoveAllGoals().
virtual bool IsGoal (ssize_t ix, ssize_t iy) const
 Implements FacadeReadInterface::IsGoal().
virtual bool HaveWork () const
 Implements FacadeReadInterface::HaveWork().
virtual void ComputeOne ()
 Implements FacadeWriteInterface::ComputeOne().
virtual void Reset ()
 Implements FacadeWriteInterface::Reset().
virtual node_status_t GetStatus (ssize_t ix, ssize_t iy) const
 Implements FacadeReadInterface::GetStatus().
virtual node_status_t GetStatus (vertex_t vertex) const
 Implements FacadeReadInterface::GetStatus().
virtual bool IsValidIndex (ssize_t ix, ssize_t iy) const
 Implements FacadeReadInterface::IsValidIndex().
virtual bool GetLowestInconsistentValue (double &value) const
 Implements FacadeReadInterface::GetLowestInconsistentValue().
void DumpGrid (FILE *stream) const
 Write the underlying grid to a stream.
void DumpQueue (FILE *stream, size_t limit) const
 Write the contents of the wavefront Queue to a stream.
void DumpPointers (FILE *stream) const
 Write the addresses of the Algorithm, Grid, and Kernel instances.
virtual const AlgorithmGetAlgorithm () const
 Implements FacadeReadInterface::GetAlgorithm().
virtual const KernelGetKernel () const
 Implements FacadeReadInterface::GetKernel().
virtual int TraceCarrot (double robot_x, double robot_y, double distance, double stepsize, size_t maxsteps, carrot_trace &trace) const
 Implements FacadeReadInterface::TraceCarrot().
virtual boost::shared_ptr<
GridCSpace const > 
GetCSpace () const
 Implements FacadeReadInterface::GetCSpace().
AlgorithmGetAlgorithm ()
 
Returns:
A non-const reference to the underlying Algorithm.

KernelGetKernel ()
 
Returns:
A non-const reference to the underlying Kernel.


Static Public Member Functions

static FacadeCreate (const std::string &kernel_name, double scale, GridOptions const &grid_options, AlgorithmOptions const &algo_options, FILE *dbgstream)
 Create a Facade and make it ready to be used.
static FacadeCreateDefault (ssize_t xsize, ssize_t ysize, double scale)
 Like Create(), but doesn't give you a choice of Kernel (it's always LSMKernel) or of diagonally connected cells (that's always disabled).

Public Attributes

const double scale
 edge length of square cells in the grid

Protected Member Functions

virtual boost::shared_ptr<
Grid const > 
GetGrid () const
 
Note:
this is a hack for legacy code, don't rely on it


Private Member Functions

node_status_t DoGetStatus (ssize_t ix, ssize_t iy, vertex_t vertex) const

Private Attributes

boost::shared_ptr< GridCSpace
const > 
m_cspace
boost::shared_ptr< Algorithmm_algo
boost::shared_ptr< Gridm_grid
boost::shared_ptr< Kernelm_kernel

Friends

class pnf::Flow


Member Typedef Documentation

typedef FacadeReadInterface::node_status_t estar::Facade::node_status_t

Note:
This typedef keeps code intact that was written before the FacadeWriteInterface/FacadeReadInterface split.

Reimplemented from estar::FacadeReadInterface.


Constructor & Destructor Documentation

estar::Facade::Facade ( boost::shared_ptr< Algorithm algo,
boost::shared_ptr< Grid grid,
boost::shared_ptr< Kernel kernel 
)

Create a Facade from existing instances of Algorithm, Grid, and Kernel.

There is NO CHECK if the separate entities are tied together they way they should though.

Note:
Create() and CreateDefault() are much more convenient if you're creating new objects anyway.


Member Function Documentation

Facade * estar::Facade::Create ( const std::string &  kernel_name,
double  scale,
GridOptions const &  grid_options,
AlgorithmOptions const &  algo_options,
FILE *  dbgstream 
) [static]

Create a Facade and make it ready to be used.

Most people can call CreateDefault() instead. Typically, the first things you will do with a freshly created Facade are:

  1. Initialize traversability information using InitMeta(). However, once you have started propagating, you should not use InitMeta() anymore. Use SetMeta() instead.
  2. Set the goal(s) by calling AddGoal().
  3. Repeatedly call ComputeOne(), HaveWork(), and/or GetStatus() to compute the navigation function until you reach the robot or until the whole grid has been propagated.
  4. Use TraceCarrot() to compute a path to the goal; you can also use Grid::ComputeStableScaledGradient() or the more basic Grid::ComputeGradient() to devise a control that, at each timestep, requires just the "best" direction to the goal.

These steps interweave quite easily with updates to the traversability information, because SetMeta() will create appropriate entries on the wavefront Queue. However, when multi-threading you have to create your own mutexes and such (for an example, see the asl-mcontrol code that is provided with the estar-devkit project, available from http://estar.sourceforge.net/).

Returns:
A fresh Facade instance, or null if something went wrong, in which case a message will have been written to dbgstream unless you set that to null.
Note:
If you're wondering why we use FILE * instead of std::ostream and int instead of bool: this makes it much easier to implement a C-wrapper and does not cost the C++ programmer too much.
Parameters:
kernel_name  Name of the Kernel subclass to use. Currently accepts "nf1" for NF1Kernel, "alpha" for AlphaKernel, and "lsm" for LSMKernel. The latter is preferred.
dbgstream  If non-null, error messages are written to this stream. This currently only happens when you specify an invalid kernel_name.

Facade * estar::Facade::CreateDefault ( ssize_t  xsize,
ssize_t  ysize,
double  scale 
) [static]

Like Create(), but doesn't give you a choice of Kernel (it's always LSMKernel) or of diagonally connected cells (that's always disabled).

It uses the default AlgorithmOptions ctor.

virtual double estar::Facade::GetScale (  )  const [inline, virtual]

Implements FacadeReadInterface::GetScale().

Implements estar::FacadeReadInterface.

double estar::Facade::GetFreespaceMeta (  )  const [virtual]

Implements FacadeReadInterface::GetFreespaceMeta().

Implements estar::FacadeReadInterface.

double estar::Facade::GetObstacleMeta (  )  const [virtual]

Implements FacadeReadInterface::GetObstacleMeta().

Implements estar::FacadeReadInterface.

double estar::Facade::GetValue ( ssize_t  ix,
ssize_t  iy 
) const [virtual]

Implements FacadeReadInterface::GetValue().

Implements estar::FacadeReadInterface.

double estar::Facade::GetMeta ( ssize_t  ix,
ssize_t  iy 
) const [virtual]

Implements FacadeReadInterface::GetMeta().

See also Algorithm::SetMeta() for more details.

Implements estar::FacadeReadInterface.

bool estar::Facade::SetMeta ( ssize_t  ix,
ssize_t  iy,
double  meta 
) [virtual]

Implements FacadeWriteInterface::SetMeta().

See also Algorithm::SetMeta() for more details.

Implements estar::FacadeWriteInterface.

bool estar::Facade::AddGoal ( ssize_t  ix,
ssize_t  iy,
double  value 
) [virtual]

Implements FacadeWriteInterface::AddGoal().

Note:
Unlike AddGoal(const Region &), obstacle vertices are not ignored.

Implements estar::FacadeWriteInterface.

void estar::Facade::AddGoal ( const Region goal  ) 

An alternative to AddGoal(ssize_t, ssize_t, double) which ignores obstacles [vertices with meta equal to GetObstacleMeta()] and doesn't tell us if it encountered any invalid indices.

Note:
FacadeWriteInterface has no corresponding abstract method.

void estar::Facade::RemoveGoal ( ssize_t  ix,
ssize_t  iy 
)

Revert a goal cell to normal status.

Unless the cell happens to be non-goal before calling this method, this sets a flag which causes the next call to ComputeOne() to reinitialize the navigation function and wavefront.

void estar::Facade::RemoveGoal ( const Region goal  ) 

Revert all cells in a goal region to normal status.

Basically just calls RemoveGoal(ssize_t, ssize_t) for all the cells in the region.

void estar::Facade::RemoveAllGoals (  )  [virtual]

Implements FacadeWriteInterface::RemoveAllGoals().

Implements estar::FacadeWriteInterface.

bool estar::Facade::IsGoal ( ssize_t  ix,
ssize_t  iy 
) const [virtual]

Implements FacadeReadInterface::IsGoal().

Implements estar::FacadeReadInterface.

bool estar::Facade::HaveWork (  )  const [virtual]

Implements FacadeReadInterface::HaveWork().

Implements estar::FacadeReadInterface.

void estar::Facade::ComputeOne (  )  [virtual]

Implements FacadeWriteInterface::ComputeOne().

Implements estar::FacadeWriteInterface.

void estar::Facade::Reset (  )  [virtual]

Implements FacadeWriteInterface::Reset().

Implements estar::FacadeWriteInterface.

Facade::node_status_t estar::Facade::GetStatus ( ssize_t  ix,
ssize_t  iy 
) const [virtual]

Implements FacadeReadInterface::GetStatus().

Implements estar::FacadeReadInterface.

Facade::node_status_t estar::Facade::GetStatus ( vertex_t  vertex  )  const [virtual]

Implements FacadeReadInterface::GetStatus().

Implements estar::FacadeReadInterface.

bool estar::Facade::IsValidIndex ( ssize_t  ix,
ssize_t  iy 
) const [virtual]

Implements FacadeReadInterface::IsValidIndex().

Implements estar::FacadeReadInterface.

bool estar::Facade::GetLowestInconsistentValue ( double &  value  )  const [virtual]

Implements FacadeReadInterface::GetLowestInconsistentValue().

Implements estar::FacadeReadInterface.

void estar::Facade::DumpGrid ( FILE *  stream  )  const

Write the underlying grid to a stream.

Actually just calls dump_grid() in dump.hpp, so if you want finer control have a look at what else is offered there.

void estar::Facade::DumpQueue ( FILE *  stream,
size_t  limit 
) const

Write the contents of the wavefront Queue to a stream.

Actually just calls dump_queue() in dump.hpp, look there for more options.

Parameters:
limit  if >0 then output stops after that number of entries (the queue can get really long even in medium-sized grids)

void estar::Facade::DumpPointers ( FILE *  stream  )  const

Write the addresses of the Algorithm, Grid, and Kernel instances.

This is mostly for debugging, for moments when you're doubting that the right objects get called...

virtual const Algorithm& estar::Facade::GetAlgorithm (  )  const [inline, virtual]

Implements FacadeReadInterface::GetAlgorithm().

Implements estar::FacadeReadInterface.

shared_ptr< Grid const > estar::Facade::GetGrid (  )  const [protected, virtual]

Note:
this is a hack for legacy code, don't rely on it

Implements estar::FacadeReadInterface.

virtual const Kernel& estar::Facade::GetKernel (  )  const [inline, virtual]

Implements FacadeReadInterface::GetKernel().

Implements estar::FacadeReadInterface.

int estar::Facade::TraceCarrot ( double  robot_x,
double  robot_y,
double  distance,
double  stepsize,
size_t  maxsteps,
carrot_trace trace 
) const [virtual]

Implements FacadeReadInterface::TraceCarrot().

Implements estar::FacadeReadInterface.

shared_ptr< GridCSpace const > estar::Facade::GetCSpace (  )  const [virtual]

Implements FacadeReadInterface::GetCSpace().

Implements estar::FacadeReadInterface.

Algorithm& estar::Facade::GetAlgorithm (  )  [inline]

Returns:
A non-const reference to the underlying Algorithm.

Note:
Should only be necessary if you're experimenting with new things to put into Facade, so consider extending this class once you're done.

Kernel& estar::Facade::GetKernel (  )  [inline]

Returns:
A non-const reference to the underlying Kernel.

Note:
Should only be necessary if you're experimenting with new things to put into Facade, so consider extending this class once you're done.

node_status_t estar::Facade::DoGetStatus ( ssize_t  ix,
ssize_t  iy,
vertex_t  vertex 
) const [private]


Friends And Related Function Documentation

friend class pnf::Flow [friend]


Member Data Documentation

const double estar::Facade::scale

edge length of square cells in the grid

boost::shared_ptr<GridCSpace const> estar::Facade::m_cspace [private]

boost::shared_ptr<Algorithm> estar::Facade::m_algo [private]

boost::shared_ptr<Grid> estar::Facade::m_grid [private]

boost::shared_ptr<Kernel> estar::Facade::m_kernel [private]


The documentation for this class was generated from the following files:
doxygen SourceForge.net Logo
E* Interpolated Graph Replanner Wed Dec 12 18:55:50 2007