gmggroup/omf-python

Detailed documentation of our vocabulary

Opened this issue · 3 comments

This includes:

  • project
  • element
  • attributes
  • texture

Hi I would like to contribute to this project, do you think this is good issue for beginner? If yes can you please give some guideline?

Hi @michiboo - thanks for the interest! We would love to have your contributions! Please refer to the contributing file for general information on how to contribute.

Regarding this issue as a good first issue, that depends on your perspective. This issue addresses a pretty big gap in the OMF documentation: Fundamentally, what do the words we chose for different objects mean? Language is complicated, and even if we spend hours in a room debating what most people think makes sense to call some-specific-thing, there will be others who disagree or bring different interpretations/perspectives/etc that lead to misunderstandings. The only way to get around this is to bring everyone to the same level by defining all our vocabulary. Then, when we use a word like "element" or "attribute" everyone can set aside their pre-conceived notions and refer to the documented OMF definitions.

There is definitely value to tackling this as a first issue - you would be learning for the first time what different words mean, in the context of OMF, so you would bring a fresh, relatively unbiased perspective to the definitions (if that makes sense?). It would even be hugely valuable if you opened a PR with just an early sketch of the definitions; this would provide a place for others to review, have a conversation, expand, and reach agreement.


If this still sounds like something you are willing to take on, great! I'd start by creating a new vocabulary.rst file in the doc content folder and referencing that from index.rst. Then just add a section for each word; they need definitions, of course, but also examples, pictures, synonyms (maybe equivalent words in different fields), etc. A few quick notes on the words listed in the top comment:

  • Project - "top-level" OMF object that holds everything
  • Element - 3D object (Note: "Geometry" exists in the v1 codebase but will be removed with #37)
  • Attribute - Values on an object (Note: this is currently "Data" in the v1 codebase - to be changed with #48)
  • Texture - Image mapped to an object

Please add any other words you encounter that are at all ambiguous or seem to have their own OMF-specific definition.


If you don't feel like this is the sort of thing you want to tackle as your first issue, there are some other much more straightforward issues, such as #47, #41 / #54, #48 - I'll add some additional details to those as well so they are easier to pick up.

Thanks!

Hi thanks for the helpful information!! I took a try at #41 and open a PR on this. hopefully I got it right!