MeshNotes – 3D Annotation Tool for Research & Heritage

Click Import ▾ and select 3D Model to open a 3D model file. The tool supports .glb, .gltf, .obj, .ply, and .stl formats. After loading, the face count is displayed in the bottom-right corner.

PLY Files: When loading a PLY file, you will be asked whether to add a texture image. If your PLY contains UV coordinates, the texture will be mapped onto the model. PLY files with vertex colors are loaded automatically without requiring a separate texture.

OBJ Files: When loading an OBJ file, you will be asked whether to add material and texture files. You can select a .mtl file together with texture images (.jpg, .png), or only texture images, or load the geometry without any materials. If only a texture is provided without an MTL file, it will be applied as a diffuse map.

Model Orientation: Ensure your model is oriented correctly (typically Y-up or Z-up) before exporting. The viewer's navigation is based on the model's original orientation and cannot be changed after loading. If your model appears upside down or sideways, re-export it with the correct orientation in your 3D software.

Tip: GLB is recommended for best compatibility as it embeds textures and orientation in a single file. If your model is in another format, you can convert it using Blender.

MeshNotes works with 3D models in .glb, .gltf, .obj, .ply, and .stl formats. Choosing the right format and preparing your model well will give you the best experience.

Recommended format: GLB (Binary glTF) is the best all-around choice. It packages geometry, textures, and materials into a single file, loads quickly, and does not allow for misleading axial orientation

Format comparison:

• GLB/GLTF — Best overall. Single file (GLB) or folder with linked textures (GLTF). Supports textures, materials, and vertex colors.
• OBJ — Widely supported format. Requires separate .mtl and texture files. Often used for models from photogrammetry or SLS software.
• PLY — Common for point clouds and laser scans, standard format for e.g. GigaMesh. Supports vertex colors natively.
• STL — Widely used in 3D scanning and 3D printing workflows. Contains geometry only (no textures or vertex colors). Supports both ASCII and binary STL files, including binary STL with per-face color.

Face count & performance: The number of faces (triangles) in your model directly affects performance. After loading, the face count is displayed in the bottom-right corner with a color indicator:

Orientation: When loading OBJ, PLY, or STL files, MeshNotes will ask you which axis is "up" in your source software. Most photogrammetry and cultural heritage tools (Metashape, CloudCompare, MeshLab, Blender) use Z-up, while some game engines and web viewers use Y-up. Selecting the correct option ensures your model displays upright. GLB/GLTF files handle orientation automatically per the glTF specification. See the Coordinate System section below for more details.

Reducing file size (Draco compression): Large photogrammetry models can produce GLB files of several hundred megabytes. Draco compression significantly reduces geometry size while preserving visual quality — MeshNotes fully supports Draco-compressed GLB files. You can compress your models using browser-based tools such as OptimizeGLB, or locally via the command-line tool gltf-transform (npx gltf-transform draco input.glb output.glb). The local option avoids uploading your model to a third-party server.

Units: MeshNotes displays distances and scalebar values in whatever unit your model was created with. If your photogrammetry software exports in meters, distances will be in meters. If it exports in millimeters, they will be in millimeters. There is no unit conversion — consistency depends on your source data. Check your 3D software's export settings if distances seem off by a factor of 1000.

MeshNotes displays all models and exports all annotation coordinates with Z pointing up. This matches the convention used by most software in cultural heritage, photogrammetry, and geospatial work, including Metashape, CloudCompare, MeshLab, QGIS, and Blender.

Why this matters: When you annotate a model in MeshNotes and export the annotations as JSON, the coordinates in that file use Z-up. If a colleague opens the same model in a different software and overlays your annotations, the points will be in the correct positions — no manual coordinate conversion needed.

How it works internally: The 3D engine that MeshNotes is built on (Three.js) uses Y-up internally, which is common for web-based 3D viewers. MeshNotes handles the translation between these two conventions automatically, so you never need to worry about it. The View Helper in the top-right corner always shows Z (blue) pointing up, Y (green) pointing forward, and X (red) pointing right, reflecting the Z-up convention most users will be used to.

On import: When loading OBJ or PLY files, MeshNotes asks which axis is up in your source software and rotates the model accordingly. GLB/GLTF files always use Y-up by specification, so MeshNotes handles them automatically. When importing annotation files, MeshNotes checks the upAxis field in the JSON. Files marked as Z-up are loaded directly; older files without this field are treated as legacy Y-up data and converted automatically.

On export: All annotation JSON files include an "upAxis": "Z" field near the top of the file. This tells any software reading the file which coordinate convention to expect. The field is deliberately not prefixed with a MeshNotes-specific namespace, so it is easy for other tools to read and interpret.

Display Mode: Click the display button to cycle through available modes: Texture (shows the model's texture maps), Colors (shows vertex colors only, if present), Mesh (solid single-color surface), and Wireframe (edge-only view). The Colors mode is only available if the model contains vertex color data. The colors used for Mesh and Wireframe modes can be customized in Settings.

Brightness slider: Adjust scene lighting from 0% to 300%. Opacity slider: Make the model transparent (10-100%) to see annotations that pass through it.

Annotation Display: In Settings, use the Point Size slider (×0.3 to ×50) to adjust the size of annotation markers, and the Text Size slider (×0.3 to ×50) to adjust annotation label sizes. The sliders use exponential scaling, so small movements have bigger effect at high values — making it easy to reach extreme sizes for very large or small models. These settings are saved automatically.

Light Source: By default, the main light follows your camera view, ensuring consistent illumination from any angle. Click the toggle to switch to Fixed Direction mode, which reveals two sliders: Horizontal (0°-360°) rotates the light around the model, and Vertical (-90° to +90°) adjusts the light height from below (-90°) through the horizon (0°) to directly above (+90°). This is ideal for raking light analysis of surface details like tool marks, inscriptions, or weathering patterns. The light is automatically boosted in fixed mode for better shadow visibility.

Background Color: In Settings, choose the viewport background color using the preset buttons (dark blue default, black, dark gray, gray, white) or click the color picker for a custom color. White or light gray backgrounds are ideal for publication-ready screenshots, while dark backgrounds reduce eye strain during extended annotation sessions. Your preference is saved automatically.

Click Point, then click on the model surface to place a point marker. A popup will appear where you can enter a name, description, author, and external links.

Click Line to start drawing a polyline. Single-click to add points along the line, double-click to finish and open the annotation popup. Lines are useful for marking edges, boundaries, cracks, or linear features.

Undo: Press Ctrl+Z (or Cmd+Z on Mac) to remove the last placed point. This allows you to correct mistakes without starting over.

Surface projection: By default, line edges are automatically projected onto the model surface — they follow the geometry's contour rather than cutting through it as straight lines. This works best on smaller objects with gently curved surfaces. If the projection deviates too far from the intended path (e.g., on complex geometry with deep recesses), MeshNotes falls back to a straight connection for that segment automatically. You can toggle surface projection on or off per annotation using the "Project line(s) to surface" checkbox in the annotation popup.

Click Polygon to start drawing a closed shape. Single-click to add vertices, double-click to close the polygon and open the annotation popup. Polygons are useful for marking areas, surfaces, or regions of interest.

Undo: Press Ctrl+Z (or Cmd+Z on Mac) to remove the last placed vertex. This allows you to correct mistakes without starting over.

Like line annotations, polygon edges are projected onto the model surface by default, following the geometry's contour. This can be toggled per annotation in the popup.

Click Surface to paint directly on the 3D model's mesh faces. Adjust the brush size using the slider (0.1-20% of model size), then click and drag to highlight faces. Right-click and drag to rotate the view while painting — this lets you paint a continuous surface annotation from multiple angles (e.g., wrapping around a statue's arm). Hold Shift while painting to erase. Double-click to finish and open the annotation popup.

Undo: Press Ctrl+Z (or Cmd+Z on Mac) to undo the last paint stroke. Each stroke (one mousedown-to-mouseup drag) is treated as one undoable step, including erase strokes. You can undo multiple strokes in succession.

Surface annotations are ideal for marking 3D regions like weathered areas, specific architectural features, or body parts on sculptures that can't be easily captured with flat polygons.

Click Box to activate the box tool, then click on the model to place a 3D box annotation. A default-sized box appears at the click location. Boxes are useful for marking volumetric regions like rooms, excavation contexts, architectural spaces, or reconstruction hypotheses.

Manipulating boxes:

• Move: Click and drag the box body to reposition it freely in 3D space
• Resize: Drag any corner handle to reshape the box (the opposite corner stays fixed)
• Rotate: Right-click and drag on the box body — horizontal movement spins the box, vertical movement tilts it
• Snap: Hold Shift while rotating to snap to 15° increments

Unlike other annotations, boxes can float freely in 3D space — they don't need to touch the model surface. This makes them ideal for marking "negative space" like missing architectural elements or hypothetical reconstructions.

The Box annotation tool was inspired by the Cuan3D annotation tool developed by Paula Dicke.

Click Measure to activate the measurement tool. Click two points on the model to measure the straight-line distance between them. Multiple measurements can be taken and all stay visible with their distance labels.

Multi-point measurement: Hold Ctrl (or Cmd on Mac) while clicking to measure a path through multiple points — useful for measuring around corners, along curved edges, or following a non-straight route. Keep holding Ctrl and clicking to add more points. The total path distance is shown as you go. Release Ctrl and click once more to finalize, or simply click without Ctrl when you have two or more points. Multi-point measurements display the total distance along with a breakdown of individual segment lengths (e.g., 1.234 + 2.345 + 3.456).

Undo: Press Ctrl+Z (or Cmd+Z on Mac) to remove the last placed measurement point before the measurement is finalized. This works for both simple two-point and multi-point measurements.

Managing measurements: Click the × button next to any measurement to delete just that one. Click on a measurement value to copy it to clipboard for pasting into documentation. Press Esc to clear all measurements at once.

Distances are displayed in the unit configured in Settings (default: "units"). You can set this to mm, cm, m, or a custom label. The actual scale depends on how your 3D model was created or exported — MeshNotes does not convert between units.

The Cutting Plane tool lets you extract cross-section profiles from your 3D model. It is located inside the Measure tool — when you activate Measure, the Cutting Plane panel appears alongside the measurement controls.

Workflow: First, rotate your camera to look at the model from the direction you want to cut through. Then click Spawn Plane — a semi-transparent blue plane appears perpendicular to your current viewpoint, centered on the model. A red preview line shows where the plane intersects the mesh in real time.

Adjusting the plane:

• Left-drag on the plane to slide it forward/backward along its normal
• Right-drag on the plane to tilt it freely
• Ctrl + Left-drag (Cmd on Mac) to swing the plane — pivoting the left/right edges forward and backward, useful for aligning with walls or irregular features

Extracting the profile: Once the plane is positioned, click Extract Profile. MeshNotes computes the exact geometric intersection between the plane and the mesh triangles, projects it onto the plane's 2D coordinate system, and displays a preview. From the preview you can download the profile as SVG (vector, ideal for publication figures) or PNG (raster, 2× resolution). Both formats include a scale bar using the unit configured in Settings.

Tips: You can spawn, adjust, and extract multiple profiles without leaving the Measure tool. Click Remove Plane to clear the cutting plane, or press Esc to leave the Measure tool entirely (which also removes the plane). The cutting plane is visual only — it does not modify the model or affect annotations.

Groups help organize annotations by category, phase, or team member. Click + Group in the sidebar to create a new group with a custom name and color. All annotations within a group share that color. Use the eye icon to show/hide all annotations in a group, and the edit icon to modify the group name, color, or opacity, or to delete the entire group. A default group is created automatically when you first annotate.

Group Opacity: Each group has an opacity slider (5–100%) that controls the transparency of all annotations in that group. This is useful when overlapping annotations from different groups need to remain distinguishable, or when you want to de-emphasize one group while focusing on another. Opacity settings are saved in the JSON export and restored on import.

Use the search box at the top of the sidebar to filter annotations by name. As you type, annotations and groups that don't match your search term are hidden from the list. Clear the search field to show all annotations again. This is helpful when working with many annotations and you need to quickly find a specific feature.

In the General Information section at the top of the sidebar, the Model Information item stores free-form notes about the entire model. Click the edit button or double-click to open it. Like annotations, it supports multiple entries from different team members with timestamps — useful for documenting the model’s origin, processing history, or general observations. The sidebar shows a preview of the latest entry.

Below Model Information, the Metadata Report provides a structured form for documenting the technical metadata of your 3D documentation project. Click the edit button or double-click to open it. The form covers seven sections: General Information (project title, location, timeline), Object Context (object type, material, dating, find spot, inventory number), Capture Metadata (documentation method, instrument, camera/scanner settings), Reference Metadata (GPS, scalebars, GCPs), Processing Metadata (software, algorithms, model details), Paradata (method rationale, sources, interpretive decisions, known limitations), and Legal (project lead, funding, copyright).

Subject kind & controlled vocabularies: At the top of the form, the Subject kind selector records what the documented subject is (movable object, feature, building, site, landscape, or mixed). This sets the CIDOC CRM root class used when the metadata is exported — it does not change which fields are shown. Several fields (Object Type, Material, Dating/Period, Location, Find Spot) also offer an optional authority URI input for linking to a controlled vocabulary such as Getty AAT, PeriodO, or a gazetteer. All of this is optional; the precise mapping is documented in the MeshNotes Metadata Format specification.

The template supports all common 3D documentation methods: photogrammetry, structured light scanning, LiDAR, and terrestrial laser scanning (TLS). Fields that don’t apply to your method can simply be left empty. Each section also allows adding custom fields for project-specific needs. A non-editable Data Management guideline with a recommended folder structure is shown at the bottom for reference.

Export & Import: The metadata popup has three buttons at the top:

• JSON (download) — Downloads the metadata as a JSON file. This is the round-trip format: re-import it into MeshNotes to restore all fields. If the form is empty, you get the blank template to fill out in a text editor.
• PDF (download) — Downloads a fillable PDF form with all fields, including the subject-kind dropdown and any authority URIs. Pre-filled values are included if available. The PDF can be opened in any PDF viewer, filled out by hand or digitally, and used as a standalone documentation form outside of MeshNotes.
• JSON (upload) — Imports a previously exported JSON metadata file, replacing the current metadata after confirmation.

Integration: Metadata is automatically included in the JSON-LD annotation export and restored on import. It also appears at the end of PDF reports (only filled fields are shown).

Per-model: Metadata belongs to the model you are documenting. You can fill it in before loading a 3D file, but loading a new model (or refreshing) clears the current metadata — MeshNotes warns you first and offers to export your work (annotations and metadata together, as JSON-LD) before continuing.

The sidebar shows how many fields are filled, with a preview of the first filled value.

Each annotation can have multiple entries from different users. When editing an annotation, you'll see all existing entries with their author and timestamp. Click + Add Entry to add your own observation without overwriting previous ones. Each entry has its own description, author name, and links. This is ideal for collaborative documentation where multiple team members contribute observations to the same feature.

Version history: When you edit an existing entry, the previous version is automatically preserved. You can view the version history by clicking Edit on any entry — a collapsible "Previous versions" section appears showing all past edits with their timestamps and authors. This ensures no information is lost during collaborative editing.

Single-click an annotation in the sidebar to focus the camera on it. Double-click to open it for editing. In the edit popup you can: change the annotation name and group, view all entries, edit existing entries (with confirmation to encourage adding new entries), delete individual entries, or delete the entire annotation. Your author name is remembered for convenience.

Version history: When editing an entry, a "Previous versions" section appears below the edit form. Click the toggle to expand it and see all previous versions of that entry, including who made each change and when. This read-only history helps you track how observations evolved over time and ensures accountability in team documentation.

When no tool is active, you can click and drag any annotation point to reposition it. The cursor changes to a hand when hovering over draggable points. While dragging, the point snaps to the model surface so your annotations stay attached to the geometry.

Lines and polygons: When you drag a point that belongs to a line or polygon, the connected edges update in real-time. If surface projection is enabled for that annotation, the adjacent edges are re-projected onto the model surface as you move the point — so the lines continue to follow the surface contour at the new position. This allows you to refine annotation boundaries precisely without recreating them.

Note: Surface annotations (painted faces) cannot be repositioned after creation. To adjust a surface annotation, delete it and paint a new one.

JSON-LD Export: Click Export ▾ and choose JSON-LD (.jsonld) to download all annotations in W3C Web Annotation format. This standard format ensures interoperability with other annotation tools and IIIF-compatible viewers. The export includes all entries, timestamps, metadata, groups, and model information.

Model Files Export: Click Export ▾ and choose Model Files to download the original model files (including material and texture files for OBJ and PLY models). This is useful when you received a model via a share link and want to save it to your computer.

Import: Click Import ▾ and choose Annotations (.jsonld) to load annotations from a .json or .jsonld file. MeshNotes supports both the new W3C format and legacy MeshNotes files for backward compatibility. Imported annotations merge with existing ones — groups with the same name are combined.

The W3C Web Annotation Data Model is a standard for interoperable annotations. Learn more at w3.org/TR/annotation-model

Click Share in the toolbar to open the sharing dialog. MeshNotes offers two sharing modes:

Quick Share (90 days): Uploads your model and annotations to meshnotes.org and generates a link. Anyone with the link can open the model and annotations directly in MeshNotes — no file download or manual import needed. Quick Share links expire after 90 days. Click Generate Link to upload. Maximum file size: 100 MB.

Tip: Large GLB models can be reduced significantly using Draco compression before sharing. See the Model Preparation & Format Guide section for details and tools.

Permanent (own hosting / DOI): For long-term, citable sharing, upload your model and annotation files to a CORS-friendly repository that supports direct file access from the browser. Enter the file URLs in the dialog, select the model format (important when the URL does not contain a file extension), and MeshNotes generates a permanent link. These links do not expire and do not use meshnotes.org storage — the files are loaded directly from your repository. If your repository mints DOIs, the link is citable in publications.

Previously generated links: The Share dialog keeps a history of all links you have generated, showing the model name, creation date, and time remaining until expiry. You can copy any previous link or remove entries from the list. This history is stored in your browser’s local storage.

Recipient workflow: When someone opens a share link, the model and annotations load automatically in MeshNotes. The recipient can view, edit, and add their own annotations. To save the work, they can export the annotations as JSON-LD, download the model files via Export ▾ → Model Files, or re-share with a new link.

MeshNotes is designed for teams working on the same 3D model. There are two ways to collaborate:

Online collaboration (Quick Share): Use the Share button to upload your annotated model and send the link to collaborators. They open the link, see your model and annotations, add their own work, and re-share with a new link. Each share creates a new snapshot — there is no real-time editing, but the workflow is fast and requires no file management. See the Sharing section above for details.

Offline collaboration (file exchange): For fully offline workflows or when data confidentiality is important, use JSON-LD export/import. Multiple people can annotate independently and then merge their work — no server or shared account required.

How it works: Every annotation and every entry within an annotation is assigned a unique ID (UUID) when created. When you import a JSON file, MeshNotes compares these IDs to determine what is new and what already exists:

• New annotations (unknown UUID) are added alongside your existing ones.
• Existing annotations (matching UUID) are updated — any new entries from collaborators are merged in, and entries that were edited are updated if the imported version has a newer timestamp.
• Groups with the same name are combined. New groups from the imported file are created automatically.
• Model Information entries are merged in the same way as annotation entries.

Example team workflow:

• 1. Alice loads the model, creates annotations, and exports a JSON file.
• 2. Bob loads the same model, imports Alice's JSON, and adds his own annotations and entries.
• 3. Bob exports his JSON and sends it back to Alice.
• 4. Alice imports Bob's file — she gets Bob's new annotations and entries merged into her existing work. Her own annotations remain untouched, and Bob's additions appear alongside them.

This process can be repeated as many times as needed. Each round of import merges only what is new or updated, so you never lose work and annotations are never duplicated.

MeshNotes exports annotations following the W3C Web Annotation Data Model, an internationally recognized standard for representing annotations on digital resources. This was a deliberate choice to ensure long-term interoperability and academic credibility.

What gets stored: Each annotation is a self-contained JSON-LD object containing its geometry (as a typed geometry selector whose coordinates are encoded as 3D WKT), all entries with author, description, links, and timestamps, as well as the group assignment and annotation type. The exported file is a standard AnnotationCollection that also includes group definitions, model information, and the metadata report.

Why it matters: Using a W3C standard means your annotation data is not locked into MeshNotes. The JSON-LD files are human-readable, can be parsed by any programming language, and are compatible with the broader ecosystem of IIIF-based annotation tools and digital humanities infrastructure. This makes MeshNotes annotations suitable for academic publication, archival, and integration into larger research data management workflows.

Formal specifications: The exact formats MeshNotes writes are documented in three versioned, citable specifications: the Annotation format (the AnnotationCollection structure), the Selector format (how each geometry type is encoded), and the Metadata format (the structured metadata block and its CIDOC CRM crosswalk). These let other software read MeshNotes files reliably.

The exported .jsonld files can be opened in any text editor to inspect their contents. Each annotation's geometry is stored as a WKT string in the selector's meshnotes:wkt field.

Click Export ▾ and choose PDF Report to generate a comprehensive documentation report of your annotated model. The report is designed for academic documentation, publication appendices, and archival. Page size (A4, Letter, A3), orientation, screenshot quality (DPI), camera framing (distance and angle), report title, institution, project name, and accent color can all be customized in Settings.

Report structure:

• Title page — An overview screenshot of the model with all visible annotations, the model filename, a summary of annotation and group counts, and all Model Information entries.
• Axis views — Six orthogonal views (Top, Bottom, Front, Back, Left, Right) arranged in an unfolded cube layout, giving a complete overview of the model from all standard directions. If you are in orthographic mode, each view includes a scalebar.
• Table of contents — A numbered list of all included annotations for quick reference.
• Annotation pages — One page per annotation with an auto-captured screenshot (the camera automatically focuses on each annotation), the annotation name, type, and group, plus all entry details including author, date, description, and links. If the camera ends up too close to (or inside) your model, increase the Camera Distance in Settings; for flatter viewing angles, lower the Camera Angle.

Controlling report content: Only visible annotations are included in the PDF. Use group visibility (the eye icon) to hide annotations you don't want in the report. For example, you could hide preliminary annotations and only include finalized ones, or generate separate reports per group by toggling visibility before each export.

Click Screenshot to save the current view as a PNG image. The screenshot includes all visible annotations, name labels, and measurement lines exactly as shown on screen — useful for documentation, reports, and publications.

Screenshot Quality: In Settings, you can choose the screenshot resolution: Standard (1×) captures at screen resolution, High (2×) renders at double resolution for sharper detail when zoomed in, and Ultra (4×) renders at four times the resolution for maximum clarity. Higher quality may take longer on large models.

Scalebar: In Orthographic camera mode, screenshots automatically include a scalebar in the bottom-right corner. The scalebar shows the real-world distance based on the model's coordinate system, with values rounded to clean numbers (e.g., 1, 2, 5, 10, 20, 50...) for readability. The unit label matches the measurement unit configured in Settings.

If you take a screenshot while in Perspective mode, MeshNotes will ask whether you want to switch to Orthographic view first. A scalebar can only be accurate in orthographic mode, where scale is uniform across the entire image — in perspective view, objects further from the camera appear smaller, making a single scalebar misleading.

Left-click + drag: Rotate the view around the model. Right-click + drag: Pan the view. Scroll wheel: Zoom in/out. Escape: Cancel current drawing action, deselect tool, or clear all measurements.

MeshNotes is optimized for tablets with stylus input (e.g., iPad with Apple Pencil). On touch devices, the interface automatically adapts with a collapsible sidebar, touch-friendly controls, and separate handling of stylus vs. finger input.

Input separation: MeshNotes distinguishes between stylus and finger input:

• Stylus (pen): Used for annotation — placing points, drawing lines/polygons, painting surfaces, placing and adjusting boxes
• Finger: Used for navigation — rotate the view (1 finger), zoom (pinch), pan (2-finger drag)

This separation lets you annotate and navigate without switching modes — simply pick up the stylus to annotate, or use your fingers to move around the model.

Stylus gestures:

• Tap: Place a point, add a line vertex, or start a box
• Double-tap: Finish a line/polygon, confirm a box, or complete a measurement
• Drag: Paint surfaces, move/resize boxes

Apple Pencil barrel tap: If you have an Apple Pencil (2nd generation) and have configured it in iPad Settings → Apple Pencil → "Switch between current tool and eraser", you can use the barrel double-tap as an alternative to double-tapping on screen. This is especially convenient for finishing lines, polygons, and confirming box placements without lifting your hand.

Box rotation: To rotate a box on tablet, use a two-finger twist gesture while the box is selected. This replaces the right-click rotation used on desktop.

Sidebar: On tablets, the sidebar starts collapsed to maximize viewport space. Tap the arrow button on the right edge to expand/collapse it. When collapsed, the viewport automatically expands to use the full screen width.

Click the Perspective/Orthographic button in the top-right corner of the viewport to toggle between camera modes. Perspective view shows depth with natural foreshortening. Orthographic view removes perspective distortion, making parallel lines appear parallel — useful for accurate measurements, technical drawings, and architectural documentation.

Click the Flip button in the bottom-right panel to rotate the model 180° upside down. This is useful for objects like coins where the front and back sides are stamped at different angles, making the reverse side difficult to reach with normal orbit controls.

Purely visual: The flip is a temporary display effect only. It does not change the model's actual orientation, and it does not affect annotation coordinates. All annotations — whether created before, during, or after flipping — are stored in the same coordinate space as if the model were in its original orientation. You can freely toggle the flip on and off without any impact on your data.

Export safety: JSON exports, PDF reports, and screenshots taken while the model is flipped will contain the same annotation coordinates as exports made without flipping. The flip state is never saved or exported — it is purely a viewing convenience that resets when you load a new model.

Annotations while flipped: You can create, edit, drag, and delete annotations normally while the model is flipped. New annotations placed on the visible (flipped) surface are automatically stored with the correct non-flipped coordinates. Existing annotations remain correctly positioned when you toggle the flip on or off.

In the top-right corner of the viewport you'll find the View Helper, an interactive widget provided by the Three.js library. It displays three colored axis lines — X (red), Y (green), and Z (blue) — radiating from a central point, with labeled circles at each positive axis end and smaller circles at each negative end. As you rotate the model, the View Helper rotates along with it, always showing your current camera orientation at a glance.

Click any axis circle to smoothly animate the camera to that standard view direction (e.g., click the Z circle for a top-down view, click the Y circle for a front view). This is particularly useful for consistent documentation — for example, always capturing the same angle of an artifact for comparison, or quickly switching between front and side views while annotating.

Use the opacity slider to see annotations on the back side of the model. Group annotations by excavation phase, feature type, or team member for better organization. Export frequently to back up your work. The tool runs entirely in your browser — your data stays on your computer unless you explicitly use the Share feature to generate a link.

MeshNotes runs entirely in your web browser. Your 3D models, annotations, and all other data remain on your computer by default. The tool does not use cookies, analytics, or tracking, and all program libraries (Three.js, jsPDF, pdf-lib, and others) are served from MeshNotes itself rather than third-party CDNs. The only network request during normal use is loading the application from its host; see the Legal / Data section for details, or run MeshNotes locally (see below) to keep everything fully offline.

Sharing (optional): The Quick Share feature uploads your model and annotations to meshnotes.org (hosted on Cloudflare) to generate a temporary shareable link. Files are automatically deleted after 90 days. No data leaves your computer unless you explicitly click "Generate Link" in the Share dialog. The Permanent sharing option does not upload anything to meshnotes.org — it generates a link that points to files you have hosted yourself on a repository of your choice. If data confidentiality is critical, use the offline JSON-LD export/import workflow instead.

When hosted on GitHub Pages, the application files are downloaded once, after which all processing happens locally. For offline use, you can clone or download the GitHub repository and run a local web server (e.g., python -m http.server or VS Code Live Server). Note that opening index.html directly via file:// won't work due to browser security restrictions on ES modules.

Exported JSON and PDF files are generated locally in your browser and saved directly to your downloads folder. Sharing annotation data with collaborators is always an explicit action on your part — you decide when and with whom to share your exported files. This makes MeshNotes suitable for documenting sensitive or unpublished archaeological sites where data confidentiality is important.

Click the Settings button in the toolbar to open the settings panel. All settings are saved automatically in your browser and persist between sessions.

User: Set a Default Author Name that is pre-filled whenever you create a new annotation entry, saving you from typing it each time.

Measurements: Choose a Display Unit (units, mm, cm, m, or custom) for measurement labels and scalebars. You can also customize the Line & Label Color and Point Color of measurements to stand out against your model.

Annotation Display: Adjust Point Size and Text Size multipliers to scale annotation markers and labels for your model's size. The sliders use exponential scaling for easy fine-tuning at both small and large values.

Screenshot: Choose the Screenshot Quality — Standard (1×) captures at screen resolution, High (2×) at double, and Ultra (4×) at four times resolution. Higher quality produces sharper images but may be slower on large models.

Model Display: Customize the Mesh Color and Wireframe Color used in the Mesh and Wireframe display modes.

PDF Export: Configure your PDF reports with a custom Report Title, Institution, and Project Name that appear on the title page. Choose an Accent Color for headings and decorative elements, a Page Size (A4, Letter, or A3), Orientation (portrait or landscape), and Screenshot Quality (72, 150, or 300 DPI). The Camera Distance multiplier (×0.5 to ×5.0) controls how far the camera is placed from each annotation — keep it low for large objects like buildings, and increase it for small objects like coins or sherds to prevent the camera from clipping through the model. The Camera Angle (15° to 80°) sets the elevation above the horizontal plane — steep angles give a top-down view, shallow angles show the object more from the side.

Background Color: Choose the viewport background from preset colors (dark blue, black, dark gray, gray, white) or pick a custom color. White or light backgrounds are ideal for publication screenshots.

Reset: Click Reset All Settings to Default at the bottom to restore all preferences to their original values.