Repository: opencv
Issue: Docs for Python imshow example improvement
Labels: category: documentation

### Describe the doc issue

Hello -- 

I feel a most basic feature, like display the image, can also be 2000.0% documentation for python.  

After the display, need to learn the un-display.  

Learning to opencv is show image first, but can forget about GUI loop implementation to freeze a python kernel.

I share some suggestion.  

Thanks you.

-- K2P



```
# =============================================================================
# from win32api import GetSystemMetrics
#     screen_w, screen_h = (GetSystemMetrics(0), GetSystemMetrics(1))
#     screen_mid = [x//2 for x in (screen_w, screen_h)]
#     wdt = size
#     if img.ndim == 2:
#         hgt = int(np.divide(*img.shape) * wdt)
#     elif img.ndim == 3:
#         assert img.shape[-1] == 3
#         hgt = int(np.divide(*img.shape[:2]) * wdt)
#     xpos = max(0, screen_mid[0] - (wdt//2))
#     ypos = max(0, screen_mid[1] - (hgt//2))
    # cv2.resizeWindow(winname, wdt, hgt)
    # cv2.moveWindow(winname, xpos, ypos)
    # cv2.applyColorMap(img, cv2.COLORMAP_VIRIDIS)
# =============================================================================
    

import cv2
import time


def opencv_show_image(img, winname='winname', time_limit_s=60):
    ## GIVE NAME TO CHECK IF CLOSED (BELOW)
    cv2.namedWindow(winname, cv2.WINDOW_KEEPRATIO)
    
    ## SHOW IMAGE
    cv2.imshow(winname, img)
    
    ## DISPLAY DURING GUI LOOP
    birth, elapsed = time.perf_counter(), 0
    while (elapsed < time_limit_s):
        
        ## LISTEN FOR KEY PRESSED TIME (no keypress = -1, any key pressed > 0)
        keyCode = cv2.waitKey(100) #msecs to wait
        
        ## CHECK WINDOW CLOSED BY USER CLICK X (visible=1.0, hidden=0.0)
        resp = cv2.getWindowProperty(winname, cv2.WND_PROP_VISIBLE) 
        if (keyCode > 0) or (resp < 0.5):
            break
        elapsed = time.perf_counter() - birth
        
    ## KILL ALL OPENCV WINDOW TO RETURN PYTHONG CONTROL
    cv2.destroyAllWindows()
    return
```


### Fix suggestion

Hello -- 

I feel a most basic feature, like display the image, can also be 2000.0% documentation for python.  

After the display, need to learn the un-display.  

Learning to opencv is show image first, but can forget about GUI loop implementation to freeze a python kernel.

I share some suggestion.  

Thanks you.

-- K2P



```
# =============================================================================
# from win32api import GetSystemMetrics
#     screen_w, screen_h = (GetSystemMetrics(0), GetSystemMetrics(1))
#     screen_mid = [x//2 for x in (screen_w, screen_h)]
#     wdt = size
#     if img.ndim == 2:
#         hgt = int(np.divide(*img.shape) * wdt)
#     elif img.ndim == 3:
#         assert img.shape[-1] == 3
#         hgt = int(np.divide(*img.shape[:2]) * wdt)
#     xpos = max(0, screen_mid[0] - (wdt//2))
#     ypos = max(0, screen_mid[1] - (hgt//2))
    # cv2.resizeWindow(winname, wdt, hgt)
    # cv2.moveWindow(winname, xpos, ypos)
    # cv2.applyColorMap(img, cv2.COLORMAP_VIRIDIS)
# =============================================================================
    

import cv2
import time


def opencv_show_image(img, winname='winname', time_limit_s=60):
    ## GIVE NAME TO CHECK IF CLOSED (BELOW)
    cv2.namedWindow(winname, cv2.WINDOW_KEEPRATIO)
    
    ## SHOW IMAGE
    cv2.imshow(winname, img)
    
    ## DISPLAY DURING GUI LOOP
    birth, elapsed = time.perf_counter(), 0
    while (elapsed < time_limit_s):
        
        ## LISTEN FOR KEY PRESSED TIME (no keypress = -1, any key pressed > 0)
        keyCode = cv2.waitKey(100) #msecs to wait
        
        ## CHECK WINDOW CLOSED BY USER CLICK X (visible=1.0, hidden=0.0)
        resp = cv2.getWindowProperty(winname, cv2.WND_PROP_VISIBLE) 
        if (keyCode > 0) or (resp < 0.5):
            break
        elapsed = time.perf_counter() - birth
        
    ## KILL ALL OPENCV WINDOW TO RETURN PYTHONG CONTROL
    cv2.destroyAllWindows()
    return
```