MeshNotes – 3D Annotation Tool for Research & Heritage

Click Load Model to open a 3D model file. The tool supports .glb, .gltf, .obj, and .ply 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, and .ply 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, standart format for e.g. GigaMesh. Supports vertex colors natively.

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 or PLY 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.

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 three modes: Texture (shows the model's texture maps), Colors (shows vertex colors only, if present), and Gray (plain geometry without any color). The Colors mode is only available if the model contains vertex color data.

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: 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: 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.

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).

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 "units" — the actual unit (meters, millimeters, etc.) depends on how your 3D model was created or exported.

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 delete the entire group. A default group is created automatically when you first annotate.

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.

At the top of the sidebar is a Model Information section for general notes about the entire model. Double-click it to add an introduction, context, or overview that applies to the whole model rather than a specific location. Like annotations, it supports multiple entries from different team members with timestamps — useful for documenting the model's origin, processing history, or general observations.

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 Export: Click to download all annotations in W3C Web Annotation format (.jsonld). This standard format ensures interoperability with other annotation tools and IIIF-compatible viewers. The export includes all entries, timestamps, metadata, groups, and model information.

Import: Click 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

MeshNotes is designed for teams working on the same 3D model. Multiple people can annotate independently and then merge their work through JSON import/export — 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 Fragment Selector with 3D coordinates), 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 and model information.

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.

The exported .jsonld files can be opened in any text editor to inspect their contents. Each annotation's geometry is stored as coordinate strings in the FragmentSelector value field.

Click PDF to generate a comprehensive documentation report of your annotated model. The report is formatted for A4 paper and designed for academic documentation, publication appendices, and archival.

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.

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.

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 depends on how your 3D model was originally created or exported (e.g., millimeters, centimeters, or meters).

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 share the exported JSON file.

MeshNotes runs entirely in your web browser. No data is uploaded to any server — your 3D models, annotations, and all other data remain on your computer at all times. The tool does not use cookies, analytics, tracking, or any external services.

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.