Skip to content

update docs w sampling data formats #895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 29, 2022
Merged

update docs w sampling data formats #895

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3dab6e9
update docs w sampling data formats
dehann Jul 26, 2022
b44bd69
Update docs/src/examples/custom_relative_factors.md
dehann Jul 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions docs/src/examples/custom_relative_factors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,17 @@ end
```
New relative factors should either inheret from `<:AbstractManifoldMinimize`, `<:AbstractRelativeMinimize`, or `<:AbstractRelativeRoots`. These are all subtypes of `<:AbstractRelative`. There are only two abstract super types, `<:AbstractPrior` and `<:AbstractRelative`.

## Summary of Sampling Data Representation

| Usage | `<:AbstractPrior` | `<:AbstractRelative` |
|-------------|--------------------|-----------------------|
| `getSample` | point `p` on Manifold | tangent `X` at some `p` (e.g. identity) |

| Usage | |
|-------------------|----|
| `sampleTangent` | tangent at point `p` or the identity element for groups |
| `rand` / `sample` | coordinates |

## Specialized Dispatch (`getManifold`, `getSample`)

Relative factors involve computaton, these computations must be performed on some manifold. Custom relative factors require that the [`getManifold`](@ref) function be overridded. Here two examples are given for reference:
Expand Down Expand Up @@ -47,7 +58,7 @@ function getSample(cf::CalcFactor{<:Pose2Pose2})
end
```

The return type for `getSample` is unrestricted, and will be passed to the residual function "as-is".
The return type for `getSample` is unrestricted, and will be passed to the residual function "as-is", but must return values representing a tangent vector for `<:AbstractRelative`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this might be the other way around, getSample on <:AbstractPrior must return a Point on manifold, on Relative, it is unrestricted, but we recommend a tangent vector TpM.
I'll try and find the issue where this was discussed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

JuliaRobotics/IncrementalInference.jl#1371

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

JuliaRobotics/RoME.jl#465

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tangent on relative factors -- that's what the PR already has, no? "a tangent vector for <:AbstractRelative"


!!! note
Default dispatches in `IncrementalInference` will try use `cf.factor.Z` to `samplePoint` on manifold (for `<:AbstractPrior`) or `sampleTangent` (for `<:AbstractRelative`), which simplifies new factor definitions. If, however, you wish to build more complicated sampling processes, then simply define your own `getSample(cf::CalcFactor{<:MyFactor})` function.
Expand All @@ -70,11 +81,11 @@ function (cf::CalcFactor{<:Pose2Pose2})(X, p, q)
end
```

It is recommended to leave the incoming types unrestricted. If you must define the types, make sure to allow sufficient dispatch freedom (i.e. dispatch to concrete types) and not force operations to "non-concrete" types. Usage can be very case specific, and hence better to let Julia type-inference automation do the hard work of inferring the concrete types.

!!! note
At present (2021) the residual function should return the residual value as a coordinate (not as tangent vectors or manifold points). Ongoing work is in progress, and likely to return residual values as manifold tangent vectors instead.

It is recommended to leave the incoming types unrestricted. If you must define the types, make sure to allow sufficient dispatch freedom (i.e. dispatch to concrete types) and not force operations to "non-concrete" types. Usage can be very case specific, and hence better to let Julia type-inference automation do the hard work of inferring the concrete types.

### Serialization

Serialization of factors is also discussed in more detail at [Standardized Factor Serialization](@ref factor_serialization).