An outline of the common steps found in all the examples.
1) For a given projection, use its default projection builder , make changes to the scale, translation .. etc, then call build() to construct a projector.
```rust
let projector = Stereographic::<f64>::builder()
.scale_set(100_f64)
.translate_set(&Coord {
x: 300_f64,
y: 300_f64,
})
.clip_angle(90_f64)
.precision_set(&10_f64)
.build();
````
2) Construct a PathBuilder
A Path is a collection of nodes where each step on the path transforms the geometry object in some manner.
An object is then streamed along the path.
Here is an overview of the key nodes.
**Clipping**: Is the process of removing hidden geometry. When displaying a globe for example africa and australia will never been visible in the same view. Two strategies are used "Antimeridian" and "ClipAngle" [ See clip_angle_set() and clip_angle_reset() ]
**Resampling**: Dense geometry can be reduced by declaring a separation distance under which points, used to describe polygons and lines, are considered indistinguishable [ See precision_set() ]
**Bounding**: A projection space box can be set, and only geometry within this extent will be displayed. Polygons partially inside the box are restructured to conform to the edges of the box. [ See clip_extent_set() clip_extent_clear() ]
**Endpoints** are special path nodes which hold the result of a calculation. A variety of endpoint are available Area, Centroid, Length which can be use to compute properties about polygons or lines. These examples only show endpoints that render to a HTML canvas element or a SVG path element.
When rendering to a HTML canvas the endpoint holds Path2D "rendering context"
```rust
// Construct a PathBuilder linked to Path2d
// rendering context.
let path2d = Path2d::new()?;
let endpoint = PathBuilder::new(path2d);
let pb = PathBuilder::new(endpoint);
let path = pb.build();
```
When generating a SVG image, the endpoint holds a string value from which a PATH element can be constructed.
```rust
let pb = PathBuilder::pathstring();
let path = pb.build();
```
3) Please see the different examples, but the common next step is to
construct a PathBuilder object and then to stream a geometry object into it :-
```rust
// 'countries' is a geometry extracted from
// a world map json file.
path.stream(&countries)
```
Running the examples
Requirements:
To view an example application either create a development build, or construct a static-web site as follows
Start And Run A Development Build
console
git clone https://github.com/martinfrances107/rust_d3_geo.git
cd rust_d3_geo/examples/ring/
npm install
npm run start
The last command "npm run start" will automatically open your default browser at http:://localhost::8080
Performance: Building A Static Site
Much better performance can be achieved by building a static web site and viewing that directly. At the expense of longer build times the RUST portions of the code a build using the "--release" tags
console
git clone https://github.com/martinfrances107/rust_d3_geo.git
cd rust_d3_geo/examples/ring
npm install
npm run build
npm run serve
Benchmarking
The github repository associated with crate has two "profile targets" and two "benches"
which can be used to to spot bottlenecks in the code.
The benches are Criterion.rs based micro benchmarks.
See also rustd3geo_voronoi
uses this library, and that project contains a benchmark which contains an exact port of a benchmark in d3-geo-voronoi.
Based on that benchmark rust is 31% faster, or permits a 37% increase in throughput.
Flamegraph
A profile_target is binary that outputs a HTML page containing a SVG image showing the globe with graticule markings.
A flame-graph can be created by entering a particular profile targets directory and running :-
bash
cd profile_target/albers_usa
sudo CARGO_PROFILE_RELEASE_DEBUG=true cargo flamegraph
The complexity of rendering 240 countries/polygons provides a good view in memory allocation issues.
Coding Standard
- Idiomatic RUST, as defined by cargo clippy where possible.
No booleans as arguments to functions/methods, use two state enums instead.
See "Reflect" as an example.
rust
pub trait ReflectSet {
/// f64 or f32.
type T;
/// Set the projection builder to invert the x-coordinate.
fn reflect_x_set(&mut self, reflect: Reflect) -> &mut Self;
/// Set the projection builder to invert the y-coordinate.
fn reflect_y_set(&mut self, reflect: Reflect) -> &mut Self;
}
This allow for a clearer statement of intent :-
```rust
builder.reflectyset(Reflect::Flipped);
```
"Type-Driven API Design" is the
preferred way of constructing state machines.
In the example below, when assembling a stream pipeline, connect() can only be called
when the state is "Unconnected". The output type's STATE is "Connected\
rust
impl StreamTransformRadians<Unconnected> {
#[inline]
/// Connect this node to the next element in the pipeline.
pub const fn connect<EP, SINK, T>(self, sink: SINK) -> StreamTransformRadians<Connected<SINK>>
where
SINK: Clone,
{
StreamTransformRadians(Connected { sink })
}
}
The "Stream" trait is only implemented when the STATE is "Connected\
Future 2.0 upgrades
Version 1.0 is stable.
"Semantic Versioning" guidelines :-
- Increment the major number when a breaking change occurs.
- Increment the minor number when a new feature is added, @deprecated notes added to outdated functions,
- Increment the patch number for tightly focused security fixes.
Future Work.
Architecture discussion
There is an aspect of the design that needs review. It related to the best way to implement a doubly-linked list which has cross links between nodes.
The clipping algorithm in clip/rejoin/mod.rs needs to be refactored.
see The intersection Problem.
Test coverage in that area is high so the algorithms is working but the data structures make extensive use of vectors ( heap objects ) containing references to other heap objects Vec<Options<Rc<RefCell<_Intersection_>>>> which is not performant.
A full discussion can be found here
Unimplemented sections of the library
Support for a custom projection is not yet supported.
For an example of this see the test labelled "projection.fitExtent(…) custom projection"
