Русский · English · Español · Français · Deutsch
360° spherical panoramas are usually stored as regular JPEG files with equirectangular projection and a 2:1 aspect ratio. The top of the image corresponds to the zenith, the middle – the horizon, and the bottom border – the nadir, that is, the point strictly below the camera.
After shooting, it is at the nadir that a tripod, the photographer’s shadow, or a poorly stitched area often remains. It can be closed with a round plaque with the company name, website address or logo. However, simply overlaying a circle at the bottom of a rectangular JPEG is not suitable: when viewing a panorama, such an image will be greatly distorted. We need a back projection that takes into account the geometry of the sphere.
In this article we will analyze the web application “Nadir signature for panoramas”. It loads a spherical JPG, shows a 360° interactive preview, correctly projects the circular signature to the bottom of the sphere, and saves the new JPEG. All processing is done locally in the browser—the original panorama is not sent to the server.
Application features
- loading JPG or JPEG by dragging or using the file selection dialog;
- checking the maximum file size and panorama aspect ratio 2:1;
- text signature up to 60 characters long;
- adjusting the color, transparency and corner radius of the die;
- interactive WebGL panorama viewer;
- rotation with the mouse or finger and changing the field of view with the wheel;
- quick transition with a glance to the nadir;
- image processing in original resolution;
- save EXIF, GPS, XMP, IPTC and JPEG comments;
- download result with suffix
_nadir.jpg.
Why nadir looks unusual on the original JPEG
In an equirectangular projection, the horizontal coordinate specifies the longitude, and the vertical coordinate specifies the latitude of the sphere. A full 360° rotation occupies the entire width of the image, and a range from zenith to nadir of 180° occupies the entire height.
The nadir point is the only point on the sphere, but in a rectangular scan it stretches across the entire lower border of the image. Therefore, the circle that the viewer should see below him turns into a characteristic stripe with nonlinear distortion. After folding the image back into a sphere, this stripe becomes a circle again.
For the pixel of the original panorama, spherical coordinates are used:
longitude = x / width × 2π − π
latitude = π/2 − y / height × π
At the bottom of the image, the angular distance to nadir is calculated. If it is less than the selected radius, the pixel is assigned a point on a circular block.
Project architecture
The application is written in React and TypeScript. The interface is in app/page.tsx, styles – in app/globals.css, and the page metadata is in app/layout.tsx.
The main logic is divided into four parts:
- JPEG loading and checking;
- creation of a round block with text;
- interactive WebGL preview;
- final overlay at full resolution via Canvas 2D.
The application does not need a server database. After the page loads, photo operations are performed by the browser API.
Loading and checking panorama
The application accepts files with MIME type image/jpeg or extension .jpg/.jpeg. The file is then read through arrayBuffer(), and its dimensions are determined using createImageBitmap().
Checks the width to height ratio:
abs(width / height − 2) ≤ 0.035
Small tolerances allow for panoramas that differ from the ideal 2:1 by a few pixels. The interface limit is 250 MB per file. The actual limit also depends on the amount of memory, the Canvas implementation, and the maximum WebGL texture size in a particular browser.
Die formation
Function makeBadge() creates a square Canvas of 1800 × 1800 pixels. It depicts:
- circle of selected color and transparency;
- white outline;
- white text in the center.
The font size decreases from 280 to 60 pixels until the line fits 80% of the circle’s width. Thanks to this, a short address is displayed large, and a long signature is automatically scaled.
Interactive viewing via WebGL
Preview does not change the original JPEG. It uses two textures:
- panorama;
- created die.
The vertex shader displays two triangles on the entire Canvas. The fragment shader builds a virtual camera ray for each pixel of the screen, applies horizontal and vertical rotation, and then translates the ray direction into equirectangular texture coordinates.
If the direction falls inside the specified angular radius from the nadir, the shader calculates the coordinates of the corresponding pixel of the solid and mixes it with the panorama, taking into account the alpha channel.
This approach is convenient for viewing: the GPU quickly recalculates the image when rotating and scaling. If the panorama exceeds MAX_TEXTURE_SIZE video device, a small copy is created for preview. This does not reduce the resulting file – final processing is performed separately at the original resolution.
Final processing via Canvas 2D
After clicking “Apply and download JPG,” the application creates a Canvas the size of the original panorama and copies the photo into it. Not the entire frame is processed, but only the bottom strip, in which the nadir plate may physically be located:
stripHeight ≈ imageHeight × radius / 180
For each horizontal coordinate, the sine and cosine of longitude are calculated in advance. This eliminates repeated trigonometric calculations within the main loop.
For each pixel of the bottom band, the algorithm:
- finds the angular distance to nadir;
- skips pixels outside the selected radius;
- converts the spherical distance into the radial coordinate of the die through the tangent ratio;
- finds the pixel of the die; The
- mixes the RGB channels of an image and solids using an alpha channel.
Periodic setTimeout(..., 0) returns control to the browser’s event loop. This allows the interface to update the progress bar and not appear completely frozen while processing a large image.
Saving JPEG metadata
Normal call canvas.toBlob("image/jpeg") re-encodes the image, but loses the original metadata. Therefore, before processing, the application reads the JPEG structure and saves the segments:
- APP1 – usually EXIF and XMP;
- APP2 – extended profiles and service data;
- APP13 — IPTC/Photoshop metadata;
- COM – JPEG comments.
After encoding the result, the stored segments are inserted immediately after the SOI marker FF D8. As a result, EXIF, GPS and XMP are transferred to the finished file.
It should be borne in mind that this is a neat transfer of source blocks, and not a full-fledged metadata editor. The image dimensions within some rare custom fields may remain the same, although in this application the width and height of the result is usually the same as the original.
Privacy
The photo is processed locally. File, ImageBitmap, Canvas, WebGL and object URL only exist in the user’s browser. There is no code to send the image via fetch, forms or server API.
This is especially important for panoramas with GPS coordinates: metadata is not transferred to the application on the server, but is saved in the downloaded result. If the finished file is planned to be published, GPS should be removed with a separate tool if necessary.
Running a project locally
Requires Node.js version 22.13 or later.
npm ci
npm run dev
After launch, you need to open the address specified by Vite in the terminal. To check the production build:
npm run build
npm run start
Additional commands:
npm test
npm run lint
Details are in the file INSTALL.md, attached to the archive.
Practical limitations
- Only JPEG is supported, PNG and TIFF are not accepted.
- Requires a full spherical panorama of approximately 2:1.
- The final JPEG is re-encoded with a quality of 0.95, so it will not be bit identical to the original.
- Very large images require a lot of RAM: Canvas stores uncompressed pixels, and 20,000×10,000 RGBA takes up about 800MB for just one buffer.
- During processing, the mobile browser may close the tab due to lack of memory.
- The text is drawn in the system font Arial/Helvetica; Separate downloading of branded fonts is not implemented.
Possible improvements
The project can be expanded by loading a transparent logo, choosing a font, processing in Web Worker, tiled processing of large files and export without re-JPEG compression. For professional use, adjusting stroke thickness, pre-patterns, and removing GPS using a separate switch are useful.
Already in its current form, the application solves the main problem: it allows you to add the correct caption to the nadir of a spherical panorama without installing a desktop editor, check the result in the interactive viewer and download the finished JPG without transferring the photo to a third-party server.