Is your feature request related to a problem? Please describe.
A user may enter an unsupported filter when querying the SDK. Instead of just throwing an error, a list of supported filters should be logged to the user.

Describe the solution you'd like
A function that raises an exception in case of a wrong filter entry and prints out a list of supported filters by the Mapillary API v4

Describe alternatives you've considered
Instead of logging the whole list of supported filters, the function can print out a list of close matches to the user's input filter.

Utility Description
Create boilerplate functions for sending HTTP requests (e.g. GET, POST, etc...) and returning the responses from the queried API endpoints.

Describe the solution you'd like
The functions will take a bunch of kwargs:

• url The endpoint URL
• method HTTP method
• body the request body.
• headers the request headers.
• etc...

Describe alternatives you've considered
This is an initial solution. It will be edited and enhanced when implementing the utility.

Additional context
Simple Python API client
Building an API wrapper

Is your feature request related to a problem? Please describe.
What should the documentation look like? How can we automate the documentation aspect?

Describe the solution you'd like
Automating the documentation generation

Describe alternatives you've considered
ReadTheDocs has the problem that it only publishes from a public repository

Additional context
NA

I didn't find the issue templates to be all that useful. Sometimes it's nice to have the flexibility of a blank template.

Simple is better than complex
Complex is better than complicated

Is your feature request related to a problem? Please describe.
Related to #27

If a bounding box crosses the international dateline, then checking if an image/map feature point falls inside the bbox could fail.

For example if the bbox of [west,south,east,north] is: [174.375,-20.879342971957897,-169.5849609375,-11.566143767762844]

And a point is located at: (178.5498046875,-17.936928637549432)

Then the longitude of 178.54 will be > the west value longitude of 174.37 but also > the east value of -169.5849609375

Then it would return as false for a check to see if it is inside a bbox. It should be < the east value to pass the check.

If the west is a negative and the east is a positive, there is not a problem, only the inverse where west is positive and east is negative.

Describe the solution you'd like
We should do a dateline check, like:

bbox =  [west,south,east,north]  # these should be int values, using names for example here
if west is a positive number and east is a negative value:
    new_east = east + 360
    bbox = [west,south,new_east,north]

Describe alternatives you've considered
Considered generating a linestring geometry representing the dateline/antemeridian and checking if the bbox geometry intersects it, but this is a more expensive computation

Additional context
The issue here over is that the dateline is where the +/-180 degrees of a sphere "resets" from positive to negative, which can break out bbox check

Remove the util functions as they are not being used anywhere within the SDK.

I personally created the functions for req#2, but did not need them later on.

Is your feature request related to a problem? Please describe.
This issue deals with the 2nd requirement from the PRD over outputting getting "near image".

Describe the solution you'd like
NA

Describe alternatives you've considered
This feature has the following implementation needs,

1. A function taking a longitude, latitude as argument and outputting near the image
2. Options for fields to include with an “all” option or individual list. For the list of fields that can be sent to the API, check out https://blog.mapillary.com/update/2021/06/23/getting-started-with-the-new-mapillary-api-v4.html
3. Option for radius, default being within 200 meters or less.
4. Option for pano, flat, or both
5. Possible options: date filter, org key
6. Geometry is always a field included, this is NOT a parameter, but an option sent to the API when a request is made, check out https://blog.mapillary.com/update/2021/06/23/getting-started-with-the-new-mapillary-api-v4.html for more details

Additional context
This makes an API call with the token set in R01 and returns a JSON object. It may make sense to set an option for the response format to be GeoJSON which slightly reshuffles the data format.

Reference:

• Converting datetime.date to UTC timestamp in Python

See example at Step 9 here: https://towardsdatascience.com/build-your-first-open-source-python-project-53471c9942a7

This should be in the root directory.

We can list all of us as multiple authors. My full name is Christopher Beddow and email [email protected]. Use one string, as mentioned here: https://stackoverflow.com/questions/9999829/how-to-specify-multiple-authors-emails-in-setup-py

We still need to determine the license type, I must ask our Facebook legal team.

Is your feature request related to a problem? Please describe.
When requesting an object detection, a field called geometry is returned. This contains the pixel coordinates of the detection. For example, it contains the outline of a building which was detected in the photo with x,y coordinates in the image. It is encoded as a vector tile, so needs to be decoded in order to be used.

Example: https://graph.mapillary.com/1933525276802129/detections?fields=id,geometry&access_token=MLY|XXX

Describe the solution you'd like
A function should use the decode() method of mapbox-vector-tile library to convert the geometry field to a JSON. This would be a utility that can be used in another function, something like get_detections(image_key).

Describe alternatives you've considered
This could also be a public method, but makes more sense as a utility that can be reused when getting information about the detections in either an image key or a map feature.

Additional context
Detections are the segmentation in the image, where a class of object was detected, such as sidewalk, road, building, traffic sign, vegetation, or bench. Multiple detections are used to form point data, such as a bench with a longitude and latitude. In the API you can pass graph.mapillary.com/IMAGE_ID/detections to get a list of everything detected in an image, or graph.mapillary.com/MAP_FEATURE_ID/detections to get a list of all detections that were determined to be the same object from multiple angles, then combined to predict a point location. Users often want to get the detection pixel coordinates in order to draw this on top of a JPG or in the MapillaryJS image viewer library, to highlight a portion of the image that matches an object displayed on a map.

Is your feature request related to a problem? Please describe.
This issue deals with the 10th requirement from the PRD extracting all map features within a shape.

Describe the solution you'd like
Same requirement steps as in R09.

Describe alternatives you've considered
NA

Additional context
NA

As the title states, the daterange filter is to be removed as per PR #68, #13. Specifically, the following excerpts,

    # Line 28-37
    # If 'min_date' or 'max_date' is in the keys
    if ("min_date" in kwargs or "max_date" in kwargs) and ("daterange" in kwargs):
        
        # Check if two contradicting keys have not been given
        raise ContradictingError(
            contradicts="daterange",
            contradicted="min_date/max_date",
            message="Using either or both of min_date and max_date, or use daterange, "
            "but not both at the same time",
        )

And,

    # Line 66
    "daterange"

The exception ContradictingError has no other use case mentioned or discussed in any other utilities, models, requirements, or configurations, and has not come up in the project discussion. Thus, it can be safely removed for now and for the future.

See models/exception.py for ContradictingError.

This is to be solved after PR #68 is merged.

Is your feature request related to a problem? Please describe.
This issue deals with the 7th requirement from the PRD of getting a complete list of all images within a BBox

Describe the solution you'd like
The base requirements are,

1. Take BBox coordinates as an argument
2. Filter argument: date, pano/flat, maybe more

Describe alternatives you've considered
NA

Additional context
Output is a GeoJSON object. Could do the same for sequences and leave as an option to return either image (point) or sequences (line). Sequences would NOT be cut at BBox boundary, would select all sequences which are partially or entirely in BBox

Results need to be replicated and presented for ease of testing and reuse without having to write boiler plate code. Preferably, some method of pulling code from the API for base purposes.

The image endpoint has some unclear properties. They can be seen in the image below, such as,

• atomic_scale
• camera_parameters
• camera_type
• exif_orientation
• merge_cc

We need a folder in the main/root directory called "docs".

Sign up for an account at: https://readthedocs.org/

We should then use the following instructions to generate documentation with Mkdocs: https://docs.readthedocs.io/en/stable/intro/getting-started-with-mkdocs.html

We need to somehow create the docs then attempt to import to read the docs.

The generated documentation will go in the docs folder.

It should look similar to the setup in OSMnx library here: https://github.com/gboeing/osmnx

And we can model after the OSMnx library docs: https://osmnx.readthedocs.io/en/stable/

Is your suggestion related to something in the interface of the package?
As discussed in the discord chat, the vector tiles API in the APIv4 documentation may be included from having a constant zoom 14 level, to also including smaller images from zoom levels 15, 16, and 17.

Is your suggestion related to the documentation?
This issue will act as a thread to keep in check the code changes that might happen in relation to the documentation updates regarding zoom levels.

Any other request/features, and their solutions you'd like
NA

Describe alternatives you've considered
NA

Additional context

• Our API/tiles may start supporting zoom 14, 15, 16, and 17 soon, not just 14. This means we can download at smaller scales, what we discussed about breaking the download into smaller pieces might be worth thinking about just within this range of tiles. We will review some scenarios for this if the change happens
• Mercantile still will do this, if we do not specify the zoom size it will choose one, it tries to go for the smallest. But we could make it say,
  1. Get bbox from the user
  2. Request starting at zoom 14
  3. If only 1 tile is returned, then go to zoom 15. If only 1 still returned, go to 16, and so on until 17
  4. If multiple tiles are returned, then we are at the most efficient method already, so request each tile then trim the resulting features to return only what is in the box
  5. Download and merge the data from all tiles. Having multiple tiles means downloading the most specific to the bbox without too much extra data.

Describe the bug
The endpoint 'https://graph.mapillary.com/:image_id', when passed any other field other than geometry causes the API to fail. The error I get is similar to this,

{
   "error": {
      "message": "Tried accessing nonexisting field (altitude) on node type (ChunkObject)",
      "type": "MLYApiException",
      "code": 100,
      "fbtrace_id": "A514B-_ujHi2raqz20DgoGT"
   }
}

To Reproduce
Visit the API endpoint at the below link,

`'https://graph.mapillary.com/219262519730517/?fields=altitude,atomic_scale,camera_parameters,camera_type,captured_at,compass_angle,computed_altitude,computed_compass_angle,computed_geometry,computed_rotation,exif_orientation,geometry,height,thumb_256_url,thumb_1024_url,thumb_2048_url,merge_cc,mesh,quality_score,sequence,sfm_cluster,width&access_token=MLY|XXX

Expected behavior
A proper GeoJSON to be returned

Screenshots
If applicable, add screenshots to help explain your problem,

Additional context
This is related to the #13 issue, originally a comment on July 4th converted into this issue.

@cbeddow your thoughts?

Is your feature request related to a problem? Please describe.
This issue deals with the 2nd requirement from the PRD for saving the data retrieved from the API

Describe the solution you'd like
The base requirements are,

1. Takes a JSON or GeoJSON object as an argument
2. Takes path as an argument, default is current working directory
3. Takes format as argument: GeoJSON, shapefile

Describe alternatives you've considered
NA

Additional context
Relies on Fiona to get the proper driver for saving to shapefile format

Is your feature request related to a problem? Please describe.
This issue deals with the 11th requirement from the PRD over getting features from a key

Describe the solution you'd like
The base requirements are,

1. Takes image or map feature key as input and returns a JSON object for that key
2. Options: which fields to include, format
3. Geometry is always an included field

Describe alternatives you've considered
NA

Additional context
Consider if this should return a GeoJSON point object by default or should return just the JSON (no properties field with sub-properties, but instead flattened) as the graph API returns by default

Should this function and all others return all fields by default?

This should be an empty file for now, in the main directory, as a placeholder for the full Python library

Is your feature request related to a problem? Please describe.
It's not always feasible for humans to know the coordinates of a location. Numbers are already harder to remember, more so longer floating values like coordinates, and it can be annoying for users to go and handpick the coordinates. However, it is very easy to remember the names of locations, e.g., 'Cairo, Egypt'.

This function will return a bounding box of that location, which can then be fed into the API for the Mapillary Python SDK, for which results can be returned as desired.

Describe the solution you'd like
Some function that does all the underlying location -> coordinates logic at the low level. Either we make a utility function that users can use, or we make something as simple as the solution that osmnx suggests, which is just taking in a string, and outputting some results for that, not bothering users deal with the numerical logic as well

Describe alternatives you've considered
NA

Additional context
This idea was slightly discussed in the 1st Maintainer Meeting on the 24th of June

As the title states.

Is your feature request related to a problem? Please describe.
Related to #27 and #39

The user could pass bad values such as strange numbers or invalid values, or reverse the values like a latitude,longitude instead of longitude,latitude order

Describe the solution you'd like
We should consider a validity check here. A bbox should always consist of a (lon,lat) for the lower left (i.e. southwest) corner of a box, and (lon,lat) for the upper right (northeast) corner.

1. longitude range: has a min value of -180, a max value of 180
2. latitude range: has a min value of -90, max value of 90
3. latitude compare: in a bbox of [west,south,east,north] the value of south should always be smaller than the value of north (because south is lower, closer to -90, north is higher toward 90, even if both are negative)
4. longitude compare: in a bbox of [west,south,east,north] the value of west should always be smaller than the value of east, EXCEPT if the bbox crosses the international dateline, which we can check with #39. Technically any time that west > east it could cross the dateline, but could also be an error. If it passes the dateline test we should just consider it valid.
5. zero values: 0 is valid for all values in a bbox n a bbox of [west,south,east,north] the value
6. equal values: we should never see east == west and never see south == north. This produces a flat box or line that has no inner size to get data within

Describe alternatives you've considered
Alternative could be to let the user just get a message that the function fails and somewhere it will be due to an a invalid bounding box, but not made clear to the user

As the title states, it could be a good idea to have issue and PR templates that help to not waste too much time thinking of what the best way would be to write an issue or send a PR.

Having a template of headers of sorts would help in thinking about what the actual content is, rather than worrying too much about the structure of things, and would help in keeping things consistent as issues and PRs can themselves act as good documentation for a particular problem.

Please take a look at the below Python code and ask any questions or make suggestions to improve the code. This is not our real code, but we will want to make a function that appears like:

get_data(bbox,type,filter)

In this case bbox is the geographic bounding area, type is the API endpoint (points, traffic signs, images, sequences), and filter would likely want to use a format with an operator (>=, ==, <, contains, etc) for the properties of the returned data, for example a map feature in the example code matching the value for a street light, but we could filter also by date > than a given input.

We also want to consider a function that would save the data to file, maybe like saveGeoJSON(path).

import mercantile, mapbox_vector_tile, requests, json
from vt2geojson.tools import vt_bytes_to_geojson

# define an empty geojson as output
output= { "type": "FeatureCollection", "features": [] }

# vector tile endpoints -- change this in the API request to reference the correct endpoint
tile_points = 'mly_map_feature_point'
tile_traffic_signs = 'mly_map_feature_traffic_sign'

# Mapillary access token -- user should provide their own
access_token = 'MLY|XXX'

# a bounding box in [east_lng,_south_lat,west_lng,north_lat] format
east, south, west, north = [-80.13423442840576,25.77376933762778,-80.1264238357544,25.788608487732198]

# list of values to filter for and keep -- update this if changing to traffic signs
filter_values = ['object--support--utility-pole','object--street-light']

# get the tiles with x and y coordinates which intersect our bounding box, MUST be at zoom level 14 where the data is available
tiles = list(mercantile.tiles(east, south, west, north, 14))

# loop through all tiles to get IDs of Mapillary data
for tile in tiles:
    tile_url = 'https://tiles.mapillary.com/maps/vtp/{}/2/{}/{}/{}?access_token={}'.format(tile_points,tile.z,tile.x,tile.y,access_token)
    response = requests.get(tile_url)
    data = vt_bytes_to_geojson(response.content, tile.x, tile.y, tile.z)

    # filter for only features matching the values in filter list above
    filtered_data = [feature for feature in data['features'] if feature['properties']['value'] in filter_values]

    # check if features are inside bbox, and push to output geojson object if yes
    for feature in filtered_data:
        if (feature['geometry']['coordinates'][0] > east and feature['geometry']['coordinates'][0] < west)\
        and (feature['geometry']['coordinates'][1] > south and feature['geometry']['coordinates'][1] < north):
            output['features'].append(feature)

# save a local geojson with the filtered data
with open('mydata.geojson', 'w') as f:
    json.dump(output, f)

Over how to distinguish between image_id and map_feature_id to make sure that the correct IDs are passed to their respective endpoints and do not silently fail.

Dependency:

We must have at least 1 basic working function built into the library before pushing a test build

Start with step 10 here: https://towardsdatascience.com/build-your-first-open-source-python-project-53471c9942a7

• sign up for account at test.pypi.org (step 11)
• compile the library (step 10)
• push the library to test.pypy.org (step 12)
• verify that it is online (step 13)

This should be created in the main directory.

It should include the following dependencies inside it:

• pip==19.0.3
• wheel==0.33.1

Double check that those are the latest versions of pip and wheel, or add the latest version ID for Python 3.

We need to consider adding these libraries and latest version also:

• fiona
• mercantile
• mapbox-vector-tile

Describe the bug
Access token introduced under tests/utils by PR #43

To Reproduce
NA

Expected behavior
NA

Screenshots
NA

Additional context
Security concern!

To fix this, thought should be given on how when we write some tests, we can automate them. The primary concern is the access_token that I should not ever be exposed to. To fix this, I need to make my tests first set the access token, then run the tests to prevent any exposure at all. This should be a separate PR, and thus not be solely handled by #44.

The controller structure needed to serve as the basis for DocStrings, function prototypes and separates the components individually into different files.

Description

A filter needed for checking the max and min dates from user input against the returned first_seen_at and last_seen_at properties of the resulting GeoJSON

Related issue(s)

#19

Extra context

We have first seen and last seen. So I would say just first_seen_at with operators >=, >, ==, <, <== then same with last_seen_at

Is your feature request related to a problem? Please describe.
This issue deals with the 1st requirement from the PRD regarding setting the token for the user session

Describe the solution you'd like

The solutions available are,

1. A function allowing the user to set an access token for the session, which they can create at mapillary.com/developer
2. Takes token as an argument and sets a global variable used by other functions making API requests

Describe alternatives you've considered
NA

Additional context
Each API request requires a token, so we set the token one time, then it can be reused by all other functions.

Is your feature request related to a problem? Please describe.
We need to make sure that the queried features within a given bbox actually exist and are confined by that bbox. When using mercantile.tiles(), the return will be all the tile that intersect with the input bbox, some features within the intersecting border tiles may not exist within the bbox itself.

Describe the solution you'd like
The implementation will be a pure boolean function that takes in a feature object and a bounding box (east, west, north, south) that returns True if the feature exists within the bbox and False if it is not confined by the bbox.

Describe alternatives you've considered
To be considered

Additional context
Chris's implementation for inspiration

A list of IDs that can be widely used throughout the project would be great without having to extract what IDs are correct or not.

Is your feature request related to a problem? Please describe.
Required implementation of a utility that reformats a JSON input to a GeoJSON format.

Describe the solution you'd like
The implementation will be a pure function that takes in a JSON input, reformats it (e.g. nest all the properties under the properties attribute), and returns an appropriate GeoJSON

Describe alternatives you've considered
NA

Resources
RFC 7946 - Specification of GeoJSON

I've been reviewing some PRs today and found their descriptions to be super bloated. It would be easier to just look at the code and see what it does instead (actually, that's what I've been doing -- skipping the PR descriptions altogether). For not, since there's only a handful of people working on this, I see no need for such a template.

In the future, you might want to add a template to help guide the community contributions, but even then I think the template could be much more simple.

Simple is better than complex
Complex is better than complicated

DocStrings for documentation required for mapillary/controller/rules/verify.py.

Is your feature request related to a problem? Please describe.
This issue deals with the 1st requirement from the PRD for specifying two 2 sets of longitude, and latitude, where the 2nd set is the "looking at" location from 1st set's perspective.

Describe the solution you'd like
The base requirements are,

1. Takes 2 sets of longitude, latitude as arguments, with the same with same options as R02
2. Longitude, latitude set 1 is close to the location, same as in R02. Longitude, latitude set 2 is the “looking at” location
3. These can be the same or different.

The options mentioned above are,

1. Options for fields to include with an “all” option or individual list
2. Option for radius, default being within 200 meters or less
3. Option for pano, flat, or both
4. Possible options: date filter, org key
5. Geometry is always a field included

Describe alternatives you've considered
NA

Additional context
Maybe eliminate arguments being 2 sets of longitude, latitude, only have 1 longitude, latitude for looking at.

It may be useful to have the function exclude images that are too close to the looking at longitude, latitude, as if within 3 meters, as the returned photo may be too close to be useful. 10+ meters may be best

What shall we name the library?

Unofficially, we are calling this the Mapillary Python SDK.

When installing the library, it can have a shorter name. For example:

pip install library => pip install mapillary-python-sdk => pip install mapillary => pip install mlypy

or

import mapillary-python-sdk

import mapillary

import mlypy

//

We often use MLY as an abbreviation of Mapillary. The PyPI.org listing for mapillary is taken currently, but I know the creator of this and have attempted to contact him so we can take it over, so maybe this will be the best choice.

Any opinions are welcome.

Opening and changing the GitHub repository to public status will help in moving the documentation even further.

This issue is to keep a track of future ideas that might get turned into separate detailed issues on their own someday, but are only briefly mentioned here to keep in mind in the future as development progresses,

• About how to retrieve and ask for help over the different filters possible in filter.py

Saving this as a task list to keep in mind some things. Maybe there isn't enough time that we can dedicate to writing longer issues, so we can just add one-liner brief ideas that we come up with, and then develop them into longer, comprehensive issues in the future.

CC: @OmarMuhammedAli, @cbeddow

Is your feature request related to a problem? Please describe.
This issue deals with the 5th requirement from the PRD for extracting all detections made for a map feature key

Describe the solution you'd like
The base requirements are to,

1. Takes map feature key argument
2. Returns same as R04

Describe alternatives you've considered
NA

Additional context
NA

Is your feature request related to a problem? Please describe.
This issue deals with the 8th requirement from the PRD extracting all map features within a BBox

Describe the solution you'd like
The base requirements are,

1. Bbox coordinates as an argument
2. Layer as argument (points or traffic signs)
3. Filter argument 1: Value list as argument (only one value or multiple values or “all”)
4. Filter argument 2: other -- date first seen, last seen, more?

Describe alternatives you've considered
NA

Additional context
Maybe split this into 2 functions, one for traffic signs and one for points

Output is a GeoJSON object

It can be useful to tell the user what kind of filter_values are possible when dealing with filtering the value in `properties.

For example, in #1, we see filter_values as,

# list of values to filter for and keep -- update this if changing to traffic signs
filter_values = ['object--support--utility-pole','object--street-light']

But I was unable to find this list of filter_values in the API docs.

This is related to #27 as we can check if the filter values given are correct, and alert the user if they've passed in the wrong filter values, and even provide as the mechanism for help as discussed in the Discord Chat (I can't find the issue that was made for this?). This is similar to #48 , but in the context of a help function.

Help needed, @cbeddow

Some files throughout the project do not have consistent license and copyright fields within the project.

Is your feature request related to a problem? Please describe.
It is not really as much of a problem, as it is that of a feature request. It would be great if there was a way of visualizing results from mapillary via a bounding box. This can help in geospatial analysis for enthusiasts in data science or for developers who like to perform visual analysis in Jupyter notebooks. The results can look something similar to this,

The above images were selected from the Getting Started with the new Mapillary API v4 post on Mapillary - Blog.

Describe the solution you'd like
One-liners, much like in libraries, for example, in networkx, and matplotlib, where there is a very easy of quickly generating a graph to see what the results look like. More code like the discussion is to be had later in the future, but this can serve as a ground basis for starting from somewhere

Describe alternatives you've considered
We can use something like the Folium library that helps in performing GeoSpatial analysis.

Additional context
This idea was slightly discussed in the 1st Maintainer Meeting on the 24th of June

Is your feature request related to a problem? Please describe.
This issue deals with the 6th requirement from the PRD for getting the thumbnails of images from the API.

Describe the solution you'd like
The base requirements are,

1. Takes image key as an argument, returns a URL for the thumbnail
2. Options for thumbnail size, ranging from 320 to 2048 width

Describe alternatives you've considered
NA

Additional context
NA

Dependency on name selection in issue #2

This should be in mapillary directory and called mapillary.py. This will contain the bulk of our code.

Is your feature request related to a problem? Please describe.
This issue deals with the 4th requirement from the PRD for extracting all the detections within an image using an image key

Describe the solution you'd like
The base requirements are,

1. Takes image key as argument
2. Returns JSON with detections (segmentations of the image)

Describe alternatives you've considered
NA

Additional context
NA

Is your feature request related to a problem? Please describe.
This issue deals with the 2nd requirement from the PRD extracting all images within a shape

Describe the solution you'd like
The base requirements are,

1. Takes a GeoJSON object as argument
2. Same as R07 for other

Describe alternatives you've considered
NA

Additional context
NA