Rust D3 Geo

Rust 2021 Edition.

This is a port d3-geo into RUST.

A collection of d3 sub packages is being ported to rust.

• d3geors
• d3delaunayrs
• d3geovoronoi_rs

Current Status

The majority of the library has been ported along with the associated tests.

The 1.0 release is close, within one week.

Currently I am reviewing the data structures, and looking for performance improvements before things become locked down and I support backwards compatibility guarentees.

When to use the rust version of the library

The limits of the javascript library become obvious when developing interactive applications that process large datasets. For example the examples/globe applications operate on a 1:50M resolution map of the earth. On a desktop machine this is beyond the javascript version.

Examples

These Examples are provided to help developers convert their existing javascript to rust. They can be found in the github reposository associated with this crate.

examples/globe/rotating This is a port into rust of this d3-geo example www.d3indepth.com/geographic/ This globe is rendered to a HTML CANVAS element. For perfomance reasons this example is best viewed by running cargo build and then "cargo serve" which compiles the rust code using the --release flag. (Scale 1:50M)
examples/globe/svg The globe is rendered as a SVG image. 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 This globe is rendered to a HTML CANVAS element 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. (Scale 1:50M)
examples/projections This globe is rendered to a HTML CANVAS element 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. (Scale 1:50M)
examples/globe/albers_usa The globe is rendered as a SVG image. 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 SVG example Sample code in both RUST and javascript that renders a complex multipolygon. ( Orthographic and Sterographic )

Here is an outline of the common steps found in all the examples.

1) Take a projection's default builder, make adjustments, 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.

A variey of endpoint are available Area, Length, Centroid, but these examples deal
only with rendering to a HTML canvas element or a SVG path element.

When rendering to a HTML canvas element build path from a Path2D "rendering conext"

  ```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();
  ```

Generating a SVG image

  ```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 extratced from
     // a world map json file.
     path.stream(&countries)
  ```

Running the examples

Requirements:

• node and npm installation guide

• wasm-pack installation guide

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

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.

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\

Future 2.0 upgrades

Version 1.0 is about to become public, where major changes are discourged.

• 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.

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.

A full discusion 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"