examples/globe/canvasrotating50m
This is a port into rust of this d3-geo example www.d3indepth.com/geographic/.
For perfomance reasons this example is best viewed by running "cargo build" and then "cargo serve" rather the running the development build.
(Scale 1:50M)
|
|
examples/globe/svg
SVG are useful when the semantic meaning of the data needs to be preserved. The example shows how to load/parse/display the globe as indivdual SVG PATH elements. It also includes code samples that generates SVG graticules.
(Scale 1:50M) |
|
examples/globe/dragandzoom
As an example it deliberately mixes typescript methods with rust.
The typescript is responsible for handling the mouse events and calculating the quaternion and finally calculating the appropiate change in rotation. In a typescript render loop calls to a rust function render the globe.(Scale 1:50M)
This example is currently undergoing rapid development.
|
|
examples/projections
As a confidence building exercise, this demo
shows a side by side comparison of the all the projections rendered by in both javascript and rust. |
|
examples/globe/albers_usa
This example show all the counties in the USA
AlbersUSA is unlike the other projections.
Alaska and Hawaii are rendered as insets.
As can be see in the code a Multidrain must be used to gather the three projections.(Scale of 1:10M)
|
|
examples/ring
Sample code in both RUST and javascript that renders a complex multipolygon. ( Orthographic and Sterographic ) |
|
Here is a summary of things to-do before the crate is published.
The recenter state-based API refacor is almost complete.
Once fitsizeresampling() is reinstated the code-coverage metric will jump 10% back to the previous value of approx 82%
The API is not stabalised. If perfomance issues arise then the API will change. Additionaly I plan a final review to remove anything uneeded before making changes become complicated.
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 algortihms is working but the data structures make extensive use of vectors ( heap objects ) containng references to other heap objects Vec<Options<Rc<RefCell<_Intersection_>>>> which is not performant.
Running the examples
Requirements:
To view the application either create a devleopment 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 acheived by bulding a static web site and viewing that directly. At the expense of longer build times the RUST protions 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
See the details.
In this project, we have two benchmarks, based on the ring and graticule examples ( see above. )
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
profile_target is binary that outputs a HTML page containing a SVG image showing the globe with graticule markings.
A flamegraph can be created with the following
bash
cd profile_target
sudo CARGO_PROFILE_RELEASE_DEBUG=true cargo flamegraph
The complexity of rendering 240 countries/polygons provides a good view in memory allocation issues.
Future Multi thread support
rayon is rust's crate for multithread support.
I have made extensive use of iterators when porting the code and rayon support the easy conversion of single threaded iterators to multithread iterators.
The Hashmaps - appear slow.
Maybe I can get performace improvements by replacing them with B-tree collections?
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. A full discusion can be found here
Coding Standard
- Idomatic 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\
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"
I am trying to get a program of mine to run faster, but I want this to eventually be a true library port. So feel free to add suggestions to my todo list.
Other To-do's
Document API changes such as
- src/projection/clipanglereset()
- src/projection/clipextentclear()
Finally
todo.md contains a more detailed list
