PhenoHUB is a WeChat Mini Program prototype that groups mobile utilities for plant-phenotyping work. The project explores how field measurements, weather queries, image analysis, and AI-assisted research tasks can be made easier to access from a phone.

This article records the January 2026 project snapshot represented by the interface above. It is not a live completeness report, and the presence of a module in the launcher does not by itself establish measurement accuracy or production readiness.

Prototype modules​

Device-orientation measurements​

The leaf-angle utility uses phone motion sensors to display and record device orientation. It can support rapid relative measurements when the phone is aligned consistently with a leaf.

The result should not be described as a precise leaf angle without a defined mounting method, sensor calibration, reference plane, and validation against a trusted instrument. Device model, case geometry, operator alignment, and motion can all affect the reading.

Land-area estimation​

The area utility records a location track and estimates the enclosed polygon. It is useful for reconnaissance and rough field records, but consumer-phone positioning is not survey-grade.

• Accuracy varies with the device, satellite visibility, buildings, trees, and sampling interval.
• Altitude from a phone location service is especially uncertain.
• Boundaries used for contracts, regulation, engineering, or precision operations require suitable survey equipment.

Weather and environmental context​

The agricultural-weather module is designed to query location-based weather information. Values obtained from a weather service describe the provider's grid or station estimate; they are not direct measurements from the phone.

Soil moisture, canopy temperature, light intensity, or other local variables require an explicit data source or external sensor. The interface should always label the provider, observation or forecast time, units, and location.

Image analysis​

The image module provides an entry point for plant-image preprocessing and quantitative analysis. Any reported area, count, color, or shape trait depends on segmentation quality, scale calibration, and acquisition conditions.

Image color alone should not be presented as chlorophyll content without a documented calibration model and independent validation.

Experimental AI assistants​

The prototype includes entries for chart generation and research assistance. These tools can help explore CSV data or draft analytical ideas, but AI output must remain reviewable:

• Charts should be traced back to the exact input rows and transformations.
• Statistical tests require their assumptions and sample structure to be checked.
• Literature, journal, and writing suggestions can be incomplete or incorrect.
• Research data sent to an external model are subject to that provider's privacy terms.

Architecture snapshot​

The mobile client uses the native WeChat Mini Program environment with reusable UI components and Canvas/ECharts-style visualization. Some analysis tasks can be local to the Mini Program, while network-dependent features can call an external API service.

This split keeps lightweight interaction on the phone but creates clear boundaries:

1. Sensor and location permissions should be requested only when the user starts the relevant tool.
2. Local and remote processing must be identified in the interface.
3. Uploaded files and API requests need size limits, failure states, and privacy guidance.
4. Model-generated results should include the provider, model, and generation time when possible.

Appropriate use​

PhenoHUB is most suitable as a prototype for:

• Field notes and rapid exploratory measurements
• Teaching mobile phenotyping concepts
• Testing interaction designs before instrument integration
• Providing one launch point for small research utilities

It should not be treated as a replacement for calibrated scientific instruments, validated statistical software, or a laboratory data-management system.

Access and reproducibility​

The project repository is hosted on WeChat Git and currently requires authenticated access. External readers cannot reliably clone it from a public URL, so this article does not present public installation or contribution steps.

For an internal or authorized deployment, record at least:

• Mini Program revision and backend revision
• Device model and operating-system version
• Permission and calibration procedure
• Weather, map, or AI provider and request time
• Input files, parameters, raw readings, and exported results

Access questions can be directed through the contact channels on the CV page.

Development priorities​

The next useful milestones are evidence-driven rather than percentage-based: validate each measurement against a reference method, label experimental modules clearly, add provenance to exports, document privacy boundaries, and test the complete workflow on both iOS and Android devices.

Botanical Extract AI Pro explores whether a multimodal image model can reduce background clutter in plant photographs without project-specific model training. It provides an interactive web workflow for individual images and a Node.js-oriented workflow for repeated processing.

This is best described as AI-assisted background isolation, not validated scientific segmentation. A generative model may redraw leaves, remove thin structures, change colors, or invent boundaries even when the prompt asks it not to.

Workflow​

The two clients follow the same basic path:

1. Load an image and decode it to confirm the format and dimensions.
2. Select the closest aspect ratio supported by the chosen model API.
3. Send the image and a constrained background-replacement instruction to the provider.
4. Save the returned image beside the untouched original.
5. Record the provider, model, prompt version, time, and processing outcome.

The web interface supports visual comparison for a single sample. The batch workflow scans a directory, mirrors its structure in an output directory, and records successes and failures.

What the prompt can and cannot do​

A prompt can request a white background and ask the model to preserve the plant. It cannot force a generative system to retain the original pixels. Statements such as “pixel-perfect” are therefore instructions to the model, not guarantees about the result.

Aspect-ratio matching is similarly limited. Choosing the nearest supported ratio can reduce avoidable cropping or stretching in the API request, but it does not guarantee identical geometry or resolution in the generated image.

Input validation​

File extensions alone are not sufficient validation. A safer client should:

• Check the binary signature and successfully decode the image
• Enforce file-size and pixel-dimension limits
• Reject unsupported or malformed data
• Normalize orientation without silently discarding the original
• Keep provider payloads separate from local metadata

The current Base64-style request pattern loads the image into memory. It should not be described as streaming, and large inputs need explicit limits.

Bounded batch processing​

Promise.allSettled(files.map(processFile)) does not control concurrency; it schedules every task immediately. A production batch client should place a small limit around the provider call:

import pLimit from 'p-limit';

const limit = pLimit(3);

const results = await Promise.allSettled(
  files.map((file) => limit(() => processOneImage(file))),
);

The processing function should also use capped exponential backoff for retryable 429 and 5xx responses, stop retrying permanent errors, and write a resumable manifest. Concurrency must be adjusted to the provider's documented limits and the available memory.

Scientific quality control​

Generated outputs should not be used directly for leaf area, shape, disease, growth, or time-series measurements without validation. A practical review should include:

1. Overlay the source and output at the same scale.
2. Inspect thin stems, leaf tips, holes, flowers, labels, and pot boundaries.
3. Check whether colors, shadows, or plant geometry changed.
4. Compare a manually annotated validation subset with appropriate mask and boundary metrics.
5. Reject or manually correct failed samples before quantitative analysis.

For measurements that require a reproducible binary mask, a conventional segmentation model or a validated interactive segmentation tool is usually more appropriate than image generation.

Privacy, cost, and reproducibility​

Unless a local model is used, uploaded images leave the device and are processed by an external provider. Before processing research data:

• Review the provider's retention and training policies.
• Remove sensitive labels, locations, and personal information.
• Store API keys in server-side or environment configuration, never in public client code.
• Estimate per-image cost and rate limits before starting a batch.
• Preserve the original files and a machine-readable processing manifest.

Current limitations​

• No public benchmark currently establishes accuracy across species, organs, backgrounds, or imaging conditions.
• Results may vary across model versions and repeated requests.
• The workflow produces an edited image, not necessarily an alpha mask or class-labeled segmentation.
• Large-scale processing requires bounded concurrency, recovery logs, and manual quality assurance.
• The project should not be described as open source unless a public repository and license are provided.

The project remains useful as a prototype for rapid visual cleanup and for studying how multimodal models behave on botanical imagery. Its outputs should be treated as generated derivatives, not as ground truth.

MCTP (Multi-Modal Crop Phenotyping Platform) is a desktop data-processing workspace developed alongside a field phenotyping collaboration with Shufeng Bio. My contribution focused on system optimization and the data-processing and analysis workflows.

The interface brings hyperspectral, LiDAR, RGB, and thermal tools into one launcher. In this project snapshot, “unified” means a consistent entry point, interaction pattern, and export convention. It does not mean that the four modalities are automatically registered, fused, or interpreted by one model.

Current module scope​

Hyperspectral processing​

The hyperspectral workflow is designed around paired ENVI files and wavelength metadata. Its project implementation includes:

• HDR/SPE ingestion and wavelength parsing
• RGB quicklooks and vegetation-index views
• Threshold-based plant masks and glare filtering
• Mean-spectrum and summary exports in CSV/JSON form
• Directory-level processing for compatible datasets

Index values and masks depend on valid radiometric metadata and suitable thresholds. They should be inspected before downstream statistical analysis.

LiDAR processing​

The LiDAR module groups common point-cloud preparation and trait-extraction operations:

• PLY, LAS, LAZ, and text-file input
• Ground rebasing, voxel downsampling, cropping, and height coloring
• DBSCAN-based clustering with interactive parameter tuning
• Coverage, height percentiles, occupancy, and convex-hull summaries
• Cropped point-cloud and JSON report export

These outputs are algorithmic estimates. Ground selection, point density, occlusion, and clustering parameters can materially change the result.

RGB processing​

The RGB workflow combines color-index thresholding with morphology and connected-component operations. The project implementation uses ExG, CIVE, and VDI features, then applies cleanup and instance-labeling steps for group-level and per-plant summaries.

This classical computer-vision approach is transparent and tunable, but it is sensitive to illumination, reflections, labels, soil color, and overlapping plants. A representative subset should be checked before batch processing.

Thermal processing​

The thermal workflow pairs image and temperature-matrix inputs, then provides threshold and morphology controls with overlay, heatmap, and plant-only previews. Depending on the module build, outputs can include images, arrays, tables, and JSON summaries.

Temperature values are only meaningful when the camera export, orientation, calibration, and environmental assumptions are correct.

Recommended workflow​

1. Archive raw data first. Keep the original files and acquisition metadata unchanged.
2. Open one representative sample. Confirm file pairing, orientation, units, and coordinate conventions.
3. Tune parameters visibly. Use previews to identify failure cases instead of relying on defaults.
4. Process a small batch. Check outputs against the raw data before scaling up.
5. Record the configuration. Save thresholds, voxel sizes, clustering settings, and software version with the results.

Boundaries of the platform​

The available project snapshot should be treated as a collection of modality-specific processing tools, not as an autonomous scientific interpretation system.

• Cross-modal registration and temporal analysis are not current automatic capabilities.
• Batch behavior differs by module; interactive tuning remains important for LiDAR and thermal data.
• Structured exports improve handoff to R, Python, or other statistics tools, but they do not replace quality control.
• No cloud processing service is documented in this snapshot.
• Reproducibility requires the raw data, module version, parameters, calibration information, and exported results to be stored together.

Next development priorities​

Potential future work includes shared project configuration files, explicit provenance records, cross-modal registration, and validated temporal analysis. These are development directions rather than claims about the current release.

Leaf surfaces do not reflect light uniformly. Their anatomy, pigments, and microscopic roughness change how radiation is scattered through a canopy, yet many canopy models use simplified optical inputs.

This study combines a custom Directional Spectrum Detection Instrument (DSDI), Cook–Torrance bidirectional reflectance distribution function (BRDF) fitting, phenotypic measurements, and ensemble learning. The goal is to estimate leaf optical parameters from traits that are easier to measure and then examine how those parameters affect simulated canopy light distribution.

At a glance​

• Plant material: maize, rice, cotton, and poplar leaves from upper and lower canopy positions.
• Directional spectra: 400–1000 nm, measured across a broad angular range with the DSDI.
• BRDF parameters: roughness $\sigma(\lambda)$, diffuse reflection coefficient $k(\lambda)$, and refractive index $n(\lambda)$.
• Predictive model: a stacking ensemble built from support vector, random forest, and gradient boosting regressors.
• Reported performance: BRDF fitting $R^2 > 0.95$; ensemble prediction $R^2 = 0.83$–$0.99$, depending on the parameter.

Measurement and modeling workflow​

1. Measure directional reflectance​

The DSDI uses a xenon light source, a fiber spectrometer, and mechanically controlled illumination and viewing angles. A Lambertian white reference is used to calibrate reflectance before leaf measurements.

Both adaxial and abaxial leaf surfaces were measured. This matters because the two surfaces differ in epidermal structure and optical response.

2. Fit the BRDF model​

The Cook–Torrance formulation represents diffuse and specular reflection with three wavelength-dependent parameters:

Adaptive grid search and least-squares optimization were used to fit these parameters to the measured directional spectra.

3. Predict optical parameters from traits​

The input variables included leaf thickness, specific leaf weight, pigment measurements, microscopy-derived surface roughness, and wavelength. The stacking model combines:

• Support Vector Regression (SVR)
• Random Forest Regression (RFR)
• Gradient Boosting Regression Trees (GBRT)
• Linear regression as the meta-learner

The resulting model provides a direct, data-driven link between measured phenotypic traits and BRDF parameters within the study domain.

4. Test canopy-scale consequences​

Predicted BRDF parameters were introduced into a rice-canopy ray-tracing workflow based on fastTracer. The simulations show that changing roughness, diffuse reflection, or refractive behavior can alter the vertical and angular distribution of light inside a canopy.

What the results support​

The study supports three practical conclusions:

1. Directional leaf reflectance can be represented accurately with a physically based BRDF model.
2. Structural and biochemical leaf traits contain useful information for predicting BRDF parameters.
3. Leaf optical diversity can materially change simulated canopy light fields and should not always be treated as uniform.

These results provide a route for connecting leaf-scale phenotyping to radiative-transfer and canopy-photosynthesis models.

Scope and limitations​

The model was developed from 270 data entries spanning four species, two canopy positions, and both leaf surfaces. It is therefore a research model, not a universal estimator for every crop, genotype, environment, or stress treatment.

• Predictions outside the measured trait and wavelength ranges require new validation.
• The ray-tracing results demonstrate changes in simulated light distribution; they do not by themselves demonstrate yield gains in the field.
• Direct optical measurement remains important when working with new species or when high-accuracy optical parameters are required.
• Future datasets should cover more genotypes, environments, developmental stages, and water-status conditions.

Code and data availability​

• BRDF fitting scripts and Roughness Calculator
• fastTracer canopy ray-tracing software
• The study data are available from the corresponding author upon reasonable request, as stated in the published article.

Citation​

Deng, L., Yu, L. X., Mao, L., Wang, Y., Guo, X., Wang, M., Zhang, Y., Song, Q., & Zhu, X.-G. (2025). Leaf bidirectional reflectance distribution function (BRDF) prediction with phenotypic traits in four species: Development of a novel measuring and analyzing framework. Plant Phenomics, 7(4), 100135. https://doi.org/10.1016/j.plaphe.2025.100135

This guide begins with a local assistant, then adds retrieval and optional tool use one boundary at a time. Each new capability should be observable, reversible, and no more privileged than the task requires.

Assistant, RAG system, or agent?​

An interactive chat with Ollama is a local assistant. Call it an agent only after adding an explicit action loop, tool contracts, state, stopping conditions, and authorization controls.

1. Write the deployment boundary first​

Document these decisions before installation:

• Which data classifications may enter prompts?
• Must the system work with the network disabled?
• Which users and devices may access it?
• Which tools are read-only, and which can change files or external systems?
• Which actions require confirmation?
• What is logged, for how long, and who can read it?
• How will model, prompt, index, and tool versions be identified?
• What is the rollback and incident-response path?

“Local model” describes where inference runs. It does not answer these system-level questions.

2. Start with Ollama on localhost​

Install Ollama from the official download page. Where the shell installer is supported:

curl -fsSL https://ollama.com/install.sh | sh

Select a current model from the official library that fits the available memory and license requirements, then replace <model-name>:

ollama pull <model-name>
ollama run <model-name>
ollama list

Test the local chat API:

import requests

response = requests.post(
    "http://localhost:11434/api/chat",
    json={
        "model": "<model-name>",
        "messages": [
            {
                "role": "user",
                "content": "Summarize this experiment plan in five bullets.",
            }
        ],
        "stream": False,
    },
    timeout=120,
)
response.raise_for_status()
print(response.json()["message"]["content"])

Install the only additional dependency used by this example:

python -m venv .venv
source .venv/bin/activate
python -m pip install requests
python -m pip freeze > requirements-lock.txt

Keep the service on localhost while testing. Confirm listening interfaces with operating-system network tools before assuming it is private.

3. Record the environment portably​

This Python report works across major desktop platforms without Linux-only commands such as free or nproc:

import json
import os
import platform
import shutil

report = {
    "platform": platform.platform(),
    "python": platform.python_version(),
    "cpu_count": os.cpu_count(),
    "ollama_path": shutil.which("ollama"),
    "docker_path": shutil.which("docker"),
}

try:
    import torch

    report["torch"] = torch.__version__
    report["cuda_available"] = torch.cuda.is_available()
    if torch.cuda.is_available():
        report["gpu"] = torch.cuda.get_device_name(0)
except ImportError:
    report["torch"] = None

print(json.dumps(report, indent=2))

Memory requirements depend on model, quantization, context, parallel requests, and runtime overhead. Benchmark the chosen artifact on the actual machine rather than labeling all 7B or 13B models with one hardware threshold.

4. Add retrieval without hiding provenance​

A maintainable local RAG pipeline has five explicit stages:

1. Ingest: allowlisted files are parsed; unsupported or encrypted files fail visibly.
2. Chunk: document structure and stable identifiers are preserved.
3. Embed: the exact embedding model and revision are recorded.
4. Retrieve: candidate chunks include source, page or section, score, and index version.
5. Generate: the prompt instructs the model to answer from evidence and cite retrieved sources.

Keep the original document identifier in every chunk. Evaluate retrieval separately from answer generation: if the relevant passage is not retrieved, changing the final prompt cannot repair the evidence gap.

Minimal evaluation set​

Create questions with expected source passages and include:

• answerable questions;
• questions whose answer is absent;
• conflicting documents;
• superseded versions;
• tables, captions, and long sections;
• adversarial text embedded inside a document.

Measure retrieval recall, citation correctness, unsupported-claim rate, latency, and behavior when evidence is missing.

5. Add tools through narrow contracts​

Do not give a model a general shell, unrestricted filesystem, or broad API token as the first tool. Wrap each capability in a small typed function.

from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True)
class ReadTextRequest:
    relative_path: str


def read_project_text(request: ReadTextRequest, workspace: Path) -> str:
    root = workspace.resolve()
    target = (root / request.relative_path).resolve()

    if root not in target.parents:
        raise ValueError("Path escapes the approved workspace")
    if target.suffix.lower() not in {".md", ".txt", ".csv"}:
        raise ValueError("File type is not allowed")
    if target.stat().st_size > 1_000_000:
        raise ValueError("File exceeds the read limit")

    return target.read_text(encoding="utf-8")

This example is read-only and workspace-scoped. A production tool still needs structured error handling, audit identifiers, denial tests, and protection against symbolic-link and race-condition edge cases.

For every tool, define:

• an input schema and size limits;
• authentication context and least-privilege credentials;
• allowed resources and denied paths;
• timeout, retry, and idempotency behavior;
• a preview for consequential actions;
• user confirmation rules;
• a structured, redacted audit event;
• a deterministic stop condition.

Treat retrieved text, webpages, emails, and documents as untrusted data. They can contain instructions designed to manipulate the model.

6. Control the agent loop​

A safe loop should be bounded by design:

receive request
  → classify data and permissions
  → propose a plan
  → choose one allowlisted tool
  → validate arguments
  → request confirmation when required
  → execute with timeout
  → record a redacted result
  → stop, or continue within a strict step budget

Set limits for steps, wall time, tokens, tool calls, file volume, and retries. The model must not be able to increase its own limits or grant itself new tools.

7. Secure the service before sharing it​

Minimum controls for any networked deployment include:

• bind only to the intended interface;
• authenticate users and authorize each tool separately;
• generate secrets outside source code and fail closed when missing;
• use TLS across untrusted networks;
• set request, context, concurrency, and rate limits;
• keep document stores and vector databases off public ports;
• redact prompts, documents, credentials, and personal data from logs;
• separate model execution from privileged tools;
• scan dependencies and pin container images by version or digest;
• back up indexes and configuration with tested restore procedures;
• provide a kill switch and revoke credentials after an incident.

Character blacklists are not a defense against prompt injection. Likewise, a default JWT secret such as your-secret-key turns a configuration error into an authentication bypass.

Docker and GPU notes​

A CPU Python base image does not gain CUDA support merely because a Compose file reserves a GPU. Use an inference image documented for the target runtime and driver, or keep Ollama outside the application container and call its restricted local endpoint.

Do not expose an unauthenticated vector database, model API, or development UI. Avoid latest image tags in a reproducible deployment. Follow current Docker installation guidance and NVIDIA container documentation rather than copying an old apt-key or nvidia-docker2 setup script.

Operational tests​

Before allowing real research data, test:

• service restart during a request;
• malformed and oversized inputs;
• prompt injection in retrieved documents;
• tool arguments that escape the allowlist;
• missing secrets and expired credentials;
• unreachable model or vector store;
• concurrent requests near the resource limit;
• cancellation and timeout behavior;
• restoration from backup;
• model or index rollback.

Record failure outcomes, not only successful demonstrations.

Reproducibility manifest​

{
  "runtime": "Ollama",
  "runtime_version": "<version>",
  "model": "<model-name>",
  "model_digest": "<digest>",
  "prompt_version": "assistant-v1",
  "embedding_model": "<model-and-revision>",
  "index_version": "documents-2026-07-16",
  "tool_policy_version": "read-only-v1",
  "network_mode": "localhost-only",
  "evaluation_set": "local-agent-eval-v1"
}

Store this record with evaluation results and deployment configuration.

Related App Lab tool​

Multimodal AI Solver is a browser client for user-supplied AI-provider credentials and multimodal requests. Its tutorial describes provider, model, browser-permission, screen-capture, and privacy boundaries. It is not a local offline model runtime.

Final checklist​

• Local assistant works before retrieval or tools are added
• Network behavior has been observed and documented
• Model and dependency versions are pinned
• Retrieval citations are evaluated
• Tools are narrow and least-privileged
• Consequential actions require confirmation
• Agent loop has hard budgets and a stop condition
• Secrets fail closed and never use a default value
• Logs are redacted and access-controlled
• Rollback and kill-switch procedures are tested

Workflow reviewed: July 2026. Re-check Ollama, container-runtime, and framework documentation before deployment.

The workflow below deliberately requires an explicit image scale. If scale calibration fails, it is safer to report pixels than to invent millimetres.

Appropriate use​

This workflow assumes:

• samples are physically separated;
• the background is mostly uniform and visible in the image corners;
• the camera is approximately perpendicular to the sample plane;
• a known-length reference lies in the same plane as the samples;
• lens distortion and perspective are negligible or corrected;
• the intended traits can be approximated from a two-dimensional silhouette.

It is not appropriate for tangled roots, dense canopies, overlapping leaves, uncontrolled field scenes, or organs whose three-dimensional curvature is central to the measurement.

Measurement plan​

Before writing code, define each output:

These are image descriptors. For example, minimum-rectangle length is not automatically equivalent to botanical leaf length along a curved midrib.

1. Capture controlled images​

1. Use diffuse, stable illumination and a matte background with strong contrast.
2. Keep camera distance, focal length, exposure, white balance, and orientation fixed.
3. Place a calibrated reference in the sample plane, not above or below it.
4. Avoid touching or overlapping samples.
5. Preserve the original image and metadata.
6. Photograph an empty background and known-size validation objects during each session.

If color is an outcome, use a color target and a controlled color-management workflow. Camera RGB values are device- and illumination-dependent.

2. Calculate scale explicitly​

Measure the visible reference span in pixels using a reviewed image or calibration tool:

pixels_per_mm = reference_length_pixels / reference_length_mm

For example, a 25 mm marker spanning 310 pixels gives 12.4 px/mm. Record how endpoints were selected. Do not fall back to an arbitrary constant when the marker is missing or ambiguous.

For higher-accuracy work, calibrate lens distortion and estimate a planar transform from multiple reference points rather than relying on one length.

3. Install a minimal environment​

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install opencv-python numpy pandas
python -m pip freeze > requirements-lock.txt

On Windows, activate with .venv\Scripts\activate.

4. Run a compact reference implementation​

Save the following as quantify_samples.py. It estimates the background from the image corners, applies Otsu thresholding to color distance, filters small connected components, and exports both a CSV and an overlay.

import argparse
from pathlib import Path

import cv2
import numpy as np
import pandas as pd


def foreground_mask(image_bgr: np.ndarray) -> np.ndarray:
    height, width = image_bgr.shape[:2]
    border = max(2, min(height, width) // 20)
    lab = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2LAB)

    corners = [
        lab[:border, :border],
        lab[:border, -border:],
        lab[-border:, :border],
        lab[-border:, -border:],
    ]
    corner_pixels = np.vstack([block.reshape(-1, 3) for block in corners])
    background = np.median(corner_pixels, axis=0)

    distance = np.linalg.norm(lab.astype(np.float32) - background, axis=2)
    distance_8bit = cv2.normalize(
        distance, None, 0, 255, cv2.NORM_MINMAX
    ).astype(np.uint8)
    _, mask = cv2.threshold(
        distance_8bit, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU
    )

    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (3, 3))
    mask = cv2.morphologyEx(mask, cv2.MORPH_OPEN, kernel)
    return cv2.morphologyEx(mask, cv2.MORPH_CLOSE, kernel)


def quantify(image_path: Path, px_per_mm: float, min_area: int) -> None:
    if px_per_mm <= 0:
        raise ValueError("--px-per-mm must be a measured positive value")

    image = cv2.imread(str(image_path))
    if image is None:
        raise FileNotFoundError(f"Could not read {image_path}")

    mask = foreground_mask(image)
    count, labels, stats, _ = cv2.connectedComponentsWithStats(mask)
    overlay = image.copy()
    rows = []

    for label in range(1, count):
        area_px = int(stats[label, cv2.CC_STAT_AREA])
        if area_px < min_area:
            continue

        component = np.where(labels == label, 255, 0).astype(np.uint8)
        contours, _ = cv2.findContours(
            component, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE
        )
        if not contours:
            continue

        contour = max(contours, key=cv2.contourArea)
        perimeter_px = float(cv2.arcLength(contour, True))
        (_, _), (side_a, side_b), angle = cv2.minAreaRect(contour)
        length_px, width_px = max(side_a, side_b), min(side_a, side_b)
        mean_b, mean_g, mean_r, _ = cv2.mean(image, mask=component)

        sample_id = f"S{len(rows) + 1}"
        rows.append(
            {
                "id": sample_id,
                "area_px": area_px,
                "perimeter_px": round(perimeter_px, 2),
                "length_mm": round(length_px / px_per_mm, 3),
                "width_mm": round(width_px / px_per_mm, 3),
                "area_mm2": round(area_px / px_per_mm**2, 3),
                "circularity": round(
                    4 * np.pi * area_px / max(perimeter_px**2, 1e-9), 4
                ),
                "angle_deg": round(float(angle), 2),
                "mean_r": round(mean_r, 1),
                "mean_g": round(mean_g, 1),
                "mean_b": round(mean_b, 1),
            }
        )

        box = np.intp(cv2.boxPoints(cv2.minAreaRect(contour)))
        cv2.drawContours(overlay, [contour], -1, (255, 120, 0), 2)
        cv2.drawContours(overlay, [box], -1, (0, 210, 255), 2)
        x, y, _, _ = cv2.boundingRect(contour)
        cv2.putText(
            overlay,
            sample_id,
            (x, max(20, y - 8)),
            cv2.FONT_HERSHEY_SIMPLEX,
            0.6,
            (20, 20, 20),
            2,
            cv2.LINE_AA,
        )

    result = pd.DataFrame(rows)
    csv_path = image_path.with_name(f"{image_path.stem}_measurements.csv")
    overlay_path = image_path.with_name(f"{image_path.stem}_overlay.png")
    result.to_csv(csv_path, index=False)
    cv2.imwrite(str(overlay_path), overlay)
    print(f"Detected {len(result)} components")
    print(f"Wrote {csv_path} and {overlay_path}")


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("image", type=Path)
    parser.add_argument("--px-per-mm", type=float, required=True)
    parser.add_argument("--min-area", type=int, default=500)
    args = parser.parse_args()
    quantify(args.image, args.px_per_mm, args.min_area)

Run it with the measured scale:

python quantify_samples.py samples.jpg --px-per-mm 12.4 --min-area 500

The script does not automatically identify or exclude the calibration object. Crop it out before analysis or remove its component only after checking the overlay and documenting the rule.

5. Review before accepting numbers​

For every batch:

1. Compare the overlay with the original at full resolution.
2. Confirm the expected number of biological samples.
3. Reject components formed by shadows, labels, marker objects, or merged samples.
4. Repeat the scale measurement and report inter-operator variation.
5. Measure a blinded validation subset manually.
6. Report error and confidence intervals in physical units.
7. Test a second acquisition session before claiming generalization.

Save exclusions rather than silently deleting them.

Interpretation boundaries​

• Downsampling or image compression can change contours and small structures.
• Otsu thresholding assumes separable foreground and background distributions.
• A rotated rectangle overestimates or misrepresents strongly curved samples.
• Perimeter and circularity are highly sensitive to boundary noise.
• Two-dimensional projected area is not total leaf or organ surface area.
• Mean RGB is not a calibrated spectral measurement or a validated vegetation index.
• The same settings may fail after changes in lighting, camera, background, crop, or growth stage.

Related browser tool​

Biological Sample Quantifier provides a browser entry point to a hosted image-analysis service. Review its App Lab tutorial, service status, upload limits, and external-processing privacy boundary before sending research images.

Reference implementation reviewed: July 2026. Validate it with your own acquisition protocol before scientific use.

This guide provides a publisher-neutral workflow. Exact status labels, DOI timing, accepted-manuscript policies, and indexing practices vary by journal, so always follow the current instructions for the selected venue.

Publication workflow​

1. Define the contribution before choosing a journal​

Write one sentence for each item:

• Problem: What unresolved question or practical limitation is addressed?
• Evidence: What observations, experiments, simulations, or analyses answer it?
• Contribution: What becomes possible or better understood because of the work?
• Boundary: Where should the conclusion not be generalized?

Choose the paper type that matches the evidence: research article, methods paper, data paper, software paper, brief report, perspective, or review. A new tool without validation is not automatically a methods contribution, and a large dataset without adequate documentation is not automatically reusable.

2. Select a journal by fit and trustworthiness​

Start with scope and audience rather than a single metric.

Impact Factor can describe a journal-level citation pattern; it does not measure the quality of an individual paper. Avoid journals that guarantee acceptance, imitate another journal's identity, conceal fees, or provide unverifiable editorial information.

3. Build a reproducible manuscript package​

Most empirical papers use an IMRaD-like structure, but the journal's author guide takes precedence.

Prepare the manuscript together with its supporting artifacts:

• figures and tables with units, sample sizes, uncertainty, and accessible labels;
• data dictionary and analysis-ready data where sharing is permitted;
• source code, environment information, and an executable workflow;
• author contributions using a consistent taxonomy such as CRediT;
• funding, conflicts of interest, ethics approvals, and consent statements;
• data and code availability statements;
• reporting checklist required by the field;
• disclosure of any generative-AI use according to journal policy.

Vector formats are useful for diagrams and plots when accepted, while raster images should meet the journal's dimensions, color mode, and resolution requirements. “300 dpi” alone is not a universal rule for every figure type.

4. Perform a pre-submission audit​

• Title and abstract match the actual evidence.
• Every stated objective is answered in the Results and Discussion.
• Sample counts are consistent across text, tables, figures, and supplements.
• Statistical units match the experimental design.
• Code reproduces the final figures and tables from the archived inputs.
• References are complete and checked against primary sources.
• All authors approve the manuscript and author order.
• Permissions are available for reused material.
• The manuscript is not simultaneously submitted elsewhere.
• The journal's formatting and policy checklist is complete.

Reference managers such as Zotero or EndNote can reduce formatting work, but imported metadata still needs human verification.

5. Submit a complete, consistent record​

Submission portals differ, but commonly request:

Save the submitted PDF, source files, metadata, cover letter, and manuscript ID together. Check the generated submission PDF before final confirmation; conversion can alter equations, fonts, line breaks, and figure order.

6. Interpret editorial statuses cautiously​

Status names are publisher-specific. The following table describes common patterns, not universal rules.

Volume, issue, page range, article number, DOI assignment, online publication, and database indexing do not always occur at the same time. Verify the article record instead of inferring its state from one label.

7. Respond to reviewers point by point​

A useful response document is easy to navigate and separates the reviewer's text, the response, and the exact manuscript change.

Reviewer 1, Comment 3
[Paste the complete comment]

Response
Thank you for identifying this ambiguity. We now define the biological
replicate before the statistical model and have rerun the analysis at the
plot level.

Change in manuscript
Methods, Section 2.4: “The plot, rather than an individual image, was
treated as the biological replicate ...”

When declining a suggestion, explain the scientific or practical reason and, when possible, add a limitation or alternative analysis. Do not claim a change was made if only the response letter changed.

8. Check proofs and the version of record​

During production, verify:

• title, author names, affiliations, and corresponding-author details;
• equations, symbols, units, and special characters;
• figure resolution, labels, captions, and color interpretation;
• table rows, footnotes, and supplementary links;
• funding, ethics, data, and code statements;
• references and DOI links.

Proof correction is not normally a second opportunity to redesign the study. If a substantive error is discovered, contact the production editor transparently.

9. Cite the actual publication state​

Use the metadata available for the version being cited and follow the required style. Do not invent a DOI, issue, or year for an accepted manuscript.

An updated APA-style reference for the example paper is:

Deng, L., Yu, L. X., Mao, L., Wang, Y., Guo, X., Wang, M., Zhang, Y., Song, Q., & Zhu, X.-G. (2025). Leaf bidirectional reflectance distribution function (BRDF) prediction with phenotypic traits in four species: Development of a novel measuring and analyzing framework. Plant Phenomics, 7(4), 100135. https://doi.org/10.1016/j.plaphe.2025.100135

The DOI is the durable link: https://doi.org/10.1016/j.plaphe.2025.100135.

10. Maintain the research record​

After publication:

1. Deposit the permitted manuscript version according to the journal policy.
2. Update ORCID, institutional profiles, Google Scholar, Web of Science Researcher Profile, and the personal website.
3. Release data and code at the promised persistent locations.
4. Create a tagged software release matching the paper.
5. Monitor repository issues and document known limitations.
6. Correct material errors promptly through the appropriate journal mechanism.
7. Preserve the analysis environment and provenance needed to reproduce the figures.

Journal-analysis workbook​

The accompanying workbook is a personal comparison aid, not an authoritative or permanently current ranking. Journal metrics, fees, scope, and review practices change; verify every decision on the official journal site.

Download the journal-analysis workbook (.xlsx)

Final checklist​

Define the contribution → select by fit → preserve provenance → write from evidence → submit consistently → respond transparently → verify the record → maintain artifacts.

Citation of this guide

Deng, L. (2025). From manuscript to publication: A practical guide for researchers. Digital Crop Photosynthesis Phenotyping Platform.

Content reviewed and bibliographic example updated: July 2026.

It is not a calibrated reconstruction system by default. A single image does not observe the back of a plant, an absolute scale, or structures hidden by leaves. The model must infer those regions, so its output cannot be treated as measured plant height, leaf area, branch count, or organ geometry without independent validation.

Scope and version​

This guide documents the public Hunyuan3D-1 workflow so an older experiment can be reproduced. It deliberately does not invent a generic Transformers API: Hunyuan3D-1 uses its own repository, weight layout, environment scripts, and main.py entry point.

Check the upstream Hunyuan3D-1 repository and Hugging Face model card before installation. Newer Hunyuan3D releases have different code and hardware requirements; do not mix commands between generations.

1. Decide whether the method fits the question​

2. Prepare an auditable input set​

For each plant image, retain:

• the untouched original and metadata;
• species or genotype and growth stage, if authorized for release;
• camera and lighting information;
• a background-removal method and its version;
• an image identifier that links generated assets to source data;
• consent and license information for any non-original images.

Use a simple background with the complete visible plant in frame. Background removal may improve conditioning, but it does not reveal occluded organs or create metric scale.

Create a small pilot set first. Include easy examples, dense canopies, thin leaves, overlapping organs, and images from species not represented in the development set.

3. Install the official Hunyuan3D-1 workflow​

The commands below mirror the upstream project structure. They assume Linux with a compatible NVIDIA environment; choose the PyTorch build that matches the installed driver and CUDA runtime.

git clone https://github.com/tencent/Hunyuan3D-1
cd Hunyuan3D-1

conda create -n hunyuan3d-1 python=3.10
conda activate hunyuan3d-1
which python
which pip

# Install the compatible PyTorch build first, following pytorch.org.
bash env_install.sh
python -m pip install "huggingface_hub[cli]"

Download the official weights into the layout expected by the repository:

mkdir -p weights
huggingface-cli download tencent/Hunyuan3D-1 --local-dir ./weights

mkdir -p weights/hunyuanDiT
huggingface-cli download Tencent-Hunyuan/HunyuanDiT-v1.1-Diffusers-Distilled \
  --local-dir ./weights/hunyuanDiT

Record the Git commit and downloaded model revisions:

git rev-parse HEAD
huggingface-cli env
python -m pip freeze > environment-lock.txt

The complete pipeline is GPU-intensive. Consult the upstream model card for the current standard, lite, split-pipeline, and memory-saving options. A successful Open3D installation or a random point-cloud visualization does not demonstrate that Hunyuan3D inference will run.

4. Generate one image-conditioned asset​

Run the repository entry point instead of calling nonexistent methods such as AutoModel.generate_point_cloud:

python3 main.py \
  --image_prompt "/absolute/path/to/plant.png" \
  --save_folder ./outputs/plant-001/ \
  --max_faces_num 90000 \
  --do_texture_mapping \
  --do_render

Start with one image and inspect the entire output directory before attempting a batch. Save the command, random seed, runtime, peak GPU memory, warnings, and failure status for every sample.

The primary output is a generated mesh and render assets, not a measured point cloud. If a downstream application requires points, sample them from the mesh while preserving that provenance:

import open3d as o3d

mesh = o3d.io.read_triangle_mesh("generated_mesh.obj")
if mesh.is_empty():
    raise ValueError("The generated mesh could not be loaded")

mesh.compute_vertex_normals()
points = mesh.sample_points_poisson_disk(number_of_points=100_000)
o3d.io.write_point_cloud("generated_mesh_sampled.ply", points)

Replace generated_mesh.obj with the actual output filename. Sampling a mesh creates a point representation of the same generated surface; it does not make the geometry more accurate.

5. Evaluate plant outputs honestly​

Visual quality review​

Score predefined criteria instead of selecting only attractive outputs:

• silhouette consistency with the visible image;
• missing, duplicated, fused, or disconnected organs;
• stem and branch continuity;
• texture leakage and background artifacts;
• plausibility of the inferred back side;
• stability across seeds and small image perturbations.

Geometric validation​

If the research claim concerns geometry, collect an independently scaled reference for the same specimen. Align only with a documented procedure, then report:

• the number of successful and failed generations;
• scale and registration method;
• surface or point distance with units;
• trait error for each biological unit;
• performance by species, growth stage, and occlusion level;
• sensitivity to seed, crop, background, and input view;
• confidence intervals or repeated-run variability.

Do not report benchmark numbers unless the dataset, split, baseline, code, and evaluation definition are available.

6. Reproducibility record​

Save a manifest such as:

{
  "sample_id": "plant-001",
  "source_image": "plant-001.png",
  "repository_commit": "<git-commit>",
  "model_revision": "<model-revision>",
  "seed": 0,
  "command": "python3 main.py ...",
  "status": "success",
  "intended_use": "exploratory visualization",
  "metric_validation": false
}

Store failed generations too. Excluding them after inspection produces a misleading estimate of robustness.

Known limitations​

• Invisible and occluded geometry is inferred rather than observed.
• Generated assets do not contain an automatic physical scale.
• Thin leaves, petioles, branching junctions, and repeated textures are difficult cases.
• A visually plausible mesh can still be geometrically wrong.
• Output quality may vary with segmentation, background, seed, and input view.
• Training-data coverage and species-specific generalization are not established by a few examples.
• Model and code licenses must be checked for the intended research or commercial use.

When to choose another method​

Use multi-view SfM for an image-based geometric reconstruction with camera calibration and scale. Use structured light, depth cameras, or laser scanning when reference geometry and repeatable measurements are the priority. Use Hunyuan3D when the research question is specifically about generative 3D behavior or when a clearly labeled synthetic visualization is appropriate.

Workflow reviewed: July 2026 for Hunyuan3D-1 documentation. Upstream commands and model availability may change.

This article presents a practical workflow built around Cross-Circular Oblique (CCO) acquisition and Structure from Motion (SfM). It distinguishes geometric measurements from visualization products and avoids treating every 3D representation as a calibrated phenotype.

Workflow at a glance​

1. Design acquisition around the trait​

A Cross-Circular Oblique flight path collects oblique views around sampling locations or plots. The changing azimuth improves view diversity around complex canopies, while an additional grid or cross-hatch flight can provide more uniform coverage and strengthen the spatial frame.

Before defining waypoints, specify:

• the biological unit: plant, row, plot, or field;
• the smallest structure that must remain visible;
• the required ground sampling distance;
• the expected canopy height and safe clearance;
• camera focal length, focus, shutter speed, and image interval;
• overlap targets appropriate to the scene and software;
• wind, illumination, battery, and legal operating limits;
• ground control points (GCPs), RTK/PPK strategy, or another source of scale.

There is no universal altitude, radius, camera pitch, or overlap setting. Validate a small pilot block before committing to a field campaign.

The browser-based CCO Waylines Builder can turn a KML boundary into previewable DJI-compatible KML, WPML, and KMZ planning files. Its tutorial explains the current export and compatibility boundaries.

2. Control image quality in the field​

Photogrammetry cannot recover detail that is consistently blurred, saturated, occluded, or absent.

1. Use manual or locked exposure where practical so brightness does not jump between adjacent frames.
2. Prefer a shutter speed that limits motion blur from both aircraft motion and wind-driven leaves.
3. Verify focus before each flight block.
4. Avoid abrupt illumination changes when possible; record cloud and wind conditions.
5. Check representative images at full resolution before leaving the site.
6. Preserve original files and metadata. Do not resize, sharpen, or re-encode the only copy.

Record the aircraft, payload, lens, image dimensions, mission geometry, timestamps, coordinate system, weather, and any interrupted flight.

3. Build the spatial reference​

Multi-view images can be aligned and orthorectified to create an orthomosaic, digital surface model (DSM), camera poses, and dense point cloud. These products serve different purposes:

Orthomosaics are not merely decorative baselines: they can support plot extraction and two-dimensional traits. They should not, however, be treated as the sole source of three-dimensional canopy structure.

4. Reconstruct measurable geometry with SfM​

SfM estimates camera poses and sparse geometry from shared visual features; dense reconstruction then estimates additional surface points.

Before extracting traits, inspect:

• aligned-camera coverage and rejected images;
• reprojection error and tie-point distribution;
• GCP/RTK residuals and independent checkpoints;
• scale and coordinate-system consistency;
• holes beneath dense upper foliage;
• floating points, ground leakage, and duplicated surfaces;
• registration consistency across dates.

Canopy height is typically calculated relative to a ground model or local reference surface, not directly from maximum point elevation. Report the percentile or robust statistic used; a single highest point is sensitive to noise.

5. Use 3D Gaussian Splatting for the right purpose​

3D Gaussian Splatting (3DGS) can provide high-quality interactive novel-view rendering from calibrated images and camera poses. It is valuable for visual inspection, communication, and research on appearance-aware scene representation.

3DGS should not automatically replace the SfM point cloud for metric phenotyping. A rendered Gaussian representation is not inherently a watertight surface or a calibrated biological measurement. Any geometry extracted from a 3DGS pipeline requires its own scale, accuracy, repeatability, and ground-truth validation.

6. Segment fields, plots, and rows​

Use the orthomosaic and experimental design to create plot polygons, then project or crop the corresponding point-cloud regions. A robust boundary workflow may combine:

1. surveyed or design-derived plot geometry;
2. vegetation or color cues from the orthomosaic;
3. topology constraints such as expected row order and spacing;
4. manual quality control for borders, missing stands, and mixed plots.

The Land Surveyor can help capture and export field polygons, but browser GPS accuracy varies by device and environment. Survey-grade boundaries require appropriate positioning equipment and procedures.

7. Derive candidate traits​

Candidate point-cloud descriptors can include:

• height percentiles and vertical profiles;
• projected canopy area;
• convex or alpha-shape volume with fully reported parameters;
• point density and spatial occupancy;
• row width and gap statistics;
• surface roughness or local height variation.

These are algorithm outputs until they are linked to a biological definition and validated. Point density, for example, also reflects image geometry, texture, reconstruction settings, and occlusion.

CanopyPC research workflow​

CanopyPC refers here to a research workflow for canopy point-cloud processing, including statistical outlier removal, optional ground filtering, row segmentation, bounding geometry, and interactive inspection. It should not be interpreted as a publicly released, installable package unless a repository, version, license, and example dataset are provided with the analysis.

8. Validate before modeling​

Select ground truth that matches the proposed claim. Examples include surveyed canopy height, manual organ measurements, destructive leaf-area measurements, or a higher-accuracy reference scan.

Use grouped validation that keeps related plants, plots, flights, sites, or dates together. Randomly splitting individual points or repeated images can create severe leakage.

Report at least:

• sample counts at the biological-unit level;
• train, validation, and test grouping;
• error metrics with units and uncertainty;
• calibration and residual plots when predicting continuous traits;
• performance by crop, growth stage, site, and acquisition condition;
• missing reconstructions and excluded cases;
• a comparison with a simple baseline.

Transfer to a new crop or environment must be measured; it should not be assumed from cross-validation in one field.

Limitations to state explicitly​

• Dense upper canopies hide lower organs, and no flight path can reconstruct surfaces that are never observed.
• Wind violates the static-scene assumption of conventional photogrammetry.
• Repeated-date comparisons require stable scale, ground reference, and registration.
• 3D models may underestimate leaf area as occlusion increases.
• Automatic segmentation can fail at plot borders, lodging, senescence, weeds, and missing stands.
• Flight efficiency and geometric completeness trade off against battery, data volume, blur, and safety.

Reproducibility checklist​

• Raw images and metadata archived
• Mission and camera settings recorded
• Coordinate system and scale source documented
• Software versions and reconstruction parameters saved
• Plot geometry versioned
• Point-cloud filters and thresholds reported
• Independent ground truth retained
• Failed cases included in the report

Workflow reviewed: July 2026. Parameters must be adapted and validated for each aircraft, crop, field, and research question.

It is important to describe that boundary precisely: the current program creates cleaned binary images; it does not calculate validated root length, density, diameter, or architecture traits by itself.

What the current tool does​

This workflow is most useful before skeletonization or measurement in software such as RhizoVision Explorer, WinRHIZO, ImageJ, or a validated laboratory pipeline.

Installation​

The source is available in the Root Quantify GitHub repository.

git clone https://github.com/smiler488/RootQuantify.git
cd RootQuantify

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

On Windows, activate the environment with:

.venv\Scripts\activate

The interface requires a graphical desktop. A headless server or notebook session cannot display the OpenCV selection windows without additional display configuration.

Run the workflow​

python RootImager.py

Two windows are used: one keeps the original image visible, while the other handles ROI selection and correction.

Keyboard controls​

After confirming the polygon, inspect the automatic threshold carefully. Correct only obvious segmentation errors; excessive manual editing reduces repeatability and should be recorded in the experiment log.

Inputs and outputs​

The program writes corrected images to an output directory with a processed- filename prefix. It moves each completed source image into processed_original.

For reproducible work, save the following alongside the outputs:

• the unmodified original images in a separate read-only backup;
• the Root Quantify commit hash;
• the preprocessing parameters used in the script;
• operator identity and correction date;
• a note describing any difficult or excluded image.

Do not use the moved copy as the only archive of raw data.

Quality-control checklist​

• Roots and background have visibly different intensities.
• The ROI excludes labels, rulers, pot edges, and unrelated objects.
• Fine lateral roots are retained after thresholding.
• Shadows are not mistaken for roots.
• Manual corrections are minimal and documented.
• A second reviewer checks a sample when measurements will support a publication.
• Downstream measurements are validated against known objects or manual reference data.

Known limitations​

• Threshold-based segmentation is sensitive to shadows, reflections, substrate, and overlapping roots.
• A binary image discards color and intensity information from the original.
• Manual correction introduces operator variability.
• Moving source files is convenient for batching but requires a deliberate backup policy.
• The desktop interaction is not designed for unattended or high-throughput server processing.
• The output is a preprocessing result, not a biological conclusion or calibrated phenotype table.

For a browser-based preprocessing workflow with different limits, see Root Image Preprocessor and its App Lab tutorial.

Workflow reviewed: July 2026. Check the repository README and source before use because the interface may change.

This guide separates three jobs that are often mixed together: running a model, adapting a model, and serving a model. Start with the smallest job that answers your research question.

Choose the right path​

For most individual researchers, local inference plus retrieval or a small LoRA experiment is more appropriate than full-parameter training.

1. Run a model locally with Ollama​

Ollama provides a straightforward local runtime on macOS, Linux, and Windows. Use the current installer from the official download page; on systems where the shell installer is supported:

curl -fsSL https://ollama.com/install.sh | sh

Browse the current model library, select a model that fits your memory budget, and replace <model-name> below:

ollama pull <model-name>
ollama run <model-name>
ollama list

Do not select a model only by parameter count. Check its license, context length, supported languages, quantization, tool-calling format, and intended use.

Test the local API​

Keep the service bound to the local machine during development. A minimal non-streaming request is:

curl http://localhost:11434/api/chat -d '{
  "model": "<model-name>",
  "messages": [
    {"role": "user", "content": "Explain canopy photosynthesis in three sentences."}
  ],
  "stream": false
}'

Confirm that the process works offline if offline operation is a requirement. A downloaded model does not prove that every surrounding integration is offline.

2. Check hardware before adapting a model​

Memory demand varies with model architecture, precision, optimizer, sequence length, batch size, and whether activations or optimizer states are offloaded. Avoid a single “minimum GPU” claim.

Use a small environment report instead:

import json
import platform

report = {
    "platform": platform.platform(),
    "python": platform.python_version(),
}

try:
    import torch

    report["torch"] = torch.__version__
    report["cuda_available"] = torch.cuda.is_available()
    if torch.cuda.is_available():
        report["gpu"] = torch.cuda.get_device_name(0)
        report["gpu_memory_gb"] = round(
            torch.cuda.get_device_properties(0).total_memory / 1024**3,
            1,
        )
except ImportError:
    report["torch"] = None

print(json.dumps(report, indent=2))

Install PyTorch using the selector on the official site so the build matches the operating system and accelerator. Do not copy a fixed CUDA wheel command onto Apple Silicon, CPU-only, or differently versioned CUDA systems.

3. Prepare data before fine-tuning​

A fine-tuning dataset should be traceable, licensed for the intended use, and split before experimentation.

1. Define the task and a measurable success criterion.
2. Remove personal, confidential, copyrighted, and duplicated material that is not authorized for training.
3. Create train, validation, and test splits that prevent near-duplicate leakage.
4. Format examples using the selected model's chat template rather than inventing a generic prompt format.
5. Keep a dataset card with provenance, exclusions, transformations, and known biases.
6. Inspect a sample of rendered prompts and labels before starting a long run.

For scientific work, split by the true unit of generalization. For example, specimens from the same plant, plot, site, or acquisition session should not be scattered across train and test sets when that would inflate performance.

4. Prefer parameter-efficient adaptation​

LoRA and QLoRA update a small set of adapter parameters while keeping most base-model weights fixed. They generally reduce memory and storage requirements, but they do not guarantee better factuality or domain performance.

Use the current official instructions for a maintained training framework such as Unsloth or Axolotl, and pin a known-working environment:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip freeze > requirements-lock.txt

Your training record should include:

• base model and immutable revision;
• tokenizer and chat template;
• LoRA target modules, rank, alpha, and dropout;
• sequence length, effective batch size, optimizer, and learning rate;
• random seed and data split identifiers;
• checkpoint selection rule and evaluation results;
• wall time, accelerator type, and peak memory.

Full-parameter fine-tuning and pre-training require a separate capacity plan, distributed-training validation, and substantially stronger data governance. They are intentionally outside this introductory workflow.

5. Evaluate the behavior that matters​

Training loss alone is not evidence of a useful model. Build an evaluation set before training and keep it unchanged while selecting checkpoints.

Report uncertainty and failure cases. BLEU or perplexity can be informative for specific tasks, but neither is a general measure of correctness or helpfulness.

6. Serve locally before serving a network​

For a single workstation, the runtime's local API is often enough. For higher-throughput GPU serving, consult the current vLLM supported-model documentation and its deployment guide.

Before accepting remote requests, add at least:

• authentication and authorization;
• request-size, token, concurrency, and rate limits;
• explicit network binding and firewall rules;
• timeouts, cancellation, and back-pressure;
• structured logs that exclude prompts by default;
• model and prompt-template version reporting;
• health checks that distinguish “process alive” from “model ready”;
• abuse testing and a rollback plan.

Never expose an unauthenticated development server or a model dashboard directly to the public internet. A Gradio share=True tunnel is also a public endpoint, not a private local interface.

Troubleshooting principles​

Out of memory​

Reduce sequence length and batch size first. Then consider gradient accumulation, checkpointing, quantization, adapter training, or a smaller model. Record every change because it can alter quality and speed.

Package or CUDA mismatch​

Create a clean environment and verify the driver, CUDA runtime, PyTorch build, and optional attention kernels independently. Optional acceleration libraries should not be installed until the basic model can load.

Training loss does not improve​

Inspect rendered examples and labels, compare against a small overfitting test, verify the learning rate, and confirm that adapter parameters receive gradients. More steps cannot repair malformed data.

Good benchmark, poor real use​

Check leakage, prompt-template differences, retrieval quality, and whether the test set represents the actual deployment population. Add examples from observed failures only to a new development set, not retroactively to the held-out test set.

Reproducibility checklist​

• Model license and revision recorded
• Dataset provenance and split strategy documented
• Dependencies locked
• Hardware and runtime recorded
• Prompts and generation settings versioned
• Baseline evaluated before adaptation
• Held-out test set preserved
• Security and privacy boundaries tested
• Limitations and failed cases reported

Further reading​

• Ollama documentation
• vLLM supported models
• Unsloth
• Axolotl
• Text Generation WebUI
• Hugging Face model hub

Workflow reviewed: July 2026. Re-check upstream documentation before reproducing the commands.

Canopy photosynthesis modeling links several distinct systems: image acquisition, 3D reconstruction, organ geometry, radiative transfer, leaf physiology, and environmental forcing. This article defines the interfaces and validation requirements between those stages.

It is a conceptual research workflow, not a complete executable simulator. Each stage requires a tested implementation, calibrated parameters, units, uncertainty analysis, and comparison with independent measurements.

Workflow map​

The arrows are data contracts. For example, a radiative-transfer model needs geometry with known units and normals; a photosynthesis model needs absorbed radiation in physical units, not arbitrary ray-hit counts.

1. Define the scientific question first​

Possible questions include:

• How does leaf-angle distribution affect within-canopy light?
• Which architectural traits explain differences in daily carbon gain?
• Can reconstructed canopies reproduce measured light interception?
• How sensitive is a crop-model parameter to 3D structural variation?

The question determines the necessary spatial and temporal resolution. A visualization model does not automatically support quantitative carbon-flux claims.

Pre-register or document:

• target variable and unit;
• spatial unit: leaf, plant, plot, or canopy;
• temporal unit: instant, hour, or day;
• experimental factors and replicates;
• calibration and validation observations;
• acceptable error or decision threshold.

2. Acquire multi-view images​

Use a capture protocol appropriate to the plant scale:

• stable illumination and minimal leaf motion;
• locked or recorded focus, exposure, white balance, and focal length;
• sufficient overlap and multiple elevations;
• measured scale controls;
• calibration images and camera metadata;
• subject identifiers that connect images to field or chamber records.

Turntable and field capture need different background strategies. In a turntable setup, static room features must be masked because the plant rotates relative to them. In field capture, wind and moving shadows can violate the static-scene assumption.

Acquisition validation​

Report image count, rejected images, angular or spatial coverage, blur screening, marker visibility, and missing views. Repeat a subset of plants to quantify capture repeatability.

3. Reconstruct geometry​

Structure from Motion and multi-view stereo​

SfM estimates camera poses and sparse scene structure; multi-view stereo creates a denser point cloud. Tools such as COLMAP can provide these stages, but command-line option names change across versions. Save the exact software version and configuration.

The geometry pipeline should produce:

• camera poses and intrinsics;
• scaled point cloud or mesh;
• per-vertex or per-face normals;
• confidence or density information where available;
• reconstruction diagnostics.

3D Gaussian Splatting​

3D Gaussian Splatting is primarily a learned radiance-field representation for novel-view rendering. A set of optimized Gaussians is not automatically a watertight, metrically validated plant mesh. Geometry extraction requires an additional, documented method and its own validation.

Do not replace an SfM-to-mesh pipeline with a few tensor parameters and call the result complete 3DGS. A practical implementation needs a differentiable rasterizer, constrained scale/rotation/opacity parameterization, densification and pruning, camera calibration, and a defined export path.

4. Validate and process the mesh​

Thin leaves, self-occlusion, texture-poor surfaces, and motion produce holes and false surfaces. Surface reconstruction can also fill unsupported regions.

Inspect:

• scale error against independent distances;
• completeness by organ and canopy depth;
• false connections between overlapping leaves;
• mesh normals and orientation;
• non-manifold or degenerate geometry;
• sensitivity to masking and reconstruction settings.

Poisson reconstruction returns a smooth closed surface and can extrapolate into low-density areas. Use density information and measured evidence to crop unsupported surfaces rather than accepting the default mesh.

5. Derive plant organs and leaf area​

A curvature threshold alone is not a robust leaf/stem segmentation method. Curvature depends on scale, mesh resolution, noise, and neighborhood definition.

Use a validated combination of:

• geometry and topology;
• color or spectral information;
• supervised organ labels;
• plant-development constraints;
• manual review on a representative subset.

For each organ, preserve:

• surface area and the method used to calculate it;
• orientation and normal convention;
• thickness or two-sided-leaf assumption;
• segmentation confidence;
• link to the original plant and treatment.

Compare total reconstructed leaf area with destructive leaf-area measurements or another independent method.

6. Build a measured or synthetic canopy​

There are two different scientific products:

1. Measured canopy: positions and geometry are reconstructed from an observed stand.
2. Synthetic canopy: plant instances and traits are generated to test hypotheses.

Synthetic perturbations must be interpretable. Record the distribution, covariance, bounds, and random seed for plant spacing, height, azimuth, leaf angle, and size. Repeatedly cloning one plant and adding arbitrary vertex noise does not reproduce population-level architectural diversity.

Check for plant overlap, below-ground geometry, unrealistic leaf intersections, and changes in leaf area after transformation.

7. Model the light environment in physical units​

A radiative-transfer stage needs:

• canopy coordinates and units;
• direct and diffuse sky radiation;
• sun position calculated from date, time, and location;
• leaf reflectance and transmittance by waveband;
• soil/background optical properties;
• an absorption and scattering model;
• a mapping from intercepted energy to absorbed PPFD or another defined quantity.

Angles provided in degrees must be converted before using NumPy trigonometric functions:

import numpy as np

elevation = np.deg2rad(elevation_degrees)
azimuth = np.deg2rad(azimuth_degrees)

Counting first ray intersections produces a sampling density, not irradiance. Each ray needs a defined energy or probability weight, and the model must describe whether it includes transmission, reflection, multiple scattering, and diffuse radiation.

Light-model validation​

Compare predictions with independent observations such as:

• above- and below-canopy PAR sensors;
• vertical or horizontal light profiles;
• intercepted-radiation measurements;
• hemispherical images or ceptometers;
• energy conservation and convergence checks.

Increase ray count or spatial resolution until the output of interest converges within a predefined tolerance.

8. Parameterize leaf photosynthesis​

The Farquhar–von Caemmerer–Berry model describes C3 leaf photosynthesis through biochemical limitations. A credible implementation needs more than a generic Vcmax25 and Jmax25.

Define and justify:

• species, cultivar, leaf age, and nitrogen status;
• leaf temperature rather than air temperature when they differ;
• intercellular or chloroplastic CO₂ treatment;
• Rubisco-, electron-transport-, and, when relevant, TPU-limited rates;
• day respiration;
• temperature-response functions;
• stomatal and, when needed, mesophyll conductance;
• absorbed light and spectral assumptions;
• fitted parameter uncertainty.

Ambient CO₂ concentration cannot simply replace intercellular CO₂ without a conductance model or an explicitly justified approximation.

Fit physiological parameters from appropriate gas-exchange observations or cite a parameter source that matches the biological material and conditions. Generic literature constants are useful for sensitivity analysis, not automatically for quantitative prediction.

9. Integrate leaf rates without losing units​

For leaf element i with net assimilation A_i in micromoles of CO₂ per square metre per second and one-sided area a_i in square metres:

P_canopy = sum_i(A_i × a_i)

The result is micromoles of CO₂ per second. An area-weighted mean is:

A_mean = sum_i(A_i × a_i) / sum_i(a_i)

Dividing total assimilation by the number of occupied voxels does not produce an area-based rate.

For daily carbon gain, integrate over time using environmental forcing and consistent time units. Report whether the canopy domain represents one plant, one row segment, one square metre of ground, or a whole plot.

10. Keep the implementation modular​

A reproducible project can expose explicit stage interfaces:

images + calibration
    -> camera poses + scaled geometry
geometry + organ labels
    -> leaf elements + area + normals
leaf elements + environment + optics
    -> absorbed PPFD by element and time
absorbed PPFD + physiology
    -> leaf assimilation by element and time
leaf assimilation + area
    -> canopy exchange + uncertainty

For every interface, validate:

• file schema and coordinate convention;
• shape, unit, range, and missing values;
• provenance and software version;
• stable identifiers across stages;
• a small fixture with a known or manually checked result.

11. Uncertainty and sensitivity​

Uncertainty enters through:

• camera calibration and scale;
• missing or falsely reconstructed leaf area;
• organ segmentation;
• leaf normals and optical properties;
• sky and sun forcing;
• physiological parameter fitting;
• numerical sampling and time integration.

Use perturbation, Monte Carlo, or a designed sensitivity analysis to determine which uncertainties control the final canopy result. Report distributions or intervals, not only a single simulated value.

Minimum evidence for a quantitative claim​

• independent geometric measurements;
• measured or well-supported optical properties;
• light-model validation;
• physiological calibration or appropriate parameter provenance;
• canopy-level gas-exchange or biomass/carbon evidence when available;
• repeatability across plants or plots;
• a fully versioned environment, configuration, and data manifest.

Without this evidence, present the output as a hypothesis-generating simulation or visualization.

References and implementations​

• COLMAP command-line interface
• 3D Gaussian Splatting paper and reference implementation
• Open3D surface reconstruction guide
• Farquhar, von Caemmerer, and Berry (1980)

These resources document individual stages. They do not remove the need to validate the integrated crop or canopy model for the intended experiment.

This guide takes original DJI P4 Multispectral imagery through WebODM and QGIS to a plot-level feature table. It distinguishes digital numbers from calibrated reflectance, treats band order and coordinate reference systems as data to verify, and keeps NoData pixels out of vegetation and texture statistics.

• Inputs: original RGB and multispectral captures, metadata, plot boundaries, and preferably calibration and accuracy controls
• Outputs: checked orthomosaic bands, vegetation indices, optional texture layers, and plot-level statistics
• Boundary: menu labels vary by WebODM and QGIS version; verify the installed interface and processing report

1. Preserve the source data​

A P4 Multispectral capture normally contains one RGB image and five narrow bands: blue, green, red, red edge, and near infrared. Preserve the camera-generated files and metadata as a read-only source dataset.

Before processing:

• copy, rather than move, the original folders;
• keep all bands from each capture together;
• preserve EXIF/XMP metadata, exposure information, and camera filenames;
• check that every capture has the expected set of bands;
• record flight, illumination, calibration-panel, RTK/GNSS, and ground-control information;
• calculate checksums when data integrity matters.

Do not rely on the downwelling light sensor alone as proof of reflectance accuracy. Calibration-panel observations, stable acquisition conditions, and independent validation strengthen the radiometric record.

2. Install and start WebODM​

WebODM uses Docker. Install Docker Desktop and Git, allocate sufficient memory and storage, then clone the official repository:

git clone https://github.com/OpenDroneMap/WebODM
cd WebODM
./webodm.sh start

Open http://localhost:8000 and create the local administrator account on first use.

Follow the current WebODM installation documentation for operating-system-specific prerequisites. Avoid copying unverified third-party registry mirrors into Docker configuration; availability and trust can change.

3. Create a multispectral task​

1. Create a project with a stable identifier, such as maize-n-trial-2025.
2. Create a task and upload all bands together.
3. Select the multispectral preset when it is available.
4. Save the exact WebODM/ODM version and task options with the results.

Radiometric calibration​

OpenDroneMap exposes three radiometric modes:

• none — output remains in sensor digital-number space;
• camera — applies supported camera corrections when the required metadata are present;
• camera+sun — additionally uses a downwelling-light-sensor signal and sun geometry; the ODM documentation labels this mode experimental.

Choose a mode deliberately and describe it in the methods. Do not label an output “reflectance” when calibration was none.

Band alignment and reconstruction​

• ODM aligns multispectral bands by default. Do not enable skip-band-alignment unless the input has already been aligned and that fact has been verified.
• Leave the primary band on automatic selection or choose a sharp, well-focused band after inspection.
• Use fixed camera parameters only when the calibration and camera model justify that constraint.
• The use-exif option is not a general “turn GPS on” switch. ODM already reads image metadata; use-exif is relevant when a GCP file is supplied but EXIF georeferencing should also be used.
• If only 2D products are required, skip-3dmodel can reduce unnecessary output. Do not assume that every intermediate point-cloud calculation can be skipped.

For survey accuracy, use well-distributed ground control and independent checkpoints when the research question requires them. RTK image positions do not remove the need to validate the final map.

4. Inspect the WebODM outputs​

Download the orthophoto and processing report from the task assets. The displayed download name can vary; do not assume the file is always called orthophoto.tif.

Before calculating an index, record:

• raster dimensions, data type, and NoData value;
• CRS and pixel size;
• number of bands and each band description;
• whether values are digital numbers or reflectance-like calibrated values;
• processing warnings and geolocation/checkpoint errors.

Use gdalinfo or QGIS → Layer Properties → Information. Never infer red and NIR band numbers from an example on the internet.

5. Set up the QGIS project​

Add the multiband orthomosaic and plot-boundary layer to QGIS.

Choose the CRS from the survey location​

Spatial operations and plot areas should use an appropriate projected CRS with linear units. Determine the UTM zone or local projected CRS from the actual survey location. A copied example such as EPSG:32645 is correct only for data located in that zone.

Reproject the plot layer when necessary; assigning a new CRS without transforming coordinates does not reproject data.

Clip without losing NoData​

Use Clip raster by mask layer with the field boundary:

• enable crop to cutline;
• select a defined NoData value;
• preserve the original raster;
• confirm the clipped edge and pixel alignment visually.

6. Calculate NDVI safely​

NDVI is:

NDVI = (NIR - Red) / (NIR + Red)

After verifying the band numbers, replace the placeholders in the QGIS Raster Calculator:

("orthomosaic@<NIR band>" - "orthomosaic@<Red band>") /
("orthomosaic@<NIR band>" + "orthomosaic@<Red band>")

Also create a valid-data mask that excludes source NoData and zero denominators. Save the output as Float32 and inspect:

• expected field patterns;
• values outside [-1, 1];
• seams, shadows, saturation, and uncalibrated exposure differences;
• consistency with known vegetation and bare-soil areas.

The valid NDVI range does not make every value biologically plausible. Interpretation depends on crop, growth stage, atmosphere, soil, viewing geometry, and calibration.

7. Build a vegetation mask​

A threshold such as 0.2 is an experiment-specific starting point, not a universal vegetation boundary. Select it using representative labelled pixels or a documented sensitivity analysis.

Keep two separate rasters:

1. a binary vegetation mask;
2. NDVI with non-vegetation pixels set to NoData, not zero.

Multiplying NDVI by a binary mask sets the background to zero. Those zeros then enter means and, if the raster is shifted for quantization, can become mid-grey values. Use an explicit NoData mask before zonal statistics or texture calculation.

8. Quantize only when a texture method requires it​

GRASS r.texture expects integer grey levels. Document the input layer, valid range, scale, offset, rounding, and NoData handling.

If the complete NDVI interval ([-1, 1]) is intentionally mapped to UInt8, the conceptual transform is:

UInt8 = round((NDVI + 1) × 127.5)

Clamp only valid vegetation pixels to 0–255 and leave background as NoData. A data-driven range can improve contrast, but it changes comparability between dates unless the same documented limits are used.

9. Calculate GLCM texture deliberately​

Enable the GRASS processing provider before using r.texture. Common outputs include:

• asm — angular second moment;
• contrast — local grey-level contrast;
• corr — correlation;
• idm — inverse difference moment;
• entr — entropy.

sa is sum average, not another name for ASM, and dv is difference variance.

Record:

• window size in pixels and its footprint in metres;
• pixel distance;
• direction or directional aggregation;
• quantization rule;
• edge and NoData behavior.

Choose the window from ground sampling distance and the biological scale of interest. A 7-pixel window at 2 cm GSD represents a different canopy area than the same window at 10 cm GSD.

10. Extract plot-level statistics​

Run Zonal statistics with the plot polygons and a stable plot_id.

Useful summaries include:

• valid-pixel count and coverage fraction;
• mean, median, standard deviation, and selected quantiles;
• vegetation fraction;
• selected texture metrics.

Exclude NoData and flag plots with too little valid vegetation. Export the attribute table to CSV together with processing metadata, not as an unexplained standalone table.

Validation checklist​

• Every capture contains the expected bands and metadata.
• The radiometric mode and calibration evidence are recorded.
• Band descriptions were checked before index calculation.
• CRS and ground sampling distance match the survey.
• Ground-control and independent-check errors are reported when applicable.
• Background pixels are NoData rather than numeric zeros in trait statistics.
• Threshold and texture parameters were tested for sensitivity.
• Plot coverage and valid-pixel counts accompany each summary.
• Software versions, task options, and formulas are archived.

References​

• OpenDroneMap multispectral and thermal processing
• ODM radiometric calibration option
• ODM options and flags
• QGIS documentation

This article is a learning roadmap, not a copy-and-run production framework. It keeps one small executable example, then explains the decisions that make a research model auditable: device handling, seeds, data splits, metrics, checkpoints, version records, and validation.

• Audience: Python users starting reproducible machine-learning experiments
• API scope: recent PyTorch 2.x and torchvision releases; always check the installed-version documentation
• Verification boundary: examples are intentionally small and syntax-checkable; no benchmark, cloud price, or hardware-performance claim is implied

1. Install from the official selector​

PyTorch packages depend on the operating system and accelerator runtime. Use the current choices at PyTorch — Start Locally rather than copying a CUDA URL from an old tutorial.

A CPU-only pip installation is useful for learning and continuous integration:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

On Windows, activate the environment with the command appropriate to PowerShell or Command Prompt. For CUDA, ROCm, XPU, or another backend, use the official selector and record the exact command.

Capture the environment:

python --version
python -m pip freeze > requirements-lock.txt

For a maintained project, prefer a dependency file and a deliberate lock/update process over an unreviewed snapshot.

2. Inspect the runtime and select a device​

Do not scatter unconditional .cuda() calls through a project. Select a device once and move both model and tensors to it.

import torch

def select_device() -> torch.device:
    if torch.cuda.is_available():
        return torch.device("cuda")
    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
        return torch.device("mps")
    return torch.device("cpu")

device = select_device()

print("PyTorch:", torch.__version__)
print("Device:", device)
print("CUDA runtime:", torch.version.cuda)

Record the device, accelerator model, driver/runtime, package versions, and precision mode with experiment results.

3. Set reproducibility controls before model creation​

Seeds must be set before initializing a model or shuffling data.

import os
import random

import numpy as np
import torch

SEED = 42
os.environ["PYTHONHASHSEED"] = str(SEED)
random.seed(SEED)
np.random.seed(SEED)
torch.manual_seed(SEED)

if torch.cuda.is_available():
    torch.cuda.manual_seed_all(SEED)

torch.use_deterministic_algorithms(True, warn_only=True)

A seed improves repeatability but does not guarantee identical results across PyTorch versions, devices, kernels, or distributed configurations. Report tolerances and rerun important experiments.

4. Train one minimal model​

The XOR example demonstrates tensors, a module, logits, a loss, an optimizer, and inference without a large dataset.

import torch
from torch import nn

torch.manual_seed(42)

X = torch.tensor(
    [[0.0, 0.0], [0.0, 1.0], [1.0, 0.0], [1.0, 1.0]]
)
y = torch.tensor([[0.0], [1.0], [1.0], [0.0]])

model = nn.Sequential(
    nn.Linear(2, 8),
    nn.ReLU(),
    nn.Linear(8, 1),
)

criterion = nn.BCEWithLogitsLoss()
optimizer = torch.optim.Adam(model.parameters(), lr=0.05)

for _ in range(500):
    logits = model(X)
    loss = criterion(logits, y)

    optimizer.zero_grad(set_to_none=True)
    loss.backward()
    optimizer.step()

model.eval()
with torch.inference_mode():
    probabilities = torch.sigmoid(model(X))
    predictions = (probabilities >= 0.5).to(torch.int32)

print(probabilities.squeeze())
print(predictions.squeeze())

Use BCEWithLogitsLoss with raw logits rather than adding a sigmoid layer before BCELoss. Do not publish exact expected probabilities: initialization, package versions, and numerical kernels can change them.

5. Structure a research dataset​

Keep dataset splitting independent of preprocessing fitted on the data.

1. define the observational unit;
2. split by a unit that prevents leakage, such as plant, plot, field, date, or subject;
3. fit normalization and feature transforms on the training split only;
4. freeze the validation split for model selection;
5. touch the test split only for final evaluation.

For image phenotyping, random image-level splitting can leak near-duplicate views of the same plant into training and validation. Group-aware splitting is usually more defensible.

A custom dataset should return a sample and target without silently changing global state:

from pathlib import Path

from PIL import Image
from torch.utils.data import Dataset

class ImageTableDataset(Dataset):
    def __init__(self, rows, transform=None):
        self.rows = list(rows)
        self.transform = transform

    def __len__(self):
        return len(self.rows)

    def __getitem__(self, index):
        row = self.rows[index]
        image = Image.open(Path(row["path"])).convert("RGB")
        if self.transform is not None:
            image = self.transform(image)
        return image, int(row["label"])

Validate paths and labels when constructing rows, and document how missing or corrupt samples are handled.

6. Use a transparent training loop​

One epoch should have a clear contract: consume a loader, update the model, and return a sample-weighted metric.

def train_one_epoch(model, loader, criterion, optimizer, device):
    model.train()
    loss_sum = 0.0
    sample_count = 0

    for inputs, targets in loader:
        inputs = inputs.to(device)
        targets = targets.to(device)

        optimizer.zero_grad(set_to_none=True)
        outputs = model(inputs)
        loss = criterion(outputs, targets)
        loss.backward()
        optimizer.step()

        batch_size = inputs.shape[0]
        loss_sum += loss.detach().item() * batch_size
        sample_count += batch_size

    return loss_sum / sample_count

For validation:

• call model.eval();
• wrap inference in torch.inference_mode();
• never update model parameters;
• aggregate metrics over all samples;
• store predictions and identifiers when error analysis is needed.

Avoid selecting a model from test-set performance.

7. Add mixed precision only when supported​

Automatic mixed precision can improve CUDA throughput, but it is an optimization, not a correctness requirement. Establish a full-precision baseline first.

from contextlib import nullcontext

import torch

use_amp = device.type == "cuda"
scaler = torch.amp.GradScaler("cuda", enabled=use_amp)

for inputs, targets in train_loader:
    inputs = inputs.to(device)
    targets = targets.to(device)
    optimizer.zero_grad(set_to_none=True)

    precision_context = (
        torch.autocast(device_type="cuda", dtype=torch.float16)
        if use_amp
        else nullcontext()
    )

    with precision_context:
        outputs = model(inputs)
        loss = criterion(outputs, targets)

    scaler.scale(loss).backward()
    scaler.step(optimizer)
    scaler.update()

The old torch.cuda.amp.autocast and torch.cuda.amp.GradScaler namespaces are deprecated in current documentation. Monitor loss, gradients, and metrics for NaN or overflow when changing precision.

8. Start computer vision with a maintained baseline​

Torchvision weight enums couple pretrained parameters to documented preprocessing:

from torch import nn
from torchvision.models import ResNet18_Weights, resnet18

weights = ResNet18_Weights.DEFAULT
preprocess = weights.transforms()

model = resnet18(weights=weights)
model.fc = nn.Linear(model.fc.in_features, 4)

Record the weights enum, input resolution, transform, class mapping, and fine-tuning policy. Avoid calling a single output head a complete YOLO detector: object detection also requires target encoding, a loss, decoding, non-maximum suppression, evaluation, and task-specific training.

For plant images, compare a learned model against simple baselines and evaluate across the domains that matter—cultivar, growth stage, sensor, field, date, and lighting.

9. Save state safely​

Save state dictionaries and metadata rather than serializing an arbitrary live Python object:

from pathlib import Path

import torch

checkpoint_path = Path("checkpoints/model.pt")
checkpoint_path.parent.mkdir(parents=True, exist_ok=True)

torch.save(
    {
        "model_state_dict": model.state_dict(),
        "optimizer_state_dict": optimizer.state_dict(),
        "epoch": epoch,
        "class_names": class_names,
    },
    checkpoint_path,
)

Load only trusted files and map them to a known device:

checkpoint = torch.load(
    "checkpoints/model.pt",
    map_location="cpu",
    weights_only=True,
)
model.load_state_dict(checkpoint["model_state_dict"])

torch.load uses restricted loading with weights_only=True, but a project should still treat external model artifacts as untrusted input and verify their provenance and integrity.

10. Evaluate more than one number​

Choose metrics before looking at final results.

• Classification: confusion matrix, per-class precision/recall, macro F1, calibration, and uncertainty intervals
• Regression: MAE, RMSE, bias, residual plots, and errors by biological or acquisition subgroup
• Segmentation: IoU/Dice per class, boundary error, object-level errors, and failure cases
• Detection: the metric definition, IoU range, object-size strata, and precision–recall curves

Report dataset composition and uncertainty. A high aggregate score can hide failure on a cultivar, field, camera, or rare class.

11. Treat deployment as a separate engineering phase​

A notebook inference call is not a production service. Before deployment, define:

• model and preprocessing version;
• input schema, size, and content limits;
• authentication and authorization;
• request rate and resource limits;
• timeout, batching, and concurrency behavior;
• privacy and data-retention policy;
• observability, rollback, and drift monitoring;
• tests using the exported artifact, not only the training model.

ONNX, torch.export, TorchScript, accelerator compilers, and serving frameworks have version-specific constraints. Select one only after measuring it on the target hardware. A minimal Flask endpoint without these controls should be described as a local demonstration, not production deployment.

Troubleshooting checklist​

Suggested learning sequence​

1. tensors, shapes, dtypes, and autograd;
2. Dataset, DataLoader, and leakage-safe splitting;
3. one transparent training and validation loop;
4. a simple baseline and documented metrics;
5. transfer learning with versioned preprocessing;
6. experiment tracking and ablation studies;
7. export and deployment validation.

Official resources​

• PyTorch documentation
• PyTorch tutorials
• PyTorch Forums
• PyTorch GitHub issues

This protocol uses a rotating plant and fixed cameras to create a multi-view image set for 3D reconstruction. It is intended as an experimental starting point, not a validated claim of high-precision phenotyping. Accuracy depends on plant motion, image sharpness, calibration, scale control, background masking, and independent validation.

Research objective​

The workflow can support:

• visualization of plant architecture;
• exploratory estimates of plant height, width, volume, and leaf orientation;
• development of organ-segmentation and light-distribution methods;
• comparison of reconstruction settings under controlled acquisition.

Do not treat mesh-derived traits as ground truth until their errors have been quantified against independent measurements.

1. Prepare the imaging area​

Stable environment​

• Stop fans and minimize airflow during capture; small leaf motion can break feature matching.
• Use diffuse, flicker-free light and keep it constant for the full sequence.
• Measure and record illuminance or exposure conditions rather than adopting an arbitrary universal lux value.
• Avoid specular highlights, deep shadows, and automatic lighting changes.

Background and turntable​

• Use a matte, visually uniform background that can be masked reliably.
• Use a rigid, matte turntable large enough for the pot and plant.
• Avoid transparent or reflective acrylic unless its reflections are controlled and validated.
• Keep static background features, color charts, cables, and supports out of the reconstruction mask. In turntable photogrammetry, the plant moves relative to the room, so static background features violate the assumed scene geometry.

Scale and control​

Place measured scale bars and uniquely identifiable coded markers on the rotating platform so they move with the plant. Avoid symmetric, repeated marker layouts that can create ambiguous correspondences.

Reserve at least one independent scale or distance as a check rather than using every measurement to define the model.

2. Configure the cameras​

One well-controlled camera moved between height levels is often easier to calibrate than two unmatched phone cameras. If multiple cameras are used:

• lock focus, shutter speed, ISO, white balance, and focal length;
• disable automatic HDR or lens switching when possible;
• record each device, lens, resolution, frame rate, and exposure setting;
• acquire calibration data for each camera;
• avoid digital zoom;
• verify that all views are sharp and free from rolling-shutter or stabilization artifacts.

Phone video is compressed and may apply computational processing between frames. Still images or high-quality intra-frame video are preferable when the workflow permits.

Use at least two elevation bands to reduce top- and underside occlusion. Exact angles and distances depend on plant size and field of view; verify that the entire specimen and scale controls remain visible.

3. Capture the sequence​

1. Center and secure the pot without deforming the plant.
2. Record a sharp reference view and the experiment metadata.
3. Start a slow, constant rotation.
4. Capture enough angular views to maintain feature overlap around the full plant.
5. Repeat at the second camera height or elevation.
6. Inspect the sequence immediately for blur, exposure drift, leaf motion, missing regions, and marker visibility.

Do not export every one or two video frames by default. At 30 frames per second, that produces thousands of highly redundant images. Sample by angular coverage and image quality. Document the final angular interval, number of retained frames, and rejection criteria.

4. Manage color separately from geometry​

A color chart such as SpyderCheck24 can help monitor camera and lighting consistency, but it does not by itself make image values physically calibrated reflectance.

• Capture the chart under the same camera and lighting settings.
• Apply one documented correction consistently to the sequence.
• Keep the static chart out of the geometry reconstruction mask.
• Preserve the uncorrected source files and the correction parameters.

If color is a scientific output, validate the corrected patch values and report the color space, white balance, exposure, and error metric.

5. Organize and screen the images​

Use names that preserve plant, camera, elevation, and view order:

Plant01/
├── raw/
│   ├── camera-a/
│   └── camera-b/
├── selected/
│   ├── upper/
│   └── horizontal/
├── masks/
├── calibration/
├── reconstruction/
└── validation/

For every selected image, check:

• sharpness at leaf edges;
• consistent exposure and white balance;
• sufficient overlap with adjacent views;
• no large leaf displacement;
• no accidental crop of the plant or scale controls;
• a mask that excludes the static room and color chart.

6. Reconstruct in Metashape or comparable software​

Software labels vary by version, so the workflow is described by purpose:

1. import the selected images;
2. apply masks before or during feature matching;
3. estimate camera poses and a sparse reconstruction;
4. inspect and remove obvious outlier tie points cautiously;
5. identify coded markers and enter measured scale constraints;
6. optimize camera parameters only after checking that the control geometry is correct;
7. generate depth maps and a dense point cloud;
8. remove unsupported background geometry;
9. build and, if required, texture a mesh;
10. export the point cloud or mesh with units and coordinate metadata.

Do not copy key-point limits, depth settings, or filtering strengths as universal defaults. Record the software version and run a small parameter comparison on representative plants.

7. Validate before extracting traits​

At minimum, report:

• number of input and aligned images;
• camera reprojection error, with its definition and units;
• marker and scale residuals;
• error on an independent distance or object;
• visibly missing or falsely filled plant regions;
• repeatability across replicate captures;
• sensitivity of traits to masking and reconstruction settings.

For manual plant height or width measurements (m_i) and reconstructed values (r_i), summarize bias and RMSE:

bias = mean(r_i - m_i)
RMSE = sqrt(mean((r_i - m_i)^2))

A visually plausible mesh can still give biased traits, particularly for thin leaf margins, overlapping leaves, and reflective or texture-poor surfaces.

8. Export research-ready outputs​

Preserve:

• original images and metadata;
• selected-frame manifest and rejection reasons;
• masks and calibration records;
• reconstruction project and software version;
• scale constraints and independent validation measurements;
• exported PLY/OBJ/GLB with units;
• scripts, parameters, and trait tables linked to a code commit.

This evidence makes the reconstruction auditable and allows future processing improvements without repeating the experiment.

This workflow combines VS Code, a project-specific Conda environment, and Git. The tools are useful, but reproducibility comes from the records around them: environment specifications, immutable raw data, configuration files, checksums, clear commits, and documented outputs.

1. Install the core tools​

• Visual Studio Code with the Python, Pylance, and Jupyter extensions
• Miniconda
• Git

Confirm that the active shell can find them:

code --version
conda --version
git --version

Configure Git once:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

2. Create a project and environment​

mkdir cotton-modeling
cd cotton-modeling
git init

conda create --name cotton python=3.11
conda activate cotton
conda install numpy pandas matplotlib scikit-learn
conda install --channel conda-forge opencv open3d

Choose the Python version and packages required by the project rather than copying this example unchanged.

Open the folder:

code .

In VS Code, run Python: Select Interpreter and select the cotton environment.

3. Use a research-friendly structure​

cotton-modeling/
├── README.md
├── environment.yml
├── pyproject.toml          # optional package and tool configuration
├── configs/                # versioned experiment parameters
├── data/
│   ├── README.md           # source, license, schema, and retrieval notes
│   ├── raw/                # immutable source data
│   └── processed/          # reproducible derived data
├── notebooks/              # exploration, not the only implementation
├── src/cotton_modeling/    # reusable Python modules
├── tests/
├── results/
│   └── README.md           # explains how outputs are generated
└── .gitignore

Keep raw data immutable. A processing script should create a new derived artifact rather than overwrite its input.

4. Decide what Git should track​

A starting .gitignore:

__pycache__/
*.py[cod]
.ipynb_checkpoints/
.env
.DS_Store
data/raw/*
data/processed/*
results/generated/*

Do not ignore the explanatory README.md files, schemas, small test fixtures, configuration, or the code required to reproduce an output.

For data too large or restricted for Git:

• store it in an approved repository or object store;
• record a persistent identifier or retrieval location;
• record checksums and access dates;
• use DVC or Git LFS only when they fit the collaboration and preservation plan.

Never commit credentials from .env.

5. Record the environment​

For a portable list of the packages you explicitly requested:

conda env export --from-history > environment.yml

Recreate it with:

conda env create --file environment.yml

--from-history is readable and cross-platform, but it does not lock every transitive dependency. When exact package builds matter, create a platform-specific explicit specification or use a lock-file tool, then archive that file with the release.

Update the environment description only after confirming the project still runs:

conda env export --from-history > environment.yml
git diff environment.yml

6. Keep notebooks and modules in sync​

Use notebooks for exploration and communication, but move stable operations into src/:

# src/cotton_modeling/preprocessing.py
from pathlib import Path

def list_images(folder: str) -> list[Path]:
    extensions = {".jpg", ".jpeg", ".png", ".tif", ".tiff"}
    return sorted(
        path for path in Path(folder).iterdir()
        if path.suffix.lower() in extensions
    )

Notebooks should import these functions instead of containing the only copy of an analysis.

For a named Jupyter kernel:

conda install ipykernel
python -m ipykernel install --user --name cotton --display-name "Python (cotton)"

7. Commit a reproducible unit of work​

Review before staging:

git status
git diff

Commit code, configuration, tests, and documentation together:

git add README.md environment.yml configs src tests
git diff --staged
git commit -m "feat: add canopy preprocessing pipeline"

Connect a GitHub repository:

git branch -M main
git remote add origin https://github.com/yourname/cotton_modeling.git
git push -u origin main

Before starting new work:

git fetch origin
git status
git pull --ff-only origin main

8. Choose one collaboration model​

Shared repository​

Members with write access create branches in the same repository:

git switch -c feature-light-simulation
# edit and test
git add configs src tests
git commit -m "feat: add light simulation module"
git push -u origin feature-light-simulation

Open a pull request, review the diff and checks, then merge.

Fork-based contribution​

Contributors without write access clone their own fork and register the original repository as upstream:

git clone https://github.com/yourname/cotton_modeling.git
cd cotton_modeling
git remote add upstream https://github.com/leader/cotton_modeling.git
git fetch upstream
git switch -c analysis-update

Push the branch to the fork and open a pull request against upstream/main.

9. Reproducibility checklist​

For each analysis or model run, preserve:

• code commit and, for releases, an annotated Git tag;
• environment or lock file;
• input dataset identifier, version, license, and checksum;
• configuration and random seeds;
• hardware or accelerator details when results are sensitive to them;
• commands used to run the workflow;
• generated logs, metrics, and a description of expected outputs;
• any manual step that cannot yet be automated.

Do not claim bit-for-bit reproducibility across platforms unless it has been tested. The stronger and usually more useful target is a documented workflow that reproduces the scientific conclusion within defined tolerances.

Common issues​

Git records changes to files on your computer. GitHub hosts Git repositories and adds collaboration features such as pull requests, issues, and automated checks. This guide follows a complete first workflow and separates safe recovery commands from history-rewriting operations.

1. Install and identify yourself​

Install Git​

• Windows: download Git for Windows.

• macOS: install the Xcode Command Line Tools or use Homebrew:

  brew install git
  

• Ubuntu or Debian:

  sudo apt update
  sudo apt install git
  

Confirm the installation:

git --version

Configure commit identity​

Use the name you want shown in commit history. The email should be an address associated with your GitHub account, or your GitHub-provided private noreply address.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main

Review the configuration:

git config --global --list

2. Create a repository​

Create a folder locally:

mkdir my-project
cd my-project
git init

Add a minimal project description:

echo "# My Project" > README.md
git status
git add README.md
git commit -m "docs: add project overview"

Before staging data, credentials, or generated files, create a .gitignore:

.env
node_modules/
__pycache__/
*.log

Never commit API keys or passwords. Removing a secret in a later commit does not remove it from earlier history; rotate an exposed credential immediately.

3. Connect the GitHub remote​

Create an empty repository on GitHub without initializing another README, then connect it:

git branch -M main
git remote add origin https://github.com/your-username/repository-name.git
git remote -v
git push -u origin main

GitHub does not accept an account password for Git operations over HTTPS. Use a supported credential manager, GitHub CLI, a personal access token, or SSH authentication.

For an existing repository:

git clone https://github.com/your-username/repository-name.git
cd repository-name

4. The everyday edit cycle​

Inspect changes before staging:

git status
git diff

Stage intentionally and commit a coherent unit:

git add path/to/file
git diff --staged
git commit -m "feat: describe the change"
git push

Prefer specific paths over git add . when a workspace contains unrelated or generated changes.

Before starting new work on a shared branch:

git fetch origin
git status
git pull --ff-only origin main

--ff-only refuses to create an unexpected merge commit. If local and remote histories have diverged, inspect them and decide whether to rebase or merge rather than forcing the operation.

5. Work on a branch​

Create and switch to a feature branch:

git switch -c feature-clear-name

Commit and publish it:

git add path/to/file
git commit -m "feat: add clear capability"
git push -u origin feature-clear-name

After review, return to the default branch and update it:

git switch main
git pull --ff-only origin main

Delete a fully merged local branch:

git branch -d feature-clear-name

6. Forks and pull requests​

Use a fork when you do not have permission to push branches to the upstream repository.

1. Open the upstream repository and select Fork.

2. Clone your fork, not the original repository:

   git clone https://github.com/your-username/forked-repository.git
   cd forked-repository
   

3. Add the original repository as upstream:

   git remote add upstream https://github.com/original-owner/repository.git
   git fetch upstream
   

4. Create a branch, commit, and push it to your fork:

   git switch -c analysis-update
   git add path/to/file
   git commit -m "feat: update analysis"
   git push -u origin analysis-update
   

5. On GitHub, open a pull request from the fork branch to the upstream default branch.

To synchronize later:

git switch main
git fetch upstream
git merge --ff-only upstream/main
git push origin main

7. Undo changes safely​

Choose the command based on where the mistake exists.

Discard an unstaged file edit​

git restore path/to/file

This permanently replaces the working copy with the last committed version.

Unstage a file but keep its edits​

git restore --staged path/to/file

Correct the most recent local commit​

If it has not been pushed:

git add path/to/fix
git commit --amend

Reverse a published commit​

Create a new commit that reverses the selected commit:

git log --oneline
git revert <commit-hash>

8. Useful inspection commands​

Final checklist​

Before pushing:

• no secrets or private data are staged;
• generated files are excluded unless intentionally versioned;
• the diff matches the commit message;
• tests or builds relevant to the change pass;
• the destination branch and remote are correct.

For more detail, use the official Git documentation and GitHub Docs.

These shortcuts cover the actions most useful in research and development work: finding files, navigating text, managing windows, capturing evidence, and recovering from an unresponsive app.

• Shortcuts can vary by app and keyboard layout.
• On newer keyboards, the Fn/Globe key may open the Character Viewer.
• Recovery shortcuts can discard unsaved work; read their warnings before using them.

Modifier-key legend​

Search, apps, and windows​

• ⌘ Space — open Spotlight.
• ⌘ Tab — switch to the next open app; keep holding Command to choose an app.
• ⌘ H — hide all windows of the front app.
• ⌥ ⌘ H — hide windows of every app except the front app.
• ⌘ M — minimize the front window.
• ⌘ W — close the front window or tab.
• ⌘ Q — quit the front app.
• ⌃ ⌘ Q — lock the screen.

Screenshots and screen recording​

• ⇧ ⌘ 3 — capture the entire screen.
• ⇧ ⌘ 4 — capture a selected region; press Space after invoking it to capture a window.
• ⇧ ⌘ 5 — open screenshot and screen-recording controls.

Use ⌃ with a screenshot shortcut when you want to copy the capture to the clipboard instead of saving a file.

Finder​

Files​

• ⌘ Delete — move selected items to the Trash.
• ⇧ ⌘ Delete — empty the Trash after confirmation.
• ⌘ I — show information for the selected item.
• ⌘ D — duplicate the selected item.
• Space — preview the selected item with Quick Look.

Navigation​

• ⌘ ↑ — open the enclosing folder.
• ⌘ ↓ — open the selected item.
• ⇧ ⌘ G — go to a folder by path.
• ⌘ 1, ⌘ 2, ⌘ 3, ⌘ 4 — switch among icon, list, column, and gallery views.

Text editing and navigation​

These work in most native text fields and many editors:

• ⌘ A — select all.
• ⌘ C, ⌘ X, ⌘ V — copy, cut, and paste.
• ⌘ Z — undo.
• ⇧ ⌘ Z — redo in apps that follow the standard convention.
• ⌥ ← / ⌥ → — move one word backward or forward.
• ⌘ ← / ⌘ → — move to the beginning or end of the current line.
• Fn Delete — forward delete on compact keyboards.

Safari and Chrome​

• ⌘ T — open a new tab.
• ⌘ W — close the current tab.
• ⇧ ⌘ T — reopen the most recently closed tab.
• ⌘ L — focus the address bar.
• ⌘ R — reload the page.
• ⌘ [ / ⌘ ] — go backward or forward in tab history.

Browser extensions and web apps may override some shortcuts.

Recovery and power controls​

• ⌥ ⌘ Esc — open Force Quit Applications.
• Press and hold the power button — force the Mac to turn off when it is unresponsive.
• ⌃ ⌘ Power — on supported built-in keyboards without Touch ID, force a restart without prompting to save open documents.
• ⌃ ⌥ ⌘ Power — on supported built-in keyboards without Touch ID, ask apps to quit and then shut down; apps with unsaved documents may prompt first.

Power-key behavior differs across Touch ID keyboards, external keyboards, and macOS versions. Prefer Apple menu → Shut Down or Restart whenever the system still responds.

Official reference​

Apple maintains the authoritative and most current list at Mac keyboard shortcuts.

This guide builds a personal portfolio with Docusaurus and publishes the generated static site to GitHub Pages. It covers the two details that cause most deployment failures: choosing the correct baseUrl and keeping the source branch separate from the generated gh-pages branch.

• Best for: portfolios, project documentation, publication lists, and technical notes
• Result: a version-controlled site with repeatable local and hosted builds
• Current baseline: Docusaurus 3 requires Node.js 20 or newer

Before you start​

Install or create:

• Node.js 20 or newer and npm
• Git
• a GitHub account
• a code editor

Check the local tools:

node --version
npm --version
git --version

The commands below use npm. Keep one package manager and its lockfile throughout the project.

1. Create the site​

Use the official project generator:

npx create-docusaurus@latest my-portfolio classic
cd my-portfolio
npm install
npm run start

The development server normally opens at http://localhost:3000. Changes to Markdown, React components, and CSS appear through hot reload.

The classic template includes:

my-portfolio/
├── blog/                  # dated Markdown or MDX posts
├── docs/                  # documentation and long-form pages
├── src/
│   ├── components/        # reusable React components
│   ├── css/custom.css     # site-wide styling
│   └── pages/             # standalone routes
├── static/                # files copied directly to the build
├── docusaurus.config.js
├── sidebars.js
└── package.json

There is no default npm run new blog command. Create a file such as blog/2026-07-16-field-workflow.md and add valid front matter.

2. Decide the GitHub Pages address​

The repository name determines the public path.

Configure docusaurus.config.js for one target. This user-site example preserves clean root URLs:

const config = {
  title: "My Portfolio",
  url: "https://<username>.github.io",
  baseUrl: "/",
  organizationName: "<username>",
  projectName: "<username>.github.io",
  deploymentBranch: "gh-pages",
  trailingSlash: false,
  // ...
};

export default config;