[Sprint 7d]: Coordinates to Region Mapping 🗾 - Chiara & Zander

[danglorioso]

💻 Summary

In this sprint, you will be identifying a region for a point (representing a school) on the map using its coordinates and the existing region boundaries that we have. This will allow us to directly map a school to a region upon ingestion (and location update) and will enable region-specific features in the app once implemented.

Goals of this sprint:

• Create a function that, given a pair of coordinates, references the existing boundaries to determine which part of the map it is in and returns this region.
• Experiment with some cool algorithms.
• Add regions to schools!

⚙️ Setup

Before starting:

1. PLEASE: Pull the latest changes from main: git pull
2. Create a new branch for this sprint.
3. Install dependencies: npm i
4. Run the dev server and verify the site builds: npm run dev
5. Confirm everything runs.
   If you experience problems, check your .env is up to date!

🧭 Implementation

Step 1: Examine the region boundaries

• As the app currently stands, the heatmap has a layer of region boundaries for MA defined in src/data/regions.json. Make sure that you understand how this is implemented.

Step 2: Define the function

• The mapping function should realistically just take the longitude and latitude of the school and return the name of the region that contains the coordinates, as this is what will be stored in the database. Also note that this function should go into src/lib.
• The function is an example of the Ray Casting Algorithm. There are some additional considerations, such as considering different regions on the map to determine which one contains the coordinates, but it is very similar in principle.
• The Ray Casting algorithm is used to determine if a polygon contains a point. At a high level, it answers this question by drawing a “ray” from outside the polygon and to your point and counting how many times it hits one of the sides of the polygon. If it is an even number once your point is reached, then your point is outside of the polygon. If it is an odd number, then your point is inside. Essentially, an odd number indicates entering your polygon, an even number indicates leaving (or not having entered) your polygon. Here is a stack overflow post about this exact problem.
• While there are existing solutions to the Ray Casting problem, it would be worthwhile to research the algorithm and understand it. It is used in ray tracing and many other things in graphics. Also note that it is just one solution to the problem of determining if a point is in a polygon. There are other solutions like the Winding Number Problem, but this one seemed to be the most efficient. However, do not let this stop you from implementing another solution if you want to, it would be awesome to learn more about existing solutions.
• We will also ask you to explain to everyone how the algorithm works during standup since it is a cool example of how these types of algorithms have actual use cases.

Step 2: Incorporate the mapping into the app

• When a school is first assigned its coordinates, it should also be assigned its region.
• However, schools also may change their location (whether it be from the settings page or their individual profile page). So, you will have to incorporate your function there as well.
• Essentially, anywhere that the school’s coordinates may change, you will have to check for a new region.
• You should also add a new column to the database table schools that indicates its region (as a string). To do this, edit src/lib/[schema.ts](http://schema.ts/) and commit the changes to the database by using the command npx drizzle-kit push on the command line from within the project repo. Make sure that you are testing on a new Neon branch as well (meaning you will want to update your database URL). You can create a child branch of full-data for this.

Step 4: Test the function

• It is important that you test your function thoroughly to ensure that schools are being matched to their correct region and that the data that we are storing is therefore correct. Luckily, this function should be pretty easy to test! Just input different coordinates that you know fall into a given region, and then ensure that region is being returned from the function.
• You must also test that the database is being populated/updated properly. On a Neon branch, feel free to change the locations of schools. You should be able to visually look at the map and see which region they are in. Then, just ensure that the database is being updated properly.
• You can also test this without checking the database to ensure that the correct region is being returned. Feel free to log it to ensure if you want to test the function before implementing the
• Consider edge cases such as potentially overlapping regions on the map and parts of the map that regions do not cover. How will you assign a region if one or multiple exist? What about coordinates that fall on one of the region borders? These should likely be contained within that region, but the region may share the given border with another region. Just be consistent in your solution and document what you chose in the code and on your PR so we know.

🙌 Acceptance Criteria

• All schools in the database have associated regions
• Function addresses edge cases mentioned and any others that are discovered
• Function is invoked when coordinates for a school change
• UI matches Figma exactly
• Code runs locally without errors and builds successfully
• Merge via PR

⁉️ Questions

If you get stuck or have questions:

• DM Dan or Shayne on Slack
• Come to office hours or ask during a hack night
• Ask questions during team meetings – we’re here to help!

📝 Resources

• Ray Casting Algorithm
• Figma - Tailwind CSS
• shadcn/ui
• npm package manager