georust/tilejson

Library for serializing the TileJSON file format

tilejson

tilejson is a crate for serializing/deserializing the TileJSON format — an open standard for representing map metadata.

Examples

Reading

use tilejson::TileJSON;

fn main() {
    let tilejson_str = r#"{
        "tilejson": "3.0.0",
        "name": "compositing",
        "scheme": "tms",
        "tiles": [
            "http://localhost:8888/admin/1.0.0/world-light,broadband/{z}/{x}/{y}.png"
        ]
    }"#;

    // Parse JSON
    let mut tilejson: TileJSON = serde_json::from_str(&tilejson_str).unwrap();
    println!("{tilejson:?}");
   
    // Add missing default values per TileJSON specification
    tilejson.set_missing_defaults();
    println!("{tilejson:?}");
}

Writing

use tilejson::tilejson;

fn main() {
    let tilejson = tilejson! {
        "http://localhost:8888/admin/1.0.0/world-light,broadband/{z}/{x}/{y}.png".to_string(),
        name: "tileset name".to_string(),
        description: "some description".to_string(),
    };

    let serialized_tilejson = serde_json::to_string(&tilejson).unwrap();

    println!("{serialized_tilejson}");
}

Contributing

Contributions are welcome! Have a look at the issues, and open a pull request if you'd like to add an algorithm or some functionality.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

tilejson's Issues

crates publishing teams

👋 Hi @stepankuzmin!

I'm following up on georust/meta#21 — not sure if you got a chance to read that.

You are the only "user-owner" of the tilejson crate on crates.io, so only you can edit that crate's owners. (edit: 🤦 copy-pasta typo)

The tldr; is that a while back, we started adding the georust/core team as a "team-owner" for all georust crates - this gave some redundancy in case the original owner became inaccessible. However, as the org has grown (🎉), this has resulted in lots of (probably too many) people having access to publish all crates, so we're scaling back the publishing teams to be just the group of people who are actually publishing that crate.

Since your crate has the distinction of never having added the georust/core team as an owner, there's no cleanup to do.

However, would you still be willing to add a publishing-team as a team owner? It can remain empty for now if there's no one else publishing, but the idea is that georust admins (currently @urschrei and @frewsxcv) could add/remove people to that team if you became inaccessible. Note that "team owners" on crates.io can't themselves edit the owners of the crate, only "user owners".

Specifically:

Step 1: Create your publishing team

Go to https://github.com/orgs/georust/new-team and enter the name tilejson-publishers and the description "crates.io publishing for the tilejson crate"

Add any additional publishers to the team at this point (or not). If you mark them as team maintainers, they will be able to edit the team themselves in the future.

Step 2: Update crate owners

cd my-crate
cargo owner --add github:georust:tilejson-publishers

# make sure everything looks good 👀 
cargo owner --list

---

Let me know if you have any questions, or you can review georust/meta#21.

Add "Geospatial" category to `Cargo.toml`

rust-lang/crates.io@9b65b4c

https://doc.rust-lang.org/cargo/reference/manifest.html#the-categories-field

Incorrect `center` field type

The center field is declared as center: Option<Vec<i32>>, which does not match specification:

OPTIONAL. Array. Default: null.
The first value is the longitude, the second is latitude (both in WGS:84 values), the third value is the zoom level as an integer. Longitude and latitude MUST be within the specified bounds. The zoom level MUST be between minzoom and maxzoom. Implementations MAY use this center value to set the default location. If the value is null, implementations MAY use their own algorithm for determining a default location.

{
  "center": [ -76.275329586789, 39.153492567373, 8 ]
}

Possible solutions

I think we should use this opportunity to improve the bounds value as well.

tuple

center: Option<(f32, f32, u8)>,
bounds: Option<(f32, f32, f32, f32)>,

structured

Per serde-rs/serde#637, uses serde_tuple crate.

#[derive(Serialize_tuple, Deserialize_tuple)]
struct Center {
  pub longitude: f32, 
  pub latitude: f32, 
  pub zoom: u8, 
}

#[derive(Serialize_tuple, Deserialize_tuple)]
struct Bounds {
  pub left: f32, 
  pub bottom: f32, 
  pub right: f32, 
  pub top: f32, 
}

...
center: Option<Center>,
bounds: Option<Bounds>,

Rework instantiation to be more useful and consistent with the spec

There are two usecases for this lib -- with and without defaults:

• A typically use case with defaults -- a client code that gets a JSON, resolves maxzoom to 30 if missing, and takes actions like loading tiles.
• Without defaults -- a tile server needs to create and send a minimal tilejson, e.g. if it doesn't support grids value, it shouldn't set it to the default [ ], but instead not set it at all.

Current API actually does the opposite -- the client use-case" serde_json::from_str(str) ignores tilespec defaults, while the server use case with TileJSON::new() sets the defaults.

Also, per specification, several fields must be present from the start, so it would make sense to introduce them as arguments:

"tilejson": "3.0.0",
"tiles": [
    "http://localhost:8888/admin/1.0.0/world-light,broadband/{z}/{x}/{y}.mvt"
  ],

When instantiating, tilejson could still be defaulted to the current version, i.e. 3.0.0. The tiles on the other hand MUST be a non-empty array.

Proposed API (breaking)

impl TileJSONBuilder {
  /// create a builder with tilejson = 3.0.0 and tiles = [ source ]
  fn new(source: String) -> Self {}
  /// create a builder with custom version and possibly multiple sources.
  /// If version is None, will use current default.
  fn new_ext(sources: Vec<String>, version: Option<String>) -> Self {}
  /// generate TileJSON **without** defaults.  Breaking change, so new method name.
  fn build() -> TileJSON {}
  // remove fn tiles(...)
}

impl TileJSON {
  /// consume to ensure each optional value has a proper default per spec. Name is TBD
  fn with_defaults(self) -> Self {}
}

Note that "vector_layers" is required conditionally - depending on the type of the tiles, so in our case we could treat it as optional unless we want to perform validation.

cc: @stepankuzmin @maxammann @Drabble @ka7eh

migrate CI to GH actions

I noticed you still have a .travis.yml

I believe free CI on travis-ci.org has been canceled since about June. Also, travis-ci recently had a nasty bug (and a not great response to said bug).

Almost all of the other georust projects are running on GH actions, would you be interested in migrating?

I could help with this if you have questions or lack the time.

Publishing to crates.io

Hi @stepankuzmin , are you the only person who publishes this crate to crates.io? I see that github team georust:tilejson-publishers also has that right, and I was wondering if you want me to participate in that process? I do plan to add a number of other features to this crate, possibly some validation code, etc. Thanks!