Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add citation bibliography #596

Merged
merged 19 commits into from
Oct 7, 2024
Merged
Show file tree
Hide file tree
Changes from 17 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
PointNeighbors = "1c4d5385-0a27-49de-8e2c-43b175c8985c"
TrixiBase = "9a0f1c46-06d5-4909-a5a3-ce25d3fa3284"

[compat]
Documenter = "1"
DocumenterCitations = "1"
OrdinaryDiffEq = "6"
PointNeighbors = "0.4"
TrixiBase = "0.1"
6 changes: 5 additions & 1 deletion docs/make.jl
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
using Documenter
using Documenter, DocumenterCitations
using TrixiParticles
using TrixiBase
using PointNeighbors
Expand Down Expand Up @@ -90,7 +90,10 @@ copy_file("NEWS.md")
# Define module-wide setups such that the respective modules are available in doctests
DocMeta.setdocmeta!(TrixiParticles, :DocTestSetup, :(using TrixiParticles); recursive=true)

bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"))

makedocs(sitename="TrixiParticles.jl",
plugins=[bib],
# Run doctests and check docs for the following modules
modules=[TrixiParticles],
format=Documenter.HTML(),
Expand Down Expand Up @@ -139,6 +142,7 @@ makedocs(sitename="TrixiParticles.jl",
"Contributing" => "contributing.md",
"Code of Conduct" => "code_of_conduct.md",
"License" => "license.md",
"References" => "references.md",
])

deploydocs(repo="github.com/trixi-framework/TrixiParticles.jl",
Expand Down
20 changes: 6 additions & 14 deletions docs/src/preprocessing/preprocessing.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,12 @@ Here, ``\Theta_i`` is the *signed* angle between ``\mathbf{c}_i - \mathbf{p}`` a
In 3D, we refer to the solid angle of an *oriented* triangle with respect to ``\mathbf{p}``.

We provide the following methods to calculate ``w(\mathbf{p})``:
- Hormann et al. (2001) evaluate the winding number combined with an even-odd rule, but only for 2D polygons (see [WindingNumberHormann](@ref)).
- Naive winding: Jacobson et al. (2013) generalized the winding number so that the algorithm can be applied for both 2D and 3D geometries (see [WindingNumberJacobson](@ref)).
- Hierarchical winding: Jacobson et al. (2013) also introduced a fast hierarchical evaluation of the winding number. For further information see the description below.
- [Hormann et al. (2001)](@cite Hormann2001) evaluate the winding number combined with an even-odd rule, but only for 2D polygons (see [WindingNumberHormann](@ref)).
- Naive winding: [Jacobson et al. (2013)](@cite Jacobson2013) generalized the winding number so that the algorithm can be applied for both 2D and 3D geometries (see [WindingNumberJacobson](@ref)).
- Hierarchical winding: [Jacobson et al. (2013)](@cite Jacobson2013) also introduced a fast hierarchical evaluation of the winding number. For further information see the description below.

## [Hierarchical Winding](@id hierarchical_winding)
According to Jacobson et al. (2013) the winding number with respect to a polygon (2D) or triangle mesh (3D) is the sum of the winding numbers with respect to each edge (2D) or face (3D).
According to [Jacobson et al. (2013)](@cite Jacobson2013) the winding number with respect to a polygon (2D) or triangle mesh (3D) is the sum of the winding numbers with respect to each edge (2D) or face (3D).
We can show this with the following example in which we determine the winding number for each edge of a triangle separately and sum them up:

```julia
Expand Down Expand Up @@ -164,7 +164,7 @@ Splitting stops when the number of a box's edges slips below a
threshold (usually ``\approx 100`` faces in 3D, here: 6 edges).

(3):
For the closure, Jacobson et al. (2013) define *exterior vertices* (*exterior edges* in 3D)
For the closure, [Jacobson et al. (2013)](@cite Jacobson2013) define *exterior vertices* (*exterior edges* in 3D)
as boundary vertices of such a segmentation (red dots in (3)).
To find them, we traverse around each edge (face in 3D) in order, and
increment or decrement for each vertex (edge) a specific counter.
Expand Down Expand Up @@ -210,7 +210,7 @@ This is because the property ``w_{\mathcal{S}}(\mathbf{p}) = - w_{\bar{\mathcal{
only holds when ``\mathbf{p}`` is outside of ``\mathcal{B}``, which is not the case here.

#### Correct evaluation
Jacobson et al. (2013) don't mention this problem or provide a solution to it.
[Jacobson et al. (2013)](@cite Jacobson2013) don't mention this problem or provide a solution to it.
We contacted the authors and found that they know about this problem and solve it
by resizing the bounding box to fully include the closing surface
of the neighboring box, since it doesn't matter if the boxes overlap.
Expand Down Expand Up @@ -255,11 +255,3 @@ Pages = [joinpath("preprocessing", "point_in_poly", "winding_number_jacobson.jl"
Modules = [TrixiParticles]
Pages = [joinpath("preprocessing", "geometries", "io.jl")]
```

### [References](@id references_complex_shape)
- Alec Jacobson, Ladislav Kavan, and Olga Sorkine-Hornung "Robust inside-outside segmentation using generalized winding numbers".
In: ACM Transactions on Graphics, 32.4 (2013), pages 1--12.
[doi: 10.1145/2461912.2461916](https://igl.ethz.ch/projects/winding-number/robust-inside-outside-segmentation-using-generalized-winding-numbers-siggraph-2013-jacobson-et-al.pdf)
- Kai Hormann, Alexander Agathos "The point in polygon problem for arbitrary polygons".
In: Computational Geometry, 20.3 (2001), pages 131--144.
[doi: 10.1016/s0925-7721(01)00012-8](https://doi.org/10.1016/S0925-7721(01)00012-8)
2 changes: 2 additions & 0 deletions docs/src/references.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
```@bibliography
```
Loading
Loading