Reference for ultralytics/cfg/__init__.py
Note
This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/cfg/__init__.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!
ultralytics.cfg.cfg2dict
Converts a configuration object to a dictionary.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cfg |
str | Path | Dict | SimpleNamespace
|
Configuration object to be converted. Can be a file path, a string, a dictionary, or a SimpleNamespace object. |
required |
Returns:
Type | Description |
---|---|
Dict
|
Configuration object in dictionary format. |
Examples:
Convert a YAML file path to a dictionary:
Convert a SimpleNamespace to a dictionary:
>>> from types import SimpleNamespace
>>> config_sn = SimpleNamespace(param1="value1", param2="value2")
>>> config_dict = cfg2dict(config_sn)
Pass through an already existing dictionary:
Notes
- If cfg is a path or string, it's loaded as YAML and converted to a dictionary.
- If cfg is a SimpleNamespace object, it's converted to a dictionary using vars().
- If cfg is already a dictionary, it's returned unchanged.
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.get_cfg
Load and merge configuration data from a file or dictionary, with optional overrides.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cfg |
str | Path | Dict | SimpleNamespace
|
Configuration data source. Can be a file path, dictionary, or SimpleNamespace object. |
DEFAULT_CFG_DICT
|
overrides |
Dict | None
|
Dictionary containing key-value pairs to override the base configuration. |
None
|
Returns:
Type | Description |
---|---|
SimpleNamespace
|
Namespace containing the merged configuration arguments. |
Examples:
>>> from ultralytics.cfg import get_cfg
>>> config = get_cfg() # Load default configuration
>>> config = get_cfg("path/to/config.yaml", overrides={"epochs": 50, "batch_size": 16})
Notes
- If both
cfg
andoverrides
are provided, the values inoverrides
will take precedence. - Special handling ensures alignment and correctness of the configuration, such as converting numeric
project
andname
to strings and validating configuration keys and values. - The function performs type and value checks on the configuration data.
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.check_cfg
Checks configuration argument types and values for the Ultralytics library.
This function validates the types and values of configuration arguments, ensuring correctness and converting them if necessary. It checks for specific key types defined in global variables such as CFG_FLOAT_KEYS, CFG_FRACTION_KEYS, CFG_INT_KEYS, and CFG_BOOL_KEYS.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cfg |
Dict
|
Configuration dictionary to validate. |
required |
hard |
bool
|
If True, raises exceptions for invalid types and values; if False, attempts to convert them. |
True
|
Examples:
>>> config = {
... "epochs": 50, # valid integer
... "lr0": 0.01, # valid float
... "momentum": 1.2, # invalid float (out of 0.0-1.0 range)
... "save": "true", # invalid bool
... }
>>> check_cfg(config, hard=False)
>>> print(config)
{'epochs': 50, 'lr0': 0.01, 'momentum': 1.2, 'save': False} # corrected 'save' key
Notes
- The function modifies the input dictionary in-place.
- None values are ignored as they may be from optional arguments.
- Fraction keys are checked to be within the range [0.0, 1.0].
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.get_save_dir
Returns the directory path for saving outputs, derived from arguments or default settings.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
args |
SimpleNamespace
|
Namespace object containing configurations such as 'project', 'name', 'task', 'mode', and 'save_dir'. |
required |
name |
str | None
|
Optional name for the output directory. If not provided, it defaults to 'args.name' or the 'args.mode'. |
None
|
Returns:
Type | Description |
---|---|
Path
|
Directory path where outputs should be saved. |
Examples:
>>> from types import SimpleNamespace
>>> args = SimpleNamespace(project="my_project", task="detect", mode="train", exist_ok=True)
>>> save_dir = get_save_dir(args)
>>> print(save_dir)
my_project/detect/train
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg._handle_deprecation
Handles deprecated configuration keys by mapping them to current equivalents with deprecation warnings.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
custom |
Dict
|
Configuration dictionary potentially containing deprecated keys. |
required |
Examples:
>>> custom_config = {"boxes": True, "hide_labels": "False", "line_thickness": 2}
>>> _handle_deprecation(custom_config)
>>> print(custom_config)
{'show_boxes': True, 'show_labels': True, 'line_width': 2}
Notes
This function modifies the input dictionary in-place, replacing deprecated keys with their current equivalents. It also handles value conversions where necessary, such as inverting boolean values for 'hide_labels' and 'hide_conf'.
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.check_dict_alignment
Checks alignment between custom and base configuration dictionaries, handling deprecated keys and providing error messages for mismatched keys.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
base |
Dict
|
The base configuration dictionary containing valid keys. |
required |
custom |
Dict
|
The custom configuration dictionary to be checked for alignment. |
required |
e |
Exception | None
|
Optional error instance passed by the calling function. |
None
|
Raises:
Type | Description |
---|---|
SystemExit
|
If mismatched keys are found between the custom and base dictionaries. |
Examples:
>>> base_cfg = {"epochs": 50, "lr0": 0.01, "batch_size": 16}
>>> custom_cfg = {"epoch": 100, "lr": 0.02, "batch_size": 32}
>>> try:
... check_dict_alignment(base_cfg, custom_cfg)
... except SystemExit:
... print("Mismatched keys found")
Notes
- Suggests corrections for mismatched keys based on similarity to valid keys.
- Automatically replaces deprecated keys in the custom configuration with updated equivalents.
- Prints detailed error messages for each mismatched key to help users correct their configurations.
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.merge_equals_args
Merges arguments around isolated '=' in a list of strings, handling three cases: 1. ['arg', '=', 'val'] becomes ['arg=val'], 2. ['arg=', 'val'] becomes ['arg=val'], 3. ['arg', '=val'] becomes ['arg=val'].
Parameters:
Name | Type | Description | Default |
---|---|---|---|
args |
List[str]
|
A list of strings where each element represents an argument. |
required |
Returns:
Type | Description |
---|---|
List[str]
|
A list of strings where the arguments around isolated '=' are merged. |
Examples:
>>> args = ["arg1", "=", "value", "arg2=", "value2", "arg3", "=value3"]
>>> merge_equals_args(args)
['arg1=value', 'arg2=value2', 'arg3=value3']
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.handle_yolo_hub
Handles Ultralytics HUB command-line interface (CLI) commands for authentication.
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.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
args |
List[str]
|
A list of command line arguments. The first argument should be either 'login' or 'logout'. For 'login', an optional second argument can be the API key. |
required |
Examples:
Notes
- The function imports the 'hub' module from ultralytics to perform login and logout operations.
- For the 'login' command, if no API key is provided, an empty string is passed to the login function.
- The 'logout' command does not require any additional arguments.
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.handle_yolo_settings
Handles YOLO settings command-line interface (CLI) commands.
This function processes YOLO settings CLI commands such as reset and updating individual settings. It should be called when executing a script with arguments related to YOLO settings management.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
args |
List[str]
|
A list of command line arguments for YOLO settings management. |
required |
Examples:
>>> handle_yolo_settings(["reset"]) # Reset YOLO settings
>>> handle_yolo_settings(["default_cfg_path=yolo11n.yaml"]) # Update a specific setting
Notes
- If no arguments are provided, the function will display the current settings.
- The 'reset' command will delete the existing settings file and create new default settings.
- Other arguments are treated as key-value pairs to update specific settings.
- The function will check for alignment between the provided settings and the existing ones.
- After processing, the updated settings will be displayed.
- For more information on handling YOLO settings, visit: https://docs.ultralytics.com/quickstart/#ultralytics-settings
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.handle_explorer
Launches a graphical user interface that provides tools for interacting with and analyzing datasets using the Ultralytics Explorer API. It checks for the required 'streamlit' package and informs the user that the Explorer dashboard is loading.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
args |
List[str]
|
A list of optional command line arguments. |
required |
Examples:
Notes
- Requires 'streamlit' package version 1.29.0 or higher.
- The function does not take any arguments or return any values.
- It is typically called from the command line interface using the 'yolo explorer' command.
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.handle_streamlit_inference
Open the Ultralytics Live Inference Streamlit app for real-time object detection.
This function initializes and runs a Streamlit application designed for performing live object detection using Ultralytics models. It checks for the required Streamlit package and launches the app.
Examples:
Notes
- Requires Streamlit version 1.29.0 or higher.
- The app is launched using the 'streamlit run' command.
- The Streamlit app file is located in the Ultralytics package directory.
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.parse_key_value_pair
Parses a key-value pair string into separate key and value components.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
pair |
str
|
A string containing a key-value pair in the format "key=value". |
'key=value'
|
Returns:
Type | Description |
---|---|
tuple
|
A tuple containing two elements: - key (str): The parsed key. - value (str): The parsed value. |
Raises:
Type | Description |
---|---|
AssertionError
|
If the value is missing or empty. |
Examples:
>>> key, value = parse_key_value_pair("model=yolo11n.pt")
>>> print(f"Key: {key}, Value: {value}")
Key: model, Value: yolo11n.pt
>>> key, value = parse_key_value_pair("epochs=100")
>>> print(f"Key: {key}, Value: {value}")
Key: epochs, Value: 100
Notes
- The function splits the input string on the first '=' character.
- Leading and trailing whitespace is removed from both key and value.
- An assertion error is raised if the value is empty after stripping.
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.smart_value
Converts a string representation of a value to its appropriate Python type.
This function attempts to convert a given string into a Python object of the most appropriate type. It handles conversions to None, bool, int, float, and other types that can be evaluated safely.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
v |
str
|
The string representation of the value to be converted. |
required |
Returns:
Type | Description |
---|---|
Any
|
The converted value. The type can be None, bool, int, float, or the original string if no conversion is applicable. |
Examples:
>>> smart_value("42")
42
>>> smart_value("3.14")
3.14
>>> smart_value("True")
True
>>> smart_value("None")
None
>>> smart_value("some_string")
'some_string'
Notes
- The function uses a case-insensitive comparison for boolean and None values.
- For other types, it attempts to use Python's eval() function, which can be unsafe if used on untrusted input.
- If no conversion is possible, the original string is returned.
Source code in ultralytics/cfg/__init__.py
ultralytics.cfg.entrypoint
Ultralytics entrypoint function for parsing and executing command-line arguments.
This function serves as the main entry point for the Ultralytics CLI, parsing command-line arguments and executing the corresponding tasks such as training, validation, prediction, exporting models, and more.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
debug |
str
|
Space-separated string of command-line arguments for debugging purposes. |
''
|
Examples:
Train a detection model for 10 epochs with an initial learning_rate of 0.01:
Predict a YouTube video using a pretrained segmentation model at image size 320:
Validate a pretrained detection model at batch-size 1 and image size 640:
Notes
- If no arguments are passed, the function will display the usage help message.
- For a list of all available commands and their arguments, see the provided help messages and the Ultralytics documentation at https://docs.ultralytics.com.
Source code in ultralytics/cfg/__init__.py
678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 |
|
ultralytics.cfg.copy_default_cfg
Copies the default configuration file and creates a new one with '_copy' appended to its name.
This function duplicates the existing default configuration file (DEFAULT_CFG_PATH) and saves it with '_copy' appended to its name in the current working directory. It provides a convenient way to create a custom configuration file based on the default settings.
Examples:
>>> copy_default_cfg()
# Output: default.yaml copied to /path/to/current/directory/default_copy.yaml
# Example YOLO command with this new custom cfg:
# yolo cfg='/path/to/current/directory/default_copy.yaml' imgsz=320 batch=8
Notes
- The new configuration file is created in the current working directory.
- After copying, the function prints a message with the new file's location and an example YOLO command demonstrating how to use the new configuration file.
- This function is useful for users who want to modify the default configuration without altering the original file.