JuliaRobotics · Affie · Mar 2, 2024 · Feb 17, 2024 · Feb 18, 2024 · Feb 19, 2024
diff --git a/CITATION.bib b/CITATION.bib
@@ -1,7 +1,7 @@
-@online{Caesarjl2022,
- author =        {{C}ontributors, {E}cosystem, and {N}av{A}bility},
- title =         {Caesar.jl Solver, v0.13.5},
- year =          {2022Q4},
- doi=            {Solver DOI: 10.5281/zenodo.7498643}, 
+@online{Caesarjl2024,
+ author =        {{C}ontributors, {E}cosystem, and {N}av{A}bility(TM)},
+ title =         {Caesar.jl Solver, v0.16.2},
+ year =          {2024},
+ doi=            {Solver DOI: 10.5281/zenodo.5146221}, 
  note =          {\url{https://github.com/JuliaRobotics/Caesar.jl}}
 }
diff --git a/NEWS.md b/NEWS.md
@@ -10,6 +10,10 @@ Major changes and news in Caesar.jl.
 - Updates for IncrementalInference upgrades relating to StaticArray variable values.
 - Manifold updates to factors.
 - Downstreamed std ROS handlers to PyCaesar.
+- Fix `saveLAS` to use `Int32`.
+- Several compat updates for dependencies.
+- Restore Docs build, and update links for NavAbility at WhereWhen.ai Technologies Inc.
+- Introduce `FolderDict` as data structure for lower memory consumption, also as potential BlobStore.
 
 ## Changes in v0.13
 

diff --git a/README.md b/README.md
@@ -2,9 +2,9 @@
 <img src="https://user-images.githubusercontent.com/6412556/134777705-acda768e-884b-4de6-b307-aac6d09b9c81.png" width="240" border="0" />
 </p>
 
-A multimodal/non-Gaussian robotic toolkit for localization and mapping -- reducing the barrier of entry for sensor/data fusion tasks, including Simultaneous Localization and Mapping (SLAM).
+A multimodal/non-Gaussian robotic toolkit for localization and mapping -- reducing the barrier of entry for sensor/data fusion tasks, including Simultaneous Localization and Mapping (SLAM).  Focus areas are mapping, localization, calibration, synthesis, planning, and digital twins.
 
-[NavAbility.io](http://www.navability.io) is administrating and supporting the ongoing development of Caesar.jl with and to help grow the community, please reach out for any additional information at info@navability.io or via the Slack badge-link below.
+[NavAbility(TM) by WhereWhen.ai Technologies Inc.](https://www.wherewhen.ai) is administrating and supporting the ongoing development of Caesar.jl with and to help grow the community, please reach out for any additional information at info@wherewhen.ai or via the Slack badge-link below.
 
 # Weblink Info
 
@@ -53,8 +53,10 @@ This project adheres to the [JuliaRobotics code of conduct](https://github.com/J
 
 [![Stargazers over time](https://starchart.cc/JuliaRobotics/Caesar.jl.svg)](https://starchart.cc/JuliaRobotics/Caesar.jl)
 
-[doi-img]: https://zenodo.org/badge/55802838.svg
-[doi-url]: https://zenodo.org/badge/latestdoi/55802838
+[doi-img]: https://zenodo.org/badge/DOI/10.5281/zenodo.5146221.svg
+[doi-url]: https://doi.org/10.5281/zenodo.5146221
+
+5146221
 
 [colp-badge]: https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet
 [colprac]: https://github.com/SciML/ColPrac

diff --git a/docs/src/concepts/arena_visualizations.md b/docs/src/concepts/arena_visualizations.md
@@ -2,7 +2,62 @@
 
 ## Introduction
 
-Over time, Caesar.jl/Arena.jl has used at various different 3D visualization technologies.  Currently work is underway to better standardize within the Julia ecosystem, with the 4th generation of Arena.jl -- note that this is work in progress.  Information about legacy generations is included below.
+Over time, Caesar.jl/Arena.jl has used at various different 3D visualization technologies.  
+
+### Arena.jl Visualization
+
+#### [Plotting a PointCloud](@id viz_pointcloud)
+
+Visualization support for point clouds is available through Arena and Caesar.  The follow example shows some of the basics:
+
+```julia
+using Arena
+using Caesar
+using Downloads
+using DelimitedFiles
+using LasIO
+using Test
+
+##
+
+function downloadTestData(datafile, url)
+  if 0 === Base.filesize(datafile)
+    Base.mkpath(dirname(datafile))
+    @info "Downloading $url"
+    Downloads.download(url, datafile)
+  end
+  return datafile
+end
+
+testdatafolder = joinpath(tempdir(), "caesar", "testdata") # "/tmp/caesar/testdata/"
+
+lidar_terr1_file = joinpath(testdatafolder,"lidar","simpleICP","terrestrial_lidar1.xyz")
+if !isfile(lidar_terr1_file)
+  lidar_terr1_url = "https://github.com/JuliaRobotics/CaesarTestData.jl/raw/main/data/lidar/simpleICP/terrestrial_lidar1.xyz"
+  downloadTestData(lidar_terr1_file,lidar_terr1_url)
+end
+
+# load the data to memory
+X_fix = readdlm(lidar_terr1_file, Float32)
+# convert data to PCL types
+pc_fix = Caesar._PCL.PointCloud(X_fix);
+
+
+pl = Arena.plotPointCloud(pc_fix)
+
+```
+
+This should result in a plot similar to:
+
+```@raw html
+<p align="center">
+<img src="https://github.com/JuliaRobotics/Arena.jl/assets/6412556/7679c346-fbeb-4d84-b20d-13bd589f3338" width="800" border="0" />
+</p>
+```
+
+
+!!! note
+    24Q1: Currently work is underway to better standardize within the Julia ecosystem, with the 4th generation of Arena.jl -- note that this is work in progress.  Information about legacy generations is included below.
 
 For more formal visualization support, contact [www.NavAbility.io](http://www.navability.io) via email or slack. 
 ## 4th Generation Dev Scripts using Makie.jl

diff --git a/docs/src/install_viz.md b/docs/src/install_viz.md
@@ -1,11 +1,19 @@
 # Install Visualization Tools
 
+## 2D/3D Plotting, Arena.jl
+
+```julia
+pkg> add Arena
+```
 
 ## 2D Plotting, RoMEPlotting.jl
 
-RoMEPlotting.jl (2D) and Arena.jl (3D) as optional visualization packages:
+!!! note
+    24Q1: Plotting is being consolidated into Arena.jl and RoMEPlotting.jl will become obsolete.
+
+RoMEPlotting.jl (2D) and Arena.jl (3D) are optional visualization packages:
 ```julia
-(v1.6) pkg> add RoMEPlotting
+pkg> add RoMEPlotting
 ```
 
 
diff --git a/docs/src/installation_environment.md b/docs/src/installation_environment.md
@@ -2,88 +2,82 @@
 
 Caesar.jl is one of the packages within the [JuliaRobotics](http://www.juliarobotics.org) community, and adheres to the [code-of-conduct](https://github.com/JuliaRobotics/administration/blob/master/code_of_conduct.md).
 
-## Possible System Dependencies
+## New to Julia
+
+### Installing the Julia Binary
+
+Although [Julia](https://julialang.org/) (or [JuliaPro](https://juliacomputing.com/)) can be installed on a Linux/Mac/Windows via a package manager, we prefer a highly reproducible and self contained (local environment) install.
+
+The easiest method is---via the terminal---[as described on the JuliaLang.org downloads page](https://julialang.org/downloads/).
+!!! note
+    Feel free to modify this setup as you see fit.
+
+## VSCode IDE Environment
+
+[VSCode IDE](https://www.julia-vscode.org/) allows for interactive development of Julia code using the Julia Extension.  After installing and running VSCode, install the Julia Language Support Extension:
 
-The following (Linux) system packages are used by Caesar.jl:
+```@raw html
+<p align="center">
+<img src="https://user-images.githubusercontent.com/6412556/97769200-444fdf80-1aff-11eb-8ca4-dc6d7a3830fd.png" width="800" border="0" />
+</p>
 ```
-# Likely dependencies
-sudo apt-get install hdf5-tools imagemagick
 
-# optional packages
-sudo apt-get install graphviz xdot
+In VSCode, open the command pallette by pressing `Ctrl + Shift + p`.  There are a wealth of tips and tricks on how to use VSCode.  See [this JuliaCon presentation for as a general introduction into 'piece-by-piece' code execution and much much more](https://www.youtube.com/watch?v=IdhnP00Y1Ks).  Working in one of the Julia IDEs like VS Code or Juno should feel something like this (Gif borrowed from [DiffEqFlux.jl](https://github.com/SciML/DiffEqFlux.jl)):
+```@raw html
+<p align="center">
+<img src="https://user-images.githubusercontent.com/1814174/88589293-e8207f80-d026-11ea-86e2-8a3feb8252ca.gif" width="800" border="0" />
+</p>
 ```
 
-For [ROS.org](https://www.ros.org/) users, see at least one usage example at [the ROS Direct page](@ref ros_direct).
+There are a variety of useful packages in VSCode, such as `GitLens`, `LiveShare`, and `Todo Browser` as just a few highlights.  These *VSCode Extensions* are independent of the already vast JuliaLang Package Ecosystem (see [JuliaObserver.com](https://juliaobserver.com/)).
+
+!!! note
+    For [ROS.org](https://www.ros.org/) users, see at least one usage example at [the ROS Direct page](@ref ros_direct).
 
 ## Installing Julia Packages
 
+### Vanilla Install
+
 The philosophy around Julia packages are discussed at length in the [Julia core documentation](https://docs.julialang.org/en/stable/manual/packages/), where each Julia package relates to a git repository likely found on [Github.com](http://www.github.com).  Also see [JuliaHub.com](https://juliahub.com/ui/Packages/Caesar/BNbRm) for dashboard-style representation of the broader Julia package ecosystem.
-To install a Julia package, simply open a `julia` REPL (equally the Julia REPL in VSCode) and type:
+To install a Julia package, simply start a `julia` REPL (equally the Julia REPL in VSCode) and then type:
 
 ```julia
-] # activate Pkg manager
-(v1.6) pkg> add Caesar
+julia> ] # activate Pkg manager
+(v___) pkg> add Caesar
 ```
 
+### Version Control, Branches
+
 These are [registered packages](https://pkg.julialang.org/) maintained by [JuliaRegistries/General](http://github.com/JuliaRegistries/General).
 Unregistered latest packages can also be installed with using only the `Pkg.develop` function:
 
 ```julia
 # Caesar is registered on JuliaRegistries/General
 julia> ]
-(v1.6) pkg> add Caesar
-(v1.6) pkg> add Caesar#janes-awesome-fix-branch
-(v1.6) pkg> add Caesar@v0.10.0
+(v___) pkg> add Caesar
+(v___) pkg> add Caesar#janes-awesome-fix-branch
+(v___) pkg> add Caesar@v0.16
 
 # or alternatively your own local fork (just using old link as example)
-(v1.6) pkg> add https://github.com/dehann/Caesar.jl
+(v___) pkg> add https://github.com/dehann/Caesar.jl
 ```
 
-See [Pkg.jl](https://github.com/JuliaLang/Pkg.jl) for details and features regarding package management, development, version control, virtual environments and much more.
-
-## Next Steps
+### Virtual Environments
 
-The sections hereafter describe [Building](@ref building_graphs), [Interacting], and [Solving](@ref solving_graphs) factor graphs.  We also recommend reviewing the various examples available in the [Examples section](@ref examples_section).  
-
-## New to Julia
-
-### Installing the Julia Binary
-
-Although [Julia](https://julialang.org/) (or [JuliaPro](https://juliacomputing.com/)) can be installed on a Linux computer using the `apt` package manager, we are striving for a fully local installation environment which is highly reproducible on a variety of platforms.
-
-The easiest method is---via the terminal---to [download the desired](https://julialang.org/downloads/) version of Julia as a binary, extract, setup a symbolic link, and run:
-
-```bash
-cd ~
-mkdir -p .julia
-cd .julia
-wget https://julialang-s3.julialang.org/bin/linux/x64/1.6/julia-1.6.7-linux-x86_64.tar.gz
-tar -xvf julia-1.6.7-linux-x86_64.tar.gz
-rm julia-1.6.7-linux-x86_64.tar.gz
-cd /usr/local/bin
-sudo ln -s ~/.julia/julia-1.6.7/bin/julia julia
-```
 !!! note
-    Feel free to modify this setup as you see fit.
+    Julia has native support for virtual environments and exact package manifests.  See [Pkg.jl Docs](https://pkgdocs.julialang.org/v1/environments/) for more info.  More details and features regarding package management, development, version control, virtual environments are available there.
 
-This should allow any terminal or process on the computer to run the Julia REPL by type `julia` and testing with:
+## Next Steps
 
-## VSCode IDE Environment
+The sections hereafter describe [Building](@ref building_graphs), [Interacting], and [Solving](@ref solving_graphs) factor graphs.  We also recommend reviewing the various examples available in the [Examples section](@ref examples_section).  
 
-[VSCode IDE](https://www.julia-vscode.org/) allows for interactive development of Julia code using the Julia Extension.  After installing and running VSCode, install the Julia Language Support Extension:
+### Possible System Dependencies
 
-```@raw html
-<p align="center">
-<img src="https://user-images.githubusercontent.com/6412556/97769200-444fdf80-1aff-11eb-8ca4-dc6d7a3830fd.png" width="800" border="0" />
-</p>
+The following (Linux) system packages have been required on some systems in the past, but likely does not have to be installed system wide on newer versions of Julia:
 ```
+# Likely dependencies
+sudo apt-get install hdf5-tools imagemagick
 
-In VSCode, open the command pallette by pressing `Ctrl + Shift + p`.  There are a wealth of tips and tricks on how to use VSCode.  See [this JuliaCon presentation for as a general introduction into 'piece-by-piece' code execution and much much more](https://www.youtube.com/watch?v=IdhnP00Y1Ks).  Working in one of the Julia IDEs like VS Code or Juno should feel something like this (Gif borrowed from [DiffEqFlux.jl](https://github.com/SciML/DiffEqFlux.jl)):
-```@raw html
-<p align="center">
-<img src="https://user-images.githubusercontent.com/1814174/88589293-e8207f80-d026-11ea-86e2-8a3feb8252ca.gif" width="800" border="0" />
-</p>
+# optional packages
+sudo apt-get install graphviz xdot
 ```
-
-There are a variety of useful packages in VSCode, such as `GitLens`, `LiveShare`, and `Todo Browser` as just a few highlights.  These *VSCode Extensions* are independent of the already vast JuliaLang Package Ecosystem (see [JuliaObserver.com](https://juliaobserver.com/)).
-
diff --git a/ext/CaesarImagesExt.jl b/ext/CaesarImagesExt.jl
@@ -38,7 +38,7 @@ import Caesar: PackedScatterAlignPose2, PackedScatterAlignPose3
 import Caesar: ImageTracks, FEATURE_VIA, FeatTrackValue, FeaturesDict, FeatureTracks, FeatureMountain, PIXELTRACK, MANYTRACKS
 import Caesar: addFeatureTracks_Frame1_Q!, addFeatureTracks_Frame2_PfwdQ!, addFeatureTracks_Frame2_QbckR!
 import Caesar: addFeatureTracks, consolidateFeatureTracks!, summarizeFeatureTracks!, buildFeatureMountain, buildFeatureMountainDistributed
-import Caesar: unionFeatureMountain, sortKeysMinSighting
+import Caesar: unionFeatureMountain, unionFeatureMountain!, sortKeysMinSighting
 
 # NOTE usage requires ImageFeatures.jl
 import Caesar: curateFeatureTracks

diff --git a/ext/Images/FeatureMountain.jl b/ext/Images/FeatureMountain.jl
@@ -2,7 +2,11 @@
 
 
 
+"""
+    $SIGNATURES
 
+Add image features to FeatureMountain dict, using an image stored in a blob of a DFG object.
+"""
 function addFeatureTracks_Frame1_Q!(
   # mountain::FeatureMountain,
   featToMany,
@@ -280,7 +284,14 @@ end
 # addFeatureTracks_Frame2_QbckR!(featToMany_, fg, pair)
 
 
+"""
+    $SIGNATURES
+
+Starting from basic short tracks between neighboring images, explore to find longer 
+tracks between many images.
 
+See also: [`summarizeFeatureTracks!`](@ref)
+"""
 function consolidateFeatureTracks!(
   featToMany_::Dict{Tuple{Symbol,Int},MANYTRACKS},
 )
@@ -334,7 +345,14 @@ function consolidateFeatureTracks!(
 end
 
 
+"""
+    $SIGNATURES
+
+Consolidate many short tracks into longer tracks.  A track is the 
+attempt to follow the same real world feature through a sequence of images.
 
+See also: [`consolidateFeatureTracks`](@ref)
+"""
 function summarizeFeatureTracks!(
   featToMany_::Dict{Tuple{Symbol,Int},MANYTRACKS},
 )
@@ -393,8 +411,6 @@ end
 
 ## union features
 
-
-
 function unionFeatureMountain(
   fMa::Dict{Tuple{Symbol,Int},MANYTRACKS}, 
   fMb::Dict{Tuple{Symbol,Int},MANYTRACKS},
@@ -419,7 +435,27 @@ function unionFeatureMountain(
   return rM
 end
 
-
+function unionFeatureMountain!(
+  fMa::Dict{Tuple{Symbol,Int},MANYTRACKS},
+  fMb::Dict{Tuple{Symbol,Int},MANYTRACKS}, 
+)
+  # Modify fMa by adding everything from fMb
+  for (ka,va) in fMb
+    # @info ka
+    # union if already exists
+    if haskey(fMa, ka)
+      # @info "CHECK TYPES" typeof(fMb[ka]) typeof(fMa[ka])
+      for (kr,vr) in va
+        if !haskey(fMa[ka], kr)
+          fMa[ka][kr] = vr # union(fMb[ka], fMa[ka])
+        end
+      end
+    else
+      fMa[ka] = va
+    end
+  end
+  return fMa
+end
 
 function sortKeysMinSighting(
   featM::Dict{Tuple{Symbol,Int},<:Any};
@@ -474,10 +510,10 @@ function buildFeatureMountainDistributed(
   featM = deepcopy(featM_1[1])
   # union other tracks into featM
   for fM in featM_1[2:end]
-    featM = Caesar.unionFeatureMountain(featM, fM)
+    featM = Caesar.unionFeatureMountain!(featM, fM)
   end
   for fM in featM_2
-    featM = Caesar.unionFeatureMountain(featM, fM)
+    featM = Caesar.unionFeatureMountain!(featM, fM)
   end
 
   return featM

diff --git a/ext/WeakdepsPrototypes.jl b/ext/WeakdepsPrototypes.jl
@@ -96,6 +96,7 @@ function buildFeatureMountain end
 function buildFeatureMountainDistributed end
 
 function unionFeatureMountain end
+function unionFeatureMountain! end
 function sortKeysMinSighting end
 
 ## ==============================================

diff --git a/src/Caesar.jl b/src/Caesar.jl
@@ -91,6 +91,9 @@ include("objects/ObjectAffordanceSubcloud.jl")
 # ImageDraw functionality, used by many extensions and therefore a regular (but minimum able) dependency
 include("images/imagedraw.jl")
 
+# experimentals
+include("dev/FolderDict.jl")
+
 # weakdeps
 include("../ext/factors/Pose2AprilTag4Corners.jl")
 include("../ext/factors/ScanMatcherPose2.jl")
@@ -103,7 +106,7 @@ include("Deprecated.jl")
 
 @compile_workload begin
   # In here put "toy workloads" that exercise the code you want to precompile
-  warmUpSolverJIT()
+  # warmUpSolverJIT()
 end
 
 end