Design a Front-End Application to Demonstrate eoAPI Capabilities

[zacharyDez]

Design a Front-End Application to Demonstrate eoAPI Capabilities

We aim to build a front-end application that can effectively demonstrate the capabilities of eoAPI. In the short term, this application will be a demonstrative tool on our eoAPI website and be shipped within eoAPI as an onboarding tool.

Features

The application should include the following basic features:

• Ability to browse STAC data by collection, space, and time, highlighting stac-fastapi.
• Ability to see STAC items dynamically visualized on a map, highlighting titiler-pgSTAC.
• Ability to link to a data source to start building, highlighting pgSTAC.

Out of Scope

The following features are not included in the first version of this application:

• Ability to browse/filter STAC data by size, cloud cover, etc.
• Ability to analyze STAC data through comparisons, charts, etc.
• Ability to download STAC data from the user interface.

Acceptance Criteria

The acceptance criteria for this task are to link to our design work (low fidelity, mock-ups) and gather feedback from the team and the community.

Additional Steps

We need to ping Oliver to see if he has any additional requirements for this application.

Success Metrics

Success for this task is defined as helping users effectively onboard eoAPI and providing them with an easy tool to demonstrate the different components of eoAPI. The application should also serve as an example for other front-end applications to get started.

Next Steps

Please provide your feedback on the proposed features and any additional requirements you might have. Your input is precious as we aim to create an application that effectively demonstrates the capabilities of eoAPI and aids users in onboarding the tool.

[zacharyDez]

@heidimok @vincentsarago @oliverroick , please let me know if you think of other requirements. Also, can you review the features list to include and exclude? I think you may have a better understanding of the details required to demonstrate the intricacies of eoAPI @vincentsarago .

[oliverroick]

Thanks for putting this together; it seems like a reasonable scope for an initial solution.

One question:

Ability to link to a data source to start building

I don't understand what this means, "to start building," in this context Can you clarify?

[heidimok]

@oliverroick I think @zacharyDez took that from the planning doc that I had put together and what I meant there was that a user would have the ability to link to the source data. I was thinking about the context that users would want to get a url to the data source so that they could then start building their own platforms/tools/features based on that data.

Another related question is:

• What (if any) STAC data is available to browse as part of the demo app? Would users be able to immediately browse all STAC data like the Radiant earth STAC-Browser or do they have to add data in order to see it?
• To what extent is the demo API offering a browsing experience like STAC-Browser vs. a catalog/items exploration experience like PLANET-STAC?

For the requirement around dynamic visualization:

• Is the UI limited to allowing users to view a single cloud-optimized geotiff at a time on the map or could they select multiple cogs and see them shown at the same time on a map?

[heidimok]

UI update Aug 2, 2023:

• I started on a design to give everyone a more visual starting point for what a demo app could be like. I'll need to pause for the rest of this week but will give time for comments and come back next week.
• The goal of this first iteration is to help people onboard to eoAPI by helping them understand how the services are connected.

Link to clickable prototype

• Instructions: Click on the prototype screen to see blue boxes around things that are clickable.

Link to design file in Figma

• Instructions: Zoom in and out of the board to see the different screens

In both cases, add comments by clicking on the comment button

---

Design decisions

• Style and UI Components - I followed the look and feel of ds-connect only using components already built there like the widget. I imagine we use the same states as well so I didn't bother prototyping them (like the hover over a list is the same as in ds-connect). I think this allows for a simple DevSeed look and feel without recreating new components.
• UX - I mostly followed the Planet Stac application but just tweaked the layout a bit. So thinking/hoping that this is kind of an extention or iteration of that app.
• Features - Intentionally limiting. We focus on the basics and lets users build versions of this (using this UI as a starter or their own UI) rather than trying to create a "swiss army knife" system that would be difficult to maintain over time because it has to be so flexible.

Key screens

• Home is an instructional view and provides users with a bit of direction on what to do. Ideally we can offer users with 1-3 collections to explore immediately. But they can also go to STAC browser to find other STAC APIs.

• Explain what this demo is, and what it isn't. I made a point to highlight this here because it's a reminder that this meant to link users back to the API, not use the UI in itself as the end product.

• Once a STAC is selected, users can look for a collection. Here we can decide if it's important to show the full collection or just allow a few for the purpose of the demo. If we show the full collection, a text search could be handy (but nice to have)
• Once a collection is selected, the query and items tabs are enabled.

• The query tab showcases how users can filter the catalog
• I have intentionally limited the filters here as a first release to focus on time, location, and media type (E.g. cogs)
  • By default, a toggle for only displayable items is turned on so that it's more likely the users will have something visual to see on the map
• In the future it could be possible to display all relevant filters based on the STAC selected (E.g. cloud coverage) such that the filters change every time. But it's unclear right now if that kind of functionality is needed for a demo and would require more thinking.

• The items tab lists items in a given collection
• If a query was made, the list would be filtered down
• For this release, users can only select a single item at a time (no multi-select to see a mosaic)

• Similar to Planet Stac, when users click into an item, they can see the preview asset and other metadata
• The map would zoom in to the appropriate place in the world where that asset exists

This is pretty much the full scope I'm proposing at this time.

Next steps:

@oliverroick would love to get your feedback as comments in the prototype on anything from questions about the flow to the UI components. As a first release are there ways to limit this even more or areas you think we could expand?
@vincentsarago does this appropriately highlight key aspects of the eoAPI as a first release? What really key features would you like to see included?
@zacharyDez we already reviewed this together but you're welcome to add thoughts here as well or tag anyone else who you think should provide direct feedback

[vincentsarago]

🙏 thanks @heidimok for this

does this appropriately highlight key aspects of the eoAPI as a first release? What really key features would you like to see included?

eoAPI has 4 components:

• Metadata Database (pgSTAC)
• A Metadata Service (stac-fastapi)
• A Raster Dynamic Tiler (titiler / titiler-pgstac)
• A Vector Dynamic Tiler (tipg)

In this first design, we can see the metadata search part which will use the metadata service but none of the 2 other services (raster/vector). TBH, it's not clear yet how the Vector service could be used but we should make sure we use the Raster one.

Raster Tiles

The raster service enables 2 things:

Per Item visualisation

For Item viz, user should be able to either visualize one asset or mix the assets bands (assuming each assets is one band)

demo: https:/
/raster.eoapi.dev/collections/MAXAR_Kahramanmaras_turkey_earthquake_23/items/37_031133101031_10300100E2780300/viewer

Options:

• assets selection
• band combination / band selection (rgb or pan)
• data rescaling (if the data is not of type Uint8)
• colormap selection
• band math expression (optional)
• color formula (optional)

Per Collection visualisation (a.k.a Mosaic)

In theory, titiler-pgstac can create mosaic tiles from any STAC Search (https://stac-utils.github.io/titiler-pgstac/intro/#2-fetch-mosaic-tiles) but in pratique this is not as simple because to be able to create a tile we HAVE TO have the same set of assets for each items returned by a search query.

The flow of creating a mosaic tile is as:

• user register a search request (it's what I've try to design in https://raster.eoapi.dev/mosaic/builder)

  • select a collection
  • apply filters (spatial, temporal, based on items properties, ....)
  • Optional: Ideally, the user could define a set of default visualizations for this search (we could also add some in the collection metadata)

• Once a search is registered, the service will return a mosaicid to be used in each tile request

demo: https://raster.eoapi.dev/mosaic/81abc4dcd1834417b031f23b1366c16e/map?assets=visual&minzoom=12&maxzoom=18

Mosaic Gotcha:

• we need to select assets found in all the items (returned by the search)
• we can't know the datatype of the assets (then if we need rescaling)
• we can't know the min/max zoom covered by the assets (we could probably find this using collection metadata)

[heidimok]

UI update Aug 16, 2023:

• I read through feedback from Oliver (in Figma), Vincent (above), and Zac (1:1 meet) and refined the designs
• The goal of this second iteration is to get closer to a future state vision, while considering how the UI can be 'chunked out' into smaller releases

Key Updates

• Separating key services into discrete demo panels/widgets on the UI
• Adding the raster service to the designs
• Not shown: the vector service - TBD

Link to clickable prototype

Instructions: Click on the prototype screen to see blue boxes around things that are clickable.

UI Overview

• Landing page encourages users to first make sure they have data ingested (otherwise nothing shows up on the UI)
• Top nav has buttons that link to each of the service demos

Metadata Service

• Indicates the ingested data catalog. If no data is ingested, the panel is empty with a helper note
• Allows users to select 1 or more collections in the catalog

• Once users select catalogs they can then browse items in the catalog

• If they want to filter, they can bring up a modal. Here we focus on date range, but only letting users input date ranges that match the data available

• Once a user selects an item, they can see a preview and asset information
• Instead of listing too much detail, we can provide a dropdown that lets users see the JSON object themselves
• At the bottom, perhaps we can provide an option for users to use this item as the starting point for demoing the raster visualization service

Raster Service

Mosaic Building

• This part of the demo could be a second release
• The raster service would have two sub-capabilities to demo (as per Vincent's notes above)

• The Mosaic Builder lets users select a collection from their ingested dataset and then toggle between item or mosaic view

• Users can apply some filters, however, we may want to restrict options because filters would change based on the data. The queryable end points gives you a list of the filters you can query on. But based on that, do we dynamically change the UI so that users can filter? (select, toggle, checkbox, etc). This is a UI challenge that requires us categorizing types of data with the right UI filter.

Item Visualization

• The Item Visualization feature lets you visualize a specific item asset
• We could connect this feature with the metadata service feature so that an item being viewed there could automatically be populated here.

Vector Service

• TBD - probably looks a bit like the raster UI as a mosaic builder, but needs to be discussed more

Next Steps

• I already reviewed this with @zacharyDez
• Would appreciate feedback from both @oliverroick and @vincentsarago (when back from vacation)

[oliverroick]

I’m still confused about what we’re trying to achieve with this frontend. The new design feels very disjointed; it showcases the individual services that are bundled with eoAPI. This might work for people who know what these services are and what they do but if you want to convince someone to adopt eoAPI, I’m not sure if they will be able to make sense of this.

For example, you can search for items in two different areas, then there’s item visualisation and mosaic visualisation. It's not clear what the difference between item and mosaic visualisation is and how the mosaic visualisation works. I understand, you can take a collection and render a mosaic of its items, but I can only see a bounding box in the demo that Vincent linked. Is there a step missing that is not included in the design? I’m assuming that when I render a mosaic, I have similar options to adjust the visualisation like I can with individual items.

Is there a way to join the different services together, UX-wise? Could we guide the user from finding a collection to visualising a mosaic, and from finding an item to visualising an item? I think this would make for a more integrated demo.

[heidimok]

^ thanks @oliverroick

Goal
The goal I'm working from is to create a demonstrative UI for developers that can be shipped within eoAPI that provides an example of what they could do and visualize on a map when using its services, so that they can make a decision about whether to build their own tools using eoAPI.

Overall UX
We can certainly try and join the services together so that the user flows from finding a collection to visualizing assets.

• In the iteration above, it was intentional to try to showcase the key capabilities of eoAPI by providing each their own entry point on the UI. The thought was that if you didn't know what eoAPI was about you might want to explore each service it includes in a pretty straightforward way. But as a result I see how it also creates a disjointed feeling and potentially can be confusing to navigate; it could be more intuitive to achieve the goal by going through a single flow from start to end.
• Mosaic vs. item visualization - I'll revisit this as I mainly just took the demos shared by Vincent thinking they were meant to be separate capabilities to highlight, but maybe they can be combined together in a more integrated way.
• Next steps: I can explore removing those top service buttons and then just combine all the service features into a flow. I think this will be an easy shift because through working on the last iteration I have more clarity of how they do all fit together.

[heidimok]

UI update Aug 22, 2023:

• Made a revision to unite the different features into a single flow

Default landing page - prompt to ingest data if it hasn't been done yet

Once data is ingested, developers can select collections from that data

Once collections area selected, users can browse items

This is where a Mosaic toggle or button can exist to see all the items 'stitched' together

If a user selects an item, they can see a few details and visualize the item assets

This is where we can incorporate some visualization options that change what shows up for a given COG or other visual asset.

---

Link to clickable prototype

Open to thoughts here. I think when development starts, the details on design can change, but ideally we'd align on the general flow and features we are highlighting. Does this flow make more sense in your view @oliverroick? Is the goal clear? I think the boundary for this UI is that we aren't helping users search for STAC data. We are trying to highlight capabilities of eoAPI through an interface experience so give people a glimpse of what they could build on their own, using the APIs.

[j08lue]

Quick question - have you made a feature comparison with the MS Planetary Computer Explore UI, which is very related to this effort here and also works more or less plug-and-play with eoAP?

There are a lot of simple but powerful features in that UI, IMO. Like:

Find items as you pan and zoom - progressive disclosure ish

Once you selected a collection, you get an overview of the items within your viewport, with additional filtering options.

Nice about this: As a user, I want to progressively discover products of interests, refining my filters and selection iteratively, so I can approach my items of interest even without knowing all the details in advance. (👈 that's me) 🕵️

Hi-fi collection selection

Nice about this: As a user, I want to have visual aid and structure to guide me to a collection that is useful to me, so I do not need to parse a lot of text. 🧠

Also: As an eoAPI provider, I want my data to look good, even when I look at it myself, so it seems high-quality and appealing. 😻

Rather than just listing collections, the selection feature includes thumbnails and descriptions, helping the user understand the content of the catalog.

Probably a feature coming from their Catalog and does require that the STAC metadata is in good shape (thumbnails, nice descriptions, etc).

[zacharyDez]

@j08lue I like both features. The progressive filtering based on pan and zoom actions is an excellent add-on to the demonstration.

I also like the hi-fi selection - it looks great with the thumbnail, and providing a description gives more context to the user. Adding the description should be a manageable lift. My only concern with the thumbnail is adding another requirement for users generating STAC catalogs. We want the front-end to demo eoAPI's capabilities and give a short example of how it can be pieced together. The primary blocker in their onboarding process is creating their STAC catalog (correctly) and ingesting it. In a subsequent iteration, we could provide a demonstration or even some GUI to effectively manage STAC catalogs, including adding thumbnails. This could tie into #127.

cc: @batpad

[j08lue]

Just connecting dots - within EOEPCA+, we have plans to further develop STAC Admin. Maybe these designs can serve as inspiration, too.

cc @ricardoduplos