traitly 0.1.0__py3-none-any.whl

traitly/__init__.py

@@ -0,0 +1,39 @@
+# traitly/__init__.py
+"""
+Traitly: Phenotyping analysis of fruits in images using computer vision.
+"""
+import re
+from importlib.metadata import version, metadata, PackageNotFoundError
+
+try:
+    _meta = metadata("traitly")
+    __version__ = version("traitly")
+    
+    _raw = _meta.get("Author-email") or ""
+    # Separar por coma fuera de los < >
+    _entries = re.split(r",\s*(?=[^<>]*(?:<|$))", _raw)
+    __authors__ = [
+        re.match(r"^(.*?)\s*<", a).group(1).strip()
+        for a in _entries if "<" in a
+    ]
+    __author__ = ", ".join(__authors__)
+
+except PackageNotFoundError:
+    __version__ = "unknown"
+    __authors__ = []
+    __author__ = "unknown"
+
+
+# Import functions from utils
+from .utils.basic_functions import (
+    load_img,
+    plot_img
+)
+
+__all__ = [
+    '__version__',
+    '__author__',
+    '__authors__',
+    'load_img',
+    'plot_img'
+]

traitly/cli.py

@@ -0,0 +1,380 @@
+# traitly/cli.py
+"""
+Command-line interface for Traitly fruit phenotyping.
+
+Provides the ``traitly`` entry point for running internal and external
+fruit analysis pipelines directly from the terminal, on single images
+or entire folders.
+
+Usage
+-----
+.. code-block:: bash
+
+    traitly --fruit_internal -i PATH [-o PATH] [--json PATH] [--num_cores N]
+    traitly --fruit_external -i PATH [-o PATH] [--json PATH] [--num_cores N]
+
+For folder inputs, delegates to
+:meth:`~traitly.fruit_phenotyping.internal_analysis.FruitInternalAnalyzer.analyze_folder`
+or
+:meth:`~traitly.fruit_phenotyping.external_analysis.FruitExternalAnalyzer.analyze_folder`.
+For single images, delegates to
+:meth:`~traitly.fruit_phenotyping.internal_analysis.FruitInternalAnalyzer.process_single_file`.
+"""
+
+import argparse
+import sys
+import os
+from pathlib import Path
+
+try:
+    from tabulate import tabulate as _tabulate
+    def _fmt_examples(rows):
+        return _tabulate(rows, tablefmt='plain')
+except ImportError:
+    def _fmt_examples(rows):
+        return "\n".join(f"  {r[0]}" for r in rows)
+
+
+# ============================================================================
+# Parser
+# ============================================================================
+
+def create_parser() -> argparse.ArgumentParser:
+    """
+    Build and return the CLI argument parser for Traitly.
+
+    Defines a mutually exclusive mode group (``--fruit_internal`` /
+    ``--fruit_external``), required and optional arguments, and a
+    formatted epilog with usage examples.
+
+    Returns
+    -------
+    argparse.ArgumentParser
+        Configured parser ready to call ``.parse_args()`` on.
+    """
+    parser = argparse.ArgumentParser(
+        prog='traitly',
+        description='Traitly - Fruit Phenotyping Tool',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="\n".join([
+            "",
+            "Examples:",
+            _fmt_examples([
+                ("  # Internal structure analysis (single image or folder)",),
+                ("  traitly --fruit_internal -i tests/sample_data/",),
+                ("  traitly --fruit_internal -i tests/sample_data/ -o results/ --num_cores 4",),
+                ("  traitly --fruit_internal -i tests/sample_data/ --json config.json",),
+                ("",),
+                ("  # External analysis (single image or folder)",),
+                ("  traitly --fruit_external -i tests/sample_data/",),
+                ("  traitly --fruit_external -i tests/sample_data/ -o results/ --json config.json --num_cores 4",),
+            ]),
+            "",
+            "For more info: https://github.com/mariameraz/traitly",
+            "",
+        ])
+    )
+
+    # Mode (mutually exclusive)
+    mode_group = parser.add_mutually_exclusive_group(required=True)
+    mode_group.add_argument(
+        '--fruit_internal',
+        action='store_true',
+        help='Analyze internal fruit structure (locules, pericarp, symmetry)'
+    )
+    mode_group.add_argument(
+        '--fruit_external',
+        action='store_true',
+        help='Analyze external fruit structure (morphology, color)'
+    )
+
+    # Required
+    parser.add_argument(
+        '-i', '--input',
+        type=str,
+        required=True,
+        metavar='PATH',
+        help='Path to image file or folder'
+    )
+
+    # Optional
+    parser.add_argument(
+        '-o', '--output',
+        type=str,
+        default=None,
+        metavar='PATH',
+        help='Output directory (default: <input>/Results/)'
+    )
+
+    parser.add_argument(
+        '--json',
+        type=str,
+        default=None,
+        metavar='PATH',
+        help='Path to JSON config file with analysis parameters'
+    )
+
+    parser.add_argument(
+        '--num_cores',
+        type=int,
+        default=1,
+        metavar='N',
+        help='Number of CPU cores for parallel processing (default: 1)'
+    )
+
+    parser.add_argument(
+        '--no_morphology',
+        action='store_true',
+        help='Skip morphology analysis'
+    )
+
+    parser.add_argument(
+        '--no_color',
+        action='store_true',
+        help='Skip color analysis'
+    )
+
+    parser.add_argument(
+        '--version',
+        action='version',
+        version='%(prog)s 0.1.0'
+    )
+
+    return parser
+
+
+# ============================================================================
+# Helpers
+# ============================================================================
+
+def _validate_input(path_str: str) -> Path:
+    """
+    Validate that the input path exists and return it as a :class:`Path`.
+
+    Prints an error message and calls ``sys.exit(1)`` if the path does
+    not exist.
+
+    Parameters
+    ----------
+    path_str : str
+        Raw input path string from the CLI argument.
+
+    Returns
+    -------
+    Path
+        Validated :class:`~pathlib.Path` object.
+    """
+    path = Path(path_str)
+    if not path.exists():
+        print(f">> Error: Path does not exist: {path_str}")
+        sys.exit(1)
+    return path
+
+
+def _validate_json(json_str: str) -> str:
+    """
+    Validate that the JSON config file exists if provided.
+
+    Prints an error message and calls ``sys.exit(1)`` if ``json_str``
+    is not ``None`` and the file does not exist.
+
+    Parameters
+    ----------
+    json_str : str or None
+        Path to the JSON config file, or ``None`` if not provided.
+
+    Returns
+    -------
+    str or None
+        The original ``json_str`` if valid, or ``None``.
+    """
+    if json_str is not None and not Path(json_str).exists():
+        print(f">> Error: JSON config file does not exist: {json_str}")
+        sys.exit(1)
+    return json_str
+
+
+# ============================================================================
+# Internal analysis
+# ============================================================================
+
+def run_internal(args: argparse.Namespace) -> None:
+    """
+    Run the internal fruit analysis pipeline from the CLI.
+
+    Instantiates :class:`~traitly.fruit_phenotyping.internal_analysis.FruitInternalAnalyzer`
+    and dispatches to:
+
+    - :meth:`~traitly.fruit_phenotyping.internal_analysis.FruitInternalAnalyzer.analyze_folder`
+      when ``args.input`` is a directory.
+    - :meth:`~traitly.fruit_phenotyping.internal_analysis.FruitInternalAnalyzer.process_single_file`
+      when ``args.input`` is a single image file.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed CLI arguments containing ``input``, ``output``, ``json``,
+        ``num_cores``, ``no_morphology``, and ``no_color``.
+    """
+    from traitly.fruit_phenotyping.internal_analysis import FruitInternalAnalyzer
+
+    path     = _validate_input(args.input)
+    json_path = _validate_json(args.json)
+
+    try:
+        analyzer = FruitInternalAnalyzer(str(path))
+    except Exception as e:
+        print(f">> Error initializing FruitInternalAnalyzer: {e}")
+        sys.exit(1)
+
+    analyze_morphology = not args.no_morphology
+    analyze_color      = not args.no_color
+
+    if path.is_dir():
+        try:
+            analyzer.analyze_folder(
+                analyze_morphology=analyze_morphology,
+                analyze_color=analyze_color,
+                json_path=json_path,
+                output_path=args.output,
+                num_cores=args.num_cores,
+                verbose=True,
+            )
+        except Exception as e:
+            print(f">> Error during internal folder analysis: {e}")
+            import traceback; traceback.print_exc()
+            sys.exit(1)
+
+    else:
+        # Single image — process_single_file
+        import json as _json
+        config = {}
+        if json_path:
+            with open(json_path, 'r', encoding='utf-8') as f:
+                config = _json.load(f) or {}
+
+        try:
+            analyzer.load_image(plot=False)
+            df_m, df_c, err, n_fruits, ann_img = analyzer.process_single_file(
+                config=config,
+                json_path=None,
+                analyze_morphology=analyze_morphology,
+                analyze_color=analyze_color,
+                save_image=True,
+                output_path=args.output,
+            )
+            if err:
+                print(f">> Error processing image: {err.get('status', 'Unknown error')}")
+                sys.exit(1)
+            print(f"Done. Fruits detected: {n_fruits}")
+        except Exception as e:
+            print(f">> Error during internal image analysis: {e}")
+            import traceback; traceback.print_exc()
+            sys.exit(1)
+
+
+# ============================================================================
+# External analysis
+# ============================================================================
+
+def run_external(args: argparse.Namespace) -> None:
+    """
+    Run the external fruit analysis pipeline from the CLI.
+
+    Instantiates :class:`~traitly.fruit_phenotyping.external_analysis.FruitExternalAnalyzer`
+    and dispatches to:
+
+    - :meth:`~traitly.fruit_phenotyping.external_analysis.FruitExternalAnalyzer.analyze_folder`
+      when ``args.input`` is a directory.
+    - :meth:`~traitly.fruit_phenotyping.external_analysis.FruitExternalAnalyzer.process_single_file`
+      when ``args.input`` is a single image file.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Parsed CLI arguments containing ``input``, ``output``, ``json``,
+        ``num_cores``, ``no_morphology``, and ``no_color``.
+    """
+    from traitly.fruit_phenotyping.external_analysis import FruitExternalAnalyzer
+
+    path      = _validate_input(args.input)
+    json_path = _validate_json(args.json)
+
+    try:
+        analyzer = FruitExternalAnalyzer(str(path))
+    except Exception as e:
+        print(f">> Error initializing FruitExternalAnalyzer: {e}")
+        sys.exit(1)
+
+    analyze_morphology = not args.no_morphology
+    analyze_color      = not args.no_color
+
+    if path.is_dir():
+        try:
+            analyzer.analyze_folder(
+                analyze_morphology=analyze_morphology,
+                analyze_color=analyze_color,
+                json_path=json_path,
+                output_path=args.output,
+                num_cores=args.num_cores,
+                verbose=True,
+            )
+        except Exception as e:
+            print(f">> Error during external folder analysis: {e}")
+            import traceback; traceback.print_exc()
+            sys.exit(1)
+
+    else:
+        # Single image
+        import json as _json
+        config = {}
+        if json_path:
+            with open(json_path, 'r', encoding='utf-8') as f:
+                config = _json.load(f) or {}
+
+        try:
+            analyzer.load_image(plot=False)
+            df_m, df_c, err, n_fruits, ann_img = analyzer.process_single_file(
+                config=config,
+                json_path=None,
+                analyze_morphology=analyze_morphology,
+                analyze_color=analyze_color,
+                save_image=True,
+                output_path=args.output,
+            )
+            if err:
+                print(f">> Error processing image: {err.get('status', 'Unknown error')}")
+                sys.exit(1)
+            print(f"Done. Fruits detected: {n_fruits}")
+        except Exception as e:
+            print(f">> Error during external image analysis: {e}")
+            import traceback; traceback.print_exc()
+            sys.exit(1)
+
+
+# ============================================================================
+# Entry point
+# ============================================================================
+
+def main() -> None:
+    """
+    Entry point for the ``traitly`` CLI command.
+
+    Parses arguments via :func:`create_parser` and dispatches to
+    :func:`run_internal` or :func:`run_external` based on the selected
+    mode flag. Prints help and exits cleanly if neither flag is set.
+    """
+    parser = create_parser()
+    args   = parser.parse_args()
+
+    if args.fruit_internal:
+        run_internal(args)
+    elif args.fruit_external:
+        run_external(args)
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

traitly/fruit_phenotyping/__init__.py

@@ -0,0 +1,20 @@
+from .internal_analysis import FruitInternalAnalyzer
+from .external_analysis import FruitExternalAnalyzer
+
+from .color_plot import (plot_color_scatter, 
+                        plot_color_histogram,
+                        plot_color_correlation,
+                        plot_dark_threshold,
+                        plot_tissue_colors)
+
+from .color_analysis import calculate_hue_index
+
+__all__ = ['FruitInternalAnalyzer', 
+           'FruitExternalAnalyzer',
+           'plot_color_scatter',
+           'plot_color_histogram',
+           'plot_color_correlation',
+           'calculate_hue_index',
+           'plot_dark_threshold',
+           'plot_tissue_colors']
+

traitly/fruit_phenotyping/analysis_parameters.py

@@ -0,0 +1,192 @@
+# traitly/fruit_phenotyping/analysis_parameters.py
+"""
+Analysis metadata tracking for traitly `FruitInternalAnalyzer` and
+`FruitExternalAnalyzer` pipelines.
+
+Provides the :class:`AnalysisParameters` dataclass for capturing and
+exporting the processing parameters used in each stage of the fruit
+phenotyping pipeline, supporting reproducibility and traceability.
+"""
+
+# ============================================================================
+# STANDARD LIBRARY
+# ============================================================================
+import importlib.metadata
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from typing import Any, Dict
+
+# ============================================================================
+# INTERNAL IMPORTS
+# ============================================================================
+from traitly import __version__
+
+# ============================================================================
+# Save parameters used and session information as txt and json files
+# ============================================================================
+
+
+@dataclass
+class AnalysisParameters:
+    """
+    Save and report processing parameters for each analysis step.
+
+    Captures the parameters used in each stage of the analysis pipeline
+    and provides methods to export them as formatted text or JSON for
+    reproducibility and traceability.
+
+    Attributes
+    ----------
+    setup_measurements_params : Dict[str, Any]
+        Parameters used in the setup measurements step.
+    generate_fruit_mask_params : Dict[str, Any]
+        Parameters used in the fruit mask generation step.
+    enhance_locule_contrast_params : Dict[str, Any]
+        Parameters used in the locule contrast enhancement step.
+    generate_locule_mask_params : Dict[str, Any]
+        Parameters used in the locule mask generation step.
+    detect_fruits_params : Dict[str, Any]
+        Parameters used in the fruit detection step.
+    analyze_morphology_params : Dict[str, Any]
+        Parameters used in the morphology analysis step.
+    analyze_color_params : Dict[str, Any]
+        Parameters used in the color analysis step.
+    """
+
+    # Create a dictionary for each step
+    img_params: Dict[str, Any] = field(default_factory=dict)
+    setup_measurements_params: Dict[str, Any] = field(default_factory=dict)
+    generate_fruit_mask_params: Dict[str, Any] = field(default_factory=dict)
+    enhance_locule_contrast_params: Dict[str, Any] = field(default_factory=dict)
+    generate_locule_mask_params: Dict[str, Any] = field(default_factory=dict)
+    detect_fruits_params: Dict[str, Any] = field(default_factory=dict)
+    analyze_morphology_params: Dict[str, Any] = field(default_factory=dict)
+    analyze_color_params: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert dataclass fields to a dictionary.
+
+        Returns
+        -------
+        Dict[str, Any]
+            Dictionary representation of all analysis parameter fields.
+        """
+        return asdict(self)
+
+    def to_formatted_string(self) -> str:
+        """
+        Return analysis parameters as a readable formatted string.
+
+        Includes version info, run date, per-step parameters, and
+        dependency versions.
+
+        Returns
+        -------
+        str
+            Formatted string with all processing parameters and metadata.
+        """
+
+        date = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+        lines = [
+            "=" * 70,
+            "ANALYSIS PROCESSING PARAMETERS",
+            "=" * 70,
+            f"traitly: v{__version__}",
+            f"run date: {date}",
+            f"image: {self.img_params.get('img_path', 'not set')}",
+        ]
+
+        sections = {
+            "SETUP_MEASUREMENTS": self.setup_measurements_params,
+            "GENERATE_FRUIT_MASK": self.generate_fruit_mask_params,
+            "ENHANCE_LOCULE_CONTRAST": self.enhance_locule_contrast_params,
+            "GENERATE_LOCULE_MASK": self.generate_locule_mask_params,
+            "DETECT_FRUITS": self.detect_fruits_params,
+            "ANALYZE_MORPHOLOGY": self.analyze_morphology_params,
+            "ANALYZE_COLOR": self.analyze_color_params,
+        }
+        for title, params in sections.items():
+            if params:
+                lines.append(f"\n{title}:")
+                for key, value in params.items():
+                    lines.append(f"   - {key}: {value}")
+
+        lines.append("\n" + "=" * 70)
+
+        # Version summary
+        lines.append("\nDEPENDENCIES:")
+        for pkg, version in self.get_package_versions().items():
+            lines.append(f"   - {pkg}: {version}")
+
+        return "\n".join(lines)
+
+    def save_to_file(self, filepath: str) -> None:
+        """
+        Save formatted parameters to a plain text file.
+
+        Parameters
+        ----------
+        filepath : str
+            Destination path for the output .txt file.
+
+        Raises
+        ------
+        OSError
+            If the file cannot be created or written to ``filepath``.
+        """
+        with open(filepath, "w", encoding="utf-8") as f:
+            f.write(self.to_formatted_string())
+
+    def save_to_json(self, filepath: str) -> None:
+        """
+        Save parameters to a JSON file.
+
+        Parameters
+        ----------
+        filepath : str
+            Destination path for the output .json file.
+
+        Raises
+        ------
+        OSError
+            If the file cannot be created or written to ``filepath``.
+        """
+        data = self.to_dict()
+
+        with open(filepath, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+    def get_package_versions(self) -> Dict[str, str]:
+        """
+        Return installed versions of key dependencies used by traitly.
+
+        Returns
+        -------
+        Dict[str, str]
+            Dictionary mapping package names to their installed version
+            strings. Includes Python version under the key ``'python'``.
+            Packages not found are reported as ``'not installed'``.
+        """
+        packages = [
+            "opencv-contrib-python",
+            "numpy",
+            "pandas",
+            "scipy",
+            "matplotlib",
+            "tqdm",
+            "psutil",
+            "easyocr",
+            "PyMuPDF",
+            "ultralytics",
+        ]
+        versions = {"python": sys.version.split()[0]}
+        for pkg in packages:
+            try:
+                versions[pkg] = importlib.metadata.version(pkg)
+            except importlib.metadata.PackageNotFoundError:
+                versions[pkg] = "not installed"
+        return versions