Reproducible data processing depends on preserving those details alongside the method. LgoPy blocks help by packaging a transformation with defined inputs, configurable parameters, and versioned code. In this tutorial, we will use a simple RGB-to-HSV conversion to show how to read plot images, save derived visualizations, and build a processing component that can be shared and reused across datasets in PhenoWorks.
LgoPy is an open-source Python library for building multimodal data science pipelines. It lets researchers package Python methods as blocks that can be installed, inspected, and combined in PhenoWorks.
Phenotyping studies often bring together field observations, images, sensor readings, and experimental metadata. Each may need a different processing method. A LgoPy block gives that method a defined input and output, along with its dependencies and documentation.
The idea is similar to building with Lego pieces. One block calculates a vegetation index; another summarizes measurements for each plot. When their inputs and outputs are compatible, the blocks can form a pipeline that a team can reuse across datasets.
Our example, blocks/image_analysis/image_2_hsv.py, reads the RGB images for a
plot and converts them to HSV: hue, saturation, and value. It then saves a
visualization of those channels as a PhenoWorks artifact, a derived file
associated with the processing run.
Hue represents color, saturation its intensity, and value its brightness. Viewing these channels separately can help you decide how to approach segmentation or feature extraction.
To make the channels viewable, the block maps H, S, and V to the red, green, and blue channels of a JPEG. The resulting colors show the HSV channel values, so they differ from the original photograph. These images are intended for visual inspection. For numerical measurements that require exact values, work from the original data or a lossless representation rather than the JPEG.
The implementation below comes from blocks/image_analysis/image_2_hsv.py:
from io import BytesIO
from typing import Annotated
from lgopy.core import Block
from PIL import Image as PILImage
import logging
class Image2HSV(Block):
"""Create visible HSV-channel JPEG artifacts from RGB plot images."""
name = "image_2_hsv"
display_name = "Image to HSV"
description = "Convert RGB image to HSV artifacts"
category = "Image Processing"
authors = ["PhenoWorks", "haruiz"]
tags = ["phenoworks", "rgb", "image-processing"]
version = "0.1.0"
logger = logging.getLogger(__name__)
def __init__(
self,
jpeg_quality: Annotated[int, "JPEG quality for saved HSV artifacts"] = 95,
) -> None:
super().__init__()
self._jpeg_quality = jpeg_quality
def call(self, dataset_item: dict) -> dict:
"""Convert RGB plot images into HSV-channel visualization artifacts.
Args:
dataset_item: Plot dataset item dictionary with plot metadata and assets grouped by modality.
Returns:
Dictionary with conversion status and processed asset counts.
"""
try:
plot_id = dataset_item.get("plot_id")
rgb_assets = dataset_item["assets"].get("rgb", [])
for rgb_asset in rgb_assets:
rgb_image = PILImage.open(rgb_asset["file_uri"])
self.logger.info(f"Processing plot {plot_id} with "
f"RGB asset {rgb_asset['file_uri']}")
# Store a visible HSV-channel visualization as JPEG.
hsv_image = rgb_image.convert("HSV")
hsv_visual = PILImage.merge("RGB", hsv_image.split())
buffer = BytesIO()
hsv_visual.save(buffer, format="JPEG", quality=self._jpeg_quality)
image_bytes = buffer.getvalue()
self.artifacts.save_artifact(
f"plot_{plot_id}_hsv_{rgb_asset['id']}.jpg",
data=image_bytes,
artifact_type='plot_hsv_image',
plot_id=plot_id if isinstance(plot_id, int) else None
)
return {
"status": "success",
"plot_id": plot_id,
"num_rgb_assets": len(rgb_assets),
}
except Exception as e:
self.logger.error(f"Error processing plot {plot_id}: {e}")
raise
if __name__ == '__main__':
Image2HSV.build(output_dir="image-2-hsv-block", format="zip")
Image2HSV inherits from LgoPy's Block class. The attributes at the top identify
it in the catalog: image_2_hsv is its name, Image to HSV its display label,
and 0.1.0 its version. The remaining metadata helps researchers find the method
and understand what it does before reading the code.
There is one configurable setting: jpeg_quality, which defaults to 95.
Its Annotated[...] declaration supplies a type and description for LgoPy's
schema. After initializing the base class with super().__init__(), the
constructor stores the chosen quality in self._jpeg_quality for use when
saving the JPEG.
When you adapt the example, keep these parameter descriptions and defaults in step with the implementation. They help other researchers configure the block correctly.
PhenoWorks passes plot-level blocks a dataset item with a plot identifier and
assets grouped by modality. This block expects RGB assets under assets["rgb"]:
{
"plot_id": 101,
"assets": {
"rgb": [
{"id": 1, "file_uri": "/path/to/plot_101_rgb.jpg"}
]
},
}
Each image needs an id and a readable file_uri. Because this block opens the
file directly with Pillow, use a local image path for the example below. Remote
assets and logical storage keys must first be resolved to files the block can
read.
For each RGB asset, call(...):
self._jpeg_quality.self.artifacts.save_artifact(...).A file named plot_101_hsv_1.jpg records both the plot and source asset identifiers.
The artifact has the type plot_hsv_image; when the plot identifier is an integer,
the block also passes it to the artifact store. The original image stays intact.
After processing, the block returns status, plot_id, and num_rgb_assets.
An empty RGB list produces a successful result with a count of zero. If processing
fails, the block logs the error and raises it to the caller.
This return value matters when you build a pipeline. The JPEG is saved through
the artifact store, while call(...) returns a status dictionary. A later step
must accept that dictionary or retrieve the saved image; a step expecting a plot
dataset item cannot use the summary directly.
You can test the block without a database or a running PhenoWorks server.
LgoPy provides in-memory artifact and metadata stores. Its artifact store exposes
save(...), while this block calls PhenoWorks' save_artifact(...) method, so a
small adapter connects the two.
The following example creates a temporary RGB image, runs the block, and checks the generated JPEG. Run it from the repository root in the project's Python environment:
from pathlib import Path
from tempfile import TemporaryDirectory
from lgopy.core.stores import InMemoryArtifactStore, InMemoryMetadataStore
from PIL import Image as PILImage
from blocks.image_analysis.image_2_hsv import Image2HSV
class TestArtifactStore(InMemoryArtifactStore):
"""Store artifact bytes in memory for local block tests."""
def save_artifact(
self, key: str, data: bytes, **attributes: object
) -> None:
"""Save an artifact without database persistence.
Args:
key: Artifact name used to retrieve the stored bytes.
data: Serialized artifact bytes.
**attributes: Database-specific attributes ignored by this test store.
"""
self.save(key, data)
artifacts = TestArtifactStore()
metadata = InMemoryMetadataStore()
block = Image2HSV()
block.artifacts = artifacts
block.metadata = metadata
with TemporaryDirectory() as directory:
image_path = Path(directory) / "rgb.jpg"
PILImage.new("RGB", (32, 32), color=(80, 150, 40)).save(image_path)
result = block.call({
"plot_id": 101,
"plot": {"name": "Plot 101"},
"assets": {
"rgb": [{"id": 1, "file_uri": str(image_path)}],
},
})
metadata.set("test.result", result)
print(result)
print("Artifacts:", list(artifacts.all()))
print("Metadata:", metadata.all())
with PILImage.open(artifacts.as_bytes_io("plot_101_hsv_1.jpg")) as image:
assert image.format == "JPEG"
assert image.size == (32, 32)
The test adapter retains the JPEG bytes but ignores database-specific attributes
such as artifact_type and plot_id. PhenoWorks supplies its own adapter during
pipeline execution to record those associations. Both test stores keep their
contents only in memory; the temporary input image is removed after processing.
Image2HSV does not write metadata itself. The example explicitly stores its
result under test.result to demonstrate the metadata store. To try a real image,
replace the temporary-image setup with an existing local path.
For this single-image example, a successful call saves the visualization and returns:
{"status": "success", "plot_id": 101, "num_rgb_assets": 1}
From the repository root, run the example's build entry point:
uv run python blocks/image_analysis/image_2_hsv.py
The __main__ section calls
Image2HSV.build(output_dir="image-2-hsv-block", format="zip"), creating a
package directory and a ZIP archive alongside it. The builder can replace an
existing output directory, so keep your source files elsewhere.
Install the generated ZIP from Analysis Modules, or install the package directory with the CLI:
phenoworks analysis-blocks install image-2-hsv-block
phenoworks analysis-blocks source image_2_hsv --version 0.1.0
phenoworks analysis-blocks requirements image_2_hsv --version 0.1.0
Once installed, inspect the package and its requirements in PhenoWorks. To
produce the visualizations, select a compatible dataset, set jpeg_quality,
and run the block in a dataset pipeline. The build command only packages the
method. The current script also runs the local smoke test after building;
processing a dataset starts when you run the installed block in a pipeline.
The same structure can support a vegetation-index calculation, a canopy-cover measurement, or a summary of image-channel statistics. The processing method changes, but the block still reads a defined input, saves its outputs, and returns a result that other code can use.
Let the next research task guide the output format. Images support visual inspection; measurements and tables support further analysis. Clear input and output descriptions make it easier for another researcher to connect your block to a pipeline and apply the method to a new dataset.
]]>The interactive diagram on our landing page follows this workflow from data to scientific discovery. Here is how its four stages fit together.
Start by organizing your field trials into projects, studies, datasets, and plots. Bring UAV and satellite imagery, sensor readings, field observations, metadata, and treatment labels together, then visualize supported images before choosing how to process them.
Research documents belong here too. Keep PDFs, manuscript drafts, reference papers, and protocols alongside the experiments they describe. The platform can also be extended to support other modalities, such as laboratory measurements and genomic data.
Move from data ingestion and quality control to feature extraction and analysis results. LgoPy blocks turn raw data into structured features, such as vegetation indices and canopy-cover measurements, that you can use in downstream analysis.
Like Lego pieces, each block performs one focused task with defined inputs and outputs. Connect compatible blocks into pipelines you can share and reuse across datasets. For example, an image-processing block can prepare images for a compatible feature-extraction step. Available methods depend on the installed block catalog.
Follow pipeline progress, inspect logs, and review the generated images, masks, summaries, and tables. These outputs stay connected to their source data and processing workflow.
Connect images, extracted features, figures, tables, model results, methods, and documents into a shared research knowledge base. Keep the evidence together so you can find relevant datasets, trace how measurements were produced, compare results, and download files for further work.
This lays the foundation for multimodal RAG: retrieving relevant context from visual, numerical, and written evidence to support an assistant's answers. What the agent can retrieve depends on the connected tools and indexing available.
Work with the PhenoWorks Agent (phenoworks-agent) to process images, extract features, and analyze data using available LgoPy blocks. Describe the task in your own words:
Can you calculate NDVI for my dataset?
Can you apply histogram equalization to the RGB images in my dataset?
The agent can help choose a suitable method, check its inputs, run a compatible pipeline, and retrieve the results. You can then ask it to interpret differences across plots or draft a preliminary-data section from selected results.
PhenoWorks MCP (phenoworks-mcp) provides the Model Context Protocol connection between compatible AI assistants and the PhenoWorks API. Its tools support finding datasets, inspecting analysis blocks, validating and running pipelines, tracking jobs, and retrieving outputs within the user's access permissions.
Learn more about the PhenoWorks Agent and its connected tools.
The options at the bottom of the diagram show what this workflow can support:
For example: “Can you draft a preliminary-data section for my grant proposal using these canopy-cover results?” Researchers review the interpretation and supporting evidence, then refine the draft for their audience.
Research feeds back into the next workflow. Add new observations, review unexpected results, refine your analysis blocks, and compare the revised outputs. This cycle connects each round of data collection and analysis with the questions that come next.
We will use this blog to share release notes, tutorials, and development updates as PhenoWorks evolves.
Interested in PhenoWorks? Express your interest through our Google Form.
]]>The initial documentation content keeps the same major sections: getting started, software overview, features, tutorials, deployment, FAQ, and troubleshooting.
Future updates can be published here as blog posts while the docs remain focused on stable user and developer guidance.
]]>