diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b0b8336..fc196c8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -123,6 +123,53 @@ You can either specify it in the YAML header (`image: image.webp`) or add `{.pre ![Slope map](slope.webp){.preview-image} ``` +## References + +To cite references, +you should create a bibtex file with bibliographic entries, +reference the bibliography and citation style in your tutorial's frontmatter, + +and then add inline citations in Markdown format in the body of the text. +A list of works cited will be automatically generated at the end of your tutorial. +Please use the acm.csl citation style that is in the root of the project. + +Save a bibtex file in your tutorial directory: + +```bibtex +@software{GRASS:2025, +title = {{GRASS}}, +author = {{GRASS Development Team}}, +organization = {Open Source Geospatial Foundation}, +doi = {10.5281/zenodo.5176030}, +license = {GPL-2.0-or-later}, +month = {11}, +url = {https://github.com/OSGeo/grass}, +version = {8.4.2}, +year = {2025} +} +``` + +Reference your bibtex file +and the project's citation style language file +in your tutorial's YAML frontmatter: + +```yaml +bibliography: tutorial.bib +csl: ../../../acm.csl +``` + +In your tutorial, +add citations in Markdown with `[@citation]`. +This will create an inline citation +and automatically generate +a list of works cited +in a reference section +at the end of the tutorial. + +```markdown +[@GRASS:2025] +``` + ## External tutorials If you want to have your GRASS external tutorials listed, you can create a `.yml` file @@ -165,7 +212,7 @@ Check your markdown with a [linter](https://dlaa.me/markdownlint/) and fix as ma Follow the [GitHub guide](https://grass.osgeo.org/grass-devel/manuals/github_guide.html) (adapt it to this repo) to submit your tutorial. You should **only commit the .qmd file and images**. -Once you sumbmit a PR, the CI pipeline will build your +Once you submit a PR, the CI pipeline will build your tutorial, so you and a reviewer can check if everything is ok. When a reviewer approves, your PR will be merged soon. diff --git a/content/tutorials/noise/acm.csl b/acm.csl similarity index 100% rename from content/tutorials/noise/acm.csl rename to acm.csl diff --git a/content/tutorials/earthworks/basics.qmd b/content/tutorials/earthworks/basics.qmd index 3248365..f325e28 100644 --- a/content/tutorials/earthworks/basics.qmd +++ b/content/tutorials/earthworks/basics.qmd @@ -6,6 +6,8 @@ date-modified: today categories: [earthworks, terrain, raster, beginner] description: Learn the basics of terrain modeling with r.earthworks. image: images/basics_05.webp +bibliography: earthworks.bib +csl: ../../../acm.csl links: r_earthworks: "[r.earthworks](https://grass.osgeo.org/grass-stable/manuals/addons/r.earthworks.html)" wxgui_rdigit: "[raster digitizer](https://grass.osgeo.org/grass-stable/manuals/wxGUI.rdigit.html)" @@ -37,7 +39,8 @@ jupyter: python3 ![Random earthworks](images/basics_05.webp) Learn the basics of terrain modeling with -{{< meta links.r_earthworks >}}. +{{< meta links.r_earthworks >}} +[@Harmon:2026]. This tool uses cut and fill operations to transform topography. Cut operations subtract from a topographic surface, while fill operations add to the topography. diff --git a/content/tutorials/earthworks/earthworks.bib b/content/tutorials/earthworks/earthworks.bib new file mode 100644 index 0000000..8f04f18 --- /dev/null +++ b/content/tutorials/earthworks/earthworks.bib @@ -0,0 +1,66 @@ +@article{Gain:2015, +author = {Gain, J. and Merry, B. and Marais, P.}, +title = {Parallel, Realistic and Controllable Terrain Synthesis}, +journal = {Computer Graphics Forum}, +volume = {34}, +number = {2}, +pages = {105-116}, +doi = {https://doi.org/10.1111/cgf.12545}, +year = {2015} +} + +@article{Harmon:2019, +author = {Harmon, Brendan and Mitasova, Helena and Petrasova, Anna and Petras, Vaclav}, +doi = {10.5194/gmd-12-2837-2019}, +journal = {Geoscientific Model Development}, +number = {7}, +pages = {2837--2854}, +title = {{r.sim.terrain 1.0:} a landscape evolution model with dynamic hydrology}, +volume = {12}, +year = {2019} +} + +@article{Harmon:2026, +doi = {10.21105/joss.09270}, +url = {https://doi.org/10.21105/joss.09270}, +year = {2026}, +publisher = {The Open Journal}, +volume = {11}, +number = {118}, +pages = {9270}, +author = {Harmon, Brendan and Petrasova, Anna and Petras, Vaclav}, +title = {{r.earthworks:} a {GRASS} tool for terrain modeling}, +journal = {Journal of Open Source Software}, +keywords = {peer_reviewed} +} + +@dataset{Harmon:2025, +author = {Harmon, Brendan}, +title = {Bayou L'Ours Dataset for GRASS}, +year = 2025, +publisher = {Zenodo}, +version = {1.0.0}, +doi = {10.5281/zenodo.15870441} +} + +@article{Tasse:2012, +author = {Tasse, F. P. and Gain, J. and Marais, P.}, +title = {Enhanced Texture-Based Terrain Synthesis on Graphics Hardware}, +journal = {Computer Graphics Forum}, +volume = {31}, +number = {6}, +pages = {1959-1972}, +doi = {https://doi.org/10.1111/j.1467-8659.2012.03076.x}, +year = {2012} +} + +@article{Zhou:2007, +author={Zhou, Howard and Sun, Jie and Turk, Greg and Rehg, James M.}, +journal={IEEE Transactions on Visualization and Computer Graphics}, +title={Terrain Synthesis from Digital Elevation Models}, +year={2007}, +volume={13}, +number={4}, +pages={834-848}, +doi={10.1109/TVCG.2007.1027} +} \ No newline at end of file diff --git a/content/tutorials/earthworks/earthworks.qmd b/content/tutorials/earthworks/earthworks.qmd index f79303d..c53619a 100644 --- a/content/tutorials/earthworks/earthworks.qmd +++ b/content/tutorials/earthworks/earthworks.qmd @@ -4,6 +4,8 @@ author: "Brendan Harmon" date: 2025-07-07 date-modified: today image: images/earthworks_01.webp +bibliography: earthworks.bib +csl: ../../../acm.csl links: r_earthworks: "[r.earthworks](https://grass.osgeo.org/grass-stable/manuals/addons/r.earthworks.html)" g_extension: "[g.extension](https://grass.osgeo.org/grass-stable/manuals/g.extension.html)" @@ -22,7 +24,7 @@ execute: ![Random fill operation with r.earthworks](images/earthworks_01.webp) -Learn how model terrain with {{< meta links.r_earthworks >}}. With this tool you can generate new terrain or modify existing terrain using cut and fill operations inspired by earthworking. The first tutorial on the basics of terrain modeling introduces key concepts such as cut and fill operations. The subsequent tutorials introduce more advanced concepts such as relative operations and growth and decay functions. These tutorials demonstrate how to generate terrain, model natural landforms, and model anthropogenic landforms - i.e. earthworks - such as roads, dams, and levees. Read our [paper](https://raw.githubusercontent.com/baharmon/r.earthworks/main/paper/paper.pdf) to learn more. +Learn how model terrain with {{< meta links.r_earthworks >}}. With this tool you can generate new terrain or modify existing terrain using cut and fill operations inspired by earthworking. The first tutorial on the basics of terrain modeling introduces key concepts such as cut and fill operations. The subsequent tutorials introduce more advanced concepts such as relative operations and growth and decay functions. These tutorials demonstrate how to generate terrain, model natural landforms, and model anthropogenic landforms - i.e. earthworks - such as roads, dams, and levees. Read our [paper](https://doi.org/10.21105/joss.09270) to learn more [@Harmon:2026]. ## Installation diff --git a/content/tutorials/earthworks/gullies.qmd b/content/tutorials/earthworks/gullies.qmd index 22387eb..73c55c4 100644 --- a/content/tutorials/earthworks/gullies.qmd +++ b/content/tutorials/earthworks/gullies.qmd @@ -6,6 +6,8 @@ date-modified: today categories: [earthworks, terrain, raster, beginner] description: Model gullies using relative cut operations with r.earthworks. image: images/gullies_03.webp +bibliography: earthworks.bib +csl: ../../../acm.csl links: r_earthworks: "[r.earthworks](https://grass.osgeo.org/grass-stable/manuals/addons/r.earthworks.html)" r_sim_terrain: "[r.sim.terrain](https://grass.osgeo.org/grass-stable/manuals/addons/r.sim.terrain.html)" @@ -38,7 +40,8 @@ jupyter: python3 Learn the how to model gullies using relative cut operations with -{{< meta links.r_earthworks >}}. +{{< meta links.r_earthworks >}} +[@Harmon:2026]. This tutorial introduces more features of {{< meta links.r_earthworks >}} including vector line input, @@ -74,7 +77,7 @@ This tutorial covers: For a simulation based approach to modeling gullies, try the landscape evolution model -{{< meta links.r_sim_terrain >}} instead. +{{< meta links.r_sim_terrain >}} [@Harmon:2019] instead. ::: {.callout-note title="Computational notebook"} This tutorial can be run as a diff --git a/content/tutorials/earthworks/levees.qmd b/content/tutorials/earthworks/levees.qmd index 961e6a5..069fbc4 100644 --- a/content/tutorials/earthworks/levees.qmd +++ b/content/tutorials/earthworks/levees.qmd @@ -6,6 +6,8 @@ date-modified: today categories: [earthworks, terrain, coast, raster, beginner] description: Model levees and alluvial ridges with r.earthworks. image: images/levees_08.webp +bibliography: earthworks.bib +csl: ../../../acm.csl links: r_earthworks: "[r.earthworks](https://grass.osgeo.org/grass-stable/manuals/addons/r.earthworks.html)" g_extension: "[g.extension](https://grass.osgeo.org/grass-stable/manuals/g.extension.html)" @@ -36,8 +38,10 @@ jupyter: python3 ![Levee improvement & ridge restoration](images/levees_08.webp) Learn the how to model levees and ridges with -{{< meta links.r_earthworks >}}. -Download the [Bayou L'Ours Dataset](https://doi.org/10.5281/zenodo.15870441). +{{< meta links.r_earthworks >}} +[@Harmon:2026]. +Download the [Bayou L'Ours Dataset](https://doi.org/10.5281/zenodo.15870441) +[@Harmon:2025]. The coordinate reference system for this project is Louisiana State Plane South in meters. We will model two of the coastal infrastructure projects @@ -540,7 +544,7 @@ and `flat` to 10. The radius of flats should be set to the region resolution to ensure that the gaps are fully closed -because we test our design with a flood simulation. +because we will test our design with a flood simulation. To better visualize the results, use {{< meta links.r_relief >}} and {{< meta links.d_shade >}} @@ -602,7 +606,7 @@ m.save("images/levees_08.webp") # Flood Simulation -Test proposed coastal infrastructure with simulated storm surge. +Test the proposed coastal infrastructure with simulated storm surge. Use {{< meta links.r_lake >}} to model inundation from storm surge over the earthworks raster. Set the water level to one meter and the coordinates to `1109000, 102750`. diff --git a/content/tutorials/earthworks/synthesis.qmd b/content/tutorials/earthworks/synthesis.qmd index 8d8d282..8fb1fd5 100644 --- a/content/tutorials/earthworks/synthesis.qmd +++ b/content/tutorials/earthworks/synthesis.qmd @@ -6,6 +6,8 @@ date-modified: today categories: [earthworks, terrain, raster, intermediate] description: Learn how to synthesize terrain with r.earthworks. image: images/synthesis_07.webp +bibliography: earthworks.bib +csl: ../../../acm.csl links: g_extension: "[g.extension](https://grass.osgeo.org/grass-stable/manuals/g.extension.html)" r_earthworks: "[r.earthworks](https://grass.osgeo.org/grass-stable/manuals/addons/r.earthworks.html)" @@ -37,15 +39,14 @@ jupyter: python3 ![Volumetric change during terrain synthesis](images/synthesis_07.webp) Learn how to synthesize terrain with -{{< meta links.r_earthworks >}}. +{{< meta links.r_earthworks >}} +[@Harmon:2026]. In terrain synthesis, landforms from one terrain are applied to another, creating a hybrid landscape. This technique is used in computer graphics to model landscapes that are challenging to create with procedural noise and erosion simulations -([Zhou et al. 2007](https://doi.org/10.1109/TVCG.2007.1027), -[Tasse et al. 2012](https://doi.org/10.1111/j.1467-8659.2012.03076.x), -[Gain et al. 2015](https://doi.org/10.1111/cgf.12545)). +[@Zhou:2007; @Tasse:2012; @Gain:2015]. Landforms that are hard to model, for example, can be sampled from real terrain and grafted onto synthetic terrain. diff --git a/content/tutorials/noise/noise.qmd b/content/tutorials/noise/noise.qmd index 156e09d..805510e 100644 --- a/content/tutorials/noise/noise.qmd +++ b/content/tutorials/noise/noise.qmd @@ -5,9 +5,9 @@ date: 2025-07-18 date-modified: today categories: [noise, terrain, raster, map algebra, python, intermediate] description: Learn how to generate procedural noise using Python scripting in GRASS. -image: images/noise_01.webp +image: images/noise_05.webp bibliography: noise.bib -csl: acm.csl +csl: ../../../acm.csl links: notebooks: "[Get started with GRASS & Python in Jupyter Notebooks](https://grass-tutorials.osgeo.org/content/tutorials/get_started/fast_track_grass_and_python.html)" g_region: "[g.region](https://grass.osgeo.org/grass-stable/manuals/g.region.html)"