dcmspec 0.2.1__py3-none-any.whl

dcmspec/apps/__init__.py

@@ -0,0 +1 @@
+"""Application interfaces for dcmspec."""

dcmspec/apps/cli/dataelements.py

@@ -0,0 +1,89 @@
+"""CLI for extracting, caching, and printing DICOM Data Elements from Part 6.
+
+Features:
+- Download and parse DICOM Data Elements table from Part 6 of the DICOM standard.
+- Cache the model as a JSON file for future runs and as a structured representation of the standard.
+- Print the resulting Data Elements as a table.
+- Supports caching, configuration files, and command-line options for flexible workflows.
+
+Usage:
+    poetry run python -m src.dcmspec.apps.cli.dataelements [options]
+
+For more details, use the --help option.
+"""
+
+import os
+import argparse
+from dcmspec.config import Config
+
+from dcmspec.spec_factory import SpecFactory
+from dcmspec.spec_printer import SpecPrinter
+
+
+def main():
+    """CLI for parsing, caching, and printing DICOM Data Elements from Part 6.
+
+    This CLI downloads, caches, and prints the list of DICOM Data Elements from Part 6 of the DICOM standard.
+
+    The tool parses the Data Elements table to extract tags, names, keywords, VR (Value Representation),
+    VM (Value Multiplicity), and status for all DICOM data elements. The output can be printed as a table.
+
+    The resulting model is cached as a JSON file. The primary purpose of this cache file is to provide a structured,
+    machine-readable representation of the DICOM Data Elements, which can be used for further processing or integration
+    in other tools. As a secondary benefit, the cache file is also used to speed up subsequent runs of the CLI scripts.
+
+    Usage:
+        poetry run python -m src.dcmspec.apps.cli.dataelements [options]
+
+    Options:
+        --config (str): Path to the configuration file.
+
+    Example:
+        poetry run python -m src.dcmspec.apps.cli.dataelements
+
+    """
+    # Parse command-line arguments
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--config", help="Path to the configuration file")
+    args = parser.parse_args()
+
+    # Determine config file location
+    config_file = args.config or os.getenv("DCMSPEC_CONFIG", None)
+
+    # Initialize configuration
+    config = Config(app_name="dcmspec", config_file=config_file)
+
+    url = "https://dicom.nema.org/medical/dicom/current/output/chtml/part06/chapter_6.html"
+    cache_file_name = "DataElements.xhtml"
+    json_cache_path = "DataElements.json"
+    table_id = "table_6-1"
+
+    # Create the factory
+    factory = SpecFactory(
+        column_to_attr={
+            0: "elem_tag",
+            1: "elem_name",
+            2: "elem_keyword",
+            3: "elem_vr",
+            4: "elem_vm",
+            5: "elem_status"
+        },
+        config=config
+    )
+
+    # Download, parse, and cache the model
+    model = factory.create_model(
+        url=url,
+        cache_file_name=cache_file_name,
+        table_id=table_id,
+        force_download=False,
+        json_file_name=json_cache_path,
+    )
+
+    # Print the model as a table
+    printer = SpecPrinter(model)
+    printer.print_table(colorize=True)
+
+
+if __name__ == "__main__":
+    main()

dcmspec/apps/cli/iodattributes.py

@@ -0,0 +1,125 @@
+"""CLI for extracting, caching, and printing the complete set of DICOM attributes for a given IOD from Part 3.
+
+Features:
+- Download and parse DICOM IOD tables from Part 3 of the DICOM standard.
+- Automatically parse all referenced Module Attributes tables for the IOD.
+- Cache the model as a JSON file for future runs and as a structured representation of the standard.
+- Print the resulting attributes as a table or tree.
+- Supports both Composite and Normalized IODs.
+- Supports caching, configuration files, and command-line options for flexible workflows.
+
+Usage:
+    poetry run python -m src.dcmspec.apps.cli.iodattributes <table_id> [options]
+
+For more details, use the --help option.
+"""
+
+import os
+import argparse
+
+from dcmspec.config import Config
+from dcmspec.iod_spec_builder import IODSpecBuilder
+from dcmspec.iod_spec_printer import IODSpecPrinter
+from dcmspec.spec_factory import SpecFactory
+
+
+def main():
+    """CLI for parsing, caching, and printing DICOM IOD attribute models.
+
+    This CLI downloads, caches, and prints all attributes for a specified DICOM IOD (Information Object Definition)
+    from Part 3 of the DICOM standard, supporting both Composite and Normalized IODs.
+
+    When an IOD table is specified, the tool parses the IOD table to determine which modules are referenced, then
+    automatically parses each referenced Module Attributes table. The resulting model contains both the list of modules
+    and, for each module, all its attributes. The print output (table or tree) shows only the attributes, not the IOD
+    table or module structure itself.
+
+    The resulting model is cached as a JSON file. The primary purpose of this cache file is to provide a structured,
+    machine-readable representation of the IOD's attributes, which can be used for further processing or integration in
+    other tools. As a secondary benefit, the cache file is also used to speed up subsequent runs of the CLI scripts.
+
+    Usage:
+        poetry run python -m src.dcmspec.apps.cli.iodattributes <table_id> [options]
+
+    Options:
+        table (str): Table ID to extract (e.g., "table_A.3-1" or "table_B.26.2-1").
+        --config (str): Path to the configuration file.
+        --print-mode (str): Print as 'table' (default), 'tree', or 'none' to skip printing.
+
+    Example:
+        poetry run python -m src.dcmspec.apps.cli.iodattributes table_A.3-1 --print-mode tree
+
+    """
+    url = "https://dicom.nema.org/medical/dicom/current/output/html/part03.html"
+
+    # Parse command-line arguments
+    parser = argparse.ArgumentParser()
+    parser.add_argument("table", help="Table ID")
+    parser.add_argument("--config", help="Path to the configuration file")
+    parser.add_argument(
+        "--print-mode", 
+        choices=["table", "tree", "none"],
+        default="table",
+        help="Print as 'table' (default), 'tree', or 'none' to skip printing"
+    )
+    args = parser.parse_args()
+
+    cache_file_name = "Part3.xhtml"
+    model_file_name = f"Part3_{args.table}_expanded.json"
+    table_id = args.table 
+
+    # Determine config file location
+    config_file = args.config or os.getenv("DCMSPEC_CONFIG", None)
+
+    # Initialize configuration
+    config = Config(app_name="dcmspec", config_file=config_file)
+
+    # Check table_id belongs to either Composite or Normalized IODs annexes
+    if "table_A." in table_id:
+        composite_iod = True
+    elif "table_B." in table_id:
+        composite_iod = False
+    else:
+        parser.error(f"table {table_id} does not correspond to a Composite or Normalized IOD")
+
+    # Create the IOD specification factory
+    c_iod_columns_mapping = {0: "ie", 1: "module", 2: "ref", 3: "usage"}
+    n_iod_columns_mapping = {0: "module", 1: "ref", 2: "usage"}
+    iod_columns_mapping = c_iod_columns_mapping if composite_iod else n_iod_columns_mapping
+    iod_factory = SpecFactory(
+        column_to_attr=iod_columns_mapping, 
+        name_attr="module",
+        config=config,
+    )
+
+    # Create the modules specification factory
+    parser_kwargs=None if composite_iod else {"skip_columns": [2]}
+    module_factory = SpecFactory(
+        column_to_attr={0: "elem_name", 1: "elem_tag", 2: "elem_type", 3: "elem_description"},
+        name_attr="elem_name",
+        parser_kwargs=parser_kwargs,
+        config=config,
+    )
+
+    # Create the builder
+    builder = IODSpecBuilder(iod_factory=iod_factory, module_factory=module_factory)
+
+    # Download, parse, and cache the combined model
+    model, _ = builder.build_from_url(
+        url=url,
+        cache_file_name=cache_file_name,
+        json_file_name=model_file_name,
+        table_id=table_id,
+        force_download=False,
+    )
+
+    # Print the model
+    printer = IODSpecPrinter(model)
+    if args.print_mode == "tree":
+        printer.print_tree(colorize=True)
+    elif args.print_mode == "table":
+        printer.print_table(colorize=True)
+    # else: do not print anything if print_mode == "none"
+
+if __name__ == "__main__":
+    main()

dcmspec/apps/cli/iodmodules.py

@@ -0,0 +1,92 @@
+"""CLI for extracting, caching, and printing DICOM IOD Module tables from Part 3.
+
+Features:
+- Download and parse DICOM IOD tables from Part 3 of the DICOM standard.
+- Extract and print the list of modules for a given IOD.
+- Cache the model as a JSON file for future runs and as a structured representation of the standard.
+- Print the resulting module list as a table.
+- Supports caching, configuration files, and command-line options for flexible workflows.
+
+Usage:
+    poetry run python -m src.dcmspec.apps.cli.iodmodules <table_id> [options]
+
+For more details, use the --help option.
+"""
+
+import os
+import argparse
+from dcmspec.config import Config
+
+from dcmspec.spec_factory import SpecFactory
+from dcmspec.spec_printer import SpecPrinter
+
+
+def main():
+    """CLI for parsing, caching, and printing DICOM IOD Module tables.
+
+    This CLI downloads, caches, and prints the list of modules of a given DICOM IOD (Information Object Definition)
+    from Part 3 of the DICOM standard.
+
+    The tool parses only the specified IOD table to extract the list of referenced modules, including their Information
+    Entity (IE), reference, and usage. It does not parse or include the attributes of the referenced module tables.
+    The output is a table listing all modules for the specified IOD.
+
+    The resulting model is cached as a JSON file. The primary purpose of this cache file is to provide a structured,
+    machine-readable representation of the IOD's module composition, which can be used for further processing or
+    integration in other tools. As a secondary benefit, the cache file is also used to speed up subsequent runs of the
+    CLI scripts.
+
+    Usage:
+        poetry run python -m src.dcmspec.apps.cli.iodmodules <table_id> [options]
+
+    Options:
+        table (str): Table ID to extract (e.g., "table_A.1-1" or "table_B.1-1").
+        --config (str): Path to the configuration file.
+
+    Example:
+        poetry run python -m src.dcmspec.apps.cli.iodmodules table_A.1-1
+
+    """
+    url = "https://dicom.nema.org/medical/dicom/current/output/html/part03.html"
+
+    # Parse command-line arguments
+    parser = argparse.ArgumentParser()
+    # parser.add_argument("table", help="Table ID")
+    parser.add_argument("table", nargs="?", default="table_A.3-1", help="Table ID")
+
+    parser.add_argument("--config", help="Path to the configuration file")
+    args = parser.parse_args()
+
+    cache_file_name = "Part3.xhtml"
+    model_file_name = f"Part3_{args.table}.json"
+    table_id = args.table 
+
+    # Determine config file location
+    config_file = args.config or os.getenv("DCMSPEC_CONFIG", None)
+
+    # Initialize configuration
+    config = Config(app_name="dcmspec", config_file=config_file)
+
+    # Create the factory
+    factory = SpecFactory(
+        column_to_attr={0: "ie", 1: "module", 2: "ref", 3: "usage"}, 
+        name_attr="module",
+        config=config,
+    )
+
+    # Download, parse, and cache the model
+    model = factory.create_model(
+        url=url,
+        cache_file_name=cache_file_name,
+        json_file_name=model_file_name,
+        table_id=table_id,
+        force_download=False,
+    )
+
+    # Print the model as a table
+    printer = SpecPrinter(model)
+    printer.print_table(colorize=True)
+
+
+if __name__ == "__main__":
+    main()

dcmspec/apps/cli/modattributes.py

@@ -0,0 +1,265 @@
+"""CLI for extracting, caching, and printing DICOM Module Attributes tables from Part 3.
+
+Features:
+- Download and parse DICOM Module Attributes tables from Part 3 of the DICOM standard.
+- Optionally merge additional information (VR, VM, Keyword, Status) from Part 6.
+- Cache the resulting model as a JSON file for future runs and as a structured representation of the standard.
+- Print the resulting model as a table or tree.
+- Supports caching, configuration files, and command-line options for flexible workflows.
+
+Usage:
+    poetry run python -m src.dcmspec.apps.cli.modattributes <table_id> [options]
+
+For more details, use the --help option.
+"""
+
+import os
+import argparse
+import logging
+from dcmspec.config import Config
+
+from dcmspec.spec_factory import SpecFactory
+from dcmspec.spec_merger import SpecMerger
+from dcmspec.spec_printer import SpecPrinter
+
+
+def create_module_model(config, table_id, force_parse, force_download, include_depth, logger=None):
+    """Create a DICOM Module Attributes model from Part 3 of the DICOM standard.
+
+    Downloads and parses the specified module attributes table from the DICOM standard (Part 3),
+    or loads it from cache if available. The resulting model contains the attributes, tags, types,
+    and descriptions for the specified module.
+
+    Args:
+        config (Config): The configuration object.
+        table_id (str): The table ID to extract (e.g., "table_C.7-1").
+        force_parse (bool): If True, force reparsing of the DOM and regeneration of the JSON model.
+        force_download (bool): If True, force download of the input file and regeneration of the model.
+        include_depth (int or None): Depth to which included tables should be parsed (None for unlimited).
+        logger (logging.Logger, optional): Logger instance for debug output.
+
+    Returns:
+        SpecModel: The parsed module attributes model.
+
+    """
+    url = "https://dicom.nema.org/medical/dicom/current/output/html/part03.html"
+    cache_file_name = "Part3.xhtml"
+    model_file_name = f"Part3_{table_id}.json"
+    factory = SpecFactory(
+        column_to_attr={0: "elem_name", 1: "elem_tag", 2: "elem_type", 3: "elem_description"}, 
+        name_attr="elem_name",
+        config=config,
+        logger=logger,
+    )
+    if logger:
+        logger.debug(f"Creating module model: cache_file_name={cache_file_name}, model_file_name={model_file_name}")
+    return factory.create_model(
+        url=url,
+        cache_file_name=cache_file_name,
+        json_file_name=model_file_name,
+        table_id=table_id,
+        force_parse=force_parse,
+        force_download=force_download,
+        include_depth=include_depth,
+    )
+
+def create_part6_model(config, logger=None):
+    """Create a DICOM Data Elements model from Part 6 of the DICOM standard.
+
+    Downloads and parses the Data Elements table from Part 6 of the DICOM standard,
+    or loads it from cache if available. The resulting model contains tags, names,
+    keywords, VR, VM, and status for all DICOM data elements.
+
+    Args:
+        config (Config): The configuration object.
+        logger (logging.Logger, optional): Logger instance for debug output.
+
+    Returns:
+        SpecModel: The parsed Part 6 Data Elements model.
+
+    """
+    url = "https://dicom.nema.org/medical/dicom/current/output/chtml/part06/chapter_6.html"
+    cache_file_name = "DataElements.xhtml"
+    json_file_name = "DataElements.json"
+    table_id = "table_6-1"
+    factory = SpecFactory(
+        column_to_attr={
+            0: "elem_tag",
+            1: "elem_name",
+            2: "elem_keyword",
+            3: "elem_vr",
+            4: "elem_vm",
+            5: "elem_status"
+            }, 
+        config=config,
+        logger=logger,
+    )
+    if logger:
+        logger.debug(f"Creating part6 model: cache_file_name={cache_file_name}, json_cache_path={json_file_name}")
+    return factory.create_model(
+        url=url,
+        cache_file_name=cache_file_name,
+        table_id=table_id,
+        force_download=False,
+        json_file_name=json_file_name,
+    )
+
+def main():
+    """CLI for parsing, caching, and printing DICOM Module Attributes tables.
+
+    This CLI extracts, caches, and prints the attributes of a given DICOM Module
+    from Part 3 of the DICOM standard. Optionally, it can enrich the module with VR, VM, Keyword,
+    or Status information from Part 6 (Data Elements dictionary).
+
+    The tool parses the specified Module Attributes table to extract all attributes, tags, types,
+    and descriptions for the module. Optionally, it can merge in VR, VM, Keyword, or Status information
+    from Part 6. The output can be printed as a table or tree.
+
+    The resulting model is cached as a JSON file. The primary purpose of this cache file is to provide
+    a structured, machine-readable representation of the module's attributes, which can be used for further processing
+    or integration in other tools. As a secondary benefit, the cache file is also used to speed up subsequent runs
+    of the CLI scripts.
+
+    Usage:
+        poetry run python -m src.dcmspec.apps.cli.modattributes <table_id> [options]
+
+    Options:
+        table (str): Table ID to extract (e.g., "table_C.7-1").
+        --config (str): Path to the configuration file.
+        --include-depth (int): Depth to which included tables should be parsed (default: unlimited).
+        --force-parse: Force reparsing of the DOM and regeneration of the JSON model.
+        --force-download: Force download of the input file and regeneration of the model.
+        --print-mode (str): Print as 'table' (default), 'tree', or 'none' to skip printing.
+        --add-part6 (list): Specification(s) to merge from Part 6 (e.g., --add-part6 VR VM).
+        --force-update: Force update of the specifications merged from part 6, even if cached.
+        -d, --debug: Enable debug logging to the console.
+        -v, --verbose: Enable verbose (info-level) logging to the console.
+
+    Example:
+        poetry run python -m src.dcmspec.apps.cli.modattributes table_C.7-1 --add-part6 VR VM
+
+    """
+    # Parse command-line arguments
+    parser = argparse.ArgumentParser()
+    parser.add_argument("table", help="Table ID")
+    parser.add_argument("--config", help="Path to the configuration file")
+    parser.add_argument(
+        "--include-depth",
+        type=int,
+        default=None,
+        help="Depth to which included tables should be parsed (default: unlimited)"
+    )
+    parser.add_argument(
+        "--force-parse",
+        action="store_true",
+        help="Force reparsing of the DOM and regeneration of the JSON model, even if the JSON cache exists."
+    )
+    parser.add_argument(
+        "--force-download",
+        action="store_true",
+        help=(
+            "Force download of the input file and regeneration of the model, even if cached. "
+            "Implies --force-parse (the file will also be re-parsed)."
+        )
+    )
+    parser.add_argument(
+        "--print-mode", 
+        choices=["table", "tree", "none"],
+        default="table",
+        help="Print as 'table' (default), 'tree', or 'none' to skip printing"
+    )
+    parser.add_argument(
+        "--add-part6",
+        nargs="+",
+        choices=["VR", "VM", "Keyword", "Status"],  
+        help="Specification to merge from Part 6 (e.g. --add-part6 VR VM)"
+    )
+    parser.add_argument(
+        "--force-update",
+        action="store_true",
+        help="Force update of the specifications merged from part 6, even if cached"
+        )
+    parser.add_argument(
+        "-d", "--debug",
+        action="store_true",
+        help="Enable debug logging to the console (overrides --verbose)"
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Enable verbose (info-level) logging to the console"
+    )
+    
+    args = parser.parse_args()
+
+    # Set up logger
+    logger = logging.getLogger("modattributes")
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter("%(asctime)s - %(levelname)s - %(message)s")
+    handler.setFormatter(formatter)
+    if not logger.hasHandlers():
+        logger.addHandler(handler)
+    if args.debug:
+        logger.setLevel(logging.DEBUG)
+        handler.setLevel(logging.DEBUG)
+    elif args.verbose:
+        logger.setLevel(logging.INFO)
+        handler.setLevel(logging.INFO)
+    else:
+        logger.setLevel(logging.WARNING)
+        handler.setLevel(logging.WARNING)
+
+    # Determine config file location
+    config_file = args.config or os.getenv("DCMSPEC_CONFIG", None)
+    config = Config(app_name="modattributes", config_file=config_file)
+
+    logger.debug(f"Config file: {config_file}")
+    logger.debug(f"Cache dir: {config.get_param('cache_dir')}")
+    logger.debug(f"Table ID: {args.table}")
+
+    # Create the module model
+    module_model = create_module_model(
+        config=config,
+        table_id=args.table,
+        force_parse=args.force_parse,
+        force_download=args.force_download,
+        include_depth=args.include_depth,
+        logger=logger,
+    )
+
+    # Optionally enrich with Part 6
+    part6_attr_map = {
+        "VR": "elem_vr",
+        "VM": "elem_vm",
+        "Keyword": "elem_keyword",
+        "Status": "elem_status",
+    }
+    merge_attrs = [part6_attr_map[x] for x in (args.add_part6 or [])]
+
+    if merge_attrs:
+        model_file_name = f"Part3_{args.table}_enriched.json"
+        part6_model = create_part6_model(config, logger=logger)
+        logger.debug("Merging module model with part6 model.")
+        merger = SpecMerger(config=config, logger=logger)
+        model = merger.merge_node(
+            module_model,
+            part6_model,
+            match_by= "attribute",
+            attribute_name="elem_tag",
+            merge_attrs=merge_attrs,
+            json_file_name=model_file_name,
+            force_update=args.force_update or args.force_download or args.force_parse,
+        )
+    else:
+        model = module_model
+
+    logger.debug("Model ready for printing/output")
+    printer = SpecPrinter(model)
+    if args.print_mode == "tree":
+        printer.print_tree(colorize=True)
+    elif args.print_mode == "table":
+        printer.print_table(colorize=True)
+    # else: do not print anything if print_mode == "none"
+
+if __name__ == "__main__":
+    main()