Documentation ¶
Overview ¶
Package index implements a stream-able geospatial index on positions in Cartesian 3-space.
Object-positions go in, and proximity (or "conjunction") reports come out.
Indexing is based on cells that cover S2.
The primary function is NewIndex, and the primary method is Update.
Index ¶
- func AtLess(a, b At) bool
- func Diff(oldCs, newCs []Conj) ([]Conj, []Conj)
- func PrintCs(cs []Conj, prefix0, prefix string)
- type At
- type CatalogNum
- type Cell
- type CellFinder
- type CellId
- type Conj
- type Id
- type IdProbPos
- type IdProbPoss
- type Index
- type IndexData
- type Key
- type Level
- type Pos
- type Prob
- type ProbPos
- type Publisher
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AtLess ¶
AtLess specifies the canonical order on At instances.
We make the computation completely explicit rather than rely on a more indirect algorithm.
Types ¶
type CatalogNum ¶
type CatalogNum uint32
CatalogNum is shared identity of the focal object.
This whole concept is perilous, but we'll attempt to use it as best we can.
Currently these identifiers are assigned by the United States Space Command; however, we plan to be able to extend this namespace at least a little (within the current confines of four bytes, which could of course change in the future).
A publisher of an unassigned object needs to take care to use a number that won't conflict with use of that number by a different publisher! Yes, this approach will become problematic, but we need this notion here in order to avoid reporting the conjuction of two views of the same thing.
The number zero represents an unknown value. In this case, any other position report is a candidate for an emitted conjunction. With that exception, no conjunction report is emitted based on two reports that have the same CatalogNum.
type Cell ¶
type Cell struct {
// contains filtered or unexported fields
}
Cell represents a set of IdProbPos in an S2 cell.
type CellFinder ¶
type CellFinder struct {
Level *Level
}
CellFinder maps a position to a cell.
func NewCellFinder ¶
func NewCellFinder(level int) *CellFinder
type Conj ¶
Conj represents an opinion about the proximity of two objects (at some unspecified time).
type Id ¶
type Id uint32
Id represents the distinct report in its totality (as far as this package goes). Two reports that are "equal" should have the same id.
We are using only four bytes to conserve RAM.
Re "Id" vs "ID": I'm in the "Id" is an abbreviation, not an acronym camp, and I've been there (rightly or wrongly) for a long time. https://github.com/golang/lint/issues/89 says I'm wrong -- at least as far as Go sources go. Had I known at the time, I probably would have complied.
type IdProbPos ¶
type IdProbPos struct { Id CatalogNum ProbPos }
type IdProbPoss ¶
type IdProbPoss struct { Id CatalogNum PPS []ProbPos }
IdProbPoss is a set of IdProbPos for a given object.
type Index ¶
type Index struct { Dist float32 CellFinder *CellFinder IPPS map[Key]*IdProbPoss Cells map[CellId]*Cell }
Index receives object positions and returns "conjunctions".
This implementation is not safe for concurrent use.
func NewIndex ¶
NewIndex creates a new index based on cells with the given level and uses the given distance as the maximum distance for "conjunction" determination.
func NewIndexWithFinder ¶
func NewIndexWithFinder(finder *CellFinder, dist float32) *Index
NewIndexWithFinder allows the caller to provide a CellFinder that can be used for multiple indexes.
func (*Index) Search ¶
Search is the core method for finding Conjs.
This implementation is not safe for concurrent use.
func (*Index) Update ¶
Update updates the index and returns canceled Conj(s) and new Conj(s).
This implementation is not safe for concurrent use.
The key is for the given set of ProbPos, which should be complete for the key. For example, if the key represents the combination of a satellite and a publisher of information about that satellite, then an Update call with that key should provide the publisher's complete knowledge for that key.
The id should represent data that was used to generate this knowledge. These ids are included in the returned Conj, so a caller can do additional processing (like scanning for closer approaches) after retrieving the source data that an id identifies.
The returned Id (if any) is the id of the previous Update call for the given key.
Some of the constants in this method body relate to tuning (such as Level). The coarser the cells, the larger the initial allocations. ToDo: Expose these values.
type Key ¶
type Key struct { CatalogNum Publisher }
Key is the key for storing positions in the index.
In an Index, a CatalogNum+Publisher has can have a single opinion of that object's position(s). Note that that opinion can include multiple possible positions.
type Level ¶
type Level struct { Level int Coverer s2.RegionCoverer }
func NewLevel ¶
NewLevel generates a Level with a Coverer with min and max levels both at given level.
type Pos ¶
Pos is the object's state.
Currently this state only includes position (ECI).
If we add velocity, then the index could sample Conjs with low relative speeds. For objects parked together, every index would emit an Conj. The resulting downstream relative computational load is unknown but possibly significant. However, most of that load is (I think) typically spread across all cores. Adding velocity results in a memory increase of maybe 40%. The guiding principle was to optimize for memory, so we'll stick to that principle for now. ToDo: Reconsider.
type Prob ¶
type Prob float32
Prob represents uncertainty (without any index-imposed meaning).
Can update this definition to support more dimensions, but of course we're mindful of memory consumption.