-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Tomas Lycken
committed
Sep 9, 2016
1 parent
db4a69c
commit b8ac7e7
Showing
5 changed files
with
90 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,7 +1,5 @@ | ||
# QuickHull | ||
|
||
[![Build Status](https://travis-ci.org/tlycken/QuickHull.jl.svg?branch=master)](https://travis-ci.org/tlycken/QuickHull.jl) | ||
|
||
[![Coverage Status](https://coveralls.io/repos/tlycken/QuickHull.jl/badge.svg?branch=master&service=github)](https://coveralls.io/github/tlycken/QuickHull.jl?branch=master) | ||
|
||
[![codecov.io](http://codecov.io/github/tlycken/QuickHull.jl/coverage.svg?branch=master)](http://codecov.io/github/tlycken/QuickHull.jl?branch=master) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
using Documenter | ||
|
||
makedocs() |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,37 @@ | ||
# The QuickHull package | ||
|
||
QuickHull is a naïve implementation of the [QuickHull][wiki] algorithm for | ||
calculating the convex hull of a set of points in 2D. | ||
|
||
![foo](figures/sample-25.png) | ||
|
||
## Usage | ||
|
||
The algorithm works with `Vec{2}`s from [FixedSizeArrays][fsa], so you can pass | ||
a vector of such points directly to the algorithm: | ||
|
||
```@example | ||
using FixedSizeArrays | ||
points = map(Vec, rand(25), rand(25)) | ||
using QuickHull | ||
hull = qhull(points) | ||
``` | ||
|
||
The points are returned in order, starting with the leftmost point and moving | ||
counter-clockwise around convex hull. | ||
|
||
You can also just pass two arrays of equal length containing the ``x`` | ||
and ``y`` values of your points, and `qhull` will figure it out: | ||
|
||
```@example | ||
xs, ys = rand(25), rand(25) | ||
using QuickHull | ||
xhull, yhull = qhull(xs, ys) | ||
``` | ||
|
||
As you notice, the format of the return values matches that of the input. | ||
|
||
[wiki]: https://en.wikipedia.org/wiki/Quickhull | ||
[fsa]: https://github.com/SimonDanisch/FixedSizeArrays.jl |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
# Performance | ||
|
||
The current implementation is not optimized at all, but still performs quite | ||
well on small enough data sets. | ||
|
||
Using [`BenchmarkTools`][bmt] we can find out just how well: | ||
|
||
```julia | ||
julia> using BenchmarkTools, QuickHull | ||
|
||
julia> points = map(Vec, rand(25), rand(25)); | ||
|
||
julia> @benchmark qhull(points) | ||
BenchmarkTools.Trial: | ||
samples: 10000 | ||
evals/sample: 9 | ||
time tolerance: 5.00% | ||
memory tolerance: 1.00% | ||
memory estimate: 5.61 kb | ||
allocs estimate: 66 | ||
minimum time: 2.15 μs (0.00% GC) | ||
median time: 2.47 μs (0.00% GC) | ||
mean time: 3.86 μs (31.64% GC) | ||
maximum time: 638.79 μs (98.87% GC) | ||
``` | ||
|
||
The data set here is quite small, but it needs to be for the hull to have a | ||
shape that is more interesting than the square ``[1,2]^2``. We can increase | ||
the data set size to convince ourselves that the library still performs quite | ||
well. To avoid different runs interfering with each-other, we run `gc()` before | ||
each time: | ||
|
||
```julia | ||
julia> points2 = map(Vec, rand(1_000_000), rand(1_000_000)); | ||
|
||
julia> gc(); @time qhull(points2); | ||
0.053300 seconds (407 allocations: 59.894 MB, 4.72% gc time) | ||
|
||
julia> gc(); @time qhull(points2); | ||
0.054250 seconds (407 allocations: 59.894 MB, 4.64% gc time) | ||
``` | ||
|
||
However, these tests are also pretty naïve - for example, the points are all | ||
constrained to a small region with a simple shape, and so fit the algorithm | ||
extremely well. | ||
|
||
If you have a use case where this library does not peform well enough, please do | ||
file an issue, and we can try to optimize it together. | ||
|
||
[bmt]: https://github.com/JuliaCI/BenchmarkTools.jl |