Introduction
I was involved in a program through CodeDay and my university that paired myself, and two other team members, with a mentor that would guide us through an open-source contribution to a project hosted on GitHub. I have worked in software for about 3 years, but I had never contributed to an open-source project. I was grateful for this opportunity to have someone show me the ropes and I will attempt to explain some of the key takeaways from my perspective that may also aid other first time contributors.
About the Project
Deck.gl is a library for visualizing large geospatial datasets and maps with WebGL.
A typical user of this framework is an individual or team, probably in a developer or data science type role. See their showcase for a great selection of example reports and applications.
Key Terms
Layer - A component of Deck.gl that will layer on top of a map or another layer.
Texture - An image in the GPU. It maps to actual images, colors, etc for rendering.
Frame Buffer Object (FBO) - An extension to OpenGL that can render a texture.
Binding - Connects the texture to the renderer.
Example ArcGis Application
In Figure 1 below, the ArcGis base map is displayed and two layers are overlaid on top of the base map. The first layer is a set of geo-json data that contains all the locations of the airports and are highlighted with magenta circles. The second layer is the arced lines that connect the airports.
Figure 1 - ArcGis Map with Layers
Figure 2 below shows a basic diagram of how this works. Deck.gl provides a pure JavaScript API and also supports React. A base map is selected and then one of the core features, the Deck component, is instantiated and assigned layers that will render to the screen over the map.
Figure 2 - Deck.gl Layer Diagram
Selected Issue
The issue I worked on was to address the broken ArcGis integration which meant that developers could not render DeckGL data on top of the ArcGis map and, while the documentation looked correct, the library was not. To start I had to isolate where in the code the problem existed. There were two places that were relevant for addressing this issue: 1) the example application provided for guidance and 2) the arcgis module. My strategy at the beginning was to identify error messages in the console and break them up into sub-problems then search for examples that existed already in the code base that were implemented in a similar manner and use them as a guide. It turned out that none of the errors were immediately helpful. A certain amount of the code was closed-box that I did not have visibility into. My strategy immediately failed. How was I to debug a system that I couldn’t step through?
Challenges
When I started this work, I had no experience working with shaders, graphics, or the GPU. I was fortunate that my mentor did have significant experience in this area and even wrote an article that explained a shader which was very helpful.
I was used to a development environment where all the code was visible and I could step through it with a debugger. Parts of this system were opaque and I realized I needed a different approach. I drew some diagrams and made some assumptions as to how I thought the system should work and then implemented code that would verify my assumptions or disprove them. I would make a single change, wait for the page to reload, and document what worked and what did not. When I was blocked I reached out for guidance from the maintainers, the Slack community, and my mentor.
To isolate which parts of the code needed to be updated I traced each method call and identified which pieces of code would render to the screen.
Solution
I ended up with a pipeline of components that I could isolate to figure out where issues were.
Figure 3 - Screen Render Diagram
What is supposed to occur is ArcGis renders directly to the screen and DeckGL renders to a texture that then renders to the screen. I started with the shader itself and removed both the render and the texture FBO to see if a gradient could be drawn directly to the screen (Figure 4). When that failed, it verified that something was wrong with the shader.
Figure 4 - Render Debug Diagram
Through some trial and error it turned out that the geometry of the shader required an update and once fixed the gradient rendered which verified that the shader could draw to the screen.
Figure 5 - Gradient from Shader
The next logical choice was to look at the communication between the Deck instance on the other end of the pipeline and the shader. The FBO and DeckGL render were removed and replaced with a hard-coded image to see if it would render (Figure 6).
Figure 6 - Pipeline Debug 1
If the image rendered did then the shader was okay and if not then the shader was still broken and the DeckGL render could be too. The image rendered (Figure 7)
Figure 7 - Image as Texture Rendered to Screen
This verified the shader could render if supplied a correctly formed and bound image texture. I looked at the DeckGL render next. Here the binding of the texture to the DeckGL instance needed updating with newly required attributes. Once those were discovered the DeckGL instance could render to the shader (see Figure 8).
Figure 8 - Pipeline Debug 2
The last piece of the puzzle was the frame buffer object. The FBO and the texture needed to be reconstructed with the correct parameters and the texture bound to it properly. When the right combinations of attributes were found the map with the proper layers rendered and the sample image was removed (see Figure. 1). This was verified to work by adding a video in the discussion that showed the example functioning in the browser. Maintainers accepted the pull request and I had my first successful open source contribution!
Conclusion
One of the not so obvious elements that I learned from this experience was the importance of tracking what has been done and what has been learned. With all the rabbit-holes, code changes, side-quests, and proven or dis-proven assumptions along the way it is easy to get lost with what you did from week to week. Especially, if one wants to write an article or a quality PR detailing the changes and why they were necessary this document is invaluable.
I really felt fortunate to be part of this program and I learned so much from the process and from my mentor. Not everyone will have access to this kind of guidance, but I encourage everyone to begin to search for a project they feel they can contribute to. Remember to search issues for the label “good first issue”, if they have a Slack or similar join, and read their contribution guidelines. Happy coding!
Top comments (0)