diff --git a/README.md b/README.md index d5dcf80..fc47e44 100644 --- a/README.md +++ b/README.md @@ -4,25 +4,25 @@ A library for differential collision detection between the following convex primitives: -- polytopes +- polytopes - capsules - cylinders - cones - spheres -- padded polygons +- padded polygons -For more details, see our paper on [arXiv](https://arxiv.org/abs/2207.00669). +For more details, see our paper on [arXiv](https://arxiv.org/abs/2207.00669). ## Interface -DCOL works by creating a struct for each shape, and calling a function to query a proximity value between them. -#### Primitives +DCOL works by creating a struct for each shape, and calling a function to query a proximity value between them. +#### Primitives Each primitive is implemented as a struct in DCOL. The defining dimensions for each primitive is described in the [paper](https://arxiv.org/abs/2207.00669), and the primitives can be constructed as the following: ```julia import DCOL as dc polytype = dc.Polytope(A, b) # polytope is described by Ax <= b -capsule = dc.Capsule(R, L) # radius R, length L -cylinder = dc.Cylinder(R, L) # radius R, length L +capsule = dc.Capsule(R, L) # radius R, length L +cylinder = dc.Cylinder(R, L) # radius R, length L cone = dc.Cone(H, β) # height H, half angle β sphere = dc.Sphere(R) # radius R polygon = dc.Polygon(A, b, R) # polygon is described by Ay <= b, cushion radius R @@ -42,14 +42,14 @@ P1.r = SA[1,2,3.0] # position in world frame W P1.p = SA[0.0,0,0] # MRP ᵂpᴮ ``` #### Proximity Functions -DCOL exposes a function `proximity` for collision detection, as well as `proximity_jacobian` for collision detection and derivatives. Two optional arguments are included that pertain to the optimization solver under the hood, `verbose` turns on logging for this solver, and `pdip_tol` is the termination criteria. +DCOL exposes a function `proximity` for collision detection, as well as `proximity_jacobian` for collision detection and derivatives. Two optional arguments are included that pertain to the optimization solver under the hood, `verbose` turns on logging for this solver, and `pdip_tol` is the termination criteria. ```julia α,x = dc.proximity(P1, P2; verbose = false, pdip_tol = 1e-6) α,x,J = dc.proximity_jacobian(P1, P2; verbose = false, pdip_tol = 1e-6) ``` These functions output $\alpha$ as the proximity value, with the following significance: -- $\alpha \leq 1$ means there **is** a collision between the two primitives -- $\alpha >1$ means there **is not** a collision between the two primitives +- $\alpha \leq 1$ means there **is** a collision between the two primitives +- $\alpha >1$ means there **is not** a collision between the two primitives Also, returned is `x` which is the intersection point between the scaled shapes (see algorithm for significance), and a Jacobian `J` which is the following: @@ -67,12 +67,12 @@ J &= \frac{\partial (x,\alpha) }{\partial (r_1,p_1,r_2,p_2)} \end{align*} $$ -## Visualizer +## Visualizer All of the primitives (both quaternion and MRP) can be visualized in [MeshCat](https://github.com/rdeits/MeshCat.jl). Below is an example of visualization for a cone: ```julia -import DCOL as dc -import Meshcat as mc +import DCOL as dc +import Meshcat as mc vis = mc.Visualizer() mc.open(vis) @@ -82,7 +82,7 @@ cone.r = @SVector randn(3) cone.q = normalize((@SVector randn(4))) # build primitive scaled by α = 1.0 -dc.build_primitive!(vis, cone, :cone; α = 1.0,color = mc.RGBA(1,0,0,0.0)) +dc.build_primitive!(vis, cone, :cone; α = 1.0,color = mc.RGBA(1,0,0,1.0)) # update position and attitude dc.update_pose!(vis[:cone],cone) @@ -94,7 +94,7 @@ DCOL calculates the collision information between two primitives by solving for - $\alpha \in \mathbb{R}$, the scaling applied to each primitive - $x \in \mathbb{R}^3$, an intersection point in the world frame -The following optimization problem solves for the minimum scaling α such that a point x exists in the scaled versions of two primitives P1 and P2. +The following optimization problem solves for the minimum scaling α such that a point x exists in the scaled versions of two primitives P1 and P2. $$ \begin{align*}