Drop or select image…
…or load sample.
Crop Circles is a tool originally designed for cropping circular center pivot irrigation fields from aerial imagery collected with, for example, ærialbot.
It's an unabashedly-built-for-myself tool, with precisely the knobs and toggles I thought would enable me to fine-tune my workflow during the creation of a series of videos like the one below.
But nothing's keeping you from using this tool to crop circular objects from imagery-in-a-more-general-sense! To that end, I think it's helpful to spend a couple minutes reading this document, or, alternatively, discovering how this tool works through play – rest assured that you can't break anything.
Filling most of the screen, the main work area contains the active image (or, initially, a prompt to select one). You can use your mouse to create selections:
Unless you uncheck the "show selections" setting, the work area also provides an overview over which fields (or other objects) you've already selected. Hovering the mouse pointer over one of them highlights it in the table in the sidebar.
The sidebar on the right, meanwhile, packs a punch: You can use it to…
The selections table lists the selections you've made in the current image (plus, if it has associated geo data, any selections you've made in other images that fall into the geographical area covered by the image). Hovering over a selection in the table highlights it in the main work area. Using the buttons in right-most column of the table, you can (re)download or delete a specific selection, or "accept" a selection you've previously made in another image that is located in the geographical area covered by the current image – this will copy it into the main part of the selections table (if you delete such a selection, it returns to the "geo suggestions" section at the bottom of the table).
Recall that that the selections you've made in the current image are kept in the selection cache, so this table will be restored if you work on another image, then select this one again.
A pair of buttons below the table allows you to download all selections: Either sequentially, which I sadly haven't gotten to work reliably in Safari (only in Chrome and Firefox), or in a single ZIP file. Note that if you have made more than a few selections that cover a large area (say, 1 megapixel each), zipping can be slower than downloading them all individually or sequentially – that seems to be a limitation of the JSZip library.
Below the sidebar, the precision helper aids you in hitting your marks when making a selection. It's divided into nine areas:
The user's guide should be self-explanatory (literally!).
Status messages may pop up in the bottom left corner and inform you about ongoing processes like zipping, or, say, about successful selection cache restores. They disappear automatically, either two seconds after being summoned or after the process they're keeping your updated on has finished.
Error messages, should they appear, cover the bottom part of the screen, are roughly the same shade of red as the two SF1000 cars that raced around the Mugello circuit on the weekend of this tool's initial release, and don't disappear automatically. (If you want to experience one, simply try to restore your settings from some random file instead of a proper backup.)
Even though most of the keyboard controls have been described in the previous section, here's a table summarizing their functions:
| ↑, W | Move the current selection upwards by a pixel (or 20 if shift is pressed), or if there is no current selection, make a copy of the most recent selection right above itself that can then be further refined. If you're using a non-qwerty key layout, W probably (i.e. if your browser abides by the standards) won't do anything: Instead, press the key that's located where the W key would be on a conventional key layout (the same goes for all other letter keys). It's implemented that way because I'm told that's how you'll expect it to work. ¯\_(ツ)_/¯ |
| ↓, S | Analogous, but downwards. |
| ←, A | Analogous, but leftwards. |
| →, D | Analogous, but rightwards. |
| +, P | Increase the radius of the current selection by a pixel (or 20 if shift is pressed). |
| -, O | Analogous, but this decreases the radius. |
| * | Analogous to shift + because I'm using a German key layout, and one of the perks of building your own tools is that you can account for your edge cases with hacks instead of having to look for more elegant solutions. |
| _ | Analogous to shift - for the same reason. |
| shift | Increase the potency of the previous operations by a factor of 20. Your key switches will be grateful. |
| enter | Accept the current selection, thereby freezing its size and location and adding it to both the table in the sidebar and the selection cache. |
| backspace | Delete the most recently accepted selection. Note that this is irreversible, and pressing backspace multiple times will delete multiple selections. Be careful (or make frequent backups)! |
| esc | Cancel the current selection. |
All of these are disabled while you're entering text into the filename template field, of course.
The settings in the sidebar are tersely explained in-place. Here's some more words about them.
If enabled (which is the default), your previously selected circles are visible in the main work area, which is helpful for keeping track of what you've already done. If the current image has associated geo data, selections you've previously made in other images that fall into the geographical area covered by the current image will show up, too.
Adjusts the zoom level of the thumbnails shown in the precision helper in the bottom right. At 1×, the image pixels will be shown at original scale with regard to logical browser pixels – on a high-DPI or Retina device, they will thus be scaled up with regard to physical pixels. This is by design.
Uncheck this checkbox if you prefer downloading your images through the selections table after first making a bunch of selections.
This is a template for the filenames of result images. It's used both for direct downloads and filenames within ZIPs. Make sure not to specify the file extension, it's added automatically depending on other settings. If you leave this field empty, as is indeed the default, the default filename template (see first row of the following table) is used.
You can make use of the following variables:
| {default} | The default filename: "cropcircles-x{x}y{y}r{r}" (or "cropcircles-{lat},{lon},{rm}m-x{x}y{y}r{r}" if the current image has associated geo data). Handy if all you want to change is adding a prefix or postfix. |
| {file} | Filename of the image the selection was made in. |
| {id} | Internal selection identifier, actually the millisecond-precision UNIX timestamp at which the selection was made, e.g. "1599251366699". |
| {date} | The current date at the time of download, in simplified extended ISO format, e.g. "2020-09-12T18.51.17.485Z". |
| {rand} | Random integer with a (zero-padded) length of 10. E.g. "1708473213" or "0072495286". Handy as a filename prefix if you want the images to end up in a random order for whatever reason. |
| {x} | x coordinate, in pixels and with respect to the top left corner of the image, of the selection center. |
| {y} | Analogous. |
| {r} | Radius of the circular selections, in pixels. |
If the current image has associated geo data, the following variables are available, as well:
| {georect} | Geo bounds of the input image, e.g. "sw42.2865,-113.9040ne42.3404,-113.8069". This allows you to drop a cropped image right back into this tool and, say, tighten the existing selection. |
| {lat} | Latitude of the selection center. |
| {lon} | Analogous. |
| {rm} | Selection radius in meters. (Note that the scale factor from pixels to meters depends on latitude.) |
If you leave this checkbox enabled, downloading your selections will yield PNG images with transparent corners: anything outside the bounds of the circular selections will be removed (like each of the three little center pivot irrigation farms in-between the sections of this user's guide).
On the other hand, if you choose to uncheck this checkbox, the surroundings of the circular selections will be visible in the corners of the final images – essentially, this turns the selection into a square. This square can be expanded into a rectangle that includes even more of the circular selection's surroundings through the following two settings. Since this removes the need for transparency, the images are downloaded as more space-efficient JPG files by default. The encoding quality is preset at 100%, making this effectively as lossless as PNG – but you can reduce the quality if you want to save space.
This functionality comes in handy for making a video like the one at the top of this user's guide, where different circular objects are shown in one place, with mainly their surroundings changing.
If enabled, you'll notice a box-shaped dashed line around the current (or highlighted) selection – that's just a preview of the crop area.
If you increase this slider from its default of 0, a vertical margin whose size you can set as a fraction of the selection radius is added above and below the circular core of the selection.
Analogous to the vertical margin, but towards the left and right.
Together, these two sliders allow you to dial in the range of surroundings to include in the images: For the example video included at the beginning of this document, the vertical margin was set to 0.2 and the horizontal margin to 1.8, yielding an aspect ratio (as shown below the two sliders) of 1:2.33 (i.e. cinemascope).
If the background doesn't need to be transparent, JPEG compression will be used – in contrast to PNG, it's lossy but significantly more space-efficient. Using this slider, you can adjust the level of compression: 100% is effectively lossless, 90% is still pretty good, anything below 70% only really works for images that won't ever be shown at their actual size.
If you want this tool to generate PNG images regardless, simply set this to 0.
Using the buttons near the bottom of the sidebar, you can download a backup of your settings or the selection cache. These backups take the form of JSON files – you can inspect and modify them in any text editor; their structure is simple enough that you won't need further information about their schemata.
These backups would be pretty bad at being backups if you couldn't restore them, so you can! Note the differing semantics:
Because settings and selection cache are stored in local storage, which – depending on your browser settings – may be wiped occasionally, I recommend making occasional backups, especially of your selection cache.
As outlined in previous sections of this user's guide, the selection cache is where your selections are safeguarded against inadvertent page reloads, browser crashes, or potential data loss when working on another image for a bit before resuming work on a previously worked-on image. To this end, the selection cache is kept in local storage and can be backed up and restored.
Each selection is assigned to the image it was made in. For simplicity's sake, sameness of two images is defined through equality of filename, filesize, and image width/height in pixels – so avoid situations where nominally-different images share all four of these attributes if you don't want selections made in one of them show up for the other one, as well.
The subset of the selection cache belonging with the current image is shown in the selections table.
It can be purged (for all images you've ever made selections in!) using a link at the very bottom of the sidebar.
Since this tool was designed for use with aerial imagery, it seemed to make sense to loop any geo data associated with that imagery all the way through the pipeline, embedding it into the output images. In my own use case, I'm not actually doing anything with that data, but maybe that'll change in future.
Geo data, in the context of this tool, refers to latitude and longitude of the center points of the circular selections, which can be derived from the latitude and longitude of two points in the input image (and hardcoded assumptions about the projection the imagery uses). For simplicity's sake, these two points must be the southwest and northeast corners of the image:
If the input image's filename contains a part of the form "sw[lat],[lon]ne[lat],[lon]", the cropped circles will be named based on their center point's latitude, longitude and circle radius (that one in meters). This interpolation is based on the assumption that the aerial imagery you've uploaded is laid out based on the Web Mercator projection, which is common among online mapping services like Google Maps. Even if that's not the case: On large-scale maps (covering fewer than 100 vertical kilometers), the difference will be in the rounding error range.
If geo data is known for the current image, additional output filename variables are unlocked, and the default template also changes. Read more about that here.
Also, latitude, longitude and radius in meters are shown in the selections table in the sidebar. Selections you make in images with associated geo data will also show up in other images covering the same area, with a dashed border. They are not automatically merged into the list of of selections of that image, instead they can be "promoted" though the selections table in the sidebar.
None of these bullet points fit well into the previous sections, so here they are:
There isn't any server communication beyond the initial page load, so you should be safe. No analytics or trackers either. This tool is hosted on GitHub Pages, so I don't even have access to web server logs (but GitHub "may collect User Personal Information […], including logs of visitor IP addresses").
Since your settings and selection cache are kept in local storage as part of your browser cache, other pages you load though the same protocol-domain-port combination may access them. That's probably not something you need to worry about, though.
But, in the words of the inimitable LeVar Burton, you don't have to take my word for it: Just download this tool, disconnect your device from the internet, open the tool in an incognito window, do your work, close the window, delete your local copy of the tool, then enable wifi again.
Building this tool would have been more difficult than it turned out to be if it wasn't for the work of others, including but not limited to the following.
