Zum Inhalt springen

Referenz f├╝r ultralytics/cfg/__init__.py

Hinweis

Diese Datei ist verf├╝gbar unter https://github.com/ultralytics/ ultralytics/blob/main/ ultralytics/cfg/init.py. Wenn du ein Problem entdeckst, hilf bitte mit, es zu beheben, indem du einen Pull Request ­čŤá´ŞĆ einreichst. Vielen Dank ­čÖĆ!



ultralytics.cfg.cfg2dict(cfg)

Konvertiert ein Konfigurationsobjekt in ein W├Ârterbuch, egal ob es sich um einen Dateipfad, einen String oder ein SimpleNamespace-Objekt handelt.

Parameter:

Name Typ Beschreibung Standard
cfg str | Path | dict | SimpleNamespace

Konfigurationsobjekt, das in ein W├Ârterbuch umgewandelt werden soll.

erforderlich

Retouren:

Name Typ Beschreibung
cfg dict

Konfigurationsobjekt im W├Ârterbuchformat.

Quellcode in ultralytics/cfg/__init__.py
def cfg2dict(cfg):
    """
    Convert a configuration object to a dictionary, whether it is a file path, a string, or a SimpleNamespace object.

    Args:
        cfg (str | Path | dict | SimpleNamespace): Configuration object to be converted to a dictionary.

    Returns:
        cfg (dict): Configuration object in dictionary format.
    """
    if isinstance(cfg, (str, Path)):
        cfg = yaml_load(cfg)  # load dict
    elif isinstance(cfg, SimpleNamespace):
        cfg = vars(cfg)  # convert to dict
    return cfg



ultralytics.cfg.get_cfg(cfg=DEFAULT_CFG_DICT, overrides=None)

Lade und f├╝hre Konfigurationsdaten aus einer Datei oder einem W├Ârterbuch zusammen.

Parameter:

Name Typ Beschreibung Standard
cfg str | Path | Dict | SimpleNamespace

Konfigurationsdaten.

DEFAULT_CFG_DICT
overrides str | Dict | optional

├ťberschreibt in Form eines Dateinamens oder eines W├Ârterbuchs. Die Voreinstellung ist Keine.

None

Retouren:

Typ Beschreibung
SimpleNamespace

Namespace f├╝r Trainingsargumente.

Quellcode in ultralytics/cfg/__init__.py
def get_cfg(cfg: Union[str, Path, Dict, SimpleNamespace] = DEFAULT_CFG_DICT, overrides: Dict = None):
    """
    Load and merge configuration data from a file or dictionary.

    Args:
        cfg (str | Path | Dict | SimpleNamespace): Configuration data.
        overrides (str | Dict | optional): Overrides in the form of a file name or a dictionary. Default is None.

    Returns:
        (SimpleNamespace): Training arguments namespace.
    """
    cfg = cfg2dict(cfg)

    # Merge overrides
    if overrides:
        overrides = cfg2dict(overrides)
        if "save_dir" not in cfg:
            overrides.pop("save_dir", None)  # special override keys to ignore
        check_dict_alignment(cfg, overrides)
        cfg = {**cfg, **overrides}  # merge cfg and overrides dicts (prefer overrides)

    # Special handling for numeric project/name
    for k in "project", "name":
        if k in cfg and isinstance(cfg[k], (int, float)):
            cfg[k] = str(cfg[k])
    if cfg.get("name") == "model":  # assign model to 'name' arg
        cfg["name"] = cfg.get("model", "").split(".")[0]
        LOGGER.warning(f"WARNING ÔÜá´ŞĆ 'name=model' automatically updated to 'name={cfg['name']}'.")

    # Type and Value checks
    for k, v in cfg.items():
        if v is not None:  # None values may be from optional args
            if k in CFG_FLOAT_KEYS and not isinstance(v, (int, float)):
                raise TypeError(
                    f"'{k}={v}' is of invalid type {type(v).__name__}. "
                    f"Valid '{k}' types are int (i.e. '{k}=0') or float (i.e. '{k}=0.5')"
                )
            elif k in CFG_FRACTION_KEYS:
                if not isinstance(v, (int, float)):
                    raise TypeError(
                        f"'{k}={v}' is of invalid type {type(v).__name__}. "
                        f"Valid '{k}' types are int (i.e. '{k}=0') or float (i.e. '{k}=0.5')"
                    )
                if not (0.0 <= v <= 1.0):
                    raise ValueError(f"'{k}={v}' is an invalid value. " f"Valid '{k}' values are between 0.0 and 1.0.")
            elif k in CFG_INT_KEYS and not isinstance(v, int):
                raise TypeError(
                    f"'{k}={v}' is of invalid type {type(v).__name__}. " f"'{k}' must be an int (i.e. '{k}=8')"
                )
            elif k in CFG_BOOL_KEYS and not isinstance(v, bool):
                raise TypeError(
                    f"'{k}={v}' is of invalid type {type(v).__name__}. "
                    f"'{k}' must be a bool (i.e. '{k}=True' or '{k}=False')"
                )

    # Return instance
    return IterableSimpleNamespace(**cfg)



ultralytics.cfg.get_save_dir(args, name=None)

Gib save_dir zur├╝ck, wie es aus den Argumenten train/val/predict erstellt wurde.

Quellcode in ultralytics/cfg/__init__.py
def get_save_dir(args, name=None):
    """Return save_dir as created from train/val/predict arguments."""

    if getattr(args, "save_dir", None):
        save_dir = args.save_dir
    else:
        from ultralytics.utils.files import increment_path

        project = args.project or (ROOT.parent / "tests/tmp/runs" if TESTS_RUNNING else RUNS_DIR) / args.task
        name = name or args.name or f"{args.mode}"
        save_dir = increment_path(Path(project) / name, exist_ok=args.exist_ok if RANK in (-1, 0) else True)

    return Path(save_dir)



ultralytics.cfg._handle_deprecation(custom)

Hardcodierte Funktion zur Behandlung veralteter Konfigurationsschl├╝ssel.

Quellcode in ultralytics/cfg/__init__.py
def _handle_deprecation(custom):
    """Hardcoded function to handle deprecated config keys."""

    for key in custom.copy().keys():
        if key == "boxes":
            deprecation_warn(key, "show_boxes")
            custom["show_boxes"] = custom.pop("boxes")
        if key == "hide_labels":
            deprecation_warn(key, "show_labels")
            custom["show_labels"] = custom.pop("hide_labels") == "False"
        if key == "hide_conf":
            deprecation_warn(key, "show_conf")
            custom["show_conf"] = custom.pop("hide_conf") == "False"
        if key == "line_thickness":
            deprecation_warn(key, "line_width")
            custom["line_width"] = custom.pop("line_thickness")

    return custom



ultralytics.cfg.check_dict_alignment(base, custom, e=None)

Diese Funktion pr├╝ft, ob die Schl├╝ssel einer benutzerdefinierten Konfigurationsliste und einer Basiskonfigurationsliste nicht ├╝bereinstimmen. Wenn nicht ├╝bereinstimmende Schl├╝ssel gefunden werden, gibt die Funktion ├Ąhnliche Schl├╝ssel aus der Basisliste aus und beendet das Programm.

Parameter:

Name Typ Beschreibung Standard
custom dict

ein W├Ârterbuch mit benutzerdefinierten Konfigurationsoptionen

erforderlich
base dict

ein W├Ârterbuch der Grundkonfigurationsoptionen

erforderlich
e Error

Ein optionaler Fehler, der von der aufrufenden Funktion ├╝bergeben wird.

None
Quellcode in ultralytics/cfg/__init__.py
def check_dict_alignment(base: Dict, custom: Dict, e=None):
    """
    This function checks for any mismatched keys between a custom configuration list and a base configuration list. If
    any mismatched keys are found, the function prints out similar keys from the base list and exits the program.

    Args:
        custom (dict): a dictionary of custom configuration options
        base (dict): a dictionary of base configuration options
        e (Error, optional): An optional error that is passed by the calling function.
    """
    custom = _handle_deprecation(custom)
    base_keys, custom_keys = (set(x.keys()) for x in (base, custom))
    mismatched = [k for k in custom_keys if k not in base_keys]
    if mismatched:
        from difflib import get_close_matches

        string = ""
        for x in mismatched:
            matches = get_close_matches(x, base_keys)  # key list
            matches = [f"{k}={base[k]}" if base.get(k) is not None else k for k in matches]
            match_str = f"Similar arguments are i.e. {matches}." if matches else ""
            string += f"'{colorstr('red', 'bold', x)}' is not a valid YOLO argument. {match_str}\n"
        raise SyntaxError(string + CLI_HELP_MSG) from e



ultralytics.cfg.merge_equals_args(args)

F├╝gt Argumente um isolierte '='-Argumente in einer Liste von Zeichenketten zusammen. Die Funktion ber├╝cksichtigt F├Ąlle, in denen das erste Argument mit '=' endet oder das zweite mit '=' beginnt, sowie wenn das mittlere Argument ein Gleichheitszeichen ist.

Parameter:

Name Typ Beschreibung Standard
args List[str]

Eine Liste von Strings, bei der jedes Element ein Argument ist.

erforderlich

Retouren:

Typ Beschreibung
List[str]

Eine Liste von Zeichenketten, bei denen die Argumente um ein isoliertes '=' herum zusammengef├╝hrt werden.

Quellcode in ultralytics/cfg/__init__.py
def merge_equals_args(args: List[str]) -> List[str]:
    """
    Merges arguments around isolated '=' args in a list of strings. The function considers cases where the first
    argument ends with '=' or the second starts with '=', as well as when the middle one is an equals sign.

    Args:
        args (List[str]): A list of strings where each element is an argument.

    Returns:
        (List[str]): A list of strings where the arguments around isolated '=' are merged.
    """
    new_args = []
    for i, arg in enumerate(args):
        if arg == "=" and 0 < i < len(args) - 1:  # merge ['arg', '=', 'val']
            new_args[-1] += f"={args[i + 1]}"
            del args[i + 1]
        elif arg.endswith("=") and i < len(args) - 1 and "=" not in args[i + 1]:  # merge ['arg=', 'val']
            new_args.append(f"{arg}{args[i + 1]}")
            del args[i + 1]
        elif arg.startswith("=") and i > 0:  # merge ['arg', '=val']
            new_args[-1] += arg
        else:
            new_args.append(arg)
    return new_args



ultralytics.cfg.handle_yolo_hub(args)

Bearbeite Ultralytics HUB Befehlszeilenschnittstelle (CLI) Befehle.

Diese Funktion verarbeitet Ultralytics HUB CLI Befehle wie Login und Logout. Sie sollte aufgerufen werden, wenn ein Skript mit Argumenten f├╝r die HUB Authentifizierung ausgef├╝hrt wird.

Parameter:

Name Typ Beschreibung Standard
args List[str]

Eine Liste von Befehlszeilenargumenten

erforderlich
Beispiel
python my_script.py hub login your_api_key
Quellcode in ultralytics/cfg/__init__.py
def handle_yolo_hub(args: List[str]) -> None:
    """
    Handle Ultralytics HUB command-line interface (CLI) commands.

    This function processes Ultralytics HUB CLI commands such as login and logout.
    It should be called when executing a script with arguments related to HUB authentication.

    Args:
        args (List[str]): A list of command line arguments

    Example:
        ```bash
        python my_script.py hub login your_api_key
        ```
    """
    from ultralytics import hub

    if args[0] == "login":
        key = args[1] if len(args) > 1 else ""
        # Log in to Ultralytics HUB using the provided API key
        hub.login(key)
    elif args[0] == "logout":
        # Log out from Ultralytics HUB
        hub.logout()



ultralytics.cfg.handle_yolo_settings(args)

Bearbeite die Befehle der Befehlszeilenschnittstelle YOLO Einstellungen (CLI).

Diese Funktion verarbeitet YOLO Einstellungen CLI Befehle wie Reset. Sie sollte aufgerufen werden, wenn ein Skript mit Argumenten f├╝r die Verwaltung der YOLO Einstellungen ausgef├╝hrt wird.

Parameter:

Name Typ Beschreibung Standard
args List[str]

Eine Liste von Befehlszeilenargumenten f├╝r die Verwaltung von YOLO Einstellungen.

erforderlich
Beispiel
python my_script.py yolo settings reset
Quellcode in ultralytics/cfg/__init__.py
def handle_yolo_settings(args: List[str]) -> None:
    """
    Handle YOLO settings command-line interface (CLI) commands.

    This function processes YOLO settings CLI commands such as reset.
    It should be called when executing a script with arguments related to YOLO settings management.

    Args:
        args (List[str]): A list of command line arguments for YOLO settings management.

    Example:
        ```bash
        python my_script.py yolo settings reset
        ```
    """
    url = "https://docs.ultralytics.com/quickstart/#ultralytics-settings"  # help URL
    try:
        if any(args):
            if args[0] == "reset":
                SETTINGS_YAML.unlink()  # delete the settings file
                SETTINGS.reset()  # create new settings
                LOGGER.info("Settings reset successfully")  # inform the user that settings have been reset
            else:  # save a new setting
                new = dict(parse_key_value_pair(a) for a in args)
                check_dict_alignment(SETTINGS, new)
                SETTINGS.update(new)

        LOGGER.info(f"­čĺí Learn about settings at {url}")
        yaml_print(SETTINGS_YAML)  # print the current settings
    except Exception as e:
        LOGGER.warning(f"WARNING ÔÜá´ŞĆ settings error: '{e}'. Please see {url} for help.")



ultralytics.cfg.handle_explorer()

├ľffne den Ultralytics Explorer GUI.

Quellcode in ultralytics/cfg/__init__.py
def handle_explorer():
    """Open the Ultralytics Explorer GUI."""
    checks.check_requirements("streamlit")
    LOGGER.info(f"­čĺí Loading Explorer dashboard...")
    subprocess.run(["streamlit", "run", ROOT / "data/explorer/gui/dash.py", "--server.maxMessageSize", "2048"])



ultralytics.cfg.parse_key_value_pair(pair)

Analysiert ein 'Schl├╝ssel=Wert'-Paar und gibt Schl├╝ssel und Wert zur├╝ck.

Quellcode in ultralytics/cfg/__init__.py
def parse_key_value_pair(pair):
    """Parse one 'key=value' pair and return key and value."""
    k, v = pair.split("=", 1)  # split on first '=' sign
    k, v = k.strip(), v.strip()  # remove spaces
    assert v, f"missing '{k}' value"
    return k, smart_value(v)



ultralytics.cfg.smart_value(v)

Konvertiere einen String in einen zugrundeliegenden Typ wie int, float, bool, etc.

Quellcode in ultralytics/cfg/__init__.py
def smart_value(v):
    """Convert a string to an underlying type such as int, float, bool, etc."""
    v_lower = v.lower()
    if v_lower == "none":
        return None
    elif v_lower == "true":
        return True
    elif v_lower == "false":
        return False
    else:
        with contextlib.suppress(Exception):
            return eval(v)
        return v



ultralytics.cfg.entrypoint(debug='')

Diese Funktion ist der Einstiegspunkt f├╝r das Paket ultralytics . Sie ist f├╝r das Parsen der Kommandozeilenargumente verantwortlich, die an das Paket ├╝bergeben werden.

Diese Funktion erm├Âglicht es: - die ├ťbergabe von obligatorischen YOLO args als Liste von Strings - die Angabe der auszuf├╝hrenden Aufgabe, entweder 'detect', 'segment' oder 'classify' - die Angabe des Modus, entweder 'train', 'val', 'test' oder 'predict' - spezielle Modi wie "checks" ausf├╝hren - ├ťbergabe von ├ťberschreibungen an die Konfiguration des Pakets

Sie verwendet die Standard-CFG des Pakets und initialisiert sie mit den ├╝bergebenen Overrides. Dann ruft sie die Funktion CLI mit der zusammengestellten cfg auf

Quellcode in ultralytics/cfg/__init__.py
def entrypoint(debug=""):
    """
    This function is the ultralytics package entrypoint, it's responsible for parsing the command line arguments passed
    to the package.

    This function allows for:
    - passing mandatory YOLO args as a list of strings
    - specifying the task to be performed, either 'detect', 'segment' or 'classify'
    - specifying the mode, either 'train', 'val', 'test', or 'predict'
    - running special modes like 'checks'
    - passing overrides to the package's configuration

    It uses the package's default cfg and initializes it using the passed overrides.
    Then it calls the CLI function with the composed cfg
    """
    args = (debug.split(" ") if debug else sys.argv)[1:]
    if not args:  # no arguments passed
        LOGGER.info(CLI_HELP_MSG)
        return

    special = {
        "help": lambda: LOGGER.info(CLI_HELP_MSG),
        "checks": checks.collect_system_info,
        "version": lambda: LOGGER.info(__version__),
        "settings": lambda: handle_yolo_settings(args[1:]),
        "cfg": lambda: yaml_print(DEFAULT_CFG_PATH),
        "hub": lambda: handle_yolo_hub(args[1:]),
        "login": lambda: handle_yolo_hub(args),
        "copy-cfg": copy_default_cfg,
        "explorer": lambda: handle_explorer(),
    }
    full_args_dict = {**DEFAULT_CFG_DICT, **{k: None for k in TASKS}, **{k: None for k in MODES}, **special}

    # Define common misuses of special commands, i.e. -h, -help, --help
    special.update({k[0]: v for k, v in special.items()})  # singular
    special.update({k[:-1]: v for k, v in special.items() if len(k) > 1 and k.endswith("s")})  # singular
    special = {**special, **{f"-{k}": v for k, v in special.items()}, **{f"--{k}": v for k, v in special.items()}}

    overrides = {}  # basic overrides, i.e. imgsz=320
    for a in merge_equals_args(args):  # merge spaces around '=' sign
        if a.startswith("--"):
            LOGGER.warning(f"WARNING ÔÜá´ŞĆ '{a}' does not require leading dashes '--', updating to '{a[2:]}'.")
            a = a[2:]
        if a.endswith(","):
            LOGGER.warning(f"WARNING ÔÜá´ŞĆ '{a}' does not require trailing comma ',', updating to '{a[:-1]}'.")
            a = a[:-1]
        if "=" in a:
            try:
                k, v = parse_key_value_pair(a)
                if k == "cfg" and v is not None:  # custom.yaml passed
                    LOGGER.info(f"Overriding {DEFAULT_CFG_PATH} with {v}")
                    overrides = {k: val for k, val in yaml_load(checks.check_yaml(v)).items() if k != "cfg"}
                else:
                    overrides[k] = v
            except (NameError, SyntaxError, ValueError, AssertionError) as e:
                check_dict_alignment(full_args_dict, {a: ""}, e)

        elif a in TASKS:
            overrides["task"] = a
        elif a in MODES:
            overrides["mode"] = a
        elif a.lower() in special:
            special[a.lower()]()
            return
        elif a in DEFAULT_CFG_DICT and isinstance(DEFAULT_CFG_DICT[a], bool):
            overrides[a] = True  # auto-True for default bool args, i.e. 'yolo show' sets show=True
        elif a in DEFAULT_CFG_DICT:
            raise SyntaxError(
                f"'{colorstr('red', 'bold', a)}' is a valid YOLO argument but is missing an '=' sign "
                f"to set its value, i.e. try '{a}={DEFAULT_CFG_DICT[a]}'\n{CLI_HELP_MSG}"
            )
        else:
            check_dict_alignment(full_args_dict, {a: ""})

    # Check keys
    check_dict_alignment(full_args_dict, overrides)

    # Mode
    mode = overrides.get("mode")
    if mode is None:
        mode = DEFAULT_CFG.mode or "predict"
        LOGGER.warning(f"WARNING ÔÜá´ŞĆ 'mode' is missing. Valid modes are {MODES}. Using default 'mode={mode}'.")
    elif mode not in MODES:
        raise ValueError(f"Invalid 'mode={mode}'. Valid modes are {MODES}.\n{CLI_HELP_MSG}")

    # Task
    task = overrides.pop("task", None)
    if task:
        if task not in TASKS:
            raise ValueError(f"Invalid 'task={task}'. Valid tasks are {TASKS}.\n{CLI_HELP_MSG}")
        if "model" not in overrides:
            overrides["model"] = TASK2MODEL[task]

    # Model
    model = overrides.pop("model", DEFAULT_CFG.model)
    if model is None:
        model = "yolov8n.pt"
        LOGGER.warning(f"WARNING ÔÜá´ŞĆ 'model' is missing. Using default 'model={model}'.")
    overrides["model"] = model
    stem = Path(model).stem.lower()
    if "rtdetr" in stem:  # guess architecture
        from ultralytics import RTDETR

        model = RTDETR(model)  # no task argument
    elif "fastsam" in stem:
        from ultralytics import FastSAM

        model = FastSAM(model)
    elif "sam" in stem:
        from ultralytics import SAM

        model = SAM(model)
    else:
        from ultralytics import YOLO

        model = YOLO(model, task=task)
    if isinstance(overrides.get("pretrained"), str):
        model.load(overrides["pretrained"])

    # Task Update
    if task != model.task:
        if task:
            LOGGER.warning(
                f"WARNING ÔÜá´ŞĆ conflicting 'task={task}' passed with 'task={model.task}' model. "
                f"Ignoring 'task={task}' and updating to 'task={model.task}' to match model."
            )
        task = model.task

    # Mode
    if mode in ("predict", "track") and "source" not in overrides:
        overrides["source"] = DEFAULT_CFG.source or ASSETS
        LOGGER.warning(f"WARNING ÔÜá´ŞĆ 'source' is missing. Using default 'source={overrides['source']}'.")
    elif mode in ("train", "val"):
        if "data" not in overrides and "resume" not in overrides:
            overrides["data"] = DEFAULT_CFG.data or TASK2DATA.get(task or DEFAULT_CFG.task, DEFAULT_CFG.data)
            LOGGER.warning(f"WARNING ÔÜá´ŞĆ 'data' is missing. Using default 'data={overrides['data']}'.")
    elif mode == "export":
        if "format" not in overrides:
            overrides["format"] = DEFAULT_CFG.format or "torchscript"
            LOGGER.warning(f"WARNING ÔÜá´ŞĆ 'format' is missing. Using default 'format={overrides['format']}'.")

    # Run command in python
    getattr(model, mode)(**overrides)  # default args from model

    # Show help
    LOGGER.info(f"­čĺí Learn more at https://docs.ultralytics.com/modes/{mode}")



ultralytics.cfg.copy_default_cfg()

Kopiere und erstelle eine neue Standardkonfigurationsdatei mit angeh├Ąngtem "_copy" an ihrem Namen.

Quellcode in ultralytics/cfg/__init__.py
def copy_default_cfg():
    """Copy and create a new default configuration file with '_copy' appended to its name."""
    new_file = Path.cwd() / DEFAULT_CFG_PATH.name.replace(".yaml", "_copy.yaml")
    shutil.copy2(DEFAULT_CFG_PATH, new_file)
    LOGGER.info(
        f"{DEFAULT_CFG_PATH} copied to {new_file}\n"
        f"Example YOLO command with this new custom cfg:\n    yolo cfg='{new_file}' imgsz=320 batch=8"
    )





Erstellt am 2023-11-12, Aktualisiert am 2024-01-10
Autoren: AyushExel (1), glenn-jocher (3), Laughing-q (1)