02 Code-Qualität in der Praxis: Refactoring - Vom Monolithen zu Modulen

"""
Road Profile Viewer - Interactive 2D Visualization
===================================================
This module contains the entire application in a single file...
"""

import numpy as np
from dash import Dash, html, dcc, Input, Output
import plotly.graph_objects as go

# Road profile generation (lines 20-60)
def generate_road_profile(num_points=100, x_max=80):
    # ... 40 lines of numpy calculations ...
    return x, y

# Geometry calculations (lines 60-180)
def calculate_ray_line(angle_degrees, camera_x=0, camera_y=2.0, x_max=80):
    # ... calculating ray intersections ...

def find_intersection(x_road, y_road, angle_degrees, camera_x=0, camera_y=1.5):
    # ... finding where ray hits road ...
    return x_intersect, y_intersect, distance

# Dash application (lines 190-390)
def create_dash_app():
    app = Dash(__name__)
    app.layout = html.Div([...])  # UI definition

    @app.callback(...)
    def update_graph(angle):
        # ... mixing UI logic with calculations ...

    return app

# Entry point
def main():
    app = create_dash_app()
    app.run(debug=True)

if __name__ == '__main__':
    main()

# Sie wollen Schnittpunkt-Logik ändern
# Aber zuerst müssen Sie:
# - Imports überspringen (20 Zeilen)
# - Straßengenerierung überspringen (40 Zeilen)
# - Hilfsfunktionen überspringen (60 Zeilen)
# - Endlich find_intersection() bei Zeile 111 erreichen

# Um find_intersection() zu testen, brauchen Sie:
# - Alles importieren (einschließlich Dash, was einen Webserver startet)
# - Auf langsame Imports warten
# - Riskiere Seiteneffekte von anderem Code

# Was Sie wollen:
from geometry import find_intersection  # Schnell, fokussierter Import

# Zwei Entwickler arbeiten an derselben Datei:
Entwickler A: Ändert Zeile 50 (Straßengenerierung)
Entwickler B: Ändert Zeile 300 (UI-Styling)
Git: MERGE-KONFLIKT (obwohl die Änderungen unabhängig sind!)

def find_intersection(...):
    # Verwendet versehentlich eine globale Variable aus dem UI-Bereich
    camera_x = CAMERA_POSITION  # Wo ist das definiert?
    # Jetzt hängt Geometrie von UI ab - schwer isoliert zu testen!

def calculate_ray_line(angle_degrees, camera_x=0, camera_y=2.0, x_max=80):
    """
    Calculate the line representing the camera ray.

    Depends on: Only numpy and the input parameters
    Side effects: None
    Returns: Calculated coordinates
    """
    angle_rad = -np.deg2rad(angle_degrees)
    slope = np.tan(angle_rad)
    # ... pure calculations ...
    return x_ray, y_ray

def find_intersection(x_road, y_road, angle_degrees, camera_x=0, camera_y=1.5):
    """
    Find intersection between camera ray and road profile.

    Depends on: Only numpy and the input parameters
    Side effects: None
    Returns: Calculated coordinates and distance
    """
    angle_rad = -np.deg2rad(angle_degrees)
    # ... pure calculations ...
    return x_intersect, y_intersect, distance

def generate_road_profile(num_points=100, x_max=80):
    """
    Generate a road profile using a clothoid-like approximation.

    Depends on: Only numpy
    Side effects: None (doesn't draw anything or start servers)
    Returns: Road coordinates
    """
    x = np.linspace(0, x_max, num_points)
    x_norm = x / x_max
    y = 0.015 * x_norm**3 * x_max + ...
    return x, y

def create_dash_app():
    """
    Create and configure the Dash application.

    Depends on: Dash, plotly, geometry functions, road functions
    Side effects: Creates web server
    Returns: Dash app instance
    """
    app = Dash(__name__)

    app.layout = html.Div([
        html.H1("Road Profile Viewer..."),
        dcc.Input(id='angle-input', ...),
        dcc.Graph(id='road-profile-graph'),
    ])

    @app.callback(
        [Output('road-profile-graph', 'figure'), ...],
        [Input('angle-input', 'value')]
    )
    def update_graph(angle):
        # Uses road generation
        x_road, y_road = generate_road_profile(...)

        # Uses geometry
        x_intersect, y_intersect, distance = find_intersection(...)

        # Creates visualization
        fig = go.Figure()
        fig.add_trace(...)
        return fig, info_text

    return app

def main():
    """
    Main function to run the Dash application.

    Depends on: create_dash_app()
    Side effects: Starts web server
    """
    app = create_dash_app()
    print("Starting Road Profile Viewer...")
    print("Open your browser and navigate to: http://127.0.0.1:8050/")
    app.run(debug=True)

if __name__ == '__main__':
    main()

"""
Geometry calculations for ray-road intersection.

This module contains pure mathematical functions for calculating:
- Camera ray lines at various angles
- Intersection points between rays and road profiles
- Distances from camera to intersection points

All functions are pure (no side effects) and depend only on numpy.
"""

import numpy as np


def calculate_ray_line(
    angle_degrees: float,
    camera_x: float = 0,
    camera_y: float = 2.0,
    x_max: float = 80
) -> tuple[np.ndarray, np.ndarray]:
    """
    Calculate the line representing the camera ray.

    Parameters
    ----------
    angle_degrees : float
        Angle in degrees from the positive x-axis (measured downward from horizontal)
    camera_x : float, optional
        X-coordinate of camera position (default: 0)
    camera_y : float, optional
        Y-coordinate of camera position (default: 2.0)
    x_max : float, optional
        Maximum x extent for the ray (default: 80)

    Returns
    -------
    tuple[np.ndarray, np.ndarray]
        x and y coordinates of the ray line

    Examples
    --------
    >>> x_ray, y_ray = calculate_ray_line(-10.0)
    >>> len(x_ray)
    2
    """
    # Convert angle to radians (angle is measured downward from horizontal)
    # Negative angle because y-axis points up but we measure downward angle
    angle_rad = -np.deg2rad(angle_degrees)

    # Calculate slope
    if np.abs(np.cos(angle_rad)) < 1e-10:
        # Vertical line case
        return np.array([camera_x, camera_x]), np.array([camera_y, -10])

    slope = np.tan(angle_rad)

    # Calculate x range where the ray is valid
    # The ray should extend from the camera to where it would intersect y=0 or beyond
    if angle_degrees < 0 or angle_degrees > 180:
        # Ray going upward - just show a short segment
        x_end = min(camera_x + 20, x_max)
    else:
        # Ray going downward - extend to x_max
        x_end = x_max

    # Generate points for the ray
    x_ray = np.array([camera_x, x_end])
    y_ray = camera_y + slope * (x_ray - camera_x)

    return x_ray, y_ray


def find_intersection(
    x_road: np.ndarray,
    y_road: np.ndarray,
    angle_degrees: float,
    camera_x: float = 0,
    camera_y: float = 1.5
) -> tuple[float | None, float | None, float | None]:
    """
    Find the intersection point between the camera ray and the road profile.

    Parameters
    ----------
    x_road : np.ndarray
        X-coordinates of the road profile
    y_road : np.ndarray
        Y-coordinates of the road profile
    angle_degrees : float
        Angle of the camera ray in degrees
    camera_x : float, optional
        X-coordinate of camera position (default: 0)
    camera_y : float, optional
        Y-coordinate of camera position (default: 1.5)

    Returns
    -------
    tuple[float | None, float | None, float | None]
        x, y coordinates of intersection and distance from camera,
        or (None, None, None) if no intersection found

    Examples
    --------
    >>> x_road = np.array([0, 10, 20, 30])
    >>> y_road = np.array([0, 2, 3, 4])
    >>> x, y, dist = find_intersection(x_road, y_road, -10.0)
    >>> x is not None
    True
    """
    angle_rad = -np.deg2rad(angle_degrees)

    # Handle vertical ray
    if np.abs(np.cos(angle_rad)) < 1e-10:
        return None, None, None

    slope = np.tan(angle_rad)

    # Ray equation: y = camera_y + slope * (x - camera_x)
    # Check each segment of the road for intersection
    for i in range(len(x_road) - 1):
        x1, y1 = x_road[i], y_road[i]
        x2, y2 = x_road[i + 1], y_road[i + 1]

        # Skip if this segment is behind the camera
        if x2 <= camera_x:
            continue

        # Calculate y values of the ray at x1 and x2
        ray_y1 = camera_y + slope * (x1 - camera_x)
        ray_y2 = camera_y + slope * (x2 - camera_x)

        # Check if the ray crosses the road segment
        # The ray intersects if it's on different sides of the road at x1 and x2
        diff1 = ray_y1 - y1
        diff2 = ray_y2 - y2

        if diff1 * diff2 <= 0:  # Sign change or zero indicates intersection
            # Linear interpolation to find exact intersection point
            if abs(diff2 - diff1) < 1e-10:
                # Parallel lines
                t = 0
            else:
                t = diff1 / (diff1 - diff2)

            # Interpolate to find intersection point
            x_intersect = x1 + t * (x2 - x1)
            y_intersect = y1 + t * (y2 - y1)

            # Calculate distance from camera to intersection
            distance = np.sqrt((x_intersect - camera_x)**2 + (y_intersect - camera_y)**2)

            return x_intersect, y_intersect, distance

    return None, None, None

from geometry import calculate_ray_line, find_intersection

"""
Road profile generation.

This module handles generation of road profiles using various mathematical
curves (currently clothoid-like approximations).

All functions are pure (no side effects) and depend only on numpy.
"""

import numpy as np


def generate_road_profile(
    num_points: int = 100,
    x_max: float = 80
) -> tuple[np.ndarray, np.ndarray]:
    """
    Generate a road profile using a clothoid-like approximation.

    A clothoid (Euler spiral) is a curve whose curvature increases linearly
    with its arc length. This function approximates it with a polynomial curve.

    Parameters
    ----------
    num_points : int, optional
        Number of points to generate (default: 100)
    x_max : float, optional
        Maximum x-coordinate value (default: 80)

    Returns
    -------
    tuple[np.ndarray, np.ndarray]
        x and y coordinates of the road profile

    Examples
    --------
    >>> x, y = generate_road_profile(num_points=50, x_max=40)
    >>> len(x)
    50
    >>> x[0], y[0]
    (0.0, 0.0)
    """
    # Generate equidistant x points from 0 to x_max
    x = np.linspace(0, x_max, num_points)

    # Create a clothoid-like curve using a combination of polynomial and sinusoidal terms
    # This creates a road that starts flat and gradually curves
    # Normalize x for the calculation
    x_norm = x / x_max

    # Clothoid approximation: starts flat, gradually increases curvature
    # Scale to keep maximum height around 8m (realistic road profile)
    y = (0.015 * x_norm**3 * x_max +
         0.3 * np.sin(2 * np.pi * x_norm) +
         0.035 * x_norm * x_max)

    # Ensure it starts at (0, 0)
    y = y - y[0]

    return x, y

from road import generate_road_profile

"""
Visualization layer for the Road Profile Viewer.

This module contains all Dash UI components, layout definitions, and callbacks.
It orchestrates the geometry and road modules to create an interactive visualization.
"""

import numpy as np
from dash import Dash, html, dcc, Input, Output
import plotly.graph_objects as go

from geometry import calculate_ray_line, find_intersection
from road import generate_road_profile


def create_dash_app() -> Dash:
    """
    Create and configure the Dash application.

    Returns
    -------
    Dash
        Configured Dash application instance ready to run
    """
    # Initialize the Dash app
    app = Dash(__name__)

    # Define the layout
    app.layout = html.Div([
        html.H1("Road Profile Viewer with Camera Ray Intersection",
                style={'textAlign': 'center', 'color': '#2c3e50', 'marginBottom': '20px'}),

        html.Div([
            html.Label("Camera Ray Angle (degrees from horizontal):",
                      style={'fontWeight': 'bold', 'marginRight': '10px'}),
            dcc.Input(
                id='angle-input',
                type='number',
                value=-1.1,
                step=0.1,
                style={'marginRight': '20px', 'padding': '5px', 'width': '100px'}
            ),
            html.Span(id='intersection-info',
                     style={'color': '#e74c3c', 'fontWeight': 'bold'})
        ], style={'textAlign': 'center', 'marginBottom': '20px', 'padding': '10px'}),

        dcc.Graph(id='road-profile-graph', style={'height': '400px'}),

        html.Div([
            html.H3("Instructions:", style={'color': '#2c3e50'}),
            html.Ul([
                html.Li("The dark grey line represents the road profile"),
                html.Li("The red point at (0, 2.0) represents the camera position"),
                html.Li("The blue line shows the camera ray at the specified angle"),
                html.Li("The green point shows where the ray intersects the road"),
                html.Li("Hover over the green point to see the distance from camera to intersection"),
                html.Li("Adjust the angle to see how the intersection point changes"),
                html.Li("Negative angles point downward, positive angles point upward")
            ])
        ], style={'margin': '20px', 'padding': '20px', 'backgroundColor': '#ecf0f1', 'borderRadius': '5px'})
    ])

    # Define the callback to update the graph
    @app.callback(
        [Output('road-profile-graph', 'figure'),
         Output('intersection-info', 'children')],
        [Input('angle-input', 'value')]
    )
    def update_graph(angle):
        """
        Update the graph based on the input angle.

        Parameters
        ----------
        angle : float
            Camera ray angle in degrees

        Returns
        -------
        tuple
            (plotly figure, info text)
        """
        if angle is None:
            angle = -1.1

        # Generate road profile
        x_road, y_road = generate_road_profile(num_points=100, x_max=80)

        # Camera position
        camera_x, camera_y = 0, 2.0

        # Find intersection first to determine ray length
        x_intersect, y_intersect, distance = find_intersection(
            x_road, y_road, angle, camera_x, camera_y
        )

        # Calculate adaptive ray line based on intersection
        if x_intersect is not None:
            # Ray goes from camera to intersection point
            x_ray = np.array([camera_x, x_intersect])
            y_ray = np.array([camera_y, y_intersect])
        else:
            # No intersection - show a short ray (20 units or to edge of plot)
            angle_rad = -np.deg2rad(angle)
            if np.abs(np.cos(angle_rad)) < 1e-10:
                # Vertical line
                x_ray = np.array([camera_x, camera_x])
                y_ray = np.array([camera_y, camera_y - 10])
            else:
                slope = np.tan(angle_rad)
                x_end = min(camera_x + 20, 80)
                y_end = camera_y + slope * (x_end - camera_x)
                x_ray = np.array([camera_x, x_end])
                y_ray = np.array([camera_y, y_end])

        # Create figure
        fig = go.Figure()

        # Add road profile
        fig.add_trace(go.Scatter(
            x=x_road,
            y=y_road,
            mode='lines+markers',
            name='Road Profile',
            line=dict(color='#4a4a4a', width=3),
            marker=dict(size=4, color='#4a4a4a'),
            hovertemplate='Road<br>x: %{x:.2f}<br>y: %{y:.2f}<extra></extra>'
        ))

        # Add camera point
        fig.add_trace(go.Scatter(
            x=[camera_x],
            y=[camera_y],
            mode='markers',
            name='Camera',
            marker=dict(size=12, color='red', symbol='circle'),
            hovertemplate='Camera<br>Position: (%{x:.2f}, %{y:.2f})<extra></extra>'
        ))

        # Add camera ray
        fig.add_trace(go.Scatter(
            x=x_ray,
            y=y_ray,
            mode='lines',
            name=f'Camera Ray ({angle}°)',
            line=dict(color='blue', width=2, dash='dash'),
            hovertemplate='Camera Ray<br>x: %{x:.2f}<br>y: %{y:.2f}<extra></extra>'
        ))

        # Add intersection point if it exists
        info_text = ""
        if x_intersect is not None:
            fig.add_trace(go.Scatter(
                x=[x_intersect],
                y=[y_intersect],
                mode='markers',
                name='Intersection',
                marker=dict(size=15, color='green', symbol='star'),
                hovertemplate=f'Intersection Point<br>Position: ({x_intersect:.2f}, {y_intersect:.2f})<br>Distance from camera: {distance:.2f}<extra></extra>'
            ))
            info_text = f"Intersection found at ({x_intersect:.2f}, {y_intersect:.2f}) | Distance: {distance:.2f} units"
        else:
            info_text = "No intersection found with current angle"

        # Update layout
        fig.update_layout(
            xaxis_title="X Position (m)",
            yaxis_title="Y Position (m)",
            hovermode='closest',
            showlegend=True,
            legend=dict(
                x=1.02,
                y=1,
                xanchor='left',
                yanchor='top',
                bgcolor='rgba(255,255,255,0.8)',
                bordercolor='#dee2e6',
                borderwidth=1
            ),
            plot_bgcolor='#f8f9fa',
            xaxis=dict(
                gridcolor='#dee2e6',
                range=[-2, 82],
                constrain='domain'
            ),
            yaxis=dict(
                gridcolor='#dee2e6',
                scaleanchor='x',
                scaleratio=1,
                range=[-0.5, 10],
                constrain='domain'
            ),
            margin=dict(l=50, r=150, t=30, b=50)
        )

        return fig, info_text

    return app

"""
Road Profile Viewer - Entry Point

This is the main entry point for the Road Profile Viewer application.
All functionality is implemented in separate modules:
- geometry.py: Ray intersection calculations
- road.py: Road profile generation
- visualization.py: Dash UI and visualization

To run the application:
    $ uv run road-profile-viewer
"""

from visualization import create_dash_app


def main():
    """
    Main function to run the Dash application.
    """
    app = create_dash_app()
    print("Starting Road Profile Viewer...")
    print("Open your browser and navigate to: http://127.0.0.1:8050/")
    print("Press Ctrl+C to stop the server.")
    app.run(debug=True)


if __name__ == '__main__':
    main()

# main.py importiert:
from visualization import create_dash_app

# visualization.py importiert:
from geometry import calculate_ray_line, find_intersection
from road import generate_road_profile

# geometry.py importiert:
import numpy as np  # Nur externe Abhängigkeit

# road.py importiert:
import numpy as np  # Nur externe Abhängigkeit

# "Wo ist die Schnittpunkt-Berechnung?"
# *Scrollt durch 390 Zeilen*

# "Wo ist die Schnittpunkt-Berechnung?"
# Öffnet geometry.py → find_intersection() ist direkt da

# Änderung des Straßengenerierungs-Algorithmus
# Datei: main.py (390 Zeilen - könnte versehentlich UI brechen)

# Änderung des Straßengenerierungs-Algorithmus
# Datei: road.py (67 Zeilen - kann UI-Code nicht versehentlich anfassen)

# Um find_intersection() zu testen
from main import find_intersection  # Importiert ALLES
# Dash startet, langsame Imports, potenzielle Seiteneffekte

# Um find_intersection() zu testen
from geometry import find_intersection  # Importiert nur Geometrie
# Schnell, fokussiert, keine Seiteneffekte

# Wollen Sie find_intersection() in einem anderen Projekt verwenden?
# Copy-Paste aus main.py → bringt unnötigen Dash-Code mit

# Wollen Sie find_intersection() in einem anderen Projekt verwenden?
# Kopieren Sie einfach geometry.py → sauberes, eigenständiges Modul

# visualization.py
from road import generate_road_profile

# road.py (SCHLECHT!)
from visualization import create_dash_app  # Warum sollte road.py UI-Code brauchen??

# Wo gehören camera_x und camera_y hin?
# - geometry.py? (wird in Berechnungen verwendet)
# - visualization.py? (ist ein UI-Parameter)
# - Eine neue config.py Datei?

# In main.py
def main():
    x, y = generate_road_profile()  # NameError: generate_road_profile not defined

# Fügen Sie den Import am Anfang hinzu
from road import generate_road_profile