ZanzoCam - Internal documentation

Internal documentation for zanzocam-core.

Better documentation coming soon.

Constants

Details of the constants stored in the zanzocam.constants module.

zanzocam.constants.AUTOHOTSPOT_BINARY_PATH = '/usr/bin/autohotspot': Path to the autohotspot script

zanzocam.constants.BACKUP_CRONJOB = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/.crontab.bak'): Path to the crontab’s backup

zanzocam.constants.BASE_PATH = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam'): Folder containing the source code

zanzocam.constants.CAMERA_DEFAULTS = {'awb_mode': 'auto', 'background_color': (0, 0, 0, 0), 'date_format': '%d %B %Y', 'extension': 'jpg', 'height': 100, 'hor_flip': False, 'jpeg_quality': 90, 'jpeg_subsampling': 0, 'let_awb_settle_in_dark': False, 'name': 'no-name', 'rotation': 0, 'time_format': '%H:%M', 'use_low_light_algorithm': True, 'ver_flip': False, 'width': 100}: Fallback values for the camera configuration

zanzocam.constants.CAMERA_LOGS = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/camera'): Logs produced during the main procedure (will be sent to the server)

zanzocam.constants.CAMERA_WARM_UP_TIME = 5: Time to allow the firmware to compute the right exposure in normal light conditions (AWB requires more)

zanzocam.constants.CHECK_UPLINK_URL = 'http://www.google.com': URL to check to ensure Internet is reachable

zanzocam.constants.CONFIGURATION_FILE = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/configuration.json'): Main configuration file

zanzocam.constants.CRONJOB_FILE = '/etc/cron.d/zanzocam': Path to the system crontab

zanzocam.constants.DATA_PATH = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data'): Folder containing the data used by the ZanzoCam for its operations

zanzocam.constants.FAILURE_REPORT_PATH = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/failure_report.txt'): Logs produced in case of issues with the server

zanzocam.constants.FONT_PATH = '/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf': Path to the default font (can be customized if you install another font)

zanzocam.constants.FTP_CONFIG_FILE_ENCODING = 'utf-8': Ecoding of the FTP server files

zanzocam.constants.HOTSPOT_FLAG = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/hotspot.flag'): Whether the hotspot is allowed

zanzocam.constants.IMAGE_OVERLAYS_PATH = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/overlays'): Local camera overlays path

zanzocam.constants.INITIAL_LOW_LIGHT_ISO = 400: Starting ISO level for low light pictures

zanzocam.constants.LOCALE = 'it_IT.utf8': Locale

zanzocam.constants.LOG_NAME_FORMAT = 'logs %d-%m-%Y %H:%M:%S.log': Used with datetime to format the log name

zanzocam.constants.MAX_SHUTTER_SPEED = 9500000: Max shutter speed allowed by the camera hardware

zanzocam.constants.MINIMUM_DAYLIGHT_LUMINANCE = 60: Minimum luminance for the daytime. If the detected luminance goes below this value, the night mode kicks in.

zanzocam.constants.MINIMUM_NIGHT_LUMINANCE = 30: Minimum luminance to target for pictures in low light conditions.

zanzocam.constants.MIN_SHUTTER_SPEED = 30000: Min shutter speed for low light, the max that PiCamera would use with automatic settings

zanzocam.constants.NO_LUMINANCE_SHUTTER_SPEED = 2000000: What “random” shutter speed to use if the image is so black that the equation doesn’t work

zanzocam.constants.NO_LUMINANCE_THRESHOLD = 1: When to consider the image totally black, where the low light estimation doesn’t work well

zanzocam.constants.OVERLAY_DEFAULTS = {'background_color': (255, 255, 255, 0), 'font_color': (0, 0, 0), 'font_size': 30, 'heigth': None, 'image': None, 'over_the_picture': False, 'padding': 10, 'text': '... testo ...', 'width': None}: Fallback values for the image overlays

zanzocam.constants.PICAMERA_AWB_MODES = ['off', 'auto', 'sunlight', 'cloudy', 'shade', 'tungsten', 'fluorescent', 'incandescent', 'flash', 'horizon']: White balancing modes from picamera

zanzocam.constants.PICTURE_LOGS = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/picture_logs.txt'): Temporary camera logs for the web UI

zanzocam.constants.PREVIEW_PICTURE = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/web_ui/static/previews/zanzocam-preview.jpg'): Path to the preview picture in the web UI

zanzocam.constants.PREVIEW_PICTURE_URL = 'static/previews/zanzocam-preview.jpg': URL to the preview picture in the web UI

zanzocam.constants.REMOTE_IMAGES_PATH = 'configuration/overlays/': Remote camera overlays path

zanzocam.constants.REQUEST_TIMEOUT = 60: Timeout for HTTP requests

zanzocam.constants.SEND_LOGS_FLAG = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/send-logs.flag'): Whether to send the logs to the server

zanzocam.constants.SERVER_LOG = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/interface.log'): Logs of the local server (stay on disk and get rotated)

zanzocam.constants.SYSTEM_USER = 'zanzocam-bot': Main user of the system, must be able to perform a passwordless sudo

zanzocam.constants.TARGET_LUMINOSITY_MARGIN = 3: How much tolerance to give to the low light search algorithm

zanzocam.constants.TEMP_CRONJOB = PosixPath('/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/.tmp-cronjob-file'): Temporary crontab path

zanzocam.constants.VERSION = '1.3.2': ZanzoCam version

zanzocam.constants.WAIT_AFTER_CAMERA_FAIL = 30: Time to wait in between failed shots of the camera (to overcome colliding crontabs)

zanzocam.constants.ZANZOCAM_EXECUTABLE = '/home/zanzocam-bot/venv/bin/z-webcam': Location of the z-webcam executable

Main module

The zanzocam.webcam.main module contains the main script that is executed at every trigger.

Here is some internal documentation of it.

Configuration module

Details of the zanzocam.webcam.configuration module.

class zanzocam.webcam.configuration.Configuration(path: Optional[Path] = None)

Bases: object

Manages the configurations.

backup(path: Optional[str] = None)

Creates a backup copy of the configuration file.

NOTE: we backup from memory and not simply copy the file because the file might have been overwritten by a server (server.update_configuration()) in the meantime.

static create_from_dictionary(data: Dict, path: Optional[Path] = None) → Configuration: Creates a Configuration object starting from a dictionary. Will save the configuration file at the specified path.

get_camera_settings(): Return all the information relative to the settings used to take and render the picture.

get_server_settings(): Return all the information relative to the settings used to connect to the server.

get_start_time(): Return either the start time defined, or 00:00

get_stop_time(): Return either the stop time defined, or 23:59

get_system_settings()

Return all the information relative to the settings that should be applied to the system.

For now is just the time settings.

list_overlays() → List[str]: List all the overlay images that should be downloaded from the server

restore_backup() → bool

Restores the configuration file from its backup copy. Does not try to reload the old config.

Returns True in case of no errors, False otherwise.

within_active_hours() → Optional[bool]

Compares the current time with the start-stop times.

Returns True if inside the interval, False if outside, None if an error occured.

zanzocam.webcam.configuration.load_configuration_from_disk(path='/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/configuration.json', backup_path='/home/runner/work/zanzocam-core/zanzocam-core/zanzocam/data/configuration.json.bak', quiet: bool = False) → Optional[Configuration]

Load current configuration from disk, or try with its backup if the file is not found.

Returns None if some error occurred.

System module

Details of the zanzocam.webcam.system module.

Camera module

Details of the zanzocam.webcam.camera module.

Overlays module

Details of the zanzocam.webcam.overlays module.

class zanzocam.webcam.overlays.Overlay(position: str, data: Dict, photo_width: int, photo_height: int, date_format: Optional[str], time_format: Optional[str])

Bases: object

Represents one overlay to add to the picture.

compute_position(image_width: int, image_height: int, border_top: int, border_bottom: int) → Tuple[int, int]: Returns the x,y position in the picture where this overlay should be pasted.

create_image_overlay() → Any: Prepares an overlay containing an image. Might return None in case of issues.

create_text_overlay(photo_width: int, photo_height: int) → Any: Prepares an overlay containing text. In case of issues, self.overlay_image will stay None.

process_text(font: Any, max_line_length: int) → Tuple[int, int]: Measures and insert returns into the text to make it fit into the image.

Utils module

Details of the zanzocam.webcam.utils module.

class zanzocam.webcam.utils.AllStringEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

To transform every value into a string

default(o)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

zanzocam.webcam.utils.log(msg: str) → None: Logs the message to the console

zanzocam.webcam.utils.log_error(msg: str, e: Optional[Exception] = None, fatal: Optional[str] = None) → None: Logs an error to the console

zanzocam.webcam.utils.log_row(char: str = '=') → None: Logs a row to the console

zanzocam.webcam.utils.retry(times: int, wait_for: float)

Makes the decorated function try to run without exceptions ‘times’ times. If an exception occurs, logs it and tries again after wait_for seconds. Otherwise returns at the first successful attempt.

Returns None in case there is an exception at the last run as well.

Custom Errors

Details of the zanzocam.webcam.errors module.

exception zanzocam.webcam.errors.ServerError: Bases: Exception