DistributedFactorGraphs.DistributedFactorGraphs — Module

DistributedFactorGraphs.jl provides a flexible factor graph API for use in the Caesar.jl ecosystem.

The package supplies:

  • A standardized API for interacting with factor graphs
  • Implementations of the API for in-memory and database-driven operation
  • Visualization extensions to validate the underlying graph
DistributedFactorGraphs.BlobEntry — Type
struct BlobEntry

A BlobEntry is a small about of structured data that holds reference information to find an actual blob. Many BlobEntrys can exist on different graph nodes spanning Robots, and Sessions which can all reference the same Blob. A BlobEntry is also a equivalent to a bridging entry between local .originId and a remotely assigned .blobIds.

Notes:

  • All .blobIds are unique across the entire distributed system and are immutable. The .originId should be globally unique except for stochastic uuid4 collisions that cannot be checked from a main reference owing to practical limitations such as network connectivity.
DistributedFactorGraphs.DFGFactor — Type
struct DFGFactor{T, N} <: AbstractDFGFactor

Complete factor structure for a DistributedFactorGraph factor.

DevNotes

  • TODO make consistent the order of fields skeleton Skeleton, Summary, thru DFGFactor

    • e.g. timestamp should be a later field.

Fields:

  • id::Union{Nothing, Base.UUID}: The ID for the factor

  • label::Symbol: Factor label, e.g. :x1f1. Accessor: getLabel

  • tags::Set{Symbol}: Factor tags, e.g [:FACTOR]. Accessors: getTags, mergeTags!, and removeTags!

  • _variableOrderSymbols::Tuple{Vararg{Symbol, N}} where N: Internal cache of the ordering of the neighbor variables. Rather use getVariableOrder to get the list as this is an internal value. Accessors: getVariableOrder

  • timestamp::TimeZones.ZonedDateTime: Variable timestamp. Accessors: getTimestamp, setTimestamp

  • nstime::Dates.Nanosecond: Nano second time, for more resolution on timestamp (only subsecond information)

  • solverData::Base.RefValue{GenericFunctionNodeData{T}} where T: Solver data. Accessors: getSolverData, setSolverData!

  • solvable::Base.RefValue{Int64}: Solvable flag for the factor. Accessors: getSolvable, setSolvable!

  • smallData::Dict{Symbol, Union{Bool, Float64, Int64, Vector{Bool}, Vector{Float64}, Vector{Int64}, Vector{String}, String}}: Dictionary of small data associated with this variable. Accessors: getSmallData, setSmallData!

DistributedFactorGraphs.DFGFactor — Method
DFGFactor(
    label,
    timestamp,
    nstime,
    tags,
    solverData,
    solvable,
    _variableOrderSymbols;
    id,
    smallData
)

Construct a DFG factor given a label.

DistributedFactorGraphs.DFGFactorSummary — Type
struct DFGFactorSummary <: AbstractDFGFactor

Read-only summary factor structure for a DistributedFactorGraph factor.

Fields:

  • id::Union{Nothing, Base.UUID}: The ID for the factor

  • label::Symbol: Factor label, e.g. :x1f1. Accessor: getLabel

  • tags::Set{Symbol}: Factor tags, e.g [:FACTOR]. Accessors: getTags, mergeTags!, and removeTags!

  • _variableOrderSymbols::Vector{Symbol}: Internal cache of the ordering of the neighbor variables. Rather use listNeighbors to get the list as this is an internal value. Accessors: getVariableOrder

  • timestamp::TimeZones.ZonedDateTime: Variable timestamp. Accessors: getTimestamp

DistributedFactorGraphs.DFGVariable — Type
struct DFGVariable{T<:InferenceVariable, P, N} <: AbstractDFGVariable

Complete variable structure for a DistributedFactorGraph variable.

Fields:

  • id::Union{Nothing, Base.UUID}: The ID for the variable

  • label::Symbol: Variable label, e.g. :x1. Accessor: getLabel

  • timestamp::TimeZones.ZonedDateTime: Variable timestamp. Accessors: getTimestamp, setTimestamp

  • nstime::Dates.Nanosecond: Nanoseconds since a user-understood epoch (i.e unix epoch, robot boot time, etc.)

  • tags::Set{Symbol}: Variable tags, e.g [:POSE, :VARIABLE, and :LANDMARK]. Accessors: getTags, mergeTags!, and removeTags!

  • ppeDict::Dict{Symbol, AbstractPointParametricEst}: Dictionary of parametric point estimates keyed by solverDataDict keys Accessors: addPPE!, updatePPE!, and deletePPE!

  • solverDataDict::Dict{Symbol, VariableNodeData{T, P, N}} where {T<:InferenceVariable, P, N}: Dictionary of solver data. May be a subset of all solutions if a solver key was specified in the get call. Accessors: addVariableSolverData!, updateVariableSolverData!, and deleteVariableSolverData!

  • smallData::Dict{Symbol, Union{Bool, Float64, Int64, Vector{Bool}, Vector{Float64}, Vector{Int64}, Vector{String}, String}}: Dictionary of small data associated with this variable. Accessors: getSmallData, setSmallData!

  • dataDict::Dict{Symbol, BlobEntry}: Dictionary of large data associated with this variable. Accessors: addBlobEntry!, getBlobEntry, updateBlobEntry!, and deleteBlobEntry!

  • solvable::Base.RefValue{Int64}: Solvable flag for the variable. Accessors: getSolvable, setSolvable!

DistributedFactorGraphs.DFGVariableSummary — Type
struct DFGVariableSummary <: AbstractDFGVariable

Summary variable structure for a DistributedFactorGraph variable.

Fields:

DistributedFactorGraphs.GenericFunctionNodeData — Type
mutable struct GenericFunctionNodeData{T<:(Union{var"#s19912", var"#s19911", var"#s19910"} where {var"#s19912"<:AbstractPackedFactor, var"#s19911"<:AbstractFactor, var"#s19910"<:FactorOperationalMemory})}

Notes

  • S::Symbol

Designing (WIP)

  • T <: Union{FactorOperationalMemory, AbstractPackedFactor}
  • in IIF.CCW{T <: DFG.AbstractFactor}
  • in DFG.AbstractRelativeMinimize <: AbstractFactor
  • in Main.SomeFactor <: AbstractRelativeMinimize
DistributedFactorGraphs.PackedVariableNodeData — Type
mutable struct PackedVariableNodeData

Packed VariableNodeData structure for serializing DFGVariables.

Fields:

  • id::Union{Nothing, Base.UUID}

  • vecval::Vector{Float64}

  • dimval::Int64

  • vecbw::Vector{Float64}

  • dimbw::Int64

  • BayesNetOutVertIDs::Vector{Symbol}

  • dimIDs::Vector{Int64}

  • dims::Int64

  • eliminated::Bool

  • BayesNetVertID::Symbol

  • separator::Vector{Symbol}

  • variableType::String

  • initialized::Bool

  • infoPerCoord::Vector{Float64}

  • ismargin::Bool

  • dontmargin::Bool

  • solveInProgress::Int64

  • solvedCount::Int64

  • solveKey::Symbol

  • covar::Vector{Float64}

  • _version::String

DistributedFactorGraphs.SkeletonDFGFactor — Type
struct SkeletonDFGFactor <: AbstractDFGFactor

Skeleton factor structure for a DistributedFactorGraph factor.

Fields:

  • id::Union{Nothing, Base.UUID}: The ID for the factor

  • label::Symbol: Factor label, e.g. :x1f1. Accessor: getLabel

  • tags::Set{Symbol}: Factor tags, e.g [:FACTOR]. Accessors: getTags, mergeTags!, and removeTags!

  • _variableOrderSymbols::Vector{Symbol}: Internal cache of the ordering of the neighbor variables. Rather use listNeighbors to get the list as this is an internal value. Accessors: getVariableOrder

DistributedFactorGraphs.SkeletonDFGVariable — Type
struct SkeletonDFGVariable <: AbstractDFGVariable

Skeleton variable structure for a DistributedFactorGraph variable.

Fields:

  • id::Union{Nothing, Base.UUID}: The ID for the variable

  • label::Symbol: Variable label, e.g. :x1. Accessor: getLabel

  • tags::Set{Symbol}: Variable tags, e.g [:POSE, :VARIABLE, and :LANDMARK]. Accessors: getTags, mergeTags!, and removeTags!

DistributedFactorGraphs.VariableNodeData — Type
mutable struct VariableNodeData{T<:InferenceVariable, P, N}

Data container for solver-specific data.

T: Variable type, such as Position1, or RoME.Pose2, etc. P: Variable point type, the type of the manifold point. N: Manifold dimension. Fields:

  • variableType::InferenceVariable: DEPRECATED remove in DFG v0.22

  • id::Union{Nothing, Base.UUID}: Globally unique identifier.

  • val::Vector: Vector of on-manifold points used to represent a ManifoldKernelDensity (or parametric) belief.
  • bw::Matrix{Float64}: Common kernel bandwith parameter used with ManifoldKernelDensity, see field covar for the parametric covariance.

  • covar::Array{StaticArraysCore.SMatrix{N, N, Float64}, 1} where N: Parametric (Gaussian) covariance.

  • BayesNetOutVertIDs::Vector{Symbol}

  • dimIDs::Vector{Int64}

  • dims::Int64

  • eliminated::Bool: Flag used by junction (Bayes) tree construction algorithm to know whether this variable has yet been included in the tree construction.

  • BayesNetVertID::Symbol

  • separator::Vector{Symbol}

  • initialized::Bool: False if initial numerical values are not yet available or stored values are not ready for further processing yet.

  • infoPerCoord::Vector{Float64}: Stores the amount information (per measurement dimension) captured in each coordinate dimension.
  • ismargin::Bool: Should this variable solveKey be treated as marginalized in inference computations.
  • dontmargin::Bool: Should this variable solveKey always be kept fluid and not be automatically marginalized.
  • solveInProgress::Int64: Convenience flag on whether a solver is currently busy working on this variable solveKey.
  • solvedCount::Int64: How many times has a solver updated this variable solveKey estimte.
  • solveKey::Symbol: solveKey identifier associated with this VariableNodeData object.
  • events::Dict{Symbol, Base.GenericCondition{ReentrantLock}}: Future proofing field for when more multithreading operations on graph nodes are implemented, these conditions are meant to be used for atomic write transactions to this VND.
DistributedFactorGraphs._getPriorType — Method
_getPriorType(_type)

If you know a variable is ::Type{<:Pose2} but want to find its default prior ::Type{<:PriorPose2}.

Assumptions

  • The prior type will be defined in the same module as the variable type.
  • Not exported per default, but can be used with knowledge of the caveats.

Example

using RoME
@assert RoME.PriorPose2 == DFG._getPriorType(Pose2)
DistributedFactorGraphs.addBlob! — Function

Adds a blob to the blob store or dfg with the given entry.

Related addBlobEntry!

addBlob!(store, _, _)
addBlob!(dfg, entry, data)
addBlob!(store, entry, data)
addBlob!(store, data)
addBlob!(store, blobId, data, _)
addBlob!(store, data, _)
addBlob!(store, blobId, data)
addBlob!(store, blobId, data)
addBlob!(store, entry, linkfile)
addBlob!(store, blobId, blob, linkfile)
addBlob!(store, blobId, blob)
DistributedFactorGraphs.addData! — Function

Add both a BlobEntry and Blob to a distributed factor graph or BlobStore. Related addBlobEntry!

addData!(dfg, label, entry, blob; hashfunction, checkhash)
addData!(
    dfg,
    blobstore,
    label,
    entry,
    blob;
    hashfunction,
    checkhash
)
addData!(
    dfg,
    blobstorekey,
    vLbl,
    bLbl,
    blob,
    timestamp;
    kwargs...
)
addData!(dfg, blobstorekey, vLbl, bLbl, blob; ...)
addData!(
    dfg,
    blobstore,
    vLbl,
    bLbl,
    blob,
    timestamp;
    description,
    metadata,
    mimeType,
    id,
    blobId,
    originId,
    hashfunction
)
addData!(dfg, blobstore, vLbl, bLbl, blob; ...)
addData!(
    dfg,
    blobstore,
    vLbl,
    blobLabel,
    blob,
    timestamp;
    description,
    metadata,
    mimeType,
    origin
)
addData!(dfg, blobstore, vLbl, blobLabel, blob; ...)
DistributedFactorGraphs.addPPE! — Function
addPPE!(dfg, sourceVariable)
addPPE!(dfg, sourceVariable, ppekey)

Add a new PPE entry from a deepcopy of the source variable PPE. NOTE: Copies the PPE.

DistributedFactorGraphs.addVariableSolverData! — Function
addVariableSolverData!(dfg, sourceVariable)
addVariableSolverData!(dfg, sourceVariable, solveKey)

Add a new solver data entry from a deepcopy of the source variable solver data. NOTE: Copies the solver data.

DistributedFactorGraphs.buildSubgraph — Method
buildSubgraph(, dfg, variableFactorLabels; ...)
buildSubgraph(
    ,
    dfg,
    variableFactorLabels,
    distance;
    solvable,
    sessionId,
    kwargs...
)

Build a deep subgraph copy from the DFG given a list of variables and factors and an optional distance. Note: Orphaned factors (where the subgraph does not contain all the related variables) are not returned. Related:

Dev Notes

  • Bulk vs node for node: a list of labels are compiled and the sugraph is copied in bulk.
DistributedFactorGraphs.cloneSolveKey! — Method
cloneSolveKey!(
    dest_dfg,
    dest,
    src_dfg,
    src;
    solvable,
    labels,
    verbose
)

Duplicate a solveKey` into a destination from a source.

Notes

  • Can copy between graphs, or to different solveKeys within one graph.
DistributedFactorGraphs.compareAll — Method
compareAll(Al, Bl; show, skip)

Recursively compare the all fields of T that are not in skip for objects Al and Bl.

TODO > add to func_ref.md

DistributedFactorGraphs.compareAllVariables — Method
compareAllVariables(fgA, fgB; skip, show, skipsamples)

Compare all variables in both ::FactorGraphs A and B.

Notes

  • A and B should all the same variables and factors.

Related:

compareFactorGraphs, compareSimilarVariables, compareVariable, ls

DistributedFactorGraphs.compareFactor — Method
compareFactor(A, B; show, skip, skipsamples, skipcompute)

Compare that all fields are the same in a ::FactorGraph factor.

DevNotes

  • TODO getSolverData(A).fnc.varValsAll / varidx are only defined downstream, so should should this function not be in IIF?
DistributedFactorGraphs.compareFactorGraphs — Method
compareFactorGraphs(
    fgA,
    fgB;
    skipsamples,
    skipcompute,
    skip,
    show
)

Compare and return if two factor graph objects are the same, by comparing similar variables and factors.

Notes:

  • Default items to skip with skipsamples, skipcompute.
  • User defined fields to skip can be specified with skip::Vector{Symbol}.
  • To enable debug messages for viewing which fields are not the same:
    • https://stackoverflow.com/questions/53548681/how-to-enable-debugging-messages-in-juno-julia-editor

Related:

compareSimilarVariables, compareSimilarFactors, compareAllVariables, ls.

DistributedFactorGraphs.compareFields — Method
compareFields(Al, Bl; show, skip)

Compare the all fields of T that are not in skip for objects Al and Bl and returns ::Bool.

TODO > add to func_ref.md

DistributedFactorGraphs.compareSimilarFactors — Method
compareSimilarFactors(
    fgA,
    fgB;
    skipsamples,
    skipcompute,
    skip,
    show
)

Compare similar factors between ::FactorGraphs A and B.

Related:

compareFactorGraphs, compareSimilarVariables, compareAllVariables, ls.

DistributedFactorGraphs.compareSimilarVariables — Method
compareSimilarVariables(fgA, fgB; skip, show, skipsamples)

Compare similar labels between ::FactorGraphs A and B.

Notes

  • At least one variable label should exist in both A and B.

Related:

compareFactorGraphs, compareAllVariables, compareSimilarFactors, compareVariable, ls.

DistributedFactorGraphs.copyGraph! — Function
copyGraph!(destDFG, sourceDFG; ...)
copyGraph!(destDFG, sourceDFG, variableLabels; ...)
copyGraph!(
    destDFG,
    sourceDFG,
    variableLabels,
    factorLabels;
    copyGraphMetadata,
    overwriteDest,
    deepcopyNodes,
    verbose,
    showprogress
)

Common function for copying nodes from one graph into another graph. This is overridden in specialized implementations for performance. Orphaned factors are not added, with a warning if verbose. Set overwriteDest to overwrite existing variables and factors in the destination DFG. NOTE: copyGraphMetadata not supported yet. Related:

DistributedFactorGraphs.deleteBlob! — Function

Delete a blob from the blob store or dfg with the given entry.

Related deleteBlobEntry!

deleteBlob!(store, _)
deleteBlob!(dfg, entry)
deleteBlob!(store, entry)
deleteBlob!(store, blobId)
deleteBlob!(store, blobId)
deleteBlob!(store, args)
deleteBlob!(store, _)
deleteBlob!(store, _)
deleteBlob!(store, blobId)
DistributedFactorGraphs.deleteBlobEntry! — Method
deleteBlobEntry!(var, key)

Delete a blob entry from the factor graph. Note this doesn't remove it from any data stores.

Notes:

  • users responsibility to delete data in db before deleting entry
DistributedFactorGraphs.findClosestTimestamp — Method
findClosestTimestamp(setA, setB)

Find and return the closest timestamp from two sets of Tuples. Also return the minimum delta-time (::Millisecond) and how many elements match from the two sets are separated by the minimum delta-time.

DistributedFactorGraphs.findFactorsBetweenNaive — Function
findFactorsBetweenNaive(dfg, from, to)
findFactorsBetweenNaive(dfg, from, to, assertSingles)

Relatively naive function counting linearly from-to

DevNotes

  • Convert to using Graphs shortest path methods instead.
DistributedFactorGraphs.findVariableNearTimestamp — Function
findVariableNearTimestamp(dfg, timest; ...)
findVariableNearTimestamp(
    dfg,
    timest,
    regexFilter;
    tags,
    solvable,
    warnDuplicate,
    number
)

Find and return nearest variable labels per delta time. Function will filter on regexFilter, tags, and solvable.

Notes

  • Returns Vector{Tuple{Vector{Symbol}, Millisecond}}

DevNotes:

  • TODO number should allow returning more than one for k-nearest matches.
  • Future versions likely will require some optimization around the internal getVariable call.
    • Perhaps a dedicated/efficient getVariableTimestamp for all DFG flavors.

Related

ls, listVariables, findClosestTimestamp

DistributedFactorGraphs.getAdjacencyMatrixSymbols — Method
getAdjacencyMatrixSymbols(dfg; solvable)

Get a matrix indicating relationships between variables and factors. Rows are all factors, columns are all variables, and each cell contains either nothing or the symbol of the relating factor. The first row and first column are factor and variable headings respectively. Note:

  • rather use getBiadjacencyMatrix
  • Returns either of ::Matrix{Union{Nothing, Symbol}}
DistributedFactorGraphs.getBiadjacencyMatrix — Method
getBiadjacencyMatrix(dfg; solvable)

Get a matrix indicating adjacency between variables and factors. Returned as a named tuple: B::SparseMatrixCSC{Int}, varLabels::Vector{Symbol) facLabels::Vector{Symbol). Rows are the factors, columns are the variables, with the corresponding labels in varLabels,facLabels.

Notes

  • Returns ::NamedTuple{(:B, :varLabels, :facLabels), Tuple{SparseMatrixCSC, Vector{Symbol}, Vector{Symbol}}}
DistributedFactorGraphs.getBlob — Function

Get the data blob for the specified blobstore or dfg.

Related getBlobEntry

getBlob(store, _)
getBlob(dfg, entry)
getBlob(store, entry)
getBlob(store, blobId)
getBlob(store, blobId)
getBlob(store, blobId)
getBlob(store, blobId)
DistributedFactorGraphs.getBlobEntriesVariables — Method
getBlobEntriesVariables(
    dfg,
    bLblPattern;
    varList,
    dropEmpties
)

Get all blob entries matching a Regex pattern over variables

Notes

  • Use dropEmpties=true to not include empty lists in result.
  • Use keyword varList for which variables to search through.
DistributedFactorGraphs.getCoordinates — Method
getCoordinates(, p)
getCoordinates(, p, basis)

Default reduction of a variable point value (a group element) into coordinates as Vector. Override if defaults are not correct.

DevNotes

  • TODO Likely remove as part of serialization updates, see #590
  • Used in transition period for Serialization. This function will likely be changed or deprecated entirely.

Related

getPoint

DistributedFactorGraphs.getData — Function

Get the blob entry and blob for the specified blobstore or dfg retured as a tuple. Related getBlobEntry

getData(dfg, vlabel, key; hashfunction, checkhash, getlast)
getData(
    dfg,
    blobstore,
    label,
    key;
    hashfunction,
    checkhash,
    getlast
)
DistributedFactorGraphs.getDimension — Function

Interface function to return the variableType dimension of an InferenceVariable, extend this function for all Types<:InferenceVariable.

DistributedFactorGraphs.getEstimateFields — Method
getEstimateFields(_)

Return the fields of MeanMaxPPE that are estimates. NOTE: This is needed for each AbstractPointParametricEst. Closest we can get to a decorator pattern.

DistributedFactorGraphs.getFactors — Method
getFactors(dfg; ...)
getFactors(dfg, regexFilter; tags, solvable)

List the DFGFactors in the DFG. Optionally specify a label regular expression to retrieves a subset of the factors.

DistributedFactorGraphs.getPPE — Function
getPPE(vari)
getPPE(vari, solveKey)

Get the parametric point estimate (PPE) for a variable in the factor graph.

Notes

  • Defaults on keywords solveKey and method

Related

getMeanPPE, getMaxPPE, getKDEMean, getKDEFit, getPPEs, getVariablePPEs

DistributedFactorGraphs.getPoint — Method
getPoint(, v)
getPoint(, v, basis)

Default escalzation from coordinates to a group representation point. Override if defaults are not correct. E.g. coords -> se(2) -> SE(2).

DevNotes

  • TODO Likely remove as part of serialization updates, see #590
  • Used in transition period for Serialization. This function will likely be changed or deprecated entirely.

Related

getCoordinates

DistributedFactorGraphs.getPointIdentity — Function

Interface function to return the user provided identity point for this InferenceVariable manifold, extend this function for all Types<:InferenceVariable.

Notes

  • Used in transition period for Serialization. This function will likely be changed or deprecated entirely.
DistributedFactorGraphs.getPointType — Function

Interface function to return the manifold point type of an InferenceVariable, extend this function for all Types<:InferenceVariable.

DistributedFactorGraphs.getSolvable — Method
getSolvable(var)

Variables or factors may or may not be 'solvable', depending on a user definition. Useful for ensuring atomic transactions.

Related:

  • isSolveInProgress
DistributedFactorGraphs.getSolveInProgress — Function
getSolveInProgress(var)
getSolveInProgress(var, solveKey)

Which variables or factors are currently being used by an active solver. Useful for ensuring atomic transactions.

DevNotes:

  • Will be renamed to data.solveinprogress which will be in VND, not DFGNode – see DFG #201

Related

isSolvable

DistributedFactorGraphs.getSummary — Method
getSummary(dfg)

Get a summary of the graph (first-class citizens of variables and factors). Returns a DFGSummary.

Notes

  • Returns ::DFGSummary
DistributedFactorGraphs.getSummaryGraph — Method
getSummaryGraph(dfg)

Get a summary graph (first-class citizens of variables and factors) with the same structure as the original graph.

Notes

  • this is a copy of the original.
  • Returns ::GraphsDFG{NoSolverParams, DFGVariableSummary, DFGFactorSummary}
DistributedFactorGraphs.getVariable — Method
getVariable(dfg, label, solveKey)

Get a DFGVariable with a specific solver key. In memory types still return a reference, other types returns a variable with only solveKey.

DistributedFactorGraphs.getVariableLabelNumber — Function
getVariableLabelNumber(vs)
getVariableLabelNumber(vs, prefix)

Small utility to return ::Int, e.g. 0 from getVariableLabelNumber(:x0)

Examples

getVariableLabelNumber(:l10)          # 10
getVariableLabelNumber(:x1)           # 1
getVariableLabelNumber(:x1_10, "x1_") # 10

DevNotes

  • make prefix Regex based for longer – i.e. :apriltag578, :lm1_4
DistributedFactorGraphs.getVariableType — Method
getVariableType(_)

Variable nodes variableType information holding a variety of meta data associated with the type of variable stored in that node of the factor graph.

Notes

  • API Quirk in that this function returns and instance of ::T not a ::Type{<:InferenceVariable}.

DevWork

  • TODO, see IncrementalInference.jl 1228

Related

getVariableType

DistributedFactorGraphs.getVariables — Method
getVariables(dfg; ...)
getVariables(dfg, regexFilter; tags, solvable, detail)

List the DFGVariables in the DFG. Optionally specify a label regular expression to retrieves a subset of the variables. Tags is a list of any tags that a node must have (at least one match).

DistributedFactorGraphs.hasTags — Method
hasTags(dfg, sym, tags; matchAll)

Determine if the variable or factor neighbors have the tags:;Vector{Symbol}, and matchAll::Bool.

DistributedFactorGraphs.incrDataLabelSuffix — Method
incrDataLabelSuffix(dfg, vla, bllb; datalabel)

If the blob label datalabel already exists, then this function will return the name datalabel_1. If the blob label datalabel_1 already exists, then this function will return the name datalabel_2.

DistributedFactorGraphs.isFactor — Method
isFactor(dfg, sym)

Return whether sym::Symbol represents a factor vertex in the graph DFG. Checks whether it both exists in the graph and is a factor. (If you rather want a quicker for type, just do node isa DFGFactor)

DistributedFactorGraphs.isInitialized — Function
isInitialized(var)
isInitialized(var, key)

Returns state of variable data .initialized flag.

Notes:

  • used by both factor graph variable and Bayes tree clique logic.
DistributedFactorGraphs.isMarginalized — Function
isMarginalized(vert)
isMarginalized(vert, solveKey)

Return ::Bool on whether this variable has been marginalized.

Notes:

  • VariableNodeData default solveKey=:default
DistributedFactorGraphs.isSolvable — Method
isSolvable(node)

Variables or factors may or may not be 'solvable', depending on a user definition. returns true if getSolvable > 0 Related:

  • getSolvable(@ref)
DistributedFactorGraphs.isVariable — Method
isVariable(dfg, sym)

Return whether sym::Symbol represents a variable vertex in the graph DFG. Checks whether it both exists in the graph and is a variable. (If you rather want a quick for type, just do node isa DFGVariable)

DistributedFactorGraphs.listBlobEntrySequence — Function
listBlobEntrySequence(dfg, lb, pattern)
listBlobEntrySequence(dfg, lb, pattern, _sort)

List a collection of blob entries per variable that match a particular pattern::Regex.

Notes

  • Optional sort function argument, default is unsorted.
    • Likely use of sortDFG for basic Symbol sorting.

Example

listBlobEntrySequence(fg, :x0, r"IMG_CENTER", sortDFG)
15-element Vector{Symbol}:
 :IMG_CENTER_21676
 :IMG_CENTER_21677
 :IMG_CENTER_21678
 :IMG_CENTER_21679
...
DistributedFactorGraphs.listFactors — Method
listFactors(dfg; ...)
listFactors(dfg, regexFilter; tags, solvable)

Get a list of the labels of the DFGFactors in the DFG. Optionally specify a label regular expression to retrieves a subset of the factors.

DistributedFactorGraphs.listNeighbors — Method
listNeighbors(dfg, label; solvable)

Retrieve a list of labels of the immediate neighbors around a given variable or factor specified by its label.

DistributedFactorGraphs.listSolveKeys — Function
listSolveKeys(variable::DFGVariable) -> Set{Symbol}
listSolveKeys(
    variable::DFGVariable,
    filterSolveKeys::Union{Nothing, Regex}
) -> Set{Symbol}
listSolveKeys(
    variable::DFGVariable,
    filterSolveKeys::Union{Nothing, Regex},
    skeys
) -> Any

List all the solvekeys used amongst all variables in the distributed factor graph object.

Related

listSupersolves, getSolverDataDict, listVariables

DistributedFactorGraphs.listVariables — Function
listVariables(dfg; ...)
listVariables(dfg, regexFilter; tags, solvable)

Get a list of labels of the DFGVariables in the graph. Optionally specify a label regular expression to retrieves a subset of the variables. Tags is a list of any tags that a node must have (at least one match).

Notes

  • Returns ::Vector{Symbol}

Example

listVariables(dfg, r"l", tags=[:APRILTAG;])

See also: ls

DistributedFactorGraphs.loadDFG! — Method
loadDFG!(
    dfgLoadInto,
    dst;
    overwriteDFGMetadata,
    useDeprExtract
)

Load a DFG from a saved folder.

Example

using DistributedFactorGraphs, IncrementalInference
# Create a DFG - can make one directly, e.g. GraphsDFG{NoSolverParams}() or use IIF:
dfg = initfg()
# Load the graph
loadDFG!(dfg, "/tmp/savedgraph.tar.gz")
# Use the DFG as you do normally.
ls(dfg)

See also: loadDFG, saveDFG

DistributedFactorGraphs.ls — Method
ls(dfg; ...)
ls(dfg, regexFilter; tags, solvable)

List the DFGVariables in the DFG. Optionally specify a label regular expression to retrieves a subset of the variables. Tags is a list of any tags that a node must have (at least one match).

Notes:

  • Returns Vector{Symbol}
DistributedFactorGraphs.ls — Method
ls(dfg; ...)
ls(dfg, node; solvable)

Retrieve a list of labels of the immediate neighbors around a given variable or factor.

DistributedFactorGraphs.lsWho — Method
lsWho(dfg, type)

Gives back all factor labels that fit the bill: lsWho(dfg, :Pose3)

Notes

  • Returns Vector{Symbol}

Dev Notes

  • Cloud versions will benefit from less data transfer
  • ls(dfg::C, ::T) where {C <: CloudDFG, T <: ..}

Related

ls, lsf, lsfPriors

DistributedFactorGraphs.lsf — Method
lsf(dfg; ...)
lsf(dfg, regexFilter; tags, solvable)

List the DFGFactors in the DFG. Optionally specify a label regular expression to retrieves a subset of the factors.

Notes

  • Return Vector{Symbol}
DistributedFactorGraphs.lsfWho — Method
lsfWho(dfg, type)

Gives back all factor labels that fit the bill: lsfWho(dfg, :Point2Point2)

Notes

  • Returns Vector{Symbol}

Dev Notes

  • Cloud versions will benefit from less data transfer
  • ls(dfg::C, ::T) where {C <: CloudDFG, T <: ..}

Related

ls, lsf, lsfPriors

DistributedFactorGraphs.mergeGraph! — Function
mergeGraph!(destDFG, sourceDFG; ...)
mergeGraph!(destDFG, sourceDFG, variableLabels; ...)
mergeGraph!(
    destDFG,
    sourceDFG,
    variableLabels,
    factorLabels;
    ...
)
mergeGraph!(
    destDFG,
    sourceDFG,
    variableLabels,
    factorLabels,
    distance;
    solvable,
    kwargs...
)

Merger sourceDFG to destDFG given an optional list of variables and factors and distance. Notes:

  • Nodes already in the destination graph are updated from sourceDFG.
  • Orphaned factors (where the subgraph does not contain all the related variables) are not included.

Related:

DistributedFactorGraphs.mergeGraphVariableData! — Method
mergeGraphVariableData!(destDFG, sourceDFG, varSyms)

Common function to update all solver data and estimates from one graph to another. This should be used to push local solve data back into a cloud graph, for example.

Notes

  • Returns ::Nothing
DistributedFactorGraphs.mergePPEs! — Method
mergePPEs!(destVariable, sourceVariable)

Merges and updates solver and estimate data for a variable (variable can be from another graph). Note: Makes a copy of the estimates and solver data so that there is no coupling between graphs.

DistributedFactorGraphs.mergeVariableData! — Method
mergeVariableData!(dfg, sourceVariable)

Merges and updates solver and estimate data for a variable (variable can be from another graph). Note: Makes a copy of the estimates and solver data so that there is no coupling between graphs.

DistributedFactorGraphs.mergeVariableSolverData! — Method
mergeVariableSolverData!(destVariable, sourceVariable)

Merges and updates solver and estimate data for a variable (variable can be from another graph). If the same key is present in another collection, the value for that key will be the value it has in the last collection listed (updated). Note: Makes a copy of the estimates and solver data so that there is no coupling between graphs.

DistributedFactorGraphs.packBlob — Function
packBlob

Convert a file (JSON, JPG, PNG, BSON, LAS) to Vector{UInt8} for use as a Blob. Returns the blob and MIME type.

DistributedFactorGraphs.printVariable — Method
printVariable(dfg, sym; kwargs...)

Display the content of VariableNodeData to console for a given factor graph and variable tag::Symbol.

Dev Notes

  • TODO split as two show macros between AMP and DFG
DistributedFactorGraphs.saveDFG — Method
saveDFG(folder, dfg; saveMetadata)

Save a DFG to a folder. Will create/overwrite folder if it exists.

DevNotes:

  • TODO remove compress kwarg.

Example

using DistributedFactorGraphs, IncrementalInference
# Create a DFG - can make one directly, e.g. GraphsDFG{NoSolverParams}() or use IIF:
dfg = initfg()
# ... Add stuff to graph using either IIF or DFG:
v1 = addVariable!(dfg, :a, ContinuousScalar, tags = [:POSE], solvable=0)
# Now save it:
saveDFG(dfg, "/tmp/saveDFG.tar.gz")
DistributedFactorGraphs.setTimestamp! — Method
setTimestamp!(dfg, lbl, ts)

Set the timestamp of a Variable/Factor object in a factor graph. Note: Since timestamp is not mutable setTimestamp! calls updateVariable! internally. See also setTimestamp

DistributedFactorGraphs.setTimestamp — Method
setTimestamp(v, ts; verbose)

Set the timestamp of a DFGVariable object returning a new DFGVariable. Note: Since the timestamp field is not mutable setTimestamp returns a new variable with the updated timestamp (note the absence of !). Use updateVariable! on the returened variable to update it in the factor graph if needed. Alternatively use setTimestamp!. See issue #315.

DistributedFactorGraphs.sortDFG — Method
sortDFG(vars; by, kwargs...)

Convenience wrapper for Base.sort. Sort variable (factor) lists in a meaningful way (by timestamp, label, etc), for example [:april;:x1_3;:x1_6;] Defaults to sorting by timestamp for variables and factors and using natural_lt for Symbols. See Base.sort for more detail.

Notes

  • Not fool proof, but does better than native sort.

Example

sortDFG(ls(dfg)) sortDFG(ls(dfg), by=getLabel, lt=natural_lt)

Related

ls, lsf

DistributedFactorGraphs.toDotFile — Function
toDotFile(dfg)
toDotFile(dfg, fileName)

Produces a dot file of the graph for visualization. Download XDot to see the data

Note

  • Default location "/tmp/dfg.dot" – MIGHT BE REMOVED
  • Can be viewed with the xdot system application.
  • Based on graphviz.org
DistributedFactorGraphs.updateBlob! — Function

Update a blob to the blob store or dfg with the given entry. Related updateBlobEntry!

updateBlob!(store, _, _)
updateBlob!(dfg, entry, data)
updateBlob!(store, entry, data)
updateBlob!(store, blobId, data)
updateBlob!(store, blobId, data)
updateBlob!(store, blobId, blob)

DevNotes

  • TODO TBD update verb on data since data blobs and entries are restricted to immutable only.
DistributedFactorGraphs.updatePPE! — Function
updatePPE!(dfg, sourceVariable; ...)
updatePPE!(dfg, sourceVariable, ppekey; warn_if_absent)

Update PPE data if it exists, otherwise add it. NOTE: Copies the PPE data.

DistributedFactorGraphs.updatePPE! — Function
updatePPE!(dfg, sourceVariables; ...)
updatePPE!(dfg, sourceVariables, ppekey; warn_if_absent)

Update PPE data if it exists, otherwise add it.

DistributedFactorGraphs.updatePPE! — Method
updatePPE!(dfg, variablekey, ppe; warn_if_absent)

Update PPE data if it exists, otherwise add it – one call per key::Symbol=:default.

Notes

  • uses ppe.solveKey as solveKey.
DistributedFactorGraphs.updateVariableSolverData! — Function
updateVariableSolverData!(dfg, variablekey, vnd; ...)
updateVariableSolverData!(
    dfg,
    variablekey,
    vnd,
    useCopy;
    ...
)
updateVariableSolverData!(
    dfg,
    variablekey,
    vnd,
    useCopy,
    fields;
    warn_if_absent
)

Update variable solver data if it exists, otherwise add it.

Notes:

  • useCopy=true to copy solver data and keep separate memory.
  • Use fields to updated only a few VND.fields while adhering to useCopy.

Related

mergeVariableSolverData!

DistributedFactorGraphs.@defVariable — Macro
@defVariable StructName manifolds<:ManifoldsBase.AbstractManifold

A macro to create a new variable with name StructName and manifolds. Note that the manifolds is an object and must be a subtype of ManifoldsBase.AbstractManifold. See documentation in Manifolds.jl on making your own.

Example:

DFG.@defVariable Pose2 SpecialEuclidean(2) ArrayPartition([0;0.0],[1 0; 0 1.0])
DistributedFactorGraphs.findShortestPathDijkstra — Method
findShortestPathDijkstra(
    dfg,
    from,
    to;
    regexVariables,
    regexFactors,
    tagsVariables,
    tagsFactors,
    typeVariables,
    typeFactors,
    solvable,
    initialized
)

Speciallized function available to only GraphsDFG at this time.

Notes

  • Has option for various types of filters (increases memory usage)

Example

using IncrementalInference

# canonical example graph as example
fg = generateGraph_Kaess()

@show path = findShortestPathDijkstra(fg, :x1, :x3)
@show isVariable.(fg, path)
@show isFactor.(fg, path)

DevNotes

  • TODO expand to other AbstractDFG entities.
  • TODO use of filter resource consumption can be improved.

Related

findFactorsBetweenNaive, Graphs.dijkstra_shortest_paths