Fotonix & Gizmos

Taking Jeff Patton's Product Leadership Course

Ryan Frazier — Fri, 25 Feb 2022 00:38:17 GMT

Around 2010 I remember watching an Intel Commercial featuring Ajay Bhatt, co-inventor of the USB. As he walks through a crowd of fawning coworkers to get his morning coffee, the tagline pops up: “Our Rockstars Aren’t Like Your Rockstars.” Despite working in the semiconductor industry, my list of rockstars has never included Ajay. Instead, it’s filled with the likes of John Carmack and Michael Abrash, pioneers in computer graphics and virtual reality, one of my core passions.

As I discovered a new passion in Product Management, my list of rockstars grew to include product leaders who created the concepts and processes I use daily. In February, I was lucky enough to take a Product Leadership Course from one of these Leaders, Jeff Patton, author of User Story Mapping. While labeled as a Certified Scrum Product Owner (CSPO) course, the class introduced many areas of product thinking, not just agile delivery, and is one of the few such classes recommended by Marty Cagan of SVPG. Below are my thoughts on the training and personal takeaways.

Contents

Quick Links

The Course

Course Title: Passionate Product Leadership Live Online Course
Format: Virtual over Zoom. Leverages Mural extensively for collaboration
Duration: Four days at four hours per day (16 hours total)
Cost: $1695 ($1395 If you register in advance)

Pre-Work

Apart from a few videos to watch before each session, there’s no formal pre-work/advanced reading for the course. However, I strongly recommend reading The Lean Startup and User Story Mapping beforehand. Otherwise, all the topics covered may leave you feeling like you’ve just drunk from a product-spewing fire hose!

If you want to get a feel for Jeff’s lecturing style, watch his REConf 2019 talk "The Game has Changed." He repeated most of this talk on the first day of class.

Class Summary

Jumping into the Zoom meeting on day one of the four-day course, I wasn’t sure what to expect. Since the pandemic, I’ve been in my fair share of virtual training sessions, and a majority of them are little more than the presenter going through a checklist of discussion topics while deflecting questions that disagree with their main points. However, as soon as I connected to Jeff’s meeting, I knew it would be different.

Instead of a premade slide deck, His screen showed a birds-eye video feed of his desk, with sticky notes and a hand-written message welcoming everybody to the class. This format was standard throughout the entire training, with Jeff discussing topics while simultaneously drawing pictures and diagrams to explain them. It made everything more engaging than a slide deck while allowing him to hop into quick tangents as participants asked questions.

The outline on the course website is largely accurate, with our four days touching the following topics

Day One - Product Development, Structuring Product Teams
Day Two - Users and Personas, Customer Interviewing, Story Mapping, Metrics
Day Three - Vision, Product Strategy, User-focused OKRs
Day Four - Discovery, Delivery, Release Strategy

Additionally, there are a couple of things to note about the sessions:

You will Learn by Doing

Interlaced throughout the training were sets of collaborative group activities. In fact, from day two onward, everybody was clustered into mini product teams tackling various tech products (our team focused on the Target app and the challenges shoppers face when items from their grocery orders are out of stock). With the aid of some very well-designed Mural boards, we were immediately able to practice newly learned concepts. The small group size meant open conversations and exposure to different perspectives.
Managing software Delivery is a small portion of the actual class

Again, this is a product leadership class, not just an agile delivery class. This course will not teach you how to write intricate, verbose requirement docs that you can cleanly hand off. Instead, it will stress that the solution to many of the points of frustration a PM faces is to continually talk to customers, involve software and stakeholders early and often, and have regular, open conversations to ensure everybody is aligned.

Office hours, held at the end of each lesson, provided a great time to discuss in detail any of the day’s topics, especially if you have specific questions on how to apply them with your organization or product. I made a point to hang back every day, not just to ask my question but to learn about the challenges and insights other participants face when adopting a product mindset. Jeff scanned any sketches from the office hour and added them to our class Mural board.

Is the Class Worth Taking?

This class completely exceeded my expectations, and not just because it managed to tie South Park into a lesson on product strategy! The informal dialog, paired with activities and Zoom chat for class discussions always left me feeling like an active participant instead of just an observer. Even though I had already implemented many of the ideas being taught, it was worth it to learn from Jeff first hand, ask questions related to my specific products, and clarify some vague topics from his book. I plan to take advantage of the alumni policy and audit the course in the future.

I walked out of the training with roughly ten pages of notes, almost all of which I’d been able to put into practice during group activities, and ½ dozen new books on my “to read” backlog. I had also earned a CSPO certificate along the way. However, CSPO is a participation award (there’s no exam to confirm you learned anything). The learnings from the class were far more valuable than a certificate to pad my resume. My most significant regret is that none of my product team took the class alongside me. Alumni can retake the course for free, and I plan to pull the rest of my trio into a future session.

If you adopt product thinking in your company, bring your entire team, so everybody gets direct experience (including SWE, UX, and Leadership)! As great as Jeff’s drawings are, they are very context heavy. If you take one to your team later and go, “See, this is what we need to do!” You’ll likely get blank stares and confusion.

Learnings and Takeaways

Note

These are my own notes and takeaways from the course, grouped roughly by concepts. They only cover a small fraction of everything that was covered during the training. You’ll notice I omitted things like “build-measure-learn” or “what is a story map” because I was already familiar with them. I strongly recommend coming into the class having read up on certain topics so you can focus on subtle details.

Focusing On Outcomes

Reviewing Shipped Features

One of the first activities was reviewing past features your team has shipped on a 2-axis plot of Outcome vs. Actual Effort. I plan to adopt this method and slowly build a cluster plot of everything we ship. It will be a great way to visualize any weak spots on our product development cycle, e.g., “Our releases are regularly larger than we’d like” or “ involving X part of the system in a release always bottlenecks us.”

For Additional Reading

Keep Actual Effort and Outcome Visible.

Users vs. Choosers

If you’re in B2B, it’s important to understand that the people who choose to purchase your product (customers) are not the same as the users themselves. More importantly, when the choosers are not the users, you should prioritize different metrics:

B2C SaaS - Focus on Pirate or Heart metrics.
B2B - Focus on user efficiency and effectiveness metrics. How long does it take them to do their job with your product, and how well can they do it?

The Continuous Tech-Product Improvement Cycle

This four-quadrant graph came up regularly throughout the course to describe the cycle of iterating and improving a tech product. A lot goes on in the image, with the right half focusing on dual-track development and the left half emphasizing vision and strategy.

The bottom-left quadrant stood out to me: Sense, Listen, and Learn. Effectively, you have three main sensing channels that result in new product opportunities:

Tactical - Composed of metrics, observations, and customer interactions, this is the most obvious way to improve your project.
Strategic - Your product has a vision, and it (hopefully) has a strategy to achieve that vision. This channel involves opportunities that help you hit that strategic goal.
Technological - It’s essential to be aware of new technologies that can improve your product as well as the technical debt you currently carry.

You need to maintain all three channels for a healthy product. For an analogy, imagine the human body and the following sensing channels: hunger, tiredness, and thirst. You can sleep as much as you want, but if you don't sleep or eat you'll eventually crash!

Products Composed of Products

One of the last topics of day one was “The Product Onion,” which tiered different product categories.

End Products - These product teams create solutions that address end customers and users
Customer Enabling Products - These product teams create product websites and modules. They need to service both end customers and other product teams.
Employee Enabling/Product Team Enabling products - These teams typically develop APIs that other product teams use to accomplish their jobs. They do not typically provide solutions to end customers.

It’s not a perfect analogy. There are exceptions (e.g., if an API becomes public and now an Employee Enabling Product Team also supports customers), but I appreciate the separation. My team needed to navigate this when separating our end product from the back-end services that enabled it.

Personas and Interviews

A Simple Product Interview Script

While a fan of Teresa Torres' story-based Interview method to avoid cognitive bias, I understand that some people may be more comfortable interviewing with a pre-defined set of questions. This quick script is an excellent introduction to customer interviewing and lets the team hear what users think without biasing them.

Can you tell me a little bit about <Product>?
What do you use <Product> for?
What do you love about it? Can you give me an example?
What do you hate about it? Can you give me an example?
If you could wave a magic want and change anything about this product to make it better, what would it be?
Imagine you had that change, how would you use it?
How do you do things today without this capability?

For Additional Reading

Personas and Protopersonas

A persona is an extensive (and time-consuming) distillation of customer research into a fictional person. Proto personas speed things up by leveraging assumptions about your users (which you must verify). There are loads of persona templates available, but the one we used had a photo and three categories:

About (Descriptors) - This can cover demographics, education, skills, and job roles
Behavior (Verbs) - What are some things this persona does? In our persona, “Susie” was responsible for sourcing the weekly snacks for her kid’s soccer team.
Motivations - What are the pains and problems this persona experiences, what are some rewards?

I liked the mantra Differences that make a difference. aka differences in personas should affect how that persona would use your product.

Personifying a Service

The classic user story template goes: “As XXX, I want to YYY so that ZZZ,” (this should really a guideline more than than a rule). During office hours, somebody asked: “Bots consume our APIs; how do we write user stories around them?” The answer: anthropomorphic personification (something I’ve only ever heard of in the context of Discworld).

Effectively, the bot takes the user's role, and you personify it as though it was a living thing. It may work for you, it may not, but I thought it was a clever observation regardless.

Strategy

Where You will Play and How you Will Win

There’s a slew of books on product strategy; one of the more famous is Richard Rumelt’s Good Strategy/Bad Strategy. While I like the book, especially the concept of a strategic kernel, I’ll be the first to admit that it is dense and can be a slog to get through.

Here is a “cheat sheet” phrase for thinking of strategy: Where you’ll play and how you’ll win.

Where You’ll Play - Your strategy should identify and focus on a specific market, user persona, and problems you’re addressing.
How You’ll Win - You need to understand how your solution is better than alternatives, including desired outcomes and metrics.

For Additional Reading

Customers Solve Business Problems; Product Teams Solve Customer Opportunities.

Your organization probably has goals: earn $XXX in revenue, increase the sign-up rate by Y%, etc. The thing is, product teams cannot directly solve those problems. I’m not going to open my wallet and hand money to the CEO. Likewise, unless I plan to go the route of Wells Fargo, I don’t have direct control over how many people sign up for a service.

Instead, a Product team’s job is to solve customer opportunities. When we solve a customer opportunity, we hypothesize that doing so will have a business impact, but we’re still addressing business goals through the customers. Opportunity Solution Trees are a great way to connect customer opportunities to business outcomes visually.

User-Focused OKRs

Since a product team should focus on addressing user opportunities, it makes sense that any product team using an OKR (Objective and Key Results) goal framework should have user-focused objectives, not business impact objectives. Jeff Outlined a 3-step process for making user-focused OKRs, and I’ve added two steps that help bridge the gap from business impacts to user outcomes.

If your team uses OKRs as defined by Marty Cagan, your product team is responsible for one or more business-oriented key results in a given quarter, e.g., “reduce churn by X%.”
Assuming you perform continuous discovery/regular user interviews, build an Opportunity-Solutions Tree (OST) around that metric. Prioritize this opportunity space (see chapter 7 of Continuous Discovery Habits) and hone in on one target opportunity.
Rewrite the opportunity as a quote from your target person. Humanizing the challenge helps to give it more context.
Write an ambitious statement that describes solving the opportunity. Make sure you capture the desired outcome and not a specific feature.
Identify 2-4 metrics that would show you are making progress towards solving the problem and their values that would indicate success. These are your Key Results.

Discovery and Delivery

Opportunity Canvas

Opportunity Canvases are a structured format to vet opportunities and see assumptions. I haven’t adopted it personally but may give it a test-run in the future.

The Next Best Test

Tests and experiments build confidence that your features provide actual user value, but they rarely need high-fidelity prototypes or shippable code. Experiments aim to test assumptions and progress you around the build-measure-learn loop as rapidly as possible. Disqualifying multiple ideas with short experiments is better than creating an expensive prototype of your first solution.

What are we trying to Learn?	What is the fastest way to learn it?
Are we solving a meaningful customer problem?	Talk to users Surveys, metrics, observations
When a user sees the solution will they want to try it?	Smoke Test/ Landing Page Test Interview + Prototype
Can we build our solution predictably?	Talk to Developers Spike
Can users easily learn to use it?	Usability Test
Will users Keep using it and really get value?	Built it, Not to scale A/B Testing

The above table outlines the recommended order of experiments to help rapidly build the confidence or kill a solution. Notice that the first question you should always answer is “Are we solving a meaningful customer problem.”

For Additional Reading

Clarifying Prototype Fidelity

Inspired covers prototype fidelity in-depth: the higher a prototype’s fidelity, the less distinguishable it should be from your final software. The book also drives home to run usability tests with only high-fidelity prototypes. However, Jeff’s definition of fidelity argues that the fidelity of a prototype lies on 3-axes: visual, data, and functional. Depending on the test, a prototype should skew along one or more axes:

My own attempt at mimicking Jeff's Sharpie + Highlighter drawing style

Testing Desirability: The prototype should have high visual fidelity. We’re seeing if users are even interested in our solution. For that, you don’t need full functionality or accurate data.
Testing Feasibility: To answer “can we build it,” your prototype should be highly functional but doesn’t need to have accurate data or be visually appealing.
Testing Usability: Usability needs to have high functional and data fidelity. Notice that it does not need to be visual. Over-prioritization of visual fidelity is a common hurdle we run into relying on tools like Figma: they look like the final product, but if the product has something like drag and drop interfaces or a drawing engine, Figma falls short or becomes expensive to prototype. A paper prototype can be just as valuable for usability testing!

Shrink Your Releases by prioritizing people, not features

We almost ran out of time for the activity that spawned this takeaway! We revisited the famous “getting ready for work” story maps we’d created earlier in the week on the last day. As a team, Jeff challenged us to update the map, assuming you had slept late and only had 15 minutes to get ready. He challenged each group to remove unnecessary stories or add alternatives to hit the deadline.

The assignment isn’t difficult when you fly solo, but since our entire team was working on one story map, there were tasks (get kids ready for school, feed the dog) that made it in even though I would not need to do them.

Despite my having neither children nor pets, they both made it into my teams "critical" story map

Jeff asked after we regrouped if anybody had irrelevant stories on their map. He then suggested, “Wouldn’t it be easy just to ignore people who have dogs or kids and focus on solving the problem well for one persona?” This point ties through to planning a product release strategy! The goal of your roadmap should be to release early, often, and provide value for a specific persona. If a release roadmap is bloated or top-heavy, the best way to clean it up is to focus on one persona and delay implementing steps/features that are irrelevant to that persona.

Release Strategy vs. Development Strategy

User Story Mapping discusses breaking up a release into multiple stages: your tracer-bullet (prove functionality), mid-game, and late game. However, I missed that this is the team's development strategy, not part of the release strategy.

Release Strategy identifies the smallest successful release that addresses a customer opportunity.
Development Strategy prioritizes the order in which the delivery team tackles stories within a release to address feasibility risks and ensure on-time delivery.

Development strategy lies in the domain of software engineers and agile delivery. It even came up that at Atlassian (creators of Jira), the Product Managers are not involved with the development strategy for that reason. While I might not go that far, I agree that once the release strategy is fleshed out, the software team knows how to build things and should have a level of autonomy.

Release to Earn vs. Release to Learn

Release to Earn is what it sounds like, production-ready that earns your company revenue. However, release to learn is software that is “Just enough to fulfill the narrative but far from feature complete.” Release to learn often involves A/B testing or releasing to a subset of users.

The concept is covered extensively in The Lean Startup. However, it’s worth noting to emphasize that delivery can be part of your discovery work while still providing incremental value to (a subset) users! It also ties back to release strategy: every release should be identified as a “release to learn” or “release to earn” release with hypothesized outcomes.

Design a Camera with Python and PyRayT: Part One

Ryan Frazier — Fri, 06 Aug 2021 01:04:29 GMT

Have you ever cut open a camera lens to look at what's inside? I don't blame you if you haven't, lenses are ridiculously expensive and it's a one way operation. However, if you look at a picture of a cross-section, you'd see that the "lens" is actually made of upwards of a dozen individual lenses, each one doing its part to create a clear, error free image. Typically, understanding what's going on in the camera lens requires exhaustive calculations or expensive lens design software costing upwards of $10,000 for a single user. My annoyance at this price barrier (as somebody who uses those tools professionally) is what sparked me to create PyRayT, a free and open source generic ray tracer that pairs with the Scientific Python stack.

To celebrate PyRayT's v0.3.0 release, I'm going to walk through how it can be used to design and optimize a multi-lens camera. This first part of the series will cover why lenses need to be so intricate, and what happens if you tried to make a camera out of a single lens instead.

Contents

Quick Links

Why Are Camera Lenses so Complex?

If you rack your brain to recall highschool physics there's probably two things you remember about lenses:

A ray parallel to the optical axis converges onto the focal point.
A ray going through the center of the lens is unmodified.

With these rules you can trace simple diagrams showing how object images are formed by lenses.

Source: Wikipedia

Notice how in the above image every point in the object corresponds to exactly one point in the image, so in theory a single lens camera should be able to capture perfect reproductions of objects we want to image. Why then, does a picture from that camera end up looking like the one below?

An ideal image (left) and the resulting image as captured by a simple camera (right)
Source: www.opticsthewebsite.com

These distortions between the object and image, called optical aberrations, are caused by higher order terms that are typically ignored when calculating lenses by hand using the paraxial approximation.

The goal of any camera design is to minimize these aberrations to the extent that they are not noticed by the end user. A single lens only has so many variables about it you can change, but adding multiple lenses to a system gives optical engineers additional degrees of freedom for the minimization (often by minimizing Siedel Aberration Coefficients, which are beyond the scope of the article).

So how bad could a single lens imager really be? And how do you improve the quality with additional lenses? Let's answer the first question by quantifing common aberrations for a single lens system.

Getting Up and Running with PyRayT

As mentioned above, hand calculations for lenses rely on approximations that don't capture aberrations. Fortunately, numeric ray tracers don't suffer from the same limitations which is why they're so valuable for accurate lens design. Since this article is about showcasing features of PyRayT, that's the ray tracer we'll be using. You can install the latest stable package from pip.

py -m pip install pyrayt

You can also check out the Getting Started Guide and list of built-in optical components for a general overview.

Creating a Simple Camera

To design our single-lens camera we only need two specs: system power and f/# (F-number). We want the system to have a focal length of 50mm, and since a lens' power is the inverse of focal length, our system power is 0.02. Our f/# will be 2.4, meaning the focal length should be 2.4x larger than the entrance aperture.

Thin Lenses

Our lens is the only component that contributes to system power, so the power of the lens has to equal the desired power of our system. To calculate lens power we'll use the lensmaker's equation.

\begin{equation*} P_{lens} = (n_{lens} -1)[\frac{1}{R_1}-\frac{1}{R_2}+\frac{(n_{lens}-1)d}{n R_1 R_2}] \end{equation*}

Since we're doing the calculation by hand we'll make a couple approximations to simplify things: (1) the radii of curvature are equal and opposite (resulting in a biconvex lens), and (2) the thickness is small enough that we can discard the final term. Later we'll numerically optimize the entire system to correct for focus, but these approximations give us a good starting point.

The simplified equation then becomes:

\begin{equation*} R_{lens} =\frac{2(n_{lens} -1)}{P_{lens}} \end{equation*}

Since the refractive index of most glasses is ~1.5, this means that our radius of curvature for a biconvex lens is equal to the inverse of the lenses power, which is also the focal length of the system!

Now we can construct our lens and visualize it with the draw function in the tinygfx package (installed as part of the PyRayT distribution).

# import the Ray Tracer Package
import pyrayt
import pyrayt.materials as matl
from tinygfx.g3d.renderers import draw

# All spatial units are mm
lens_diameter = 30
lens_thickness = 5
system_focus = 50 # The focus of the system
f_num = 2.4 # f-number of system

# Creating a simple Lens
lens_material = matl.glass["ideal"]
lens_radius = 2*(lens_material.index_at(0.633)-1)*system_focus
lens = pyrayt.components.thick_lens(
    r1=lens_radius,
    r2=-lens_radius,
    thickness=lens_thickness,
    aperture=lens_diameter,
    material=lens_material)

draw(lens)

A lens is not too impressive by itself. Let's add the remaining parts of our system so we can start running ray traces!

Apertures and Baffles

There's two more pieces we need in order to make the camera: an aperture to block rays that exceed our f/# and an imager placed on our camera's focal plane. From a modeling perspective both will be accomplished with variations of PyRayT's baffle. Baffle's are 2D planes that absorb all light incident on them, perfect for modeling sensors as well as ideal beam-stops. For the imager we create a square baffle the same size as our lens and move it to the focal plane.

imager = components.baffle((lens_diameter, lens_diameter)).move_x(system_focus)

Our aperture can be thought of as a "baffle with a hole", where the hole is large enough to only let in rays with a cone angle specified by our f/#. pyrayt and tinygfx create arbitrary shapes via constructive solids meaning an aperture is a baffle with the center shape subtracted from it. The convenience function aperture does just this, creating a baffle with an arbitrarily shaped hole in the middle.

The diameter of the aperture that gives us the desired f/# depends on where in the system the aperture is located. If we place it half-way between the lens and the focal plane, the diameter of the opening has to be:

\begin{equation*} d_{ap}=\frac{1}{2*P_{sys}}*\frac{1}{f_\#} \end{equation*}

aperture_position = system_focus / 2
aperture_diameter = aperture_position / f_num

aperture = components.aperture(
    size=(lens_diameter, lens_diameter), # make a square baffle
    aperture_size=aperture_diameter # put a circular opening in the center
    ).move_x(aperture_position)

Our First Ray Trace

With our components defined we're ready to simulate. The only thing we need is a test source that generates rays to trace through the system. For that we'll use PyRayT's LineOfRays which generates a set of linearly spaced rays projected towards the +x axis. The last step is to load all the components into a RayTracer object and run the trace function.

Note

Almost all of the sources used to characterize our system will be parallel bundles of rays at various angles. This is because we're assuming the camera is focused at infinity, where any angular deviation between sets of rays originating from the same point are effectively zero.

# Create a Parallel ray set
source = components.LineOfRays(0.8*lens_diameter, wavelength = 0.633).move_x(-10)

tracer = pyrayt.RayTracer(source, [lens, aperture, imager])
tracer.set_rays_per_source(11)
results = tracer.trace()

The results of a trace is a Pandas dataframe which stores information about the ray at every intersection of the simulation. However, for now we'd rather just visualize the ray trace, which is done with the show function.

# import matplotlib so we can manipulate the axis
import matplotlib.pyplot as plt

def init_figure() -> Tuple[plt.Figure, plt.Axes]:
    """
    Convenience function to generate an axis with a set size
    """
    fig = plt.figure(figsize = (12,8))
    axis = plt.gca()
    axis.grid()
    return fig, axis

# set up the figure and axis
fig, axis = init_figure()
axis.set_xlabel("distance (mm)")
axis.set_ylabel("distance (mm)")


# display the ray trace
tracer.show(
    ray_width=0.2,
    axis=axis,
    view='xy')
plt.show()

Looks like our lens is doing its job! All rays that transmit through the aperture are focused to an approximate point at the focal distance, and any ray angle that exceeds our f/# is blocked. Unfortunately since the aperture and imager are 2D objects, they don't show up in the ray trace, but we know that they are there because rays terminate on their surfaces.

Characterizing Lens Performance

A picture may be worth 1000 words, but when it comes to analyzing our lens' performance data is key. Using the results dataframe we can explore the RaySet metadata of each ray as they travel through the system, and we'll use that information to see how our single lens design holds up against common imaging aberrations: spherical, chromatic, and coma. As mentioned above, characterizing the system with Seidel coefficients is beyond the scope of the article, instead we'll use Matplotlib to generate plots of the system focus across different parameters.

Spherical Aberrations

Spherical lenses don't actually focus light to a perfect point. In fact, the focal point is a function of the radius where the light enters the lens (in our case the position on the y-axis where the ray originates). We can easily visualize the spherical aberrations by creating a helper function that generates a set of rays along the y-axis, and calculates where each ray intercepts the x-axis.

def spherical_aberration(system, ray_origin: float, max_radius:float, sample_points=11):

    # the souce is a line of rays only on the +y axis. It's slightly shifted so zero is not a point
    # as it would focus at infinity
    source = pyrayt.components.LineOfRays(0.9*max_radius).move_x(ray_origin).move_y(max_radius/2)


    tracer = pyrayt.RayTracer(source, system)
    tracer.set_rays_per_source(sample_points)
    results = tracer.trace()

    # Since we don't have the actual imager as a variable in the function
    # assume it is the last thing a ray intersect with, meaning the rays that hit it have the
    # highest generation
    imager_rays = results.loc[results['generation'] == np.max(results['generation'])]

    # Intercept is calculated using the tilt for each ray, with is a normalized vector representing
    # the direction the ray is travelling
    intercept = -imager_rays['x_tilt']*imager_rays['y0']/imager_rays['y_tilt'] + imager_rays['x0']

    # the original radii
    radii = results.loc[np.logical_and(results['generation']==0, results['id'].isin(imager_rays['id']))]['y0']

    # create a new dataframe with the aberration metrics
    results = pd.DataFrame({'radius': np.asarray(radii), 'focus': np.asarray(intercept)})
    return results

Using the function on our single-lens system yields the above plot, showing that the focal length of the lens is changing by almost 10% based on the radius alone! This aberration would cause our single-lens images to come out "blurry" even when the imager is aligned to the focal plane.

An image suffering from spherical aberrations. Source: www.opticsthewebsite.com

Speaking of the focal plane, we also see that the focus of our lens is ~52mm instead of the 50 we calculated, due the the thick lens portion of the lensmaker's equation we chose to ignore.

Chromatic Aberrations

Unlike spherical aberrations, chromatic aberrations are explained by the lensmaker's equation: the focal point of the lens depends on the refractive index of the lens' material. Real materials don't have a constant refractive index; instead, the refractive index is a function of wavelength. This effect, called dispersion, is more often associated with the reason prisms split white light into a rainbow of colors. In our case it means our lens will have a wavelength dependent focus.

The same way we wrote a function to characterize spherical aberrations, we can write one to quantify chromatic aberration:

def chromatic_abberation(system, ray_origin: float, test_radius:float, wavelengths: np.ndarray) -> pd.DataFrame:
    # create a set of sources for every wavelength of light
    sources = [
        pyrayt.components.LineOfRays(0, wavelength = wave)
        .move_y(test_radius)
        .move_x(ray_origin)
        for wave in wavelengths]

    # Create the ray tracer and propagate
    tracer = pyrayt.RayTracer(sources, system)
    tracer.set_rays_per_source(1)
    results = tracer.trace()

    #filter the rays that intersect the imager
    imager_rays = results.loc[results['generation'] == np.max(results['generation'])]

    # calculate intercept of the imager rays with the x-axis and form into a dataframe
    intercept = -imager_rays['x_tilt']*imager_rays['y0']/imager_rays['y_tilt'] + imager_rays['x0']
    results = pd.DataFrame({'wavelength': imager_rays['wavelength'], 'focus': intercept})

    return results

If we run this function on our current system the results will say that every wavelength has the exact same focus! This is because we made the lens out of an "ideal" glass with a refractive index (n) of 1.5. Let's replace our lens with one made of a popular crown glass instead:

lens_material = matl.glass["BK7"] # Update this line of the lens definition

Running the function on our newly dispersive system shows a focal length shift of ~1mm (2%) across the visible spectrum.

An image taken with this lens would result in sharp edges in our photos having a 'rainbow' effect. Interestingly, this aberration is sometimes sought after for artistic effect, going as far as being including as a graphics setting in id's 2016 Doom reboot.

An image with and without chromatic aberration. Source: wikipedia.org

Coma Aberrations

The last aberration we'll quantify is coma. Instead of being a change in focal length, coma is a change mangification vs. angle of incidence on the system. The name comes from the fact that a point imaged with a system suffering from coma looks like the coma of a comet.

The easiest way to visualize coma is to plot a LineOfRays hitting the lens at non-normal incidence. In a coma free imager, the distribution of ray-imager intersections should be symmetrically distributed about the central ray.

While we could generate three sources at three distinct angles and run a single ray trace, we're instead going to leverage PyRayT's pin function to manipulate the angle of the lens. Since the position of the lens is a property of the lens itself, updating the position without remembering to undo it later will effect calculations down the line. the pin context manager takes care of this for us by undoing any transformations of pinned objects when the context manager exits.

The main advantage of rotating the lens instead of the source is that the incoming rays stay perpendicular to the imager, and nominally centered about y=0.

# Create the system
source = pyrayt.components.LineOfRays(0.9 * lens_diameter).move_x(-10)
tracer = pyrayt.RayTracer(source, [lens, imager])
tracer.set_rays_per_source(1001)
angles = (12,6,0)
fig, axis = init_figure()

for n,angle in enumerate(angles):
    with pyrayt.pin(lens):
        # pin the lens in place so its rotation resets between iterations
        lens.rotate_z(angle)
        results = tracer.trace()
    imager_rays = results.loc[results['generation'] == np.max(results['generation'])]
    axis.hist(imager_rays['y1'], bins=21, label = f"{angle}-degree incidence", density=True, alpha=0.8)

# plot labels
axis.set_xlabel("position along Y-axis (mm)")
axis.set_ylabel("density (AU)")
axis.set_label("Focal Spot Distribution vs. Angle of Incidence")

plt.legend()
plt.show()

Just looking at the ray trace we can see the angled rays don't come to any central focus, and the histogram has a strong skew towards the -y axis. Like spherical aberrations, coma will cause our images to blur; however, the distortion is worse the further you are from the center of the imager, with the middle of the image remaining sharp.

An image suffering from coma aberrations. Source: www.opticsthewebsite.com

Next Steps

This wraps up the first part of our camera design. It might not seem like much, but understanding the limitations of a simple system helps justify why we go through the process of desiging a complex one. The full Jupyter notebook for the design is on GitHub, and next post I'll show how with just one additional lens, we can drastically minimize all three of the above aberrations to help our camera generate a cleaner final image! In the mean time feel free to explore the design and see how much optimization you can do with just one lens:

What about the design changes if you pick a different material?
If you break the symmetry between the front and back surface can you reduce aberrations?
Is there a way to reduce chromatic aberration only by changing the physical dimensions (not material) of the lens?

Writing an (Overly) Idiomatic Fizzbuzz with Rust

Ryan Frazier — Fri, 09 Jul 2021 00:27:33 GMT

The last few months have been a whirlwind exposure to Rust. It started when I was looking for a systems language to speed up pieces of PyRayT that was more general than Cython, but not C/C++ (which I have my own love/hate relationship with). After reading the excellently written Rust Book I was hooked on the language, using it for a couple CLIs, a webserver, and even going through old Advent of Code puzzles to get more practice.

This is slowly becoming my reply to all things software related

This post isn't going to be a gushing review of Rust (though as 2020's most loved language you won't be hard pressed to find one of those either). Instead, it's sparked from an article I saw on This Week in Rust back in June about writing an idiomatic binary search. The binary search is a well known algorithm, which got me thinking: what's another well known program I could use to practice writing idiomatic code? The answer: Fizzbuzz, the programming puzzle commonly used in interviews to make sure the candidate actually knows what a for loop is.

In this post I'll be starting with a standard Fizzbuzz solution, and polishing it up to take full advantage of all the features and programming style Rust offers.

Contents

Quick Links

What Makes Code Idiomatic?

Before diving into the how, it's worth covering what idiomatic code actually is. Outside of coding context, idiomatic means "using, containing, or denoting expressions that are natural to a native speaker." When discussing idiomatic programming, it means the program leverages features unique to the language to accomplish the task. Coming from Python, I would hear this as writing "Pythonic" code (list comprehension, generators, etc.).

Idiomatic Rust should leverage Rust's unique features such as match, traits, iterators, and ownership. Since I'm still learning Rust every day, I use the linter Clippy, to catch common mistakes and recommend idiomatic alternatives!

The Basic Fizzbuzz

The goal of Fizzbuzz is simple:

Write a short program that prints each number from 1 to 100 on a new line.
For each multiple of 3, print "Fizz" instead of the number.
For each multiple of 5, print "Buzz" instead of the number.
For numbers which are multiples of both 3 and 5, print "FizzBuzz" instead of the number.

The first bullet screams "for loop" while the next three are conditional (if) statements. With that in mind we'll write our simplest solution relying on a series of if-else statements and the modulo operator.

Run on the Rust Playground

fn main() {
    for x in 1..=100 {
        if x % 3 == 0 && x % 5 == 0 {
            println!("FizzBuzz")
        } else if x % 3 == 0 {
            println!("Fizz")
        } else if x % 5 == 0 {
            println!("Buzz")
        } else {
            println!("{}", x)
        }
    }
}

This gets us the desired output, but there's nothing idiomatic about it. With the exception of ..= (specifies a range "up to and including"), none of Rust's unique features are being used. In fact, it looks almost identical to a solution written in Python! Clearly we can do better.

Make Me a Match

If you haven't read Rust Book, bookmark it right away! It's one of the best introductions to a language I've ever read, and explains not just the core language, but the toolchains surrounding it that make Rust so accessible. One thing the book wastes no time introducing is Rust's match operator:

"Rust has an extremely powerful control flow operator called match that allows you to compare a value against a series of patterns and then execute code based on which pattern matches. Patterns can be made up of literal values, variable names, wildcards, and many other things"

—The Rust Book Ch. 6-2

Let's update our basic function to use match instead of if-else. We want to match the output of two modulo operators, if they're both zero we'll output Fizzbuzz, if only one is zero we'll output Fizz or Buzz depending on the zero. and if neither are zero we'll simply output the number.

Run on the Rust Playground

fn main() {
    for x in 1..=100 {
        match (x % 3, x % 5) {
            (0, 0) => println!("FizzBuzz"),
            (0, _) => println!("Fizz"),
            (_, 0) => println!("Buzz"),
            _ => println!("{}", x),
        }
    }
}

Now this is starting to look more like Rust! By using match we're able to eliminate a lot of unnecessary brackets and only have to calculate the modulo once, instead of at every if statement. Since the match control flow operates from top to bottom, we need the "FizzBuzz" case to be listed first, as both "Fizz" and "Buzz" also satisfy the (0,0) case.

Getting Idiomatic

The above code would be more than enough to show an interviewer you passed CS 100, but we want to squeeze every possible idiomatic opportunity out of this function, so our next step will be pulling our logic out of the main function and into a trait. Again referencing the Rust Book:

"A trait tells the Rust compiler about functionality a particular type has and can share with other types. We can use traits to define shared behavior in an abstract way. We can use trait bounds to specify that a generic can be any type that has certain behavior."

—The Rust Book Ch. 10-2

Right now we're only going to focus one one small feature of traits: defining sets of methods that can be called on a type (in our case i32). Our trait Fizzy will be simple in that it only has one function (also named fizzy) that accepts a reference to the number and returns a String based on our Fizzbuzz rules.

pub trait Fizzy{
    fn fizzy(&self) -> String;
}

Trait definitions only declare the methods, they do not define the actual logic. For that we need to implement the trait for our selected type. This is as easy as making an impl for i32 and moving the match statement out of our main function into the fizzy method. Our new program is shown below with the logic separated out into its own trait.

Run on the Rust Playground

pub trait Fizzy {
    fn fizzy(&self) -> String;
}

impl Fizzy for i32 {
    fn fizzy(&self) -> String {
        match (self % 3, self % 5) {
            (0, 0) => String::from("FizzBuzz"),
            (0, _) => String::from("Fizz"),
            (_, 0) => String::from("Buzz"),
            _ => format!("{}", self),
        }
    }
}

fn main() {
    for x in 1..=100 {
        println!("{}", x.fizzy())
    }
}

It may look like all we did was shuffle around where the code was (and for this simple of a program traits are already overkill) but structuring our logic into a trait allows for flexibility down the road, especially if we have to add more methods to Fizzy or define it for different types (imagine a new Fizzbuzz with letters instead of numbers). The separation also allows us to write unit tests to validate fizzy since it can be called separately from the main function.

Idiomatic Testing???

Unit tests themselves are not unique/idiomatic to Rust. In fact, you'd be hard pressed to find a modern language that does not have an extensive unit test framework to tap into. What is idiomatic, however, is how testing is built into the core language and Rust's solution to testing private interfaces.

When writing a class/interface, I'll split complex methods into multiple small methods that can be easily tested, but I don't want those interim methods exposed to the end user. Python makes this easy enough with private methods, prefixing a function with an underscore (_) marks it as private, and most documentation and linters will treat it as such. However, it's actually as public as any other function, so while the IDE might flag a warning when I call the method to test it, there's nothing illegal about doing so (see below).

class Greeter(object):

    def __init__(self, name):
        self.name = name

    # putting an _ before a method marks it as private
    def _address(self, preamble: str) -> None:
        print(f"{preamble} {self.name}")

    def hello(self) -> None:
        self._address("Hello") # a public interface can call a private method


if __name__ == '__main__':
    greeter = Greeter("Fotonix")
    greeter.hello() # this instance method is public
    greeter._address("Buongiorno") # this method is private, but can still be called

#-- Output --
# Hello Fotonix
# Buongiorno Fotonix

On the opposite side of the accessability spectrum we have C++, which uses its public, private, and protected keywords to strictly enforce what objects and classes have access to those methods. While this is great from a security standpoint, it makes testing non-public interfaces difficult because you either have to (1) accept that you can only write "blackbox tests" that test the interfaces end users have, or (2) create friend classes that wrap the private functions in a public interface, and test that new interface.

Rust strikes a happy medium between the two. You can still declare traits as public or private, and that privacy is not only respected, but enforced at compile-time. However, using the modules system, you can put your tests in a path that has access to the private traits (i.e. they're within the trait's scope).

The most common way to do this is to inline unit tests in the same file as the methods you're testing and wrapping them in a module called test. Apart from this unique layout, writing the tests themselves is similar to most unit-test frameworks. Rust has built-in macros for assertions and tests can be separated into functions to run concurrently. We'll add unit-tests to the bottom of our Fizzbuzz program to validate the Fizzy trait. Tests can by run by running cargo test from the terminal, or "test" from the pull-down menu in the playground.

Run on the Rust Playground

#[cfg(test)]
mod test {
    use super::*;

    #[test]
    fn test_fizz() {
        for x in &[3, 6, 27] {
            assert_eq!(x.fizzy(), "Fizz")
        }
    }

    #[test]
    fn test_buzz() {
        for x in &[5, 10, 20] {
            assert_eq!(x.fizzy(), "Buzz")
        }
    }

    #[test]
    fn test_fizzbuzz() {
        for x in &[15, 30, 60] {
            assert_eq!(x.fizzy(), "FizzBuzz")
        }
    }

    #[test]
    fn test_num() {
        for x in &[13, 29, 98] {
            assert_eq!(x.fizzy(), format!("{}", x))
        }
    }
}

Generic Traits and Monomorphization

At this point pulling out the above Fizzbuzz will knock any interviewer's socks clean off... or they'll be annoyed that you've spend so much time on such an easy question, could go either way. But we're not here to please an imaginary interviewer! We're writing the most idiomatic Fizzbuzz in the history of Rust, so let's add one more "totally unnecessary in this context but useful in general" feature: Generic Types.

Up until now we've used i32 as the base type for all things Fizzbuzz. It's a safe bet for general integers, having a range of >4 billion, but will it always be the right choice for our program? If Fizzbuzz will only ever use positive numbers, you may as well use an unsigned int. If you only ever need to calculate up to 100, 32-bits is overkill and you're better off with u8. Instead of trying to predict the end use-case, we want to write our trait implementation such that the main function can call it with any integer type, and an appropriate trait method is called.

Rust solves this issue with generics. Instead of defining a function for a specific type, the programmer defines a set of traits that the type must implement. Generics are one of Rust's zero-cost abstractions, and provide flexibility while incurring no overhead at runtime.

To make Fizzy generic to all int types, we'll use the num crate. The trait we want is PrimInt which is a general abstraction for integer types, and Zero which will generate the zero value we compare to. We also need the Display trait from the standard library, which enforces that the type can be formatted into a string.

Run on the Rust Playground

use num_traits::{identities::Zero, PrimInt}; // 0.2.14

pub trait Fizzy {
    fn fizzy(&self) -> String;
}

impl<T> Fizzy for T
where
    T: PrimInt + Zero,
    T: std::fmt::Display,
{
    fn fizzy(&self) -> String {
        let zero = T::zero();
        let three = T::from(3).unwrap(); // These will never fail
        let five = T::from(5).unwrap();
        match (*self % three, *self % five) {
            (x, y) if x == zero && y == zero => String::from("FizzBuzz"),
            (x, _) if x == zero => String::from("Fizz"),
            (_, x) if x == zero => String::from("Buzz"),
            _ => format!("{}", self),
        }
    }
}

fn main() {
    for x in 1..=100 {
        println!("{}", x.fizzy())
    }
}

Notice how we can no longer use integers in fizzy, but instead have to convert them to our generic type within the function. Fortunately the compiler optimizes this out and replaces them with constants in the final code. This is also a case where its acceptable to use unwrap without fear of causing a panic at runtime. Since T implements PrimInt we know a conversion from integers to T will never fail.

Update

/u/TinBryn pointed out that that type bounds I picked were unnecessarily complex due to Rust's super traits system. A type implementing PrimInt implies it also implements Zero and Copy, and Copy implies Clone. Ultimately all we need to include is where T: PrimInt + std::fmt::Display to get the same functionality.

Going off the Deep End

We did it, we wrote an amazing Fizzbuzz leveraging a slew of Rust's unique features! But we also cheated slightly... The rules of the game asked us to print the result of the fizzbuzz check, but to enable testing we return a String that's printed in the main loop. We can trim down this waste of a whopping 72 bytes of memory by having fizzy write directly to an IO stream! The easiest solution would be to have our function call the println! macro directly, but then we can no longer test our function. Instead, We'll borrow a tip from the Rust CLI Book (different than The Rust Book, but equally as good) where we pass a mutable reference to a Writer handle. In the main loop that handle will point to stdout, but for testing it will be a vector that we can compare to the expected output.

This requires a couple modifications to our fizzy function:

We need to replace all the match statement arms with writeln! macro calls.
Since writeln! can fail we need to modify the signature of fizzy to return a std::io::Result enum, allowing us to squeeze in yet another idiomatic feature: Error Types!

We also want to be able to catch the error in the main function. so we'll replace the for loop with an iterator, and consume it with a try_for_each method.

Run on the Rust Playground

use num_traits::{identities::Zero, PrimInt}; // 0.2.14
use std::io::{Result, Write};

pub trait Fizzy {
    fn fizzy(&self, writer: &mut impl Write) -> Result<()>;
}

impl<T> Fizzy for T
where
    T: PrimInt + Zero,
    T: std::fmt::Display,
{
    fn fizzy(&self, writer: &mut impl Write) -> Result<()> {
        let zero = T::zero();
        let three = T::from(3).unwrap(); // These will never fail
        let five = T::from(5).unwrap();
        match (*self % three, *self % five) {
            (x, y) if x == zero && y == zero => writeln!(writer, "FizzBuzz"),
            (x, _) if x == zero => writeln!(writer, "Fizz"),
            (_, x) if x == zero => writeln!(writer, "Buzz"),
            _ => writeln!(writer, "{}", self),
        }
    }
}

fn main() {
    let mut out = std::io::stdout();
    if let Err(error) = (1..=100).try_for_each(|x| x.fizzy(&mut out)) {
        println!("IO Error Writing to Stream: {}", error)
    }
}

With those small changes we've added mutable references, iterators, and error handling to the list of features this little program can demonstrate. Was any of it necessary? Not at all! Our final output is no different than the first program composed of if-else statements. But it's always fun to start with a trivial program and think up ways to transform it into something that makes me feel like I'll one day earn the title of "Rustacean".

Update - Why no Love for Enum?

After posting this code onto the r/rust subreddit, the most common feedback I got was along the lines of "why are you passing strings around/writing directly to stdout, make an enum and use that instead." This somewhat surprised me because my first pass at writing this code did use an enum with an associated value, and the feedback for that code was "the enum is unnecessary if all you'll ever do is print the output, just print it directly to stdout." These conflicting feedbacks have helped me spawn my own definition for truly idiomatic Rust:

"The most idiomatic Rust is whatever code you did not write, but somebody else has decided you should."

—Fotonix

Not one to disappoint, however, lets write a final Fizzbuzz that forgoes our custom trait in favor of an enum that implements std::fmt::Display!

Run on the Rust Playground

use num_traits::{identities::Zero, PrimInt}; // 0.2.14
use std::fmt;

#[derive(Debug, PartialEq)]
enum FizzbuzzResult<T> {
    Fizz,
    Buzz,
    FizzBuzz,
    Num(T),
}

impl<T> fmt::Display for FizzbuzzResult<T>
where
    T: fmt::Display,
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match *self {
            FizzbuzzResult::Fizz => write!(f, "Fizz"),
            FizzbuzzResult::Buzz => write!(f, "Buzz"),
            FizzbuzzResult::FizzBuzz => write!(f, "FizzBuzz"),
            FizzbuzzResult::Num(ref val) => write!(f, "{}", val),
        }
    }
}

fn fizzbuzz<T>(num: T) -> FizzbuzzResult<T>
where
    T: PrimInt + Zero,
    T: Copy + Clone,
{
    let zero = T::zero();
    // These will never fail
    let three = T::from(3).expect("Could not convert '3' to generic type");
    let five = T::from(5).expect("Could not convert '5' to generic type");

    match (num % three, num % five) {
        (x, y) if x == zero && y == zero => FizzbuzzResult::FizzBuzz,
        (x, _) if x == zero => FizzbuzzResult::Fizz,
        (_, x) if x == zero => FizzbuzzResult::Buzz,
        _ => FizzbuzzResult::Num(num),
    }
}

fn main() {
    for x in 1..=100 {
        println!("{}", fizzbuzz(x))
    }
}

This code has a few distinct advantages, but the main ones are you only ever return an enum that lives on the stack, and testing no longer involves string comparison, but instead compares the returned enum to the expected type (This is why PartialEq is derived for FizzbuzzResult). On the flip side, we now have two match comparisons: one to generate the enum and one to display it, whereas our first attempt has only one.

At this point I don't know which of these options is more idiomatic, but I do know now that I've written them down, somebody is going to come in with a third option claiming it's superior to both 😄.

Version Controlling Your Data Science Projects

Ryan Frazier — Mon, 31 May 2021 15:46:46 GMT

Historically I've been a huge advocate of Mathematica for scientific computing. The symbolic analysis made physics modeling a breeze, and I could quickly create attractive summary plots to be shared with my team. As I started looking at large datasets and collaborating with more engineers, however, Mathematica became more hinderance than help. As Code could not be easily version controlled, it would often end up emailed back and forth with the receiver having to manually check that they had all dependent files, as well as update file-paths to load data without errors.

Most of my coworkers were not familiar with Mathematica, and there wasn't justification in purchasing license seats just for them to open and run my files. All of this culminated in an environment where most data analysis bottlenecked through me and caused unnecessary slowdowns.

These issues sparked my conversion to Python for almost all analysis. As free, open-source software, anybody on my team can install it in minutes, and its popularity as a scripting language means nearly everybody we onboard has some Python experience. Today I'll be covering the repository structure I've adopted to make a data analysis workflow that anybody can easily use and contribute to. It assumes you have familiarity with the Python ecosystem and Jupyter Notebook environment, as well as a light understanding of Git.

Contents

Quick Links

What Makes this Structure Special?

Our new analysis flow is going to borrow extensively from the great open source tools that have come about for data science combined with best practices for software maintenance. In the end we will have a repository that can be extended for any data analysis project featuring:

A version controlled Git repository with hooks in place to only store code.
Jupyter notebook integration to perform the actual analysis.
A managed Python environment to keep track of dependencies.
Version controlled data which is stored separately from your code, but tracked in the main repository.
A clean, informative ReadMe enabling other users to download and run the same analysis.

If you want to skip the explanation, you can fork a template of the final repository from GitHub.

Required Software

While most of the tools we use will be installed through Python's own package manager, there's a few pieces that need to be downloaded separately:

A Python Distribution - The base Python Interpreter. At the time of writing I recommend version 3.8, which is well supported. It's worth noting that if you are on Windows, the pywinpty package (required by Jupyter) only supports 64-bit Python, so make sure to download a 64-bit interpreter.
Poetry - We'll use Poetry to manage virtual environments as well as make sure others can install the same package versions we're using (via the poetry.lock file).
Visual Studio Code - While any text editor will work, VSCode's extensive Python support (including a Jupyter extension that runs a server in the editor) makes it a one-stop shop for data analysis.
Git - At the end of the day Jupyter notebooks are still code, and we want to exercise best software practices when writing them, version control included. Git can be daunting at first, but VSCode's Git integration means your commits can be done through the UI instead of command line.

Once everything is installed we're ready to set up the environment. Create a new folder that will hold the repository and open it in VSCode (Ctrl+K if you're already in VSCode).

Setting Up Our Python Environment

We want the packages we depend on to be isolated from the rest of the Python installation. Since Python dynamically links libraries at runtime, updating a package down the line (e.g. to install a different library with a newer dependency) might break your old code, or worse, introduce a subtle bug that you don't catch until much later. While we could go to an extreme and containerize all of our code, running it in a Docker Environment or similar, Python instead offers a simpler solution through virtual environments. If virtual environments are a new concept, I recommend reading the tutorial on python.org.

Easy Virtual Environments with Poetry

Poetry makes creating new environments easy with its poetry init command. This will ask a series of questions about your project which the tool will use to generate a pyproject.toml file. You can also choose to add any package dependencies when creating the environment. It's simple and often faster to add dependencies later, so I typically skip this step.

If there's not a console at the bottom of your VSCode window, open it with Ctrl+Shift+`, or Terminal -> New Terminal and run the initialization.

$ poetry init

This command will guide you through creating your pyproject.toml config.

Package name [data_analysis]:  my_awesome_analysis_repository
Version [0.1.0]:
Description []:
Author [Ryan Frazier <ryan@fotonixx.com>, n to skip]:
License []:
Compatible Python versions [^3.9]:  >3.8,<3.9

Would you like to define your main dependencies interactively? (yes/no) [yes] no
Would you like to define your development dependencies interactively? (yes/no) [yes] no

Once it's done, pyproject.toml will be generated in the root directory with the information you entered. By default Poetry will create the environment in a separate directory, but you can access it with poetry run. Test that your environment is running by executing poetry run py --version, and making sure it matches the version you specified.

Adding Common Dependencies

The specific packages you need will vary project-to-project, you'll almost always be using the Scientific Python Stack, so let's add it to our dependencies! We also need to install the Interactive Python (IPython) Kernel so we can register this environment as a Jupyter Kernel later. All of these can be installed using poetry's add command.

$ poetry add jupyterlab numpy scipy matplotlib pandas ipykernel

If you open pyproject.toml you'll see all those packages are now listed in the dependencies section. Additionally, Poetry created a poetry.lock file which is used to store the exact versions of every package and dependency in the environment.

Registering Our Environment as an IPython Kernel

Jupyter uses IPython Kernels running as a separate process to evaluate cells. In order for Jupyter to use our newly created virtual environment, we need to register it with a kernel using the ipykernel package. Run the below command, replacing name and display-name with appropriate values for the project.

$ poetry run python -m ipykernel install --user --name project_x_env --display-name "My Awesome Data Science Environment"

Now you can Launch Jupyter from any environment, including the global environment, and still access this environment's packages. If you don't have Jupyter installed globally, you can run the installation in our environment by executing poetry run jupyter lab. Alternatively, creating and opening an *.ipynb file in VSCode will enable the data science view.

Our newly created Kernel as a selectable option

Adding Version Control

You might be wondering why a data analysis project needs version control, or what version control even is. To quote Atlassian:

"Version control software keeps track of every modification to the code in a special kind of database. If a mistake is made, developers can turn back the clock and compare earlier versions of the code to help fix the mistake while minimizing disruption to all team members."

Sounds pretty great, right?! If you still need convincing: imagine you're toying with a new way to look at data but you don't want to delete your current method. Instead of copying the file into a new one, you can create a branch and merge the changes if they work, or delete them if not. Not only that but you can have multiple people simultaneously looking at the data, each person focused on their specific tasks, with all changes merged at the end.

Making a New Repository

To keep things simple we'll use VSCode's Git plugins to create, commit to, and push our repository. On the left side of the VSCode window you should see the directory structure with the pyproject and poetry.lock files. Depending on your Poetry settings the virtual environment may also be in this base directory.

Open the Command Pallette (Ctrl+Shift+P or f1 on Windows) and type "git init". There should be only one option that reads "Git: Initialize Repository". Press Enter and select the current folder to initialize the repository.

Notice that pyproject.toml and poetry.lock have turned green in the Explorer (Ctrl+Shift+E)! This is because VSCode knows you have a repository in the directory and that those files have not been staged for a commit. If you open the Source Control Panel (Ctrl+Shift+G) you'll see both those files listed as changes with a "U" on the right meaning they're unstaged. Before staging and making our initial commit, however, we want to add a few more files that will help flesh out the repository. These include:

a readme.md file in the base directory
a .gitignore file in the base directory
a new directory /notebooks/ with a readme.md inside of it.
a /data/ directory with an empty .gitkeep file inside of it.

When you've added the files your project directory should look similar to below:

Choosing which Files to Ignore

Git uses the .gitignore file to black-list specific files or even entire directories from being captured into version control. This helps keep the repository size small and only commit files that are necessary to reproduce the environment. As a rule of thumb the following should be excluded from your commits:

Any IDE settings (the ./.vscode/ directory )
Auto-generated files (*.pyc, file backups etc.)
User specific environment files
Large files that don't often change (downloaded datasets, third-party libraries)

It might seem alarming that datasets should not be part of version control, after all you have nothing to analyze without data! Further down we'll talk about how to synchronize data with the repository, but for now we'll ignore all files in the /data/ directory except for our whitelisted .gitkeep file.

# Ignore data directories
/data/*
!/data/.gitkeep

The rest of our .gitignore file is built off of GitHub's python.gitignore with the above additions to ignore our data directory, as well as VSCode settings, and Jupyter backup files. The entire file can be found here.

Creating a Git Hook to Prevent Messy Commits

While I love Jupyter for exploration and data analysis, one thing that always bothers me is how the code lives in the same file as evaluated evaluated output. When version controlling notebooks this can cause issues for a couple of reasons:

If the data you're working on is private but the code is public, the private data could end up in an output and committed, available for anybody to see.
Git works by logging differences in your file. This includes things like cell number, cell output, and picture metadata, if you version control an evaluated notebook you'll have unstaged changes as soon as you evaluate a cell, even though none of the written code actually changed!

We want a way to scrub our notebooks of all evaluated output before committing them. To do so we'll use githooks which are custom scripts that run when you perform a Git command. Flipping through the Githook documentation, the pre-commit hook is exactly what we need. Unfortunately, installing a Githook is a manual process that requires you to add a file to your /.git/ directory.

Githooks are a great way to keep your repository clean, but you must make sure your file is saved before running the hook, otherwise the script will overwrite any unsaved changes.

In order to make it as easy as possible for anybody to use this template, as well as make writing the githook simple, we'll instead use the pre-commit python package and write our hook with a YAML file that will live in the root of our version control. The pre-commit config we'll be using comes from Yuri Zhauniarovich's blog and uses nbconvert to scrub the output in-place.

Let's add pre-commit and nbconvert to our poetry environment. Since it's not needed to actually run the notebooks, and will only be used by people contributing to the codebase we'll install them as developer packages.

$ poetry add pre-commit nbconvert --dev

To define the hook, a new file in the base directory called .pre-commit-config.yaml and add the following text:

repos:
  - repo: local
    hooks:
      - id: jupyter-nb-clear-output
        name: jupyter-nb-clear-output
        files: \.ipynb$
        stages: [commit]
        language: system
        entry: poetry run jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace

The last piece is to install the githook so that it's run before every commit. Pre-commit makes this easy for us with it's install argument.

$ poetry run pre-commit install
pre-commit installed at .git\hooks\pre-commit

This is a good spot for our first commit! We've fleshed out the repository, filled our .gitignore and added most of our template files (even if they are empty). To commit using VSCode we'll again use the Source Control Panel (Ctrl+Shift+G). You can manually stage files by pressing the "+" icon to the right of the files, or you can stage all changes by clicking the "+" to the right of the "Changes" drop-down.

All commits should have a meaningful message so that you can look back and quickly understand what was changed. Chris Beam's Blog has a great post on the importance of a good commit message and how to write one, but for our first commit message we'll keep it simple with "initial commit".

With the files staged and commit message filled out, press the check-mark at the top of the panel to commit the changes.

Version Controlling Data

Next comes adding data to the repository. Copy any necessary data files over to the /data/ directory we made earlier. You can have a nested directory tree inside of that directory so organize it into a structure that works for you. Looking at the Explorer panel you'll notice all these files are greyed out and don't show up if you tab over to the Source Control panel. Since /data/ is ignored every file and folder below is is subsequently ignored as well.

Why Don't We Store Everything in the Git Repository?

To understand why we wouldn't want to store our large data files in a Git repository, lets peel back what happens when you clone an existing repository onto your local system. From Atlassian's Git-LFS tutorial:

"Git is a distributed version control system, meaning the entire history of the repository is transferred to the client during the cloning process. For projects containing large files, particularly large files that are modified regularly, this initial clone can take a huge amount of time, as every version of every file has to be downloaded by the client."

The solution to this problem is to not version control the large files at all, but instead version control small reference files that tell you where the data lives so you only check-out the version you want, instead of the entire history. Git-LFS (Large File System) is one implementation of this strategy, but we're going to instead use the Data Version Control (DVC) Python package, which is specifically designed with data-analysis in mind.

Setting up DVC

Since DVC is a Python package, we can install it with Pip just like our other dependencies. The assumption is anybody using our repository will want access to the data, not just developers, so we won't both with the --dev flag either.

$ poetry add dvc

DVC is designed to mimic a Git workflow, so many of the commands you'd use for Git have DVC parallels. For example, to initialize DVC in our repository and add the data directory we use the init and add commands respectively.

$ poetry run dvc init
$ poetry run dvc add ./data/
~~~
To track the changes with git, run:
        git add data.dvc .gitignore

Notice the final output after adding the data directory, DVC is telling us that it's created a new file called data.dvc that's tracking changes to our data directory. It's also updated .gitignore automatically for us to ignore /data/ (Our previously committed .gitkeep will not be ignored since it's already tracked). DVC's offering a convenience in case we had forgotten to ignore the directory ourselves, but since we already had, let's revert our .gitignore to its previous state. In the Source Control Panel, right-click .gitignore and select "Discard Changes". This will reset the file to its state in the previous commit.

If you add new data to the directory, you can update data.dvc by running dvc add ./data/ again. Make sure to commit data.dvc as soon as you add new data, otherwise committed notebooks might lose sync with the data changes.

Adding a Remote

DVC allows you to back-up version-controlled data to remote servers, perfect for enabling multiple users to access the same version of a dataset. From the documentation:

The same way as GitHub provides storage hosting for Git repositories, DVC remotes provide a location to store and share data and models. You can pull data assets created by colleagues from DVC remotes without spending time and resources to build or process them locally. Remote storage can also save space on your local environment – DVC can fetch into the cache directory only the data you need for a specific branch/commit.

Using DVC with remote storage is optional. DVC commands use the local cache (usually in dir .dvc/cache) as data storage by default. This enables the main DVC usage scenarios out of the box.

I recommend setting up a default remote even if you're the only one looking at the dataset. Mine are usually directories on an internal network drive, but DVC has support for multiple storage types, so use whichever structure works best for you. The remote can even be a separate directory on you computer.

Once the remote is set-up, pushing to it is as simple as running dvc push <remote>. To pull from your remote you similarly run dvc pull <remote>.

Document Everything with a ReadMe

A good ReadMe will elevate your repository from "that collection of code that only you know how to use" to "an easily understood project that anybody can contribute to." Think of the ReadMe like a lab report with instruction on how to reproduce the analysis, it should:

Clearly summarize the goal of the repository.
Explain how to duplicate the code on a user's machine. This includes:
- Installing required software (Python, Poetry, etc.).
- Creating the Virtual Environment and installing necessary packages.
- Registering the Environment with Jupyter.
- Pulling data from the DVC remote.
Explain how to run the analysis, with a description of what each notebook does and what results it will generate.
Give clear instructions for how users can contribute to/extend the repository:
- Installing the additional developer dependencies.
- Making sure the githook is set-up so only clean files are committed.

I'm a big fan of othneildrew's Best ReadMe Template and use it for most of my projects. A modified version can be found on the example repository which covers all of the above requirements.

Remember we also had a second ReadMe in the /notebooks/ directory which we'll use to describe each notebook in greater detail. You can even include example plots and outputs that the notebooks should generate. GitHub will show a rendered ReadMe in every directory that has one, so you can even group all your notebooks into separate subdirectories, and have a specific ReadMe explaining the purpose of every group!

With data added, committed, and ReadMe's filled in it's time for our next commit! Stage all the changed files and give it a meaningful message: e.g. highlight what data was added and where it came from. Be sure to follow the 50-72 rule so your messages stay meaningful and concise.

This is a great time to push your commits up to your favorite server. If VCS is completely new to you, I'd recommend GitHub for its sheer popularity and option to make both public and private repositories with a free account.

What's the Workflow Look Like?

With the repository set up, it's time to outline how to use it for analysis. While at the end of the day you should do whatever is natural for your team. I recommend adopting a modification of the Gitflow workflow:

No work is done in the main branch of the repository.
When you have a new task, make a branch off of main and do all of your work in that new branch.
All notebooks should live in the /notebook/ directory. Use subdirectories to group similar notebooks.
When the task is finished, clean up the branch and update the ReadMe to describe any new files. Depending on how formal your team is, manually merge the branch back into main or submit a pull-request.

This structure ensures that analysis tasks are done in isolated environments and only merged back when they're finalized, and you don't need to constantly worry about pulling from the main branch and resolving merge requests.

How to Save Results

This repository structure does a great job making sure analysis is done in a clear, reproducible matter, but I haven't touched on how to actually save results. In fact, because of our commit-hook, even if your VCS server rendered Jupyter notebooks (and many do) there would be no output and only code! How do we actually save results in a format that can be looked back on? This will vary from person-to-person, but I like to create a /results/ directory and use Sphinx to create a static website with a new page for each result. Be sure to populate them with saved images and hard coded values so that the results persist even if you edit the code later on.

Static site generation with Sphinx can easily be integrated into a CI/CD workflow and Github even offers free hosting of static pages. Look into gh-pages for an easy way to deploy your pages into a GitHub hosted Static site.

This entire template can be found on my GitHub, feel free to fork it for your own projects and submit requests for additional features!

5 Video Game Soundtracks to Jam Out to While Coding

Ryan Frazier — Sat, 24 Apr 2021 20:35:11 GMT

Looking for a great programming playlist, try a video game soundtrack! The lack of lyrics stop them from being a distraction, but they're engaging enough to help you focus and drown out background noise. Below are five soundtracks I regularly listen to when I need to shut out the world and code.

5. Doom (2016) - Mick Gordon

For when you find yourself up too late with bloodshot eyes and an energy drink in hand, blazing through code like a wannabe hacker channeling your inner Cereal. There's nothing better to keep you in the zone like the grandfather of shooters: Doom!

Filed under Progressive Metal, Mick Gordon's TGA winning soundtrack is full of high energy tracks to get your blood pumping. While a few songs feature samples of the 1993 classic (I'm looking at you "At DOOM's Gate"), most tracks set themselves apart from the original game's already great songs. If you want to make an evening of debug feel like you're pulling off a Shadowrun heist, look no further than Doom.

4. Celeste - Lena Raine

A game that needs no introduction, Celeste is an incredibly popular platformer that still manages to regularly show up on "hidden indie gems" lists. When an entire subcomponent of the game is to collect floating casette tapes to unlock "B-Side" levels, you know music must play a big role, and Lena Raine does not disappoint!

I find myself regularly looping through the 100 minutes of tracks only to be left wanting more when it ends. The feel of the songs range from motivating and energetic, to downright haunting, but every one is a perfect accompaniment when focusing on a task.

3. Desktop Dungeons - Danny Baronowsky & Grant Kirkhope

There's a solid chance you haven't heard of Desktop Dungeons, a smaller indie game from 2013. However, you've probably heard of Ubisoft's X-Com/Mushroom Kingdom Crossover Mario + Rabbids, Kingdom Battle (music by Kirkhope) or the indie hit turned Legend of Zelda spinoff Crypt of the Necrodancer (music by Baronowsky). With two great composers behind it, it's no wonder the Desktop Dungeons soundtrack turned out as good as it did.

Mostly orchestral with some great brass sections, these tracks are great to put on when you need a bit of energy but don't want something so intense that it distracts your focus. The game itself is well worth attention too. Branded as a "coffee break" turn-based dungeon crawler, the games 15 minute rounds are incredibly satisfying, and the alpha is available for free on the developer's website.

2. Payday 2 - Simon Viklund

Similar to Doom, Payday 2's soundtrack is full of blood pumping tracks to keep you amped while you fly through for loops (or rob a bank, you do you). Unlike Doom's metal approach, however, Payday's songs are more suited for an early 2000's rave, with lots of industrial sound effects and synthesizers.

Only recently going up on Spotify, these tracks are the creations of Simon Viklund, who has since left Overkill Software to make another well received Co-Op shooter, GTFO. Supposedly Payday 3 is in the works for a 2023 release, but with both Viklund and original game designer Ulf Anderson out of the picture, I'm hard pressed to believe it will capture the charm of the originals.

1. A Hat in Time - Pascal Michael Stiefel

If you need to dedicate a long period of time to focus, look no further than the soundtrack to A Hat In Time. Clocking in at over five hours, this is the perfect soundtrack to put on when you want a constant stream of background music without jumping between albums.

Originally released in 2017, this is the only game on the list that I hadn't played before hearing the soundtrack. But after listening to it multiple times, I've picked it up to see just what crazy world all these upbeat tracks exist in. Standout songs are Train Rush and Trainwreck of Electro Swing but you really can't to wrong with any of the tracks that vary from slow and atmospheric, to upbeat and jazzy. Best of all, each song is full-length and fleshed out, instead of being a collection of looping sound bytes.

2D Binary Spacing Partitioning with Python and NetworkX

Ryan Frazier — Tue, 30 Mar 2021 00:20:56 GMT

I'm a sucker for tricks programmers use to get games to run efficiently, from the metro train in Fall Out 3 that's actually a piece of armor, to the spell casting bunnies in World of Warcraft that triggered world events. In a slightly different camp, however, are tricks that enabled game makers to do the impossible with the hardware they're given, and one name that's constantly tied to these feats is John Carmack, cofounder of id software and pioneer of 3D computer games. His use of ray casting for Wolfenstein 3D and the fast inverse square root algorithm alone are topics worthy of their own posts, but today I'm going to focus on the algorithm he used to enable real-time 3D level rendering in the original Doom: binary space partitioning (BSP).

Carmack's vision for Doom was to have maps with varying heights, zone-specific lighting, and non-orthogonal walls. Unfortunately, the ray casting algorithm used in id's previous game, Wolfenstein 3D, couldn't render such complex scenes, so he was left looking for a new solution. David Kushner's Masters of Doom, as well as this post on twobithistory have already covered this story wonderfully, so I won't go into excessive detail but instead focus on the solution. By representing levels as binary trees of line segments, the rendering engine could quickly decide which surfaces to draw and in what order. Despite being incredibly curious when I first read Masters of Doom, I wasn't working on anything related to computer graphics at the time, and filed BSP trees off for something to look at another day.

Fast forward to now: I'm trying to incorporate OpenGL rendering into my ray tracer, which requires constructive solid geometry performed on polygonal meshes. Turns out binary space partitioning is a core part of this algorithm too, so it's finally time to dive in and learn how to create and use BSP trees!

Contents

Quick Links

What's So Special About Binary Space?

Binary space partitioning divides an n-dimensional space into segments that are entirely in front or behind a dividing hyperplane. For now we'll focus on the 2D case, which means the partition splits a group of line segments into sets that are either in front, behind, or colinear to a dividing line. Repeatedly performing this partitioning on the resulting sets creates a binary tree, where every node contains a dividing line and all colinear segments, and each edge connects to a child node whose segments are completely in front or behind the current node.

Construction of a BSP tree by repeatedly subdividing a collection of surfaces. Edges labeled + are in front of the previous node, and - are behind.

The most popular use for BSP trees is for visible surface determination in computer graphics, notably for the painter's algorithm. As the painter's algorithm draws the entire set of surfaces from back to front, it needs to be able to quickly sort the surfaces from any viewpoint. BSP trees allow for the computationally expensive sorting to happen just once. When the scene needs to be rendered the tree is traversed in linear time from the current viewpoint and a sorted list of surfaces is generated. It's worth noting this only works for static surfaces, which made it ideal for rendering Doom's level maps. As soon as an individual surface is transformed, however, the entire tree needs to be regenerated.

A less famous use of BSP trees is performing constructive solid geometry (CSG) operations on discrete polygonal meshes. This application uses two separate BSP trees, one for each object the operations are being applied to. The trees are then 'projected' onto each other, resulting in a set of surfaces from one object that are entirely in the other. Depending on the operation (union, intersection, or difference), certain surfaces are discarded, and the remaining ones make up the new shape. The actual CSG algorithm is beyond the scope of this post, but the documentation and code for the csg.js library provides a basic explanation.

Creating a BSP Tree

In addition to the standard library, we'll use Numpy to calculate the line-segment intersections, and NetworkX to create the tree. NetworkX is a general purpose graph library that prevents us from having to define our own nodes and edges, and includes extensive traversal algorithms and visualization features. Both packages are installable via pip.

py -m pip install numpy, networkx

The BSP algorithm

Below are the steps we'll be implementing to create our tree. Given a set of 2D line segments and a dividing line:

Calculate the intersection of the dividing line with all segments.
Split any segments that intersect the dividing line into two segments at the intersection.
Add colinear line segments to the current node of the tree.
Create a new child node and repeat steps 1-6 for all segments in front of the dividing line.
Create a new child node and repeat steps 1-6 for all segments behind the dividing line.
Connect the new nodes to the current node with an edge.

Since tree generation is a recursive process, steps 4 and 5 repeat every step up to and including themselves until every line segment can be described as colinear to a node. Also, the number of segments in the returned tree may drastically exceed the number of segments in the original set, depending on how many are bisected at each iteration. We'll break the algorithm down into two pieces: the code used to intersect and split a set of segments with a dividing line, and the recursive function that builds the tree.

Bisecting a Line

The bulk of the processing is determining where each line segment in a set intersects the dividing line. We'll make a function called bisect that accepts an array of line segments and a dividing line, and returns three arrays, one each for segments ahead, behind, and colinear to the dividing line.

def bisect(segments: np.ndarray, line: np.ndarray) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
    # separates a set of line segments based on where they intercept a dividing line

The segments array is an Nx2x2 array, where N is the number of segments being sorted. Each row of the array is a set of two xy-pairs representing the start and endpoints of the segment. For example, a square centered at the origin is composed of four segments:

square = np.ndarray([
    [[1,-1],[-1,-1]],
    [[-1,-1],[-1,1]],
    [[-1,1],[1,1]],
    [[1,1],[1,-1]]
])

Similarly, a line is represented by a single 2x2 array of two XY-pairs. The advantage of using Numpy data structures instead of Python lists and tuples is that we can apply the intersection algorithm to the entire segment array at once, instead of iterating over each segment with a for loop. Since Numpy calls compiled C-code, there is almost always a performance gain when a loop can be replaced with array operations.

The last decision we need to make before writing the bisect function is coming up with a consistent definition for what "in front" and "behind" mean in the context of our lines. An easy enough way to visualize it is this: If you take your right hand and orient it so that the pad of your hand is on top of the first point of the line, and your fingers point towards the second, everything on the left side of your hand (closest to the palm) is in front of the line, and everything on the right side (closes to the back of your hand) is behind the line. Later we'll define this more formally with projections onto a normal vector of the line. If the concept of a vector projection is new, I recommend reading up on dot and cross-products, or skipping straight to the implementation.

Intersecting Two Lines

To calculate the intercepts we'll describe the lines and segments as vectors with one independent variable.

\begin{equation*} \begin{aligned} \vec{l}(t) &= \vec{p}_0+(\vec{p}_1-\vec{p}_0)*t \\ &= \vec{p}_0 + \vec{v}*t \end{aligned} \end{equation*}

Since segments have a defined start and end, t is valid over a closed range $t \in [0,1]$. Lines on the other hand extend infinitely in all directions, so t can be any real number. For convenience I'm going to refer to our line segments as $\vec{g}(t) = \vec{p_0} + \vec{v}_0t$, and the dividing line as $l(s) = \vec{p}_1 + \vec{v}_1 s$. We're interested in the value t where the two lines meet.

\begin{align*} \begin{aligned} \vec{g}(t) &= \vec{l}(s) \\ \vec{p}_0 + \vec{v}_0 t &= \vec{p}_1 + \vec{v}_1 s \\ &... \end{aligned}\\ t = \frac{(\vec{p}_1-\vec{p}_0) \times \vec{v}_1}{\vec{v}_0 \times \vec{v}_1} \end{align*}

intersection point shown in red

I've skipped a few steps in the above equation because the intercept of two vector equations is well understood. What we're more interested in is using the results to determine where the segments lie with respect to our line.

Red flags might be going off because this equation is dividing two vectors, which is (1) an invalid operation and (2) can't result in a scaler. Since our lines and segments are all 2D, however, we're going to use the 2D definition of cross product: $\vec{A} \times \vec{B} = A_x*B_y-A_y*B_x$. This scaler is the z-component of the cross product vector we would have gotten had we taken a traditional 3D cross-product and set the z-values to zero for $\vec{A}$ & $\vec{B}$.

Ahead, Behind, Bisected or Colinear

It's easy to tell that the line bisects a given segment when the t is between 0 and 1. What about the other cases though: how do we determine if the segment is in front or behind the line, and what about cases where t is undefined? To get more insight into what's happening with the intersection equation, we'll look at the numerator and denominator separately.

Numerator

We already defined the two-dimensional vector cross product: $\vec{A} \times \vec{B} = A_x*B_y-A_y*B_x$. Taking a closer look, it's identical to $(A_x, A_y) \cdot (B_y, -B_x)$, and $(B_y, -B_x)$ is the same as rotating $(B_x,B_y)$ clockwise 90 degrees, aka it's proportional to the unit normal vector of the dividing line. The numerator can be rewritten as:

\begin{equation*} ((\vec{p}_0-\vec{p}_1) \cdot \hat{n})|\vec{v}_1| \end{equation*}

Meaning the numerator is taking the distance between a point on the segment and a point on the line, and projecting that vector onto the normal vector of the line (this is identical to calculating the shortest distance between a point and a line). From our definition of "in front" and "behind", we can claim that a line segment is partially in front of the line if the numerator is > 0, and partially behind if the numerator is < 0. If the numerator is equal to zero, it means the first point of the segment is on the line, and we need to look at the denominator to define whether it's in front or behind.

Denominator

Using the same logic as above, the denominator can be rewritten as a vector projection onto the normal vector:

\begin{equation*} -(\vec{v}_0 \cdot \hat{n})|\vec{v}_1| \end{equation*}

This projection is a measure of how far $\vec{g}(t)$ travels towards line $\vec{l}(s)$ per interval t. Since the numerator is how far the lines are apart (projected onto the normal vector), and the denominator is how fast one line is approaching the second along that same normal, it makes sense that the ratio is the amount of time (t) until they intersect!

If the denominator is equal to zero, the two lines are parallel, and the sign of the numerator determines where the segment lies relative to the line.

With the exception of cases where t is between 0 & 1, the numerator and denominator must be considered when defining the segments location. A summary of all cases is given below.

t	Numerator	Denominator	Line Segment Location
0 < t < 1	-	-	Bisected by line
t > 0 or t < 1	> 0	-	In front of line
t > 0 or t < 1	<0	-	Behind line
t = 0	-	< 0	In front of line
t = 0	-	> 0	Behind line
-	= 0	= 0	Colinear

Putting it Into a Function

Cases in hand we're ready to implement the first half of our bisect function!

def bisect(segments: np.ndarray, line: np.ndarray):

    segment_start = segments[..., 0, :]
    segment_end = segments[..., 1, :]

    v0 = segment_end - segment_start
    v1 = line[1] - line[0]

    # need to solve for the intersection equation, first find the numerator and denominator

    numerator = np.cross((line[0] - segment_start), v1)
    denominator = np.cross(v0, v1)

    # if the denominator is zero the lines are parallel
    parallel = np.isclose(denominator, 0)
    not_parallel = np.logical_not(parallel)

    # the intersection time is the point along the line segment where the line bisects it
    intersection = numerator / (denominator + parallel)

    ahead = np.logical_or(numerator > 0, np.logical_and(np.isclose(numerator, 0), denominator < 0))
    behind = np.logical_or(numerator < 0, np.logical_and(np.isclose(numerator, 0), denominator > 0))

    # segments are colinear if they are parallel and the numerator is zero
    colinear = np.logical_and(parallel, np.isclose(numerator, 0))

    # bisected segments are segments that aren't parallel and t is in (0,1)
    bisected = np.logical_and(
        not_parallel,
        np.logical_and(intersection > 0, intersection < 1)
    )

Right now all it does is build a set of boolean masks used to index the segment array. Before returning the new segments we need to write some code to split bisected segments into two new segments. Notice how when calculating t the denominator has an extra component parallel. This boolean value is cast as a 1 if the denominator would have been zero, and prevents Numpy from throwing a warning about divide by zero errors.

Handling Bisected Lines

If a segment is bisected by the line at time t, we need to create two new segments, one from 0-t, and a second from t-1. Fancy indexing with Numpy can be slower than doing simple operations on an entire array (this is highly dependent on the application), so we'll create two new segments for every segment and then filter.

intersection_points = segment_start + intersection[..., np.newaxis] * v0
l_segments = np.stack((segments[..., 0, :], intersection_points), axis=1)
r_segments = np.stack((intersection_points, segments[..., 1, :]), axis=1)

Notice how they're split into left and right segments, not 'in front' and 'behind'. That's because right now we don't know which segments are which, and need to filter them based on the numerator. If the numerator is >0, the first point of the segment is ahead of the line, making l_segment ahead and r_segment behind.

mask = numerator[..., np.newaxis, np.newaxis] > 0
bisected_ahead = np.where(mask, l_segments, r_segments)[bisected]
bisected_behind = np.where(np.logical_not(mask), l_segments, r_segments)[bisected]

An example of two segments where the left and right splits are on opposite sides of the dividing line

Once the bisected segments have been split, all that's left to do is combine them with their respective ahead/behind sets, and return the three sets of segments. The full function is found here, with a set of if statements to catch cases where ahead/behind sets are empty arrays. The Tuple Typehint is from the typing module, and is useful for IDE's to infer what types the function will return.

Recursively Building the Tree

Compared to the amount of code required to partition our line segments, the function build the BSP tree is relatively simple.

def build_tree(segments: np.ndarray, starting_segment: np.ndarray = None) -> nx.DiGraph:

    def bsp_helper(segments: np.ndarray, division_line: np.ndarray):
        ahead, behind, colinear = bisect(segments, division_line)  # get the bisected segments
        node_id = id(division_line)  # make your line hashable so it's usable as a node
        graph.add_node(node_id, line=division_line, colinear_segments=colinear)  # add the node to the graph
        if behind.size != 0:  # if there's any elements behind
            node_behind = bsp_helper(behind, behind[0])  # recursively call for all segments behind
            graph.add_edge(node_id, node_behind, position=-1)  # add an edge from this node to the behind node
        if ahead.size != 0:
            node_ahead = bsp_helper(ahead, ahead[0])  # recursively call for all segments in front
            graph.add_edge(node_id, node_ahead, position=1)  # add an edge from this node to the front node
        return node_id  # return the hashed id

    graph = nx.DiGraph()  # make a new directed graph
    if starting_segment is None:
        starting_segment = segments[0]

    # run the recursive helper function, which should add all nodes and edges
    bsp_helper(segments, starting_segment)
    return nx.relabel.convert_node_labels_to_integers(graph)

Let's pick it apart, starting with the function signature. The function expects a nx2x2 array of line segments, and an optional starting segment that it used as the first dividing line. The output will be a NetworkX directed graph object where every node is a dividing line holding the colinear segments for that line.

def build_tree(segments: np.ndarray, starting_segment: np.ndarray = None) -> nx.DiGraph:

Next is the initialization block, here we create the actual graph object and check if the user provided a starting segment. If no segment was given, the first segment of the array is used instead. The function then calls the bsp_helper function that fills the graph with divided segments, and then relabels all nodes sequentially before returning the graph.

graph = nx.DiGraph()  # make a new directed graph
if starting_segment is None:
    starting_segment = segments[0]

# run the recursive helper function, which should add all nodes and edges
bsp_helper(segments, starting_segment)
return nx.relabel.convert_node_labels_to_integers(graph)

The final piece is the nested bsp_helper function. Defining bsp_helper within build_tree allows it to access the graph variable without explicitly passing it (this is part of the enclosing scope in an LEBG model). It also keeps bsp_helper out of the module namespace. The function calculates where each segment in a set falls relative to the dividing line. It then creates a new node with two attributes: the dividing line of the node, and any segments that are colinear to that dividing line. If there's any segments in front of the line, the helper function recursively calls itself with only the set of segments ahead of current dividing line, returning the id of the created node. The returned node is connected to the current node with an edge, whose position attribute is +1 (meaning it's ahead of the current node). The same is then done for segments behind the current line. If recursive functions are a new concept, RealPython has a great tutorial on understanding and implementing them, as well as introduces the @lru_cache decorator.

Taking it for a Test Drive

As a last step we'll create a tree from scratch and plot the results. First lets make a function to draw the segments stored in a BSP tree, with markers showing where the the segments are divided. The drawing itself will be handled by matplotlib, which can also be installed from pip.

def draw_segments(tree: nx.DiGraph, axis=None, *args, **kwargs) -> None:
    if axis is None:
        axis = plt.gca()
    all_segments = np.concatenate([value for value in dict(nx.get_node_attributes(tree, "colinear_segments")).values()])
    for segment in all_segments:
        axis.plot(*(segment.T), *args, **kwargs)

Next we'll import some prebuilt line segments and reshape the list of points into an appropriate shape. Then it's as simple as creating the bsp tree and plotting the results!

segments = np.loadtxt("points.csv")
segments = segments.reshape(int(segments.shape[0] / 4), 2, 2)

tree = build_tree(segments)
fig = plt.figure()
draw_segments(tree, color='k', marker='o')
plt.show()

The fruit of our labor, bisected points are shown in red

Despite creating an impressive BSP tree, at the end of the day it's still just a graph, and could use a killer application to make the power of BSP shine! The full code has additional functions for performing operations on trees as well as implementing CSG operations. Alternatively, pair BSP with Pyglet you're half way towards a working 2.5D game engine.

Rendering Constructive Solid Geometry With Python

Ryan Frazier — Mon, 15 Mar 2021 11:35:26 GMT

I recently hit a road block with my ray tracer: cubes, cylinders, and spheres rendered fine, but there wasn't an easy way to create arbitrary shapes whose intersection and normal functions I hadn't already hard coded. Since PyRayT's end use is for optical design, at the bare minimum it needed a flexible way to create lenses and mirrors. Flipping through Jamis Bucks' The Ray Tracer Challenge, it turns out the last chapter Constructive Solid Geometry (CSG) addressed my needs perfectly! However, Buck's equations for CSG did not blend well with PyRayTs flow of rendering multiple rays at once. Today I'll be covering my own algorithm for adding constructive solid geometry to a ray tracer, as well as its implementation in Python using NumPy.

Getting Up and Running with Nikola

Ryan Frazier — Mon, 01 Mar 2021 21:43:38 GMT

I have no background in web development or design, which is probably as good of a disclosure as any when writing a post about deploying a website.