Class Layer

Inheritance Relationships

Base Types

Class Documentation

class cpphots::Layer : public virtual cpphots::interfaces::TimeSurfacePoolCalculator, public virtual cpphots::interfaces::Clusterer

Composable layer.

This class implements a HOTS layer that can be built from different components.

The four components that can be added must implement one the following interfaces:

If one of the components is a subclass of interfaces::Clusterer, clustering is also performed on every event.

Layer bahaves as both a interfaces::TimeSurfacePoolCalculator and a interfaces::Clusterer.

Public Functions

Layer(interfaces::TimeSurfacePoolCalculator *tspool = nullptr, interfaces::Clusterer *clusterer = nullptr, interfaces::EventRemapper *remapper = nullptr, interfaces::SuperCell *supercell = nullptr)

Construct a new Layer.

All parameters are optional, but a pool must be provided before calling Layer::process.

The Layer takes ownership of all the components.

Parameters

  • tspool – time surface pool calculator

  • clusterer – clusterer

  • remapper – event remapper

  • supercell – supercell modifier

~Layer()

Destroy the Layer object, deleting its components.

Layer(const Layer &other)

Copy constructor

Parameters

other – layer to be copied

Layer(Layer &&other)

Move constructor

Parameters

other – objelayerct to be moved

Layer &operator=(const Layer &other)

Copy assignment

Parameters

other – layer to be copied

Layer &operator=(Layer &&other)

Move assignment

Parameters

other – layer to be moved

void addTSPool(interfaces::TimeSurfacePoolCalculator *tspool)

Add a time surfaces pool calculator.

Old one is deleted. The Layer takes ownership of the component.

Parameters

tspool – time surface pool calculator

template<typename T, typename ...Args>
inline void createTSPool(const Args&... args)

Create a new time surfaces pool object and add it to the layer.

Template Parameters

  • T – type of component

  • Args – type of the arguments of the constructor

Parameters

args – arguments to construct the component

interfaces::TimeSurfacePoolCalculator &getTSPool()

Get the time surfaces pool component, if present.

If the component is not present, an exception will be raised.

Returns

the requested component

const interfaces::TimeSurfacePoolCalculator &getTSPool() const

Get the time surfaces pool component, if present.

If the component is not present, an exception will be raised.

Returns

the requested component

void addClusterer(interfaces::Clusterer *clusterer)

Add a clusterer.

Old one is deleted. The Layer takes ownership of the component.

Parameters

clusterer – clusterer

template<typename T, typename ...Args>
inline void createClusterer(const Args&... args)

Create a new clusterer and add it to the layer.

Template Parameters

  • T – type of component

  • Args – type of the arguments of the constructor

Parameters

args – arguments to construct the component

interfaces::Clusterer &getClusterer()

Get the clusterer component, if present.

If the component is not present, an exception will be raised.

Returns

the requested component

const interfaces::Clusterer &getClusterer() const

Get the clusterer component, if present.

If the component is not present, an exception will be raised.

Returns

the requested component

void addRemapper(interfaces::EventRemapper *remapper)

Add a remapper modifier.

Old one is deleted. The Layer takes ownership of the component.

Parameters

remapper – event remapper

template<typename T, typename ...Args>
inline void createRemapper(const Args&... args)

Create a new event remapper and add it to the layer.

Template Parameters

  • T – type of component

  • Args – type of the arguments of the constructor

Parameters

args – arguments to construct the component

interfaces::EventRemapper &getRemapper()

Get the event remapper component, if present.

If the component is not present, an exception will be raised.

Returns

the requested component

const interfaces::EventRemapper &getRemapper() const

Get the event remapper component, if present.

If the component is not present, an exception will be raised.

Returns

the requested component

void addSuperCell(interfaces::SuperCell *supercell)

Add a supercell modifier.

Old one is deleted. The Layer takes ownership of the component.

Parameters

supercell – supercell modifier

template<typename T, typename ...Args>
inline void createSuperCell(const Args&... args)

Create a new supercell and add it to the layer.

Template Parameters

  • T – type of component

  • Args – type of the arguments of the constructor

Parameters

args – arguments to construct the component

interfaces::SuperCell &getSuperCell()

Get the supercell component, if present.

If the component is not present, an exception will be raised.

Returns

the requested component

const interfaces::SuperCell &getSuperCell() const

Get the supercell component, if present.

If the component is not present, an exception will be raised.

Returns

the requested component

event process(uint64_t t, uint16_t x, uint16_t y, uint16_t p, bool skip_check = false)

Process an event and return a new one.

Parameters

  • t – time of the event

  • x – horizontal coordinate of the event

  • y – vertical coordinate of the event

  • p – polarity of the event

  • skip_check – if true consider the event as valid

Returns

the emitted event, possibly invalid

inline event process(const event &ev, bool skip_check = false)

Process an event and return a new one.

Parameters

  • ev – the event

  • skip_check – if true consider the event as valid

Returns

the emitted event, possibly invalid

bool canCluster() const

Chech if the layer can cluster time surfaces.

Returns

true if the layer has a clusterer

Returns

false otherwise

inline virtual void update(uint64_t t, uint16_t x, uint16_t y, uint16_t p) override

Update the time context with a new event.

Parameters

  • t – time of the event

  • x – horizontal coordinate of the event

  • y – vertical coordinate of the event

  • p – polarity of the event

inline virtual void update(const event &ev) override

Update the time context with a new event.

Parameters

ev – the new event

inline virtual std::pair<TimeSurfaceType, bool> compute(uint64_t t, uint16_t x, uint16_t y, uint16_t p) const override

Compute the time surface for an event.

This function does not update the time context.

A time surface is considered valid if there is a certain number of relevant events, determined using an heuristic extended from the one described in the paper.

Parameters

  • t – time of the event

  • x – horizontal coordinate of the event

  • y – vertical coordinate of the event

  • p – polarity of the event

Returns

a std::pair with the computed time surface and whether the surface is valid or not

inline virtual std::pair<TimeSurfaceType, bool> compute(const event &ev) const override

Compute the time surface for an event.

This function does not update the time context.

A time surface is considered valid if there is a certain number of relevant events, determined using an heuristic extended from the on described in the paper.

Parameters

ev – the event

Returns

a std::pair with the computed time surface and whether the surface is valid or not

inline virtual std::pair<TimeSurfaceType, bool> updateAndCompute(uint64_t t, uint16_t x, uint16_t y, uint16_t p) override

Update the time context and compute the new surface.

Parameters

  • t – time of the event

  • x – horizontal coordinate of the event

  • y – vertical coordinate of the event

  • p – polarity of the event

Returns

a std::pair with the computed time surface and whether the surface is valid or not

inline virtual std::pair<TimeSurfaceType, bool> updateAndCompute(const event &ev) override

Update the time context and compute the new surface.

Parameters

ev – the event

Returns

a std::pair with the computed time surface and whether the surface is valid or not

inline virtual std::pair<uint16_t, uint16_t> getSize() const override

Returns the size of the context.

Returns

{width, height}

inline virtual TimeSurfacePtr &getSurface(size_t idx) override

Access a time surface with boundaries check.

This method will throw an invalid_argument exception if the index of the surfaces exceeds the number of actual time surfaces.

Parameters

idx – index of the time surface

Returns

reference to the time surface

inline virtual const TimeSurfacePtr &getSurface(size_t idx) const override

Access a time surface with boundaries check.

This method will throw an invalid_argument exception if the index of the surfaces exceeds the number of actual time surfaces.

Parameters

idx – index of the time surface

Returns

reference to the time surface

inline virtual std::vector<TimeSurfaceType> sampleContexts(uint64_t t) const override

Sample and decay all temporal contexts from the pool.

This functions applies the decay to the all temporal contexts and returns them.

Parameters

t – sample time

Returns

vector of decayed temporal contexts

inline virtual size_t getNumSurfaces() const override

Get the number of surfaces in the pool.

Returns

number of surfaces

inline virtual uint16_t cluster(const TimeSurfaceType &surface) override

Performs clustering.

In case of online clustering algorithms, also updates the clusters, if learning is enabled.

Parameters

surface – the timesurface to cluster

Returns

id of the cluster

inline virtual uint16_t getNumClusters() const override

Get the number of clusters.

Returns

the number of clusters

inline virtual void addCentroid(const TimeSurfaceType &centroid) override

Add a new centroid to the clusterer.

This function should not be used manually, seeding should be done via a ClustererSeeding function.

If the Clusterer already has enough centroids, an exception is raised.

Parameters

centroid – the centroid to add

inline virtual const std::vector<TimeSurfaceType> &getCentroids() const override

Get the list of centroids.

Returns

the list of centroids

inline virtual void clearCentroids() override

Remove all centroids.

inline virtual bool hasCentroids() const override

Check if clusterer has enough centroids.

A clusterer has centroids if there is a number of centroids equal to the number of clusters.

Returns

true if clusterer has centroids

Returns

false otherwise

inline virtual bool isOnline() const override

Check if clusterer can perform online cluster updates or not.

Returns

true if it can

Returns

false otherwise

inline virtual bool toggleLearning(bool enable = true) override

Enable or disable learning.

This affects whether the centroids are updated when Clusterer::cluster is called or not.

During the learning phase, output of Clusterer::cluster may be undefined, depending on the implementaton.

Parameters

enable – true if learning should be active, false otherwise

Returns

the previous learning state

inline virtual void train(const std::vector<TimeSurfaceType> &tss)

Fit a set of time surfaces.

Udpate the centroids by clustering the set of time surfaces.

Parameters

tss – set of time surfaces

inline virtual std::vector<uint32_t> getHistogram() const override

Get the histogram of centroids activations.

Returns

the histogram of activations

virtual void reset() override

Reset the layer.

Resets both the time surfaces pool and the clusterer.

virtual void toStream(std::ostream &out) const override

Insert to stream.

Calls toStream on the components that support it.

Parameters

out – stream where to insert to

virtual void fromStream(std::istream &in) override

Extract from stream.

Parameters/current state is expected to be overwritten or invalidated.

Calls fromStream on the components that support it.

Parameters

in – stream where to extract from

virtual Layer *clone() const override

Clone the object.

Returns

pointer to the new object