Skip to content

Commit e1c30df

Browse files
AffieAffie
committed
fix docs
1 parent c701b04 commit e1c30df

File tree

12 files changed

+180
-111
lines changed

12 files changed

+180
-111
lines changed

‎.github/workflows/ci.yml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,6 @@ jobs:
6464
fail_ci_if_error: false
6565

6666
docs:
67-
needs: test
6867
name: Documentation
6968
runs-on: ubuntu-latest
7069
continue-on-error: true
@@ -75,7 +74,7 @@ jobs:
7574
- name: Setup julia
7675
uses: julia-actions/setup-julia@v2
7776
with:
78-
version: 'lts'
77+
version: '1.12'
7978
arch: x64
8079

8180
- name: Build Docs

‎docs/Project.toml‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
11
[deps]
2-
Cairo = "159f3aea-2a34-519c-b102-8c37f9878175"
3-
Compose = "a81c6b42-2e10-5240-aca2-a61377ecd94b"
42
DistributedFactorGraphs = "b5cc3c7e-6572-11e9-2517-99fb8daf2f04"
53
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
64
GraphMakie = "1ecd5474-83a3-4783-bb4f-06765db800d2"

‎docs/src/DataStructure.md‎

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,16 +37,11 @@ Accessible properties for each of the factor structures:
3737
- [`VariableSummary`](@ref)
3838
- [`FactorSummary`](@ref)
3939

40-
## DFG Portable and Storeable types
40+
## DFG full types (solvable, portable and storeable)
4141

4242
- [`VariableDFG`](@ref)
4343
- [`FactorDFG`](@ref)
4444

45-
## DFG Full solvable types
46-
47-
- [`VariableCompute`](@ref)
48-
- [`FactorCompute`](@ref)
49-
5045
## Additional Offloaded Data
5146

5247
Additional, larger data can be associated with variables and factors using keyed blob entries.

‎docs/src/GraphData.md‎

Lines changed: 22 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,9 @@ Each variable or factor can have a timestamp associated with it.
5353

5454
Tags are a set of symbols that contain identifiers for the variable or factor.
5555

56-
- [`getTags`](@ref)
56+
- [`listTags`](@ref)
5757
- [`mergeTags!`](@ref)
58-
- [`removeTags!`](@ref)
58+
- [`deleteTags!`](@ref)
5959
- [`emptyTags!`](@ref)
6060

6161

@@ -72,52 +72,11 @@ The solvable flag indicates whether the solver should make use of the variable o
7272

7373
#### Variable Type
7474

75-
The `variableType` is the underlying inference variable type, such as a Pose2.
75+
The `AbstractStateType` is the underlying inference variable type, such as a Pose2.
7676

77-
- [`getVariableType`](@ref)
77+
- [`getStateKind`](@ref)
7878

7979

80-
#### Packed Parametric Estimates
81-
82-
Solved graphs contain packed parametric estimates for the variables, which are keyed by the solution (the default is saved as :default).
83-
84-
For each PPE structure, there are accessors for getting individual values:
85-
86-
- [`getPPEMax`](@ref)
87-
- [`getPPEMean`](@ref)
88-
- [`getPPESuggested`](@ref)
89-
90-
91-
Related functions for getting, adding/updating, and deleting PPE structures:
92-
93-
94-
- [`listPPEs`](@ref)
95-
- [`getPPE`](@ref)
96-
- [`addPPE!`](@ref)
97-
- [`updatePPE!`](@ref)
98-
- [`deletePPE!`](@ref)
99-
- [`mergePPEs!`](@ref)
100-
101-
102-
Example of PPE operations:
103-
104-
```julia
105-
# Add a new PPE of type MeanMaxPPE to :x0
106-
ppe = MeanMaxPPE(:default, [0.0], [0.0], [0.0])
107-
addPPE!(dfg, :x0, ppe)
108-
@show listPPEs(dfg, :x0)
109-
# Get the data back - note that this is a reference to above.
110-
v = getPPE(dfg, :x0, :default)
111-
# Delete it
112-
deletePPE!(dfg, :x0, :default)
113-
# Update add it
114-
updatePPE!(dfg, :x0, ppe, :default)
115-
# Update update it
116-
updatePPE!(dfg, :x0, ppe, :default)
117-
# Bulk copy PPE's for x0 and x1
118-
updatePPE!(dfg, [x0], :default)
119-
```
120-
12180
#### Variable States (Solver Data)
12281

12382
Variable `State`s are used by the IncrementalInference/RoME/Caesar solver.
@@ -147,23 +106,23 @@ stateBack = getState(dfg, :x0, :parametric)
147106
deleteState!(dfg, :x0, :parametric)
148107
```
149108

150-
#### Metadata
109+
#### Bloblets
151110

152-
Metadata (small data) allows you to assign a dictionary to variables. It is a useful way to
153-
keep small amounts of primative (Strings, Integers, Floats, Bool) data in a variable. As it is stored in the graph
111+
Bloblets allow you to assign a dictionary of key-value [Symbol-String] pairs to nodes. It is a useful way to
112+
keep small amounts of primitive (Strings, Integers, Floats, Bool) data that is stored as a string in a node. As it is stored in the graph
154113
itself, large entries will slow the graph down, so if data should exceed a
155114
few bytes/kb, it should rather be saved in Blobs.
156115

157116

158-
- [`getMetadata`](@ref)
159-
- [`setMetadata!`](@ref)
117+
- [`getVariableBloblet`](@ref)
118+
- [`addVariableBloblet!`](@ref)
160119

161120

162121
Example:
163122

164123
```julia
165-
setMetadata!(x0, Dict("entry"=>"entry value"))
166-
getMetadata(x0)
124+
addVariableBloblet!(dfg, :x0, Bloblet(:bloblet_label,"bloblet value"))
125+
getVariableBloblet(dfg, :x0)
167126
```
168127

169128
#### Big Data
@@ -179,23 +138,25 @@ you are working with an in-memory graph, the DFG structure contains the graph it
179138

180139
Graphs reside inside a hierarchy made up in the following way:
181140
- Agent
182-
- Metadata
141+
- Bloblets
183142
- Blobentries
184143
- Graph
185-
- Metadata
144+
- Bloblets
186145
- Blobentries
187146

188-
This data can be retrieved with the follow functions:
189-
190-
- [`getAgentMetadata`](@ref)
191-
- [`getGraphMetadata`](@ref)
147+
Agent and Graph bloblets are useful for storing data that is related to the entire graph, and support CRUD operations:
192148

149+
- [`getAgentBloblet`](@ref)
150+
- [`getGraphBloblet`](@ref)
193151

194-
It can be set using the following functions:
152+
- [`addAgentBloblet!`](@ref)
153+
- [`addGraphBloblet!`](@ref)
195154

196-
- [`setAgentMetadata!`](@ref)
197-
- [`setGraphMetadata!`](@ref)
155+
- [`mergeAgentBloblet!`](@ref)
156+
- [`mergeGraphBloblet!`](@ref)
198157

158+
- [`deleteAgentBloblet!`](@ref)
159+
- [`deleteGraphBloblet!`](@ref)
199160

200161
Example of using graph-level data:
201162

‎docs/src/services_ref.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,18 @@ Modules = [DistributedFactorGraphs]
2323
Pages = ["services/CommonAccessors.jl"]
2424
```
2525

26+
## Common
27+
```@autodocs
28+
Modules = [DistributedFactorGraphs]
29+
Pages = [
30+
"services/list.jl",
31+
"services/find.jl",
32+
"services/Tags.jl",
33+
"entities/Bloblet.jl",
34+
"services/Bloblet.jl",
35+
]
36+
```
37+
2638
## DFG Variable Accessors CRUD and SET opperations
2739

2840
```@autodocs

‎src/Deprecated.jl‎

Lines changed: 0 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,6 @@
44
export FactorCompute
55
const FactorCompute = FactorDFG
66

7-
"""
8-
Types valid for small data.
9-
"""
107
const MetadataTypes = Union{
118
Int,
129
Float64,
@@ -135,18 +132,10 @@ function getVariableTypeName(v::VariableSummary)
135132
return v.statetype
136133
end
137134

138-
"""
139-
$(SIGNATURES)
140-
Get the Metadata entry at `key` for variable `label` in `dfg`
141-
"""
142135
function getMetadata(dfg::AbstractDFG, label::Symbol, key::Symbol)
143136
return getVariable(dfg, label).smallData[key]
144137
end
145138

146-
"""
147-
$(SIGNATURES)
148-
Add a Metadata pair `key=>value` for variable `label` in `dfg`
149-
"""
150139
function addMetadata!(dfg::AbstractDFG, label::Symbol, pair::Pair{Symbol, <:MetadataTypes})
151140
v = getVariable(dfg, label)
152141
haskey(v.smallData, pair.first) && throw(LabelExistsError("Metadata", pair.first))
@@ -155,10 +144,6 @@ function addMetadata!(dfg::AbstractDFG, label::Symbol, pair::Pair{Symbol, <:Meta
155144
return v.smallData #or pair TODO
156145
end
157146

158-
"""
159-
$(SIGNATURES)
160-
Update a Metadata pair `key=>value` for variable `label` in `dfg`
161-
"""
162147
function updateMetadata!(
163148
dfg::AbstractDFG,
164149
label::Symbol,
@@ -174,30 +159,18 @@ function updateMetadata!(
174159
return v.smallData #or pair TODO
175160
end
176161

177-
"""
178-
$(SIGNATURES)
179-
Delete a Metadata entry at `key` for variable `label` in `dfg`
180-
"""
181162
function deleteMetadata!(dfg::AbstractDFG, label::Symbol, key::Symbol)
182163
v = getVariable(dfg, label)
183164
pop!(v.smallData, key)
184165
mergeVariable!(dfg, v)
185166
return 1
186167
end
187168

188-
"""
189-
$(SIGNATURES)
190-
List all Metadata keys for a variable `label` in `dfg`
191-
"""
192169
function listMetadata(dfg::AbstractDFG, label::Symbol)
193170
v = getVariable(dfg, label)
194171
return collect(keys(v.smallData)) #or pair TODO
195172
end
196173

197-
"""
198-
$(SIGNATURES)
199-
Empty all Metadata from variable `label` in `dfg`
200-
"""
201174
function emptyMetadata!(dfg::AbstractDFG, label::Symbol)
202175
v = getVariable(dfg, label)
203176
empty!(v.smallData)

‎src/DistributedFactorGraphs.jl‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -303,8 +303,16 @@ export deleteVariableBloblet!
303303
export listVariableBloblets
304304

305305
export getAgentBloblet
306-
export getGraphBloblet
306+
export addAgentBloblet!
307+
export mergeAgentBloblet!
308+
export deleteAgentBloblet!
309+
export listAgentBloblets
307310

311+
export getGraphBloblet
312+
export addGraphBloblet!
313+
export mergeGraphBloblet!
314+
export deleteGraphBloblet!
315+
export listGraphBloblets
308316
##------------------------------------------------------------------------------
309317
## FileDFG
310318
##------------------------------------------------------------------------------

‎src/entities/Bloblet.jl‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,9 @@ function getBloblet(node, label::Symbol)
5050
return refBloblets(node)[label]
5151
end
5252

53+
"""
54+
$(SIGNATURES)
55+
"""
5356
function getBloblets(node)
5457
return collect(values(refBloblets(node)))
5558
end

‎src/entities/DFGFactor.jl‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ StructUtils.@kwarg struct FactorDFG{T <: AbstractObservation, N} <: AbstractGrap
6161
Accessor: [`getLabel`](@ref)"""
6262
label::Symbol
6363
"""Factor tags, e.g [:FACTOR].
64-
Accessors: [`getTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
64+
Accessors: [`listTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
6565
tags::Set{Symbol} = Set{Symbol}([:FACTOR])
6666
"""Ordered list of the neighbor variables.
6767
Accessors: [`getVariableOrder`](@ref)"""
@@ -222,7 +222,7 @@ $(TYPEDFIELDS)
222222
Accessor: [`getLabel`](@ref)"""
223223
label::Symbol
224224
"""Factor tags, e.g [:FACTOR].
225-
Accessors: [`getTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
225+
Accessors: [`listTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
226226
tags::Set{Symbol}
227227
"""Ordered list of the neighbor variables.
228228
Accessors: [`getVariableOrder`](@ref)"""
@@ -258,7 +258,7 @@ $(TYPEDFIELDS)
258258
Accessor: [`getLabel`](@ref)"""
259259
label::Symbol
260260
"""Factor tags, e.g [:FACTOR].
261-
Accessors: [`getTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
261+
Accessors: [`listTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
262262
tags::Set{Symbol}
263263
"""Ordered list of the neighbor variables.
264264
Accessors: [`getVariableOrder`](@ref)"""

‎src/entities/DFGVariable.jl‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -147,13 +147,13 @@ $(TYPEDFIELDS)
147147
# steadytime::Union{Nothing, Nanosecond} = nothing #NOTE changed to TimeDateZone in v0.29
148148
#nstime::String = "0" #NOTE different uses, as 0-999_999 nanosecond part of timestamp now in timestamp, as steady timestamp now in steadytime
149149
"""Variable tags, e.g [:POSE, :VARIABLE, and :LANDMARK].
150-
Accessors: [`getTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
150+
Accessors: [`listTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
151151
tags::Set{Symbol} = Set{Symbol}()
152152
"""Dictionary of state data. May be a subset of all solutions if a solver label was specified in the get call.
153153
Accessors: [`addState!`](@ref), [`mergeState!`](@ref), and [`deleteState!`](@ref)"""
154154
states::OrderedDict{Symbol, State{T, P, N}} = OrderedDict{Symbol, State{T, P, N}}() #NOTE field renamed from solverDataDict in v0.29
155155
"""Dictionary of small data associated with this variable.
156-
Accessors: [`getBloblet`](@ref), [`setBloblet!`](@ref)"""
156+
Accessors: [`getBloblet`](@ref), [`addBloblet!`](@ref)"""
157157
bloblets::Bloblets = Bloblets() #NOTE changed from smallData in v0.29
158158
"""Dictionary of large data associated with this variable.
159159
Accessors: [`addBlobentry!`](@ref), [`getBlobentry`](@ref), [`mergeBlobentry!`](@ref), and [`deleteBlobentry!`](@ref)"""
@@ -289,7 +289,7 @@ $(TYPEDFIELDS)
289289
Accessors: [`getTimestamp`](@ref)"""
290290
timestamp::TimeDateZone
291291
"""Variable tags, e.g [:POSE, :VARIABLE, and :LANDMARK].
292-
Accessors: [`getTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
292+
Accessors: [`listTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
293293
tags::Set{Symbol}
294294
"""Symbol for the state type for the underlying variable."""
295295
statetype::Symbol
@@ -315,7 +315,7 @@ Base.@kwdef struct VariableSkeleton <: AbstractGraphVariable
315315
Accessor: [`getLabel`](@ref)"""
316316
label::Symbol
317317
"""Variable tags, e.g [:POSE, :VARIABLE, and :LANDMARK].
318-
Accessors: [`getTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
318+
Accessors: [`listTags`](@ref), [`mergeTags!`](@ref), and [`deleteTags!`](@ref)"""
319319
tags::Set{Symbol} = Set{Symbol}()
320320
end
321321

0 commit comments

Comments
 (0)