Add full scene example to user vignette

[wjones127]

The current user guide describes the individual functions, but doesn't provide a complete example of a script. A few related thoughts on how a complete example could help:

• It took a minute to read the fine print about needing to set_active_scene(). Helpful to show that as part of the example script so it's obvious I need to include that.
• The coordinate system with x and z as horizontal and y as vertical wasn't obvious at first. Might be worth describing that in user guide.
• There's also a question of unit size; by default should units be considered meters? If other packages are providing assets, it might be helpful if they are scaled in some standard way.
• add_default_tree() seems like it can take vectors for position and other arguments (great!), though I didn't find that obvious from docs since most example show a scalar provided there.

Here is an example scene I put together while testing the package:

library(unifir)
library(terra)

num_trees <- 100
pos <- data.frame(
  x = runif(num_trees, -40, 40),
  z = runif(num_trees, -40, 40)
)

plot(pos$x, pos$z)

project_path <- file.path("projects", "random-trees")
# heightmap_path <- normalizePath(file.path(project_path, "Assets", "heightmap.tiff"))
# terra::writeRaster(heightmap, heightmap_path, overwrite = TRUE)

tree_script <- make_script(project = project_path) |>
  add_light(light_type = "Directional", light_name = "Sun",
            x_rotation = 35, y_rotation = 20) |>
  add_default_player()
# Does seem to have a user-facing way to create a ground, so player will always fall


raster <- tempfile(fileext = ".tiff")
r <- terra::rast(matrix(rnorm(1000^2, mean = 100, sd = 20), 1000),
                 extent = terra::ext(0, 1000, 0, 1000)
)
terra::writeRaster(r, raster)
tree_script <- create_terrain(
  tree_script,
  heightmap_path = raster,
  x_pos = -125,
  z_pos = -125,
  width = 1000,
  height = 0.1,
  length = 1000,
  heightmap_resolution = 1000
)

tree_script <- add_default_tree(
  tree_script,
  "tree_1",
  x_position = pos$x,
  z_position = pos$z,
  x_rotation = -90 # should we make this default?
)

tree_script <- tree_script |>
  save_scene(scene_name = "trees") |>
  set_active_scene(scene_name = "trees")

action(tree_script)

[mikemahoney218]

Much appreciated and fully agreed, will do

[mikemahoney218]

Two comments on things brought up here:

1. The supported way to get the player controller on the ground would be to have a point (in the raster's CRS) where you want the player to be, use terra::extract to get the elevation at that point, and then associate_coordinates to place the player in the scene; I'm attempting to keep unifir as not-spatial as possible so it's a "lighter" installation (hence terra and sf in Suggests) and easier to incorporate into other packages
2. Fixed the tree rotation thing, that was silly on my end (1e2b056) (and is related to the coordinate system thing -- most 3D modeling programs use a different coordinate system, so their models aren't properly rotated for Unity https://www.techarthub.com/a-guide-to-unitys-coordinate-system-with-practical-examples/ )

Otherwise, I've added a lot to the user vignette in bb1c218 .

[github-actions]

This issue has been automatically locked. If you believe you have found a related problem, please file a new issue (with a reprex: https://reprex.tidyverse.org) and link to this issue.