search

CesiumGS / 3d-tiles

Specification for streaming massive heterogeneous 3D geospatial datasets :earth_americas:
2.11k stars 467 forks source link

Cleanup pass for 1.1 #674

Closed javagl closed 2 years ago

javagl commented 2 years ago

This addresses some points from https://github.com/CesiumGS/3d-tiles/issues/651 :

Update or remove CONTRIBUTING.md

Removed it, because it was obsolete as of https://github.com/CesiumGS/3d-tiles/pull/668

Update Q-and-A.md

This was done. Some questions have been updated to reflect the current state. Some other questions have been removed. When the question of an answer points to a seven year old open issue with 0 comments, then the question cannot be so relevant...

Update RESOURCES.md

This was largely done by moving some of the next/RESOURCES.md into this file. Currently, some of them are still mentioned in a "Next" section at the bottom. When the respective parts (e.g. Demos) are available for 1.1 (maybe as Sandcastles), this part can be removed as well.

Other things could be added to this PR, depending on the preferred solution:

Remove examples folder. Instead there should be a prominent link in the README to 3d-tiles-samples.

The examples folder also bugged me. One example is linked from the main README. Others are used in "hidden" places that generally talk about JSON schema. If there are no objections, I'd remove the examples folder entirely, and see how the updates in the "hidden" places can be made in the most sensible form.

Update or remove CREDITS.md

It probably cannot be removed, due to attribution requirements. I think it could make sense to move the attribution to the place where it is due (i.e. into an image caption). I can try that, if I'm confident to be able to figure out what the attribution refers to. (Once this is figured out, it will no longer be a problem in the future.... doing it once can be hard...)

Update or remove ECOSYSTEM.md

Deleting it would be simple. Should there be any form of replacement? It could make sense to distribute this into the "Implementations" and "Developer Resources" sections from https://github.com/javagl/3d-tiles/blob/draft-1.1-structure-pass-2/RESOURCES.md , if this sounds reasonable...

lilleyse commented 2 years ago

If there are no objections, I'd remove the examples folder entirely, and see how the updates in the "hidden" places can be made in the most sensible form.

No objections from me

It probably cannot be removed, due to attribution requirements. I think it could make sense to move the attribution to the place where it is due (i.e. into an image caption). I can try that, if I'm confident to be able to figure out what the attribution refers to. (Once this is figured out, it will no longer be a problem in the future.... doing it once can be hard...)

Yeah, makes sense to move the attribution to the specific images.

Deleting it would be simple. Should there be any form of replacement? It could make sense to distribute this into the "Implementations" and "Developer Resources" sections from https://github.com/javagl/3d-tiles/blob/draft-1.1-structure-pass-2/RESOURCES.md , if this sounds reasonable...

I don't have to much to say about the specific structure, but I do think combining RESOURCES.md, next/RESOURCES.md, and ECOSYSTEM.md into a single document is a good idea.

lilleyse commented 2 years ago

I don't have to much to say about the specific structure, but I do think combining RESOURCES.md, next/RESOURCES.md, and ECOSYSTEM.md into a single document is a good idea.

Actually a few more thoughts here... Instead of a separate document this could go in the main README. There's already an ecosystem section that could be expanded into several sections like demos, tools, resources, presentations, etc that would pull together the material that is currently spread across a few different pages:

The glTF repo is a good reference for this. The CesiumJS repo is also good, especially the featured demos section.

javagl commented 2 years ago

Regarding the "sitemap":

I have mixed feelings about this page. It's a convenient way to locate things. But it's another page to keep up to date and it's hard to know the value it will bring vs. just navigating the directory structure.

This was a first draft, mainly to see which links it could contain. I considered to actually create some "table"
- Metadata Some description here
    - Semantics Reference Some decription here
... ...

I also see that it has to be kept up to date, although I think that it refers to such a "coarse" and "settled" structure that it should probably not change very frequently. Still, the "effort-to-usefulness" ratio has to be considered. The file can be removed at any time (from this PR), and iff we consider to add something like this, it can be a dedicated PR.

Regarding the resources/ecosystem:

Actually a few more thoughts here... Instead of a separate document this could go in the main README. There's already an ecosystem section that could be expanded into several sections like demos, tools, resources, presentations, etc that would pull together the material that is currently spread across a few different pages:

The glTF repo is a good reference for this. The CesiumJS repo is also good, especially the featured demos section.

I think that the main README should be relatively short, and rather "dispatch" the user to the page that contains the desired information. But regardless of whether it will be a section in the main README or a dedicated file, I wonder about the best structure.

The ECOSYSTEM.md contains mainly screenshots, without information what these things actually are. The "Ecosystem" section in the main README contains some information, but only a small selection (and I'm not sure whether the validator should be featured so prominently, as long as it does not support 1.1).

The glTF repo originally listed all the tools (and they have been moved to the glTF-Project-Explorer in the meantime), roughly classified into "Viewers/Importers/Exporters...". I can try to go through the list in the ECOSYSTEM.md, and have a look what this actually is - maybe it can also be classified in a sensible way.

lilleyse commented 2 years ago

Let's remove the sitemap to help move this PR along. It can be a separate PR.

The ecosystem/resources restructuring can be a separate PR as well.

javagl commented 2 years ago

If this is OK, I'd update the checklist at https://github.com/CesiumGS/3d-tiles/issues/651 after this is merged.