Help & Tutorial

Toolbar Tools

The floating toolbar above the canvas includes:

• Reset view: Restores the original zoom and position.
• Feature selector: Enables selection mode for existing polygons.
• SAM Tool: Uses the Segment Anything Model for automatic segmentation.
  • Select the SAM tool, then left-click inside the object to add a positive point. Positive points appear as green + markers. At least one positive point is required.
  • Add more positive points to include missing areas. The segmentation preview updates automatically after each change.
  • Right-click areas that do not belong to the object to add negative points, shown as red − markers. Negative points help remove unwanted areas from the preview.
  • Press Backspace to remove the most recently added point. You can continue adding or removing points until the preview matches the object.
  • Press Enter or click the ✓ button to save the current preview as a polygon. If SAM is still processing, Argiope waits for the latest preview before saving. The tool remains active so you can start another object.
  • Press Esc or click the × button to cancel the current SAM session without saving its preview.
• Polygon draw: Manually trace regions of interest.
• Line draw: Manually trace regions of interest.
• Undo, and Redo: Undo and redo the last 10 changes applied to polygons.
• Zoom in, Zoom out, and Pan: Adjust the viewport. Holding Shift is a shortcut for Pan.
• Import feature file: Add annotations directly from the viewer. Import a JSON in the COCO format or an ImageJ ROI file (https://imagej.net/ij/). For ImageJ ROIs, unzip the file first and select the desired objects.
• Export feature file: Export a JSON in the COCO format or an ImageJ ROI file (https://imagej.net/ij/).
• Select model: Choose which AI model to apply; Generate features (AI) executes it on the current image.

Objects List & Tags

The side panel lists every object. You may add tags to classify the image or individual objects.

AI Models: How to Add Models

• Click AI Models. To add a model, type a name and select the model type:
  • Zero-shot Segmentation:
    • Objects list: add keywords describing targets (comma-separated), e.g., butterfly, small green square, big circle. Try variants for robust performance.
    • Detection threshold: per-object confidence threshold (comma-separated). Very low thresholds (e.g., 0.001%) can help during exploration.
    • Max. number of features: maximum objects per type to retain (comma-separated). Keeps the highest-confidence results.
    • Buffer (%): edge offset applied to polygons. Positive values dilate outward; negative values erode inward. The percentage is applied per border (e.g., -10 removes about 10% from each side).
  • Zero-shot Detection: same as above but returns bounding boxes.
  • Roboflow Segmentation:
    • URL: provide the roboflow model URL address; e.g., colorchecker-segmentation/3
    • API Key: required for Roboflow inference (kept personal and confidential). To locate you API Key go to your user account in the Roboflow WebApp
    • Detection threshold (%): minimum confidence. Only detection with confidence values above the threshold will be kept.
    • Max. number of features: maximum objects per image.
    • Buffer (%): edge offset applied to polygons. Positive values dilate outward; negative values erode inward. The percentage is applied per border (e.g., -10 removes about 10% from each side).
  • Roboflow Classification:.
    • URL and API Key as above.
  • Roboflow Workflow:
    • Workspace name: the slug shown in the Roboflow workspace URL, for example, evolutionary-ecology-lab.
    • Workflow ID: the ID or URL slug of the Workflow published in Roboflow Deploy.
    • API Key: the personal Roboflow account key used to run the Workflow.
    • Image input name: the name assigned to the Workflow image input; normally image.
    • Apply results as: choose segmentation to create editable polygons or tags to add image labels.
    • Workflow output key: optional. Leave blank to detect the predictions output automatically; use a dot-separated path only when the Workflow has multiple outputs, for example, output.predictions.
    • Buffer (%): expansion or contraction applied to polygons when using segmentation results.
  • Gemini Classification:.
    • API Key: required for Gemini inference (kept personal and confidential). To locate you API Key go to your user account in the Google AI for Developers (https://ai.google.dev/).
    • Model: select Gemini model.
    • Prompt: type a prompt for the Gemini model. For instance, "read the label on this image and return its content."
  • ChatGPT Classification:
    • API Key: create or access a key on the OpenAI platform (https://platform.openai.com/api-keys). ChatGPT subscriptions and API credits are separate services.
    • Model: select or enter an OpenAI model that supports image input.
    • Prompt: describe the desired classification and response format, for example, "identify the species and return only its scientific name."
  • Claude Classification:
    • API Key: create or access a key in the Anthropic Console (https://console.anthropic.com/settings/keys). The account must have API credits available.
    • Model: select or enter a Claude model that supports image input.
    • Prompt: describe the desired classification and response format.

Analyses

Use the Analyses to append statistics to the exported table. All outputs are written per object; results that create images also attach previews inside the session folder.

Basic Statistics

• Raw Values Stats: object_overall_max/min/mean/std/median/mad* and mean std**. Summary stats of all pixel values merged across channels in the object.
• Square root-transformed Stats and Natural logarithm-transformed(ln+1) Stats: the same stats after transforming pixels values by the square root or the natural logarithm + 1.
• Kernel Density Estimation: KDE-based mode estimation (highest-density point) for the object (column 'object_multimax'). These represent the most common combination of pixel channel values. For instance, in an RGB image KDE will estimate the most common combination of R, G and B values.
• Channel-level Stats:
• channel_CWL and channel_FWHM: Center Wavelength and Full Width at Half Maximum from image metadata; one pair per channel.
• channel_mean, channel_std, channel_median, channel_mad, channel_max, channel_min: per-channel statistics of the polygon.
• channel_relative_intensity: mean relative intensity of the channel (channel value divided by the per-pixel channel sum, then averaged over all pixels). For instance, in an RGB image, R_relative = R/(R+G+B), G_relative = G/(R+G+B) and B_relative = B/(R+G+B); then R_relative, G_relative, and B_relative are averaged across the polygon.
• Each line of the spreadsheet represents one spectral channel inside one polygon. Metrics that belong to the whole polygon (number of pixels, overall mean, etc.) are repeated on every line for convenience.

*The median absolute deviation (mad) is a measure of variability calculated as 1.4826*median(abs(x_i-median(x)))

**object_overall_mean_std, object_ln1_overall_mean_std, object_sqrt_overall_mean_std: the mean standard deviation of channels at the pixel level. For instance, in an RGB image, this will be calculated as mean(std(R,G,B)).

Shape Descriptors

Select only the shape descriptors you want to export. These metrics are calculated from the polygon mask, independently of pixel intensity values.

• Circularity: exports object_Circ. Calculated as 4*pi*area/perimeter^2. Values closer to 1 indicate a more circular shape; values closer to 0 indicate a more elongated shape.
• Aspect Ratio: exports object_AR. Calculated as major_axis/minor_axis from the fitted ellipse axes.
• Roundness: exports object_Round. Calculated as 4*area/(pi*major_axis^2).
• Solidity: exports object_Solidity. Calculated as area/convex area.
• Centroid: exports object_X and object_Y. These are the average x and y coordinates of all pixels inside the polygon mask.
• Perimeter: exports object_Perim. This is the perimeter of the polygon mask in pixel units.
• Bounding Box: exports object_BX, object_BY, object_Width, and object_Height. These describe the smallest axis-aligned rectangle containing the polygon mask.

Principal Component Analysis (PCA)

• Computes eigenvalues and eigenvectors from the masked pixels (requires at least two channels and enough pixels).
• Exports PC1 and PC2 eigenvalues (object_PC1, object_PC2) and the eigenvalues sum (object_PC_sum).
• A JSON file with all eigenvalues/vectors, covariance, and sample count is saved on the image folder inside the polygon folder.

Moran's I on PCA

• Measures spatial autocorrelation on PC1 and PC2 rasters derived from the polygon.
• Exports moran_I_PC1 and moran_I_PC2; higher positive values indicate clustering, negative values indicate dispersion.

Image Semivariogram

The image semivariogram describes how differences between pixel values change with spatial distance inside each selected object. Pixels are treated as continuous multichannel measurements; they are not classified or converted into categories. Each object is analyzed independently on its regular image grid, and pairs are never formed between different images or objects.

For a pair of pixels, Argiope calculates the mean squared difference across the selected channels and divides it by two. Pixel pairs are grouped into distance classes (bins). The empirical semivariance for a class is the pair-count-weighted mean of those values. With one channel, this reduces to the conventional scalar semivariogram.

Calculation options

• Calculation — Approximate: recommended for large images. It samples offsets and pixel pairs separately within each distance class, preventing long distances from dominating. A new random seed is generated for every analysis run and saved in the JSON metadata. Increase Maximum sampled pairs/bin or Sampling repetitions when results vary excessively between runs.
• Calculation — Exact: evaluates all valid pairs for every eligible regular-grid offset without building a complete pixel-by-pixel distance matrix. It is slower and is most useful for small objects, reference calculations, or validation of approximate results.
• Nugget — Free (estimated): estimates a non-negative discontinuity at distances immediately above zero. It may represent unresolved short-range variation or measurement noise, but it can be strongly correlated with sill and range.
• Nugget — Fixed at zero: removes the nugget from the optimization and fits a model whose limiting semivariance at the origin is zero. This can stabilize the other parameters when the freely estimated nugget is negligible. It should not be used automatically when the first distance classes indicate a real discontinuity.
• Mask pair policy — Valid endpoints: the default conventional policy. A pair is accepted whenever both endpoint pixels are valid, even if the straight segment between them crosses an area outside the mask.
• Mask pair policy — Same connected component: accepts a pair only when both endpoint pixels belong to the same 8-connected mask component. It prevents pairs between disconnected regions, but does not reject pairs whose segment crosses outside the mask when the endpoints remain connected by another path.
• Minimum pairs/bin: classes below this pair count remain in the empirical table, are marked as insufficient, and are excluded from fitting.
• Maximum distance: limits the spatial extent of the calculation. If blank, Argiope uses half of the image-grid diagonal. The distance should be long enough to show the plateau; a range beyond the analyzed extent is flagged.
• Bin width: controls the width of the distance classes. If blank, approximately 40 classes are created, never narrower than one grid step. Very narrow bins can contain too few pairs; very wide bins can hide short-range structure.
• Maximum sampled pairs/bin: approximate-mode sampling budget for each distance class. Larger values reduce sampling noise but take longer.
• Sampling repetitions: repeats the stratified sampling to estimate sampling uncertainty. It is available only in approximate mode. The output separates sampling_run_sd (variation between individual runs) from sampling_mean_se (standard error of the mean across repetitions).
• Directional analysis: additionally analyzes 0°, 45°, 90°, and 135° in image coordinates. Direction 0° follows increasing columns and 90° follows increasing rows. Directional ranges are used to report the continuity direction and anisotropy ratio.

Models to fit

• Nugget only: a null/reference model with no distance-dependent spatial structure. With the nugget fixed at zero it becomes the zero semivariogram.
• Spherical: reaches its sill at a finite mathematical range.
• Exponential: approaches the sill asymptotically and has a relatively sharp short-distance behavior.
• Gaussian: approaches the sill asymptotically with a smoother origin.
• Matérn: compares the smoothness values ν = 0.5, 1.5, and 2.5. The selected ν is exported; ν = 0.5 corresponds to exponential-type correlation.

Each model selected by the user is fitted independently by Cressie weighted least squares, with weights proportional to N(h) / gamma_model(h)^2. Argiope does not rank the models or select a best model. The user must decide which model is scientifically appropriate after examining the curve, residuals, convergence, parameter stability, observed distance range, and warnings. A small fit error is meaningful only when comparing the same data scale, channels, weights, bins, and spatial configuration.

Confidence-interval limitation: pixel pairs in a semivariogram are not independent because many pairs share pixels and spatial dependence remains between observations. The displayed normal intervals therefore use an approximate standard error and must be treated as descriptive, not as calibrated 95% coverage intervals. In approximate mode, sampling_mean_se quantifies Monte Carlo uncertainty of the repeated sampling mean; it does not include all spatial/process uncertainty.

Parameter-uncertainty limitation: parameter standard errors come from the local least-squares Jacobian. Distance classes can be correlated and the approximation does not replace a spatial bootstrap or a field-level likelihood analysis. Treat these standard errors and parameter-correlation warnings as diagnostics, especially for boundary estimates, ranges beyond the observed extent, or strongly correlated parameters.

Interpretation and files

• Nugget: modeled short-distance discontinuity; zero when fixed.
• Sill: nugget plus partial sill, representing the modeled semivariance plateau.
• Effective range: distance where the predicted correlation falls to 0.05; the spherical model instead also has a finite mathematical range.
• Main PNG: empirical points sized by pair count, uncertainty, and all fitted model curves, with no preferred curve highlighted.
• Validation PNG: observed-versus-fitted values and residuals for every converged model, plus fitting-error diagnostics without automatic ranking.
• Empirical CSV: bin limits, mean distance, semivariance, pair counts, uncertainty, direction, and insufficient-class status.
• Models CSV: every candidate, convergence, errors, warnings, nugget mode, and fitted parameters.
• JSON: complete results and reproducibility metadata, including channels, configuration, generated seed, mask extent, timing, memory estimate, and algorithm version.
• Results table: one row for each fitted model and direction, with nugget mode, nugget, sill, effective range, Matérn ν, anisotropy, fit quality, convergence, and warnings.

K-Means Clustering

• Segments the pixels inside the polygon into hard clusters. Manual mode uses the chosen n clusters; automatic mode tests up to max clusters using silhouette score.
• Exports cluster labels (kmeans_labels_img), kmeans_n_clusters, cluster centers, and proportions. Optional landscape metrics are selected separately.
• The best cluster count in automatic mode is the one with the highest silhouette score, balancing compactness and separation.
• A JSON file is saved on image folder inside the polygon folder with details on the analysis.
• An image file with clusters and cluster centers is saved on image folder inside the polygon folder.

Gaussian Mixture Model (GMM)

• Fits a diagonal-covariance mixture model. Manual mode uses the provided component count; automatic mode selects the best up to max components using BIC. Optionally scale inputs before fitting.
• Exports gmm_labels_img, gmm_n_clusters, and cluster means/weights. Optional landscape metrics are selected separately.
• Note: gmm_labels_img may display fewer visible clusters than the model components if some components receive no pixels.
• BIC chooses the simplest model that explains the data.
• A JSON file is saved on image folder inside the polygon folder with details on the analysis.
• An image file with clusters and clusters means is saved on image folder inside the polygon folder.

Landscape configuration metrics

After K-Means or GMM converts every classified pixel into a map class, enable landscape metrics and select only the measurements you need. Class-level results use columns such as kmeans_landscape_class_1_pland; landscape-level results use columns such as gmm_landscape_pielou_evenness. Patches use 8-neighbor connectivity, areas are pixel counts, and edges are counted as pixel sides. Let A be the classified landscape area, A_i the area of class i, a and P a patch area and perimeter, p_i = A_i/A, and K the number of classes.

• Total class area: A_i, the number of classified pixels in the class.
• PLAND: 100 A_i/A. It measures how much of the object is occupied by the class.
• Number of patches (NP): number of disconnected 8-neighbor components of the class. Higher values indicate greater subdivision.
• Patch density (PD): 100 NP/A, reported as patches per 100 classified pixels.
• Mean, median, and maximum patch area: summaries of the pixel counts of the class patches.
• Largest patch index (LPI): 100 max(a)/A. It measures dominance of the largest patch in the whole classified landscape.
• Total edge (TE): sum of class-patch perimeters. A pixel side contributes when it touches another class or the outside of the classified mask.
• Edge density (ED): TE/A, the amount of class edge per classified pixel.
• Mean perimeter-area ratio: mean of P/a. Larger values indicate more edge relative to patch area.
• Mean shape index: mean of P/(4√a). A compact square has value 1; more irregular patches have larger values.
• Mean circularity: mean of 4πa/P². Values nearer 1 indicate more circular patches.
• Mean fractal dimension: mean of 2 ln(0.25P)/ln(a). It describes boundary complexity; one-pixel patches are excluded because the logarithmic expression is undefined.
• Mean nearest-neighbor distance: mean of the shortest Euclidean distance to another patch of the same class, measured between the centers of the closest boundary pixels. It is undefined when the class has only one patch.
• Mean proximity index: for each patch, sums a_j/d_ij² over all other same-class patches using boundary-pixel center distances, then averages the sums. The search area is the full classified landscape; the value is 0 when no other same-class patch exists.
• Aggregation index: 100 g_ii/max(g_ii), where g_ii is the number of shared cardinal sides between class pixels and the denominator is the maximum possible for that class area. Larger values indicate aggregation.
• Contiguity index: mean patch-level FRAGSTATS contiguity. A 3×3 template weights cardinal neighbors by 2, diagonal neighbors by 1, and the focal pixel by 1; each patch value is ((Σc/a)−1)/12. It equals 0 for a one-pixel patch.
• Clumpiness: let G_i be directed like cardinal adjacencies divided by all cardinal pixel surfaces of class i, including surfaces facing background or the landscape boundary. CLUMPY is (G_i−p_i)/(1−p_i) when G_i≥p_i or p_i≥0.5; otherwise it is (G_i−p_i)/p_i. It is undefined when one class occupies the whole landscape.
• Relative patch diversity: (1/Σp_i²)/K, exported as kmeans_patch_diversity_relative or gmm_patch_diversity_relative. It approaches 1 when classes occupy equal proportions and approaches 1/K when one class dominates.
• Pielou evenness: J = H′/ln(K), where H′ = −Σp_iln(p_i). Values near 1 indicate equal class proportions; it is undefined when only one class is present.

User Defined Formulas

• Create custom metrics per polygon at the pixel level. For each formula, provide a name and expression; results are exported as User_{name}.
• Click Read channels to detect the channel names of the selected images. If no image is selected, it reads the channel names of all images.
• Refer to channels by their labels (e.g., R, band1) or with band("label"). Supported math/stat helpers include mean, median, std, min, max, sum, count, exp, log, basic arithmetic symbols (+ - * / ^), comparisons (> < >= <= == !=), and logical operators (and, or, not, &&, ||, !).
• Example: count(R > 0.5 and G < 0.4) counts pixels inside the polygon where both conditions are true.
• Example: (R - G) / (R + G) computes a normalized difference at the pixel level and calcutes the avegare across pixels inside the polygon.

Adding and Organizing Files

• Add files or Add folder to import from disk.
• Imported items appear as thumbnails. You may drag and drop cards to reorder them.
• Important: If the files you added are stored on an external source that requires an internet connection, make sure your connection is stable. An unstable connection may affect the software’s performance.

1) If you chose Stacking images, three tabs are available: Channels, Alignment, and Calibration.

Channels Tab

The Stacking images structure appears as groups of images. Each row represents one group to be treated as a multispectral image. Rows are aligned so each image within a row is handled consistently.

• Within a group, you may reorder (drag and drop) or remove (trash icon) images.
• Between groups, you may reorder (drag and drop) or remove (trash icon) groups.
• You may create a new group.
• Use the settings icon at the bottom to choose whether to use all channels (R, G, B) or let Argiope automatically select a single best channel.
• Specify CWL (center wavelength) and FWHM (full width at half maximum) for every channel. The input accepts numbers (e.g., 450) or labels (e.g., UV). While not strictly required for calibration, accurate interpretation of color metrics depends on correct wavelength values.

Alignment Tab

Aligns images relative to each other so all spectral channels overlap correctly for multispectral composition. There are three options: Feature Matching + Homography, Phase correction or Manual. Automatic alignment works for most cases.