Overview
GrapheNova is a web application for microscopy-image workflows involving graphene and graphene-derived materials. In the current application, the primary user-facing workflow is focused on image labelling and expert review: upload an image, open the labelling workspace, review or create annotations, and preserve the reviewed results.
The detailed workspace retains the established scientific-review structure: Sample Context, Model-Assisted Detection, Label & Review, Structural Summary, and Export. Model-assisted detection is optional as a labelling aid, but a full detection run is currently required before the review canvas can create manual free-shape or rectangular ROIs.
Getting Started
- From Home, select Start Image Labelling, or use Image Labelling in the main navigation.
- Upload a supported microscopy image. The newly uploaded image becomes the active image automatically.
- Confirm the active-image preview and select Open Labelling Workspace.
- Complete useful sample and imaging metadata in Sample Context.
- Prepare candidate objects using the Model-Assisted Detection stage when needed, then move to Label & Review.
- Review labels, add expert ROIs, set reviewer status, and enter notes before moving to Export.
Supported image formats
The upload control accepts .tif, .tiff, .png, .jpg, .jpeg, and .bmp. TIFF images are converted to PNG only for browser preview; the uploaded source file remains the active server-side image.
Uploading Images
Upload zone
Use the large upload area on the Image Labelling page in either of two ways:
- Click the upload area and choose a supported image from your device.
- Drag a supported image directly onto the upload area.
What happens after upload
When upload succeeds, the application displays a success message, stores the filename as the active image for the current browser session, and shows the image in the Active Image card. No additional image-selection dropdown is used.
Select the displayed image to open a larger preview. Select Open Labelling Workspace to continue with that image.
Image Labelling Interface
The workspace is organized into five internal stages. These are workflow stages inside Image Labelling, not separate main application pages.
| Stage | Purpose | Main controls |
|---|---|---|
| Sample Context | Capture material identity and imaging setup so exported annotations retain the correct scientific context. | Material family, oxidation/reduction state, functionalization, modality, detector/contrast, magnification, calibration, identifiers, pixel size, instrument, substrate, preparation, analysis preset. |
| Model-Assisted Detection | Preview preprocessing and create candidate objects that can then be inspected and edited by a reviewer. | Preprocessing presets, custom preprocessing controls, detection model cards, target checkboxes, model parameters, Preview Detection, Run Full Detection, Save/Load Preset, Reset. |
| Label & Review | Review detected objects and add expert-defined regions. | Image views, Free shape, Draw ROI, filters, sortable object table, pagination, object inspector, label/custom label, status, reviewer note, delete user ROI. |
| Structural Summary | View aggregate counts, distributions, morphology statistics, and QC information computed from the latest full detection and review state. | Read-only overview cards, distributions, morphology summary, navigation to Review or Export. |
| Export | Choose which information to include and preserve reviewed results. | Report-section checkboxes, JSON, CSV, PDF print, Save session, image/mask downloads. KI/project-save controls are currently disabled. |
Sample Context controls
| Control | Use |
|---|---|
| Material Family | Required material classification. Selecting a family automatically loads a matching analysis/detection preset. |
| Oxidation State | Records oxidation metadata: None, Low, Medium, or High. |
| Reduction Status | Records whether the material is pristine, partially reduced, or fully reduced. |
| Functionalization / Coating | Records surface chemistry such as None, Carboxyl, Hydroxyl, PMMA, or Other. |
| Imaging Modality | Records TEM, SEM, AFM, or Optical Microscopy. AFM selection controls whether the AFM-specific summary area is shown. |
| Detector / Contrast Mode | Records Bright field / High contrast, Dark field, HAADF-STEM, or Phase contrast. |
| Magnification | Used by the workspace to gate detection targets that are not meaningful at the entered magnification. |
| Pixel Size | When supplied, summary sizes and areas can be converted from pixels into physical units. |
| Calibration Status | Records Confirmed, Pending, or Not calibrated for QC/export context. |
| Analysis Preset | Normally auto-loaded from Material Family but can be overridden before detection setup. |
| Study/Sample/Batch/Replicate & setup fields | Free-text metadata carried into report/export content. |
Preprocessing and model-assisted detection
Before creating reviewer objects, the current workspace provides a two-stage preparation flow: preview preprocessing, confirm the result, then choose a detection model and run detection.
| Control | What it does |
|---|---|
| Aggressive / Balanced / Conservative | Select predefined preprocessing intensity. Balanced is the default. |
| Custom | Opens custom preprocessing settings, including contrast normalization, background subtraction, denoising, edge enhancement, and threshold behavior. |
| Preview Preprocessing | Runs preprocessing and displays the original/preprocessed comparison plus applied steps. |
| Ignore scale-bar text & bar | Tells the detection stage to skip those pixels while leaving the source image unchanged. |
| I'm satisfied — unlock model selection | Confirms preprocessing and unlocks the detection-model stage. |
| TEM Detector | Default multi-target detection pipeline for flakes and related structural/artefact targets. |
| Otsu Threshold | Simple binary segmentation baseline. |
| Bayesian GMM | Gaussian-mixture segmentation with configurable component count. |
| Watershed | Marker-based watershed segmentation with a distance-threshold parameter. |
| Level Set | Edge-stopping level-set segmentation with configurable iteration count. |
| micro-SAM | SAM-based instance segmentation with model, mode, and minimum-region controls. |
| Preview Detection | Runs a fast, downsampled test. The preview is not pushed into Label & Review, Structural Summary, or Export. |
| Run Full Detection | Runs full-resolution detection and populates the review, summary, and export stages with candidate objects and outputs. |
| Save Preset / Load Preset | Saves or reloads a detection configuration in the current browser. |
| Reset | Returns sample/preset, preprocessing, targets, parameters, and model selections to defaults after confirmation. |
Creating Labels / Annotations
1. Open Label & Review
After a full detection has completed, open Label & Review. The workspace contains an image panel, an object table, and an object inspector.
2. Choose the image view
Use Raw, Contour, Segmentation mask, or Label colors to change the display used for review. These controls affect visualization only; they do not alter the uploaded source image.
3. Select an existing object
Select a row in the object table to highlight the corresponding region and open its measurements and review controls in the inspector.
4. Assign or edit a label
Use the Label dropdown to reassign the object. The available groups include:
- Main objects: Single flake, Overlapping flakes, Restacked region, Thick aggregate, Small fragment.
- Structural features: Edge, Fold, Wrinkle, Tear, Hole / pore, Crack, Layer boundary.
- Non-target: Substrate, Contamination, Artefact, Debris.
A custom-label text field is also available for an object-specific label. Entering a custom label overrides the dropdown label for that object in the review display and exports.
5. Draw a manual region
| Tool | How to use it |
|---|---|
| ✐ Free shape | Select the tool, press and drag around the target feature, and release to create a polygon region. The new ROI is added to the object table and opened in the inspector. |
| ▭ Draw ROI | Select the tool and drag a rectangle around a region. The new ROI is added to the table and can then be labelled in the inspector. |
| Point / Brush / Split / Merge / Exclude / Measure | Displayed as unavailable/coming-next tools in the current implementation; they do not currently perform annotation actions. |
6. Remove an incorrect manual annotation
For user-drawn regions only, the inspector displays Delete this user-drawn ROI. After confirmation, the ROI is removed from the live table and its stored browser data.
Reviewing Results
Filter and navigate the object table
| Control | Review use |
|---|---|
| Label type | Filter the table by detected feature category or user ROI category. |
| Reviewer status | Show All, Pending, Accepted, Rejected, Uncertain, or Edited objects. |
| Min confidence | Hide model-generated objects below the selected confidence threshold. |
| Min area | Hide objects below the selected pixel-area threshold. |
| Column headers | Select a sortable header to sort; select it again to reverse the order. |
| Rows/page & pager | Choose 100, 200, 500, or 1000 rows per page and navigate with First, Previous, Next, and Last controls. |
Set reviewer status
For the selected object, use Accept, Reject, or Uncertain. Changing an object's label without an explicit status changes its review state from Pending to Edited. Reviewer status is reflected in the table, summary/QC calculation, and exported object information.
Add reviewer notes
Use the reviewer-note field to record a free-text observation for the selected object. Notes are stored per object in the browser and are included when reviewer information is enabled in exports.
Check the structural summary
The Structural Summary stage aggregates the latest full-detection results into overview cards, distributions, and a morphology table. If Pixel Size is available, relevant sizes/areas can be shown in physical units; otherwise they remain in pixels.
Saving / Submitting Results
The current implementation provides browser-local persistence and downloadable exports. It does not currently submit labelling results directly to the ACCORDs Knowledge Infrastructure; the corresponding project/KI controls remain disabled.
Automatic browser persistence during review
Reviewer labels, custom labels, statuses, notes, and user-drawn ROIs are persisted per image in the browser's local storage as you edit them. This supports continued review in the same browser profile.
Export controls
| Action | Result |
|---|---|
| JSON | Downloads the enabled report sections, which can include sample/imaging metadata, preset/detection settings, object measurements, summaries, distributions, reviewer information, and QC data. |
| CSV | Downloads object-level data for model detections and user-drawn regions, including reviewer status, reviewer label, and reviewer note. |
| PDF report (print) | Builds a metadata header, switches to the Structural Summary, and opens the browser print / print-to-PDF dialog. |
| Save session | Saves the current export payload for the image in browser local storage and displays a confirmation alert. |
| Annotation masks & images | Provides available PNG downloads such as the preprocessed image, labelled overlay, segmentation image, and per-target masks generated by the selected model. |
| Link to project record / Save to KI later | Currently disabled and marked for a future KI-integration milestone. |
Tips and Best Practices
- Record context before review. Enter a useful Sample ID and the relevant imaging setup so exported labels remain traceable to the correct material and acquisition conditions.
- Use Material Family deliberately. It determines the default preset used when preparing model-assisted candidate objects.
- Confirm preprocessing before full detection. Preview first, inspect the image comparison, then confirm that you are satisfied before running the full-resolution model.
- Use consistent label terminology. Prefer the provided controlled label options when they fit. Use a custom label only when the existing list does not adequately describe the object.
- Avoid accidental duplicate ROIs. Before drawing a manual region, inspect the existing objects and label-color view so the same feature is not labelled twice.
- Review boundaries visually. For free-shape and rectangle annotations, verify that the ROI covers the intended feature and does not unnecessarily include substrate or neighboring objects.
- Use status consistently. Reserve Accepted for reviewed objects you agree with, Rejected for objects that should not be retained as valid labels, and Uncertain when the image evidence is insufficient for a confident decision.
- Add notes for ambiguous cases. Reviewer notes make it easier to understand why an object was relabelled, rejected, or left uncertain.
- Export before clearing browser data. Review states, user ROIs, saved presets, and saved sessions use browser storage in the current implementation.
Troubleshooting
| Issue | What to check |
|---|---|
| Image upload fails | Confirm the file uses a supported extension and retry the upload. The Image Labelling page displays the server-provided upload error when the request fails. |
| Uploaded image does not display | If the previously active image is no longer available on the server, the page clears that active state and asks you to upload the image again. Re-upload the source image and continue. |
| Labelling workspace does not open | The workspace route requires the uploaded file to exist on the server. Return to Image Labelling, upload the image again, and reopen the workspace. |
| Free shape or Draw ROI does not start | These tools currently require a full detection result in the workspace. Run Run Full Detection first, open Label & Review, then use the annotation tool. |
| Preview results do not appear in Review | This is expected. Preview Detection is intentionally temporary and does not populate Label & Review, Structural Summary, or Export. Run Full Detection when you want reviewable candidate objects. |
| Labels or notes seem missing after switching objects | Re-select the object in the table. Review labels, statuses, and notes are stored per image/object in browser local storage and restored by the inspector. |
| After reloading, no detected objects are visible | Detection results are generated in the active workspace. Re-run Full Detection to rebuild the object list; previously stored reviewer state for matching objects can then be restored by the browser. |
| Need a durable copy of the work | Use the Export stage to download JSON/CSV or print a PDF. Browser-local Save session is useful for the same browser but is not a server submission. |