view release on metacpan or  search on metacpan

lib/Algorithm/KNN/XS.pm  view on Meta::CPAN

=over 4

=item * $knn->set_annMaxPtsVisit( ... )

This class method sets the maximum number of points that the search methods
are going to process before they abort. They can return more points than the
set value because the abort condition is only checked before processing a
leaf node.

    $knn->set_annMaxPtsVisit(
        max_points => 5,
    );

=over 8

=item * max_points

Must be 0 or greater. The value 0 means no limit.

The default value is 0.

=back

=back

=cut

sub set_annMaxPtsVisit {
    my ($self, %args) = @_;

    return $self->tree->set_annMaxPtsVisit($args{max_points} || 0);
}

=over 4

=item * $knn->annkSearch( ... )

This class method performs a k nearest neighbor search.

    my %result = $knn->annkSearch(
        query_point      => [],
        limit_neighbors => 0,
        epsilon          => 0,
    );

=over 8

=item * query_point

A list of points which must be the same dimension as the tree.

=item * limit_neighbors

Determines how many neighbors should be returned. The value 0 means no limit.

The default value is 0.

=item * epsilon

The relative error bound for approximate nearest neighbor searching. Please
refer the libANN manual for more information.

The default value is 0.

=item * Return value

Following structure is returned:

    my $result = [
        # 'distance' is the squared distance to the given query point
        # (the query point found itself in this case)
        {
            'distance' => '0',
            'point' => [
                '1.1345', 
                '2.657'
            ]
        }, {
            'distance' => '15.00963986',
            'point' => [
                '4.023',
                '5.2389'
            ]
        }
    ];

=back

=back

=cut

sub annkSearch {
    my ($self, %args) = @_;

    return $self->_restructure_return_value(
        $self->tree->annkSearch($args{query_point}, $args{limit_neighbors} || 0, $args{epsilon} || 0)
    );
}

=over 4

=item * $knn->annkPriSearch( ... )

This class method performs a k nearest neighbor priority search as described
by Arya and Mount, please refer the libANN manual for further information.

    my %result = $knn->annkPriSearch(
        query_point      => [],
        limit_neighbors => 0,
        epsilon          => 0,
    );

=over 8

=item * query_point

A list of points which must be the same dimension as the tree.

=item * limit_neighbors

Determines how many neighbors should be returned. The value 0 means no limit.

The default value is 0.

=item * epsilon

The relative error bound for approximate nearest neighbor searching. Please
refer the libANN manual for more information.

The default value is 0.

=item * Return value

Following structure is returned:

    my $result = [
        # 'distance' is the squared distance to the given query point
        # (the query point found itself in this case)
        {
            'distance' => '0',
            'point' => [
                '1.1345', 
                '2.657'
            ]
        }, {
            'distance' => '15.00963986',
            'point' => [
                '4.023',
                '5.2389'
            ]
        }
    ];

=back

=back

=cut

sub annkPriSearch {
    my ($self, %args) = @_;

    return $self->_restructure_return_value(
        $self->tree->annkPriSearch($args{query_point}, $args{limit_neighbors} || 0, $args{epsilon} || 0)
    );
}

=over 4

=item * $knn->annkFRSearch( ... )

This class method performs a fixed radius k nearest neighbor search.

    my %result = $knn->annkFRSearch(
        query_point      => [],
        limit_neighbors => 0,
        epsilon          => 0,
        radius           => 10,
    );

=over 8

=item * query_point

A list of points which must be the same dimension as the tree.

=item * limit_neighbors

Determines how many neighbors should be returned. The value 0 means no limit.

The default value is 0.

=item * epsilon

The relative error bound for approximate nearest neighbor searching. Please
refer the libANN manual for more information.

The default value is 0.

=item * radius

The radius in which the search should take place.

Defaults to 0.

=item * Return value

Following Structure is returned:

Following structure is returned:

    my $result = [
        # 'distance' is the squared distance to the given query point
        # (the query point found itself in this case)
        {
            'distance' => '0',
            'point' => [
                '1.1345', 
                '2.657'
            ]
        }, {
            'distance' => '15.00963986',
            'point' => [
                '4.023',
                '5.2389'
            ]
        }
    ];

=back

=back

=cut

sub annkFRSearch {
    my ($self, %args) = @_;

    return $self->_restructure_return_value(
        $self->tree->annkFRSearch($args{query_point}, $args{limit_neighbors} || 0, $args{epsilon} || 0, $args{radius} || 0)
    );
}

=over 4

=item * $knn->annCntNeighbours( ... )

This class method performs a fixed radius k nearest neighbor search and
returns the number of neighbors.

    my $neighbors = $knn->annCntNeighbours(
        query_point      => [],
        epsilon          => 0,
        radius           => 10,
    );

=over 8

=item * query_point

A list of points which must be the same dimension as the tree.

=item * epsilon

The relative error bound for approximate nearest neighbor searching. Please
refer the libANN manual for more information.

The default value is 0.

=item * radius

The radius in which the search should take place.

The default value is 0.

=item * Return value

Number of found neighbors.

=back

=back

=cut

sub annCntNeighbours {
    my ($self, %args) = @_;

    return $self->tree->annCntNeighbours($args{query_point}, $args{epsilon} || 0, $args{radius} || 0);
}

=over 4

=item * $knn->theDim()

Returns the dimension that the points in the current tree have.

    my $dimension = $knn->theDim();

=over 8

=item * Return value

Dimension of the tree points.

=back

=back

=cut

sub theDim {
    return shift->tree->theDim();
}

=over 4

=item * $knn->nPoints()

Returns the number of points in the current tree.

    my $n_points = $knn->nPoints();

=over 8