# CommandSection

title: SYNOPSIS
content:
<b>powerprofilesctl</b> [<i>OPTIONS</i>] <i>COMMAND</i> [<i>ARGUMENTS</i>]<br><br>Commands:<br>  <b>list</b><br>  <b>get</b><br>  <b>set</b> <i>&lt;profile_name&gt;</i>


title: PARAMETERS
content:
<b><b>list</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists all available power profiles and indicates the currently active one.<br><br><b><b>get</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the name of the currently active system power profile.<br><br><b><b>set</b> <i>&lt;profile_name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the system's power profile to the specified <i>&lt;profile_name&gt;</i>. Valid profile names can be found using the <b>list</b> command.<br><br><b><b>-r</b>, <b>--recursive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Used with <b>set</b>) Attempts to apply the chosen power profile recursively to all supported hardware components, such as CPU and GPU, if the profile and underlying drivers support it. This might offer deeper power optimizations or performance boosts.<br><br><b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message for the command and exits.<br><br><b><b>-V</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version information of <b>powerprofilesctl</b> and exits.<br><br>


title: DESCRIPTION
content:
<b>powerprofilesctl</b> is a command-line utility used to query and control the power profiles of a Linux system. It acts as an interface to the <b>power-profiles-daemon</b>, a key component that standardizes how power settings are managed across diverse hardware configurations. Through <b>powerprofilesctl</b>, users can easily switch between predefined power modes such as "balanced," "power-saver," and "performance." Each profile intelligently adjusts underlying system parameters, including CPU frequency scaling, power limits, and fan behavior, to optimize for either energy efficiency or maximum computational power. This tool provides a consistent and unified approach to system power management, abstracting complex low-level hardware configurations into simple, user-friendly choices, and is widely integrated into modern desktop environments like GNOME and KDE for a seamless user experience.


title: CAVEATS
content:
The effectiveness and available profiles of <b>powerprofilesctl</b> depend heavily on the presence and configuration of the <b>power-profiles-daemon</b> service. The actual impact of setting a profile (e.g., changes in CPU speed, fan noise) can vary based on your system's specific hardware and kernel support. The <b>--recursive</b> flag's functionality is also contingent on driver and profile implementation.


title: INTEGRATION WITH DESKTOP ENVIRONMENTS
content:
This command provides the underlying CLI interface for power profile management often exposed through graphical settings panels in desktop environments like GNOME (under Power settings) and KDE Plasma. This ensures a consistent user experience whether managing power profiles via GUI or command line, as both interfaces interact with the same underlying daemon.


title: HOW PROFILES WORK
content:
Power profiles abstract complex low-level power management settings. When a profile is set, the <b>power-profiles-daemon</b> communicates with kernel drivers (e.g., <i>intel_pstate</i>, <i>amd_pstate</i>, <i>cpufreq</i>) and other hardware-specific services to adjust parameters like CPU governor, maximum frequency, power limits, and potentially GPU clock speeds or fan curves. The specific parameters adjusted depend on the profile's intent (e.g., "power-saver" prioritizes efficiency, "performance" prioritizes speed, and "balanced" aims for a middle ground).


title: HISTORY
content:
<b>powerprofilesctl</b> is part of the <b>power-profiles-daemon</b> project, which was developed to provide a standardized, D-Bus-based interface for system power profiles. It emerged as a solution to unify power management across different hardware and desktop environments, especially as distributions like Ubuntu and Fedora adopted it. Its development aimed to replace more ad-hoc power management scripts and tools with a robust, consistent framework. The daemon and its control utility, <b>powerprofilesctl</b>, gained prominence in the late 2010s and early 2020s, becoming a core component for modern Linux power management.


title: SYNOPSIS
content:
<b>powershell</b> { <b>-Command</b> <<i>string</i>> | <b>-File</b> <<i>path</i>> } [<b>-NoProfile</b>] [<b>-NoExit</b>] [<b>-NonInteractive</b>] [<b>-Version</b> <<i>string</i>>] [<b>-EncodedCommand</b> <<i>string</i>>] [<b>-Help</b>] [<i><script_parameters></i>]


title: PARAMETERS
content:
<b><b>-Command</b> <<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes the specified commands or script blocks. This is the primary way to run short commands or call scripts from the command line.<br><br><b><b>-File</b> <<i>path</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs the specified <i>PowerShell</i> script file. Any additional arguments following <b>-File</b> are passed as parameters to the script.<br><br><b><b>-NoProfile</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not load the current user's <i>PowerShell</i> profile. Useful for clean environments or performance testing.<br><br><b><b>-NoExit</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Does not exit after running startup commands. The <i>PowerShell</i> session remains open after the command or script finishes.<br><br><b><b>-NonInteractive</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <i>PowerShell</i> from prompting for user input. Essential for automated scripts in CI/CD pipelines.<br><br><b><b>-EncodedCommand</b> <<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Accepts a base-64 encoded string version of a command. Useful for obfuscating commands or handling complex strings.<br><br><b><b>-Version</b> <<i>string</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the <i>PowerShell</i> version to use. For example, <b>-Version 7.x</b>.<br><br><b><b>-Help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays help information for the <i>powershell</i> command-line executable.<br><br>


title: DESCRIPTION
content:
<i>PowerShell</i> is a powerful <b>cross-platform</b> task automation and configuration management framework, developed by Microsoft. It includes a command-line shell, a scripting language, and a framework for processing cmdlets. On Linux, <i>PowerShell</i> enables administrators and developers to leverage its rich object-oriented pipeline and extensive cmdlet ecosystem to manage systems consistently across diverse environments, including cloud services and hybrid infrastructures.<br>It brings the capabilities of <i>PowerShell</i>, previously Windows-centric, to Linux, facilitating operations like system administration, deployment, and data processing with a unified scripting experience.


title: CAVEATS
content:
While <i>PowerShell</i> offers powerful capabilities on Linux, users should be aware of a few points:<br>1. <b>Platform Parity:</b> Not all cmdlets available on Windows are present or function identically on Linux (e.g., cmdlets interacting with Windows-specific APIs).<br>2. <b>Performance:</b> For very simple tasks, native Linux utilities might offer better performance due to <i>PowerShell</i>'s .NET runtime overhead.<br>3. <b>Integration:</b> Direct piping with traditional Linux text-based tools can require careful handling due to <i>PowerShell</i>'s object-oriented pipeline.


title: INSTALLATION ON LINUX
content:
<i>PowerShell</i> can be installed on various Linux distributions. The most common methods involve downloading official Microsoft packages (e.g., .deb, .rpm) or using a package manager after adding the Microsoft repository. Installation details vary by distribution.


title: CORE CONCEPTS
content:
<i>PowerShell</i>'s strength lies in its core concepts:<br><b>Cmdlets:</b> Lightweight, single-function commands that often follow a Verb-Noun naming convention (e.g., <b>Get-Process</b>).<br><b>Pipeline:</b> Commands can be chained together, passing objects (not just text) from one cmdlet to the next.<br><b>Object-Oriented:</b> Commands output objects with properties and methods, enabling powerful filtering and manipulation.


title: HISTORY
content:
<i>PowerShell</i> was originally developed by Microsoft for Windows, with its first stable version released in 2006. It was designed to provide a more consistent and powerful way to manage Windows systems than traditional command prompts.<br>In 2016, Microsoft open-sourced <i>PowerShell</i> and made it cross-platform, releasing <i>PowerShell Core</i> (now simply known as <i>PowerShell</i>) for Linux and macOS. This move aimed to provide a unified management experience across hybrid and cloud environments, bridging the gap between Windows and non-Windows systems.


title: PARAMETERS
content:
<b><b>-r</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Raw output</I><br>Displays raw power values without unit conversion or aggregation.<br><br><b><b>-c</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>CSV output</I><br>Outputs data in a comma-separated values (CSV) format, suitable for parsing and analysis.<br><br><b><b>-C</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Cumulative power</I><br>Reports cumulative power consumption since the start of the command or the last reset.<br><br><b><b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Per-processor power</I><br>Shows power consumption for each individual CPU core/processor if supported by hardware.<br><br><b><b>-a</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show all</I><br>Includes all available power metrics in the output, overriding defaults.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Quiet mode</I><br>Suppresses the initial header, displaying only the power statistics.<br><br><b><b>-H</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>No header</I><br>Similar to <b>-q</b>, but typically used for more compact output when piping to other tools.<br><br><b><b>-i <I>interval</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Sampling interval</I><br>Sets the time in seconds between each power measurement sample. The default is 5 seconds.<br><br><b><b>-n <I>count</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Number of samples</I><br>Specifies the total number of samples to take before exiting. By default, <b>powerstat</b> runs indefinitely.<br><br><b><b>-R</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Reset battery counter</I><br>Resets the battery power counter, useful for starting a fresh measurement cycle.<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>System units</I><br>Displays power in system units (e.g., Watts) instead of the default percentage or other abstracted units.<br><br><b><b>-z</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show idle states</I><br>Includes information about CPU idle states (C-states) and their residency.<br><br><b><b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Debug output</I><br>Enables verbose debugging information, useful for troubleshooting.<br><br><b><b>-D</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Display device names</I><br>Attempts to display human-readable names for detected power devices.<br><br><b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Help</I><br>Displays a brief help message and exits.<br><br><b><b>-o <I>FILENAME</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Output to file</I><br>Redirects the command's output to the specified file instead of standard output.<br><br><b><b>-S <I>SECTION</I></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specific section</I><br>Filters the output to show only a particular section, e.g., <b>CPU</b>, <b>GPU</b>, <b>DEVICES</b>, <b>BATTERY</b>.<br><br><b><b>-T</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Show temperature</I><br>Includes temperature readings from available sensors in the output.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Version</I><br>Displays the <b>powerstat</b> version information and exits.<br><br>


title: DESCRIPTION
content:
<b>powerstat</b> is a Linux command-line tool designed to measure the power consumption of a running system. It provides real-time insights into various power-related metrics, including CPU, GPU, device, and battery usage. The tool samples power counters and presents the data in a human-readable format, making it invaluable for diagnosing power-related issues, evaluating power efficiency of hardware components, or monitoring the impact of system configurations on energy consumption.<br><br>It relies on hardware support for reporting power data, such as Intel's RAPL (Running Average Power Limit) interface for CPUs. <b>powerstat</b> can display average, minimum, and maximum power values over a specified interval, helping users understand power trends under different workloads. Its output can be customized to show raw data, CSV format, or focus on specific hardware sections. It's often used by developers and system administrators to optimize energy usage and extend battery life on portable devices.


title: CAVEATS
content:
<I>Root Privileges Required</I>: <b>powerstat</b> often requires root privileges (or <b>sudo</b>) to access hardware power counters and system metrics.<br><br><I>Hardware Dependency</I>: The accuracy and completeness of the reported data are highly dependent on the underlying hardware's support for power reporting interfaces (e.g., Intel RAPL, AMD PMC, ACPI). Not all systems or components will provide full data.<br><br><I>System Overhead</I>: While generally lightweight, running <b>powerstat</b> continuously may introduce a minimal amount of system overhead due to data sampling.<br><br><I>Interpretation</I>: Understanding the reported values (especially raw ones) might require knowledge of specific hardware architectures and power management concepts.


title: UNITS OF MEASUREMENT
content:
By default, <b>powerstat</b> attempts to display power in Watts (W) or Joules (J), but depending on the hardware and the <b>-s</b> option, it might show percentages or abstract values. Understanding the units is crucial for correct interpretation.


title: TYPICAL USAGE
content:
A common way to use <b>powerstat</b> is <b>sudo powerstat 5 10</b> to take 10 samples at 5-second intervals, or <b>sudo powerstat -S CPU</b> to focus specifically on CPU power.


title: INTERPRETING OUTPUT
content:
The output typically shows average, minimum, and maximum power consumption over the sampling period, along with battery drain rates if applicable. High variability between min/max can indicate fluctuating workloads.


title: HISTORY
content:
<b>powerstat</b> originated from the Ubuntu Kernel team, with significant contributions from Arjan van de Ven. It was developed to provide a simpler, more direct alternative or complement to existing power profiling tools like <b>powertop</b>, which primarily focuses on identifying specific processes or components causing power drain. <b>powerstat</b> instead gives an immediate, aggregated overview of system-wide power consumption, making it quick to assess the overall power state and the impact of system changes. Its development aligns with the broader Linux community's effort to improve power efficiency on servers and portable devices.


title: SEE ALSO
content:
<b>powertop(8)</b>, <b>perf(1)</b>, <b>turbostat(8)</b>, <b>s-tui(1)</b>, <b>mpstat(1)</b>, <b>iostat(1)</b>


title: PARAMETERS
content:
<b><b>-h</b>, <b>--help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits.<br><br><b><b>-v</b>, <b>--version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the <b>powertop</b> version information and exits.<br><br><b><b>-d</b>, <b>--debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debug output for more verbose operation, useful for troubleshooting.<br><br><b><b>-r</b>, <b>--html=</b><i>FILENAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a detailed HTML report of the current power consumption analysis to the specified <i>FILENAME</i>.<br><br><b><b>-c</b>, <b>--csv=</b><i>FILENAME</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a CSV report suitable for spreadsheet analysis to the specified <i>FILENAME</i>.<br><br><b><b>-t</b>, <b>--time=</b><i>SECONDS</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs <b>powertop</b> for the specified number of <i>SECONDS</i> in non-interactive mode and then exits.<br><br><b><b>-C</b>, <b>--calibrate</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs a calibration cycle to improve the accuracy of power consumption estimates, especially when running on battery.<br><br><b><b>-a</b>, <b>--auto-tune</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies all recommended power-saving tunables (marked as <i>"Good"</i>) to the system automatically. This is a common and powerful option for immediate optimization.<br><br><b><b>-q</b>, <b>--quiet</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses non-essential output, making it useful for scripting or automated environments.<br><br><b><b>--workload=</b><i>COMMAND</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Executes <i>COMMAND</i> during the calibration or reporting phase to simulate a specific system load and observe its power impact.<br><br><b><b>--battery</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <b>powertop</b> to use battery discharge data for calibration and reporting, even if the system is currently on AC power.<br><br><b><b>--no-ac</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>powertop</b> from checking for AC power status, useful for debugging specific power states or scenarios.<br><br>


title: DESCRIPTION
content:
<b>powertop</b> is an essential Linux utility developed by Intel that helps users identify what is consuming power on their system and suggests ways to reduce it. It provides an interactive, curses-based interface showing real-time power consumption estimates for individual processes, devices, kernel timers, and other system components. The tool categorizes items as <i>"Good"</i> or <i>"Bad"</i> for power efficiency and offers a <i>"Tunables"</i> tab where users can apply various power-saving optimizations, such as enabling <i>runtime PM</i> for USB devices, configuring <i>ALPM</i> for SATA controllers, or adjusting <i>CPU frequency scaling</i> governors.<br><br>It leverages kernel data like wakeups, device activity, and CPU states to generate its insights. <b>powertop</b> is invaluable for laptop users looking to extend battery life, server administrators aiming to reduce energy costs, and developers optimizing embedded systems for low power. It's a proactive tool that not only reports but also helps implement power efficiency improvements, aiming to maximize energy savings without compromising system stability.


title: CAVEATS
content:
<b>powertop</b> requires <i>root</i> privileges (e.g., using <b>sudo</b>) to display full power consumption information and apply tunables. Power consumption estimates are approximations and may not always be perfectly accurate, especially without proper calibration. Applying <b>--auto-tune</b> might, in rare cases, affect performance or cause minor system instability with certain hardware configurations (e.g., some USB devices might misbehave after suspension). The tool itself consumes some power while running. Modern Linux kernels and hardware often have good default power management, so <b>powertop</b>'s impact might be less dramatic on newer systems but still valuable for fine-tuning.


title: INTERACTIVE INTERFACE TABS
content:
When run without arguments, <b>powertop</b> presents an interactive interface with several tabs:<br><ul><li><b>Overview</b>: Provides a summary of estimated power consumption.</li><li><b>Idle stats</b>: Shows how much time the CPU spends in various idle (C-states).</li><li><b>Device stats</b>: Displays activity and estimated power usage for individual hardware devices.</li><li><b>Tunables</b>: Lists potential power-saving optimizations, indicating whether they are currently <i>"Bad"</i> (not optimized) or <i>"Good"</i> (optimized). You can toggle these manually.</li><li><b>WakeUp</b> (or <b>Frequency/Statistics</b>): Shows what components are waking up the system or detailed statistics on CPU frequencies.</li></ul>


title: CALIBRATION FOR ACCURACY
content:
For the most accurate power consumption estimates, especially for battery drain, it is highly recommended to run <b>powertop</b> with the <b>--calibrate</b> option. This performs a short calibration cycle, usually involving a few minutes of measurement, to better understand your system's specific power characteristics while on battery power.


title: GENERATING REPORTS
content:
For long-term analysis or sharing results, <b>powertop</b> can generate static reports in HTML or CSV formats using the <b>--html=</b><i>FILENAME</i> or <b>--csv=</b><i>FILENAME</i> options respectively. These reports capture the detailed power statistics and tunable recommendations at a specific point in time, allowing for offline review and comparison.


title: HISTORY
content:
<b>powertop</b> was initially developed by Intel's <i>LessWatts.org</i> initiative, launched around 2007, with the primary goal of improving Linux power efficiency, especially for mobile devices like laptops. It quickly became an indispensable tool for identifying power regressions in the Linux kernel and user-space applications. Its development has continued to evolve alongside kernel changes and new hardware, playing a crucial role in making Linux a more power-efficient operating system. It remains a cornerstone tool for power analysis and optimization within the Linux ecosystem.


title: SYNOPSIS
content:
<b>ppdc</b> [ <i>options</i> ] <i>filename.ppd</i> [ ... ]<br><br>This command processes one or more <i>PPD</i> files.<br>By default, <b>ppdc</b> compiles the specified <i>PPD</i> files and writes the binary output to standard output (<i>stdout</i>). This output is typically redirected to a new file, for example: <b>ppdc</b> <i>input.ppd</i> > <i>output.binary</i>.<br>When used with the <i>-N</i> option, <b>ppdc</b> acts solely as a validator, checking the <i>PPD</i> file's syntax and structure without producing compiled output.


title: PARAMETERS
content:
<b><b>-D</b> <i>name=value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a variable for conditional compilation. This is useful for building <i>PPD</i> files that adapt to different environments or printer models based on predefined values.<br><br><b><b>-I</b> <i>directory</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an additional directory to search for included <i>PPD</i> files or other resources referenced within the main <i>PPD</i>.<br><br><b><b>-M</b> <i>directory</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a migration directory. This option is used when updating <i>PPD</i> files that might have changed structure or options, allowing for backward compatibility handling.<br><br><b><b>-N</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not compile the <i>PPD</i> file; only validate its syntax and structure. This option is primarily used for debugging and ensuring <i>PPD</i> file correctness.<br><br><b><b>-P</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pre-filter the <i>PPD</i> file. This option removes comments, whitespace, and performs basic optimizations, resulting in a cleaner and potentially smaller <i>PPD</i> file, without full binary compilation.<br><br><b><b>-W</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress warnings. This option prevents <b>ppdc</b> from displaying non-critical warning messages during processing, which can be useful when dealing with <i>PPD</i> files that are known to generate minor warnings but are otherwise functional.<br><br>


title: DESCRIPTION
content:
<b>ppdc</b> is the PostScript Printer Description Compiler for the Common Unix Printing System (CUPS).<br><br>Its primary role is to process <i>PPD</i> (PostScript Printer Description) files. <i>PPD</i> files are standardized text files that describe the capabilities and features of PostScript printers, including supported paper sizes, resolutions, duplexing options, and various device-specific settings.<br><br>When <b>ppdc</b> compiles a <i>PPD</i> file, it converts the human-readable text format into a more compact and efficient binary representation. This binary format allows CUPS to load and parse printer capabilities much faster, improving performance, especially in environments with many printers or complex <i>PPD</i> files.<br><br>Beyond compilation, <b>ppdc</b> also serves as a validator. It can check <i>PPD</i> files for syntax errors, compliance with Adobe's <i>PPD</i> specification, and other common issues, helping printer driver developers ensure the correctness and robustness of their <i>PPD</i>s. Additionally, it can pre-filter <i>PPD</i> files to remove comments or optimize their structure, which can be useful for distribution or specific CUPS configurations.


title: CAVEATS
content:
While <b>ppdc</b> is essential for traditional <i>PPD</i>-based printer configurations, modern printing standards like IPP Everywhere are increasingly common.<br>These newer standards aim to reduce the reliance on <i>PPD</i> files by providing more standardized and auto-discoverable printer capabilities.<br>Consequently, <b>ppdc</b>'s direct utility might decrease for purely IPP-based setups, though it remains crucial for supporting a vast array of legacy and feature-rich PostScript printers.


title: OUTPUT FORMATS
content:
By default, <b>ppdc</b> compiles <i>PPD</i> files into a binary format optimized for CUPS.<br>However, with the <i>-P</i> option, it can produce a 'pre-filtered' text <i>PPD</i>, which is an optimized version of the original <i>PPD</i> without comments or extraneous whitespace, but still in human-readable text format.<br>Without any output redirection, the compiled binary is sent to standard output (<i>stdout</i>).


title: PURPOSE OF PPD COMPILATION
content:
The compilation of <i>PPD</i> files into a binary format significantly speeds up the loading and parsing of printer capabilities by the CUPS daemon (<b>cupsd</b>).<br>This is especially beneficial in large printing environments or when dealing with complex <i>PPD</i> files that contain numerous options and constraints, ensuring quicker printer setup and job processing.


title: HISTORY
content:
<b>ppdc</b> is an integral part of the CUPS (Common Unix Printing System) project, which was originally developed by Easy Software Products and first released in 1997.<br>CUPS revolutionized printing on Unix-like systems by providing a standardized, modular, and network-aware printing solution.<br>As <i>PPD</i> files were central to describing printer capabilities in the PostScript world, a dedicated tool like <b>ppdc</b> was necessary to efficiently manage and optimize these files for the CUPS scheduler.<br>Its development has closely mirrored that of CUPS, evolving to support new <i>PPD</i> features and maintain compatibility across various PostScript specifications.


title: SEE ALSO
content:
<b>cupsd</b>(8), <b>lpadmin</b>(8), <b>lpinfo</b>(8), <b>cups-files.conf</b>(5), <b>cups-ppdc</b>(1)


title: PARAMETERS
content:
<b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Includes comments from the PPD file in the generated HTML output.<br><br><b>-f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs filter limits and common options defined in the PPD file.<br><br><b>-l language</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the language for the output HTML, e.g., 'en' for English, 'de' for German.<br><br><b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs all options defined in the PPD file, even if the PPD file specifies too many options (which might typically be truncated).<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, displaying additional information during the conversion process.<br><br><b>PPD_file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the PPD file to be converted into HTML.<br><br>


title: DESCRIPTION
content:
The <b>ppdhtml</b> command, part of the <I>cups-filters</I> package, is a utility designed to convert PostScript Printer Description (PPD) files into a single HTML file.<br>PPD files are standardized descriptions of a printer's capabilities, originally developed by Adobe for PostScript printers. They specify features like paper sizes, resolution, color depth, duplexing, and available printer options.<br>By converting a PPD file to HTML, <b>ppdhtml</b> makes it easy to view a printer's capabilities and options using a standard web browser. This is particularly useful for documenting printer features, integrating printer information into web-based administration interfaces, or for general debugging and understanding of a printer's configuration without needing specialized PPD parsing tools.<br>The generated HTML file typically includes sections for general printer information, installed options, media handling, and specific printer capabilities defined within the PPD. The command offers various options to control the verbosity and content of the generated HTML output.


title: CAVEATS
content:
While <b>ppdhtml</b> provides a human-readable format for PPD files, it's primarily a display utility. It does not allow for modification or dynamic interaction with the printer's capabilities.<br>Complex or malformed PPD files might result in incomplete or incorrect HTML output. The utility is dependent on a correctly formatted PPD file conforming to the Adobe PPD specification.


title: PPD FILES
content:
PPD files are standardized text files that describe the capabilities and available options for a PostScript printer. They are crucial for print drivers and spoolers (like CUPS) to correctly configure print jobs for a specific printer model. The <b>ppdhtml</b> tool helps in understanding the content of these files without needing to parse the raw PPD syntax.


title: EXIT STATUS
content:
The <b>ppdhtml</b> command returns 0 on success. Any non-zero exit status indicates an error during the conversion process.


title: HISTORY
content:
The <b>ppdhtml</b> command is part of the <I>cups-filters</I> project, which spun off from the main CUPS (Common Unix Printing System) project. CUPS was originally developed by Apple Inc. (previously Easy Software Products) to provide a modular printing system for Unix-like operating systems.<br>PPD files have been a cornerstone of PostScript printing environments since their inception by Adobe. With the widespread adoption of CUPS, tools like <b>ppdhtml</b> were developed to facilitate easier management and understanding of printer capabilities in web-centric environments, leveraging existing PPD file definitions. Its development is tied to the evolution of CUPS and the need for user-friendly access to printer configuration data.


title: PARAMETERS
content:
<b><i>-o output-file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path and name for the merged output PPD file. If not provided, the merged PPD is written to standard output.<br><br><b><i>PPD-file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input PPD files to be merged. These files describe the capabilities of a PostScript printer.<br><br>


title: DESCRIPTION
content:
<i><b>ppdmerge</b></i> is a CUPS (Common Unix Printing System) utility designed to combine multiple PPD (PostScript Printer Description) files into a single output PPD file.<br><br>PPD files describe the capabilities and options of a PostScript printer. Merging can be useful for adding custom options to an existing driver, combining features from different PPDs (e.g., adding a duplex unit option from one PPD to a base driver PPD), or updating printer capabilities. When conflicts arise (e.g., the same option defined differently in multiple PPDs), <i><b>ppdmerge</b></i> typically prioritizes the options from later specified input files, though careful review of the merged output is always recommended.<br><br>This tool simplifies the customization and maintenance of printer configurations within the CUPS environment.


title: CAVEATS
content:
<i><b>ppdmerge</b></i> handles conflicts by prioritizing options from later PPD files specified on the command line. This behavior requires users to carefully order their input files to achieve the desired result.<br><br>Complex PPD structures or highly customized options might not merge perfectly, necessitating manual inspection and editing of the resulting PPD file.<br><br>It's crucial to validate the merged PPD file (e.g., using <i><b>ppdhtml</b></i> or testing with <i><b>lpadmin</b></i>) before deploying it in a production CUPS environment.


title: HISTORY
content:
<i><b>ppdmerge</b></i> is an integral part of the CUPS (Common Unix Printing System) suite. CUPS was originally developed by Easy Software Products (ESP) in the late 1990s and became the de facto standard printing system for Unix-like operating systems. Apple Inc. acquired ESP in 2007, continuing its development. <i><b>ppdmerge</b></i> has been a utility within CUPS to manage and customize printer driver capabilities, supporting its evolution from a simple print spooler to a comprehensive printing solution.


title: SYNOPSIS
content:
<I>Not applicable</I> - The command "ppdpo" is not a standard Linux utility and its syntax cannot be universally defined. If it exists, its synopsis would be specific to its proprietary or custom implementation.


title: DESCRIPTION
content:
The command <I>"ppdpo"</I> does <I>not</I> appear to be a standard or commonly recognized utility in most mainstream Linux distributions (e.g., Debian, Ubuntu, Red Hat, Fedora, Arch Linux). It is highly probable that <I>"ppdpo"</I> is a <I>typo</I> for another command, part of a <I>highly specialized</I> or <I>proprietary</I> software package, or a <I>custom script</I> specific to a particular environment.<br><br>Without specific context regarding its origin or the software package it belongs to, it is impossible to provide accurate information about its functionality, options, or typical usage. Users encountering this command should <I>verify its spelling</I> or consult documentation specific to the software system where it was encountered.


title: CAVEATS
content:
This command is <I>not</I> included in standard GNU Core Utilities or common Linux system administration toolsets. Attempting to execute "ppdpo" on a typical Linux system will most likely result in a "<I>command not found</I>" error. Its functionality, if it exists, would be entirely dependent on its specific distribution and installation.


title: VERIFICATION AND CONTEXT
content:
If you encountered 'ppdpo', please <I>double-check the spelling</I> of the command. If it was mentioned in documentation, ensure you have the <I>correct software package installed</I> that provides this utility, as it is not a standard system command.


title: POSSIBLE TYPOGRAPHICAL INTENTIONS
content:
Consider if you might have intended to type a common package manager command (e.g., <I>dpkg</I>, <I>apt</I>, <I>yum</I>, <I>rpm</I>) or a command related to printer configurations, such as those dealing with <I>PPD</I> (PostScript Printer Description) files.


title: HISTORY
content:
There is <I>no known</I> public development or usage history for a standard, widely adopted Linux command named "ppdpo". Its existence would be limited to specific, non-standard software distributions, custom scripts, or private projects.


title: PARAMETERS
content:
<b><I>factor</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A non-negative floating-point number representing the brightness adjustment. Values greater than 1 brighten, values between 0 and 1 dim.<br><br><b>[<I>ppmfile</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input Portable Pixmap (PPM) image file. If omitted, <I>ppmbrighten</I> reads the PPM image from standard input.<br><br>


title: DESCRIPTION
content:
<I>ppmbrighten</I> is a Netpbm tool that adjusts the brightness of a Portable Pixmap (PPM) image.<br>It works by multiplying each color component (red, green, blue) of every pixel by a specified <I>factor</I>.<br>If the <I>factor</I> is greater than 1, the image is brightened.<br>If the <I>factor</I> is less than 1 (but greater than or equal to 0), the image is dimmed.<br>A <I>factor</I> of 1 leaves the image unchanged.<br>The output image's maximum color value (<I>maxval</I>) remains the same as the input's, and pixel values are clamped to this <I>maxval</I> if they exceed it after multiplication.


title: CAVEATS
content:
<I>ppmbrighten</I> works exclusively with the PPM image format. For other Netpbm formats (PGM, PBM), you might need to convert first.<br>Simple multiplicative scaling can lead to loss of detail in very bright or very dark areas due to value clamping, as pixel values are clipped at the image's maximum color value.<br>It does not perform gamma correction, which is perceptually different from simple linear brightness adjustment.


title: INPUT/OUTPUT
content:
<I>ppmbrighten</I> reads its input PPM image from the file specified on the command line or from standard input if no file is given. The processed PPM image is always written to standard output.


title: MAXVAL HANDLING
content:
The maximum color value (<I>maxval</I>) of the output image is preserved from the input image. Pixel values are scaled by the <I>factor</I> and then clamped to this <I>maxval</I>, meaning values exceeding <I>maxval</I> after scaling will be set to <I>maxval</I>.


title: HISTORY
content:
Part of the comprehensive <I>Netpbm</I> suite of graphics tools, <I>ppmbrighten</I> embodies the Unix philosophy of small, specialized utilities that do one thing well. Its core functionality for simple brightness adjustment has been a staple of the suite for a long time, providing a fundamental image manipulation capability.


title: SYNOPSIS
content:
<b>ppmchange</b> [<i>-verbose</i>] [<i>-map mapfile</i>] [<i>oldcolor1 newcolor1</i> [<i>oldcolor2 newcolor2</i> ...]] [<i>netpbmfile</i>]


title: PARAMETERS
content:
<b><i>-verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a progress report to standard error as the image is processed, showing the percentage completed.<br><br><b><i>-map mapfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reads the color transformation pairs from the specified <i>mapfile</i> instead of the command line. Each non-comment line in the file should contain an <i>oldcolor</i> followed by a <i>newcolor</i>, separated by whitespace.<br><br><b><i>oldcolor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The color to be found and replaced in the input image. This can be a standard X11 color name (e.g., 'red', 'blue') or a hexadecimal RGB value (e.g., '#FF0000', '#0000FF').<br><br><b><i>newcolor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The color to which matching <i>oldcolor</i> pixels will be changed. Specified in the same format as <i>oldcolor</i>.<br><br><b><i>netpbmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PPM image file. If omitted, <i>ppmchange</i> reads image data from standard input.<br><br>


title: DESCRIPTION
content:
<i>ppmchange</i> is a utility from the Netpbm suite designed for modifying the colors of pixels within a Portable Pixmap (PPM) image. It reads an input PPM image, either from a specified file or standard input, and applies a series of color replacement rules to its pixels. For each pixel in the image, <i>ppmchange</i> compares its color against a list of "old" colors. If a match is found, the pixel's color is changed to the corresponding "new" color.<br><br>This command is particularly useful for tasks such as remapping color palettes, selectively changing specific colors in an image, or performing basic color correction. The color changes can be specified directly on the command line as pairs of <i>oldcolor</i> and <i>newcolor</i>, or loaded from a separate map file for more complex or numerous transformations. The output is a new PPM image, typically written to standard output, allowing for easy piping with other Netpbm tools. It processes changes sequentially, meaning the order of color replacement pairs can affect the final image if colors overlap.


title: CAVEATS
content:
<i>ppmchange</i> primarily works with the PPM (Portable Pixmap) image format. While Netpbm can convert other formats to PPM, <i>ppmchange</i> itself expects PPM input.<br><br>Color matching is exact; there is no tolerance for near matches. Colors must be specified precisely according to their RGB values or defined color names.<br><br>The order of <i>oldcolor newcolor</i> pairs is significant. Changes are applied sequentially from left to right on the command line (or top to bottom in a map file). If the <i>newcolor</i> of one transformation matches the <i>oldcolor</i> of a subsequent transformation, the pixel will undergo multiple changes (e.g., changing 'red' to 'blue' and then 'blue' to 'green' will result in an original 'red' pixel becoming 'green').


title: COLOR SPECIFICATION
content:
Colors can be specified either by standard X11 color names (e.g., 'red', 'green', 'white', 'black', 'lightgray', etc.), which <i>ppmchange</i> looks up in a color name database, or by hexadecimal RGB values. Hexadecimal values are written as '#RRGGBB', where RR, GG, and BB are two-digit hexadecimal numbers representing the red, green, and blue components respectively (e.g., '#FF0000' for pure red, '#00FF00' for pure green, '#0000FF' for pure blue).


title: PROCESSING ORDER OF CHANGES
content:
When multiple color replacement pairs are provided, <i>ppmchange</i> applies them in the exact order they are listed. This means that a pixel's color might be changed multiple times if it matches subsequent <i>oldcolor</i> values after an initial transformation. For instance, if you have rules 'red blue' and then 'blue green', an original red pixel would first become blue, and then immediately become green. This cascading effect must be considered when defining complex color transformations.


title: HISTORY
content:
<i>ppmchange</i> is an integral part of the Netpbm package, a widely used suite of graphics utilities. It originated as part of the Pbmplus package, created by Jef Poskanzer, which formed the foundation of Netpbm. Since its inception, it has been maintained and expanded upon within the Netpbm project, serving as a fundamental tool for specific color manipulation tasks in PPM images. Its design reflects the Unix philosophy of small, specialized tools that can be chained together for complex image processing workflows.


title: SYNOPSIS
content:
<b>ppmcie</b> [<i>-cielab</i> | <i>-rgb</i> | <i>-ciexyz</i> | <i>-xyy</i>] [<i>-srgb</i> | <i>-linear</i>] [<i>-gamma</i> <i>value</i>] [<i>-whitepoint</i> <i>x y</i>] [<i>-maxval</i> <i>maxval</i>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b><i>-cielab</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies that the input image is in the CIE L*a*b* color space. This is often the default behavior.<br><br><b><i>-rgb</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indicates that the input image is in the RGB color space, and <b>ppmcie</b> should convert it to CIELAB.<br><br><b><i>-ciexyz</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Processes the image using the CIE XYZ color space for conversion.<br><br><b><i>-xyy</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Works with the CIE x,y,Y color space, which represents color using chromaticity coordinates and luminance.<br><br><b><i>-srgb</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the sRGB standard for the output RGB color space, including its specific primaries and transfer function. This is the default output RGB space if not specified.<br><br><b><i>-linear</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies that the output RGB color space should be linear (without gamma correction applied).<br><br><b><i>-gamma</i> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a custom gamma correction <i>value</i> to the RGB conversion process. Overrides <i>-srgb</i> or <i>-linear</i> gamma if used.<br><br><b><i>-whitepoint</i> <i>x y</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the chromaticity coordinates (<i>x</i>, <i>y</i>) of the reference white point for color space conversions (e.g., 0.3127 0.3290 for D65 illuminant). Defaults to D65.<br><br><b><i>-maxval</i> <i>maxval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum pixel value for the output image. Must be between 1 and 65535. The default is 255 if the input maxval is <= 255, or 65535 otherwise.<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input Portable Pixmap (PPM) image file. If omitted, <b>ppmcie</b> reads from standard input.<br><br>


title: DESCRIPTION
content:
<b>ppmcie</b> is a powerful utility within the Netpbm image manipulation suite, designed for converting pixel data between various color spaces. Its primary function is to transform images represented in the CIE L*a*b* (CIELAB) color space, which is designed to approximate human vision, into the RGB color space, which is commonly used for display devices. It can also perform conversions involving CIE XYZ and CIE x,y,Y color spaces.<br><br>This tool is essential for professional image processing and color management workflows where accurate color representation across different devices or standards is critical. Users can specify input and output color space models, gamma correction values, and white point illuminants (like D65), allowing for precise control over the conversion process. <b>ppmcie</b> reads a PPM (Portable Pixmap) image as input and outputs a PPM image, making it compatible with other Netpbm tools and a wide range of image processing pipelines.


title: CAVEATS
content:
Accurate color space conversion requires a good understanding of color models, gamma correction, and white points. Incorrect parameters can lead to color shifts or inaccurate results. <b>ppmcie</b> strictly operates on PPM files; other image formats must be converted to PPM first (e.g., using <b>anytoppm</b>).


title: DEFAULT BEHAVIOR
content:
By default, <b>ppmcie</b> assumes the input is a CIELAB image and converts it to sRGB. The default white point used for conversions is D65 (standard illuminant with a correlated color temperature of 6500K). When no input file is specified, it reads from standard input and writes to standard output, making it suitable for use in command-line pipelines.


title: HISTORY
content:
<b>ppmcie</b> is a part of the Netpbm project, which traces its origins back to the PBMPlus package created by Jef Poskanzer in the late 1980s. Netpbm evolved into a comprehensive suite of tools for manipulating graphic images in the Portable Anymap (PAM) format family (PBM, PGM, PPM). <b>ppmcie</b> was developed to address the growing need for precise color management in digital imaging, allowing for accurate conversions between device-dependent (RGB) and device-independent (CIELAB) color spaces, reflecting the maturation of digital color standards.


title: SYNOPSIS
content:
<b>ppmcolormask</b> [<I>-exact</I>] [<I>-color <I>color</I></I> | <I>-colorname <I>colorname</I></I>] [<I>ppmfile</I>]


title: PARAMETERS
content:
<b><I>-exact</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Masks only pixels that *exactly* match the specified color, with no tolerance for minor variations in color components. By default, there's a tolerance of one Netpbm quantum per color component.<br><br><b><I>-color <I>color</I></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target color to mask. <i>color</i> can be a color name (e.g., "red", "blue"), a hexadecimal RGB value (e.g., "#FF0000"), or a triplet of numbers representing R, G, B values (e.g., "255,0,0"). If this option is not used, the default color is red.<br><br><b><I>-colorname <I>colorname</I></I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An alias for <I>-color</I>. This option is provided for backward compatibility.<br><br><b><I>ppmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PPM image file. If not provided, <b>ppmcolormask</b> reads from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<b>ppmcolormask</b> is a command-line utility from the Netpbm image manipulation toolkit. It reads a Portable Pixmap (PPM) image as input and generates a Portable Graymap (PGM) image as output. The output PGM image serves as a mask: pixels in the original PPM image that match a specified color are rendered as pure white (maximum intensity) in the PGM mask, while all other pixels are rendered as pure black (zero intensity). This utility is particularly useful for tasks like chroma keying or creating alpha masks for image compositing, where you need to isolate specific color regions.<br><br>By default, <b>ppmcolormask</b> looks for the color red, but users can specify any desired color using various formats, including color names, hexadecimal RGB values, or numeric triplets. Unless the <I>-exact</I> option is used, the command allows for a small tolerance in color matching, considering pixels within one Netpbm quantum of each color component as a match.


title: CAVEATS
content:
The default color matching has a tolerance of one Netpbm quantum per component. For precise matching, always use the <I>-exact</I> option. Color names are system-dependent and rely on the `rgb.txt` file; using hexadecimal or numeric triplets is more portable for defining colors.


title: INPUT/OUTPUT
content:
<b>ppmcolormask</b> expects a PPM image as input and produces a PGM image as output. Both can be read from and written to standard input/output respectively, enabling easy piping with other Netpbm tools for chained operations.


title: COLOR SPECIFICATION
content:
When specifying colors with <I>-color</I> or <I>-colorname</I>, Netpbm uses the `rgb.txt` database for color names. If a name is not found, or for more precise control, hexadecimal RGB values (`#RRGGBB`) or comma-separated decimal triplets (`R,G,B`) can be used to define the color.


title: HISTORY
content:
<b>ppmcolormask</b> is an integral part of the Netpbm project, a widely used suite of graphics file format converters and image processing tools. Netpbm originated from Jef Poskanzer's PBMplus package in the late 1980s. This utility, like other Netpbm tools, adheres to the philosophy of simple, single-purpose commands that can be piped together to achieve complex image manipulations. Its ongoing development as part of the larger Netpbm codebase ensures continued compatibility and utility for various image processing tasks on Unix-like systems.


title: SYNOPSIS
content:
<B>ppmdim</B> [<I>-x=float</I>] [<I>-y=float</I>] [<I>ppmfile</I>]<br><B>ppmdim</B> [<I>scale_factor</I>] [<I>ppmfile</I>]


title: PARAMETERS
content:
<b><I>scale_factor</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A floating-point number representing a uniform scaling factor applied to both the horizontal and vertical dimensions. If this is the only numeric argument, it scales uniformly.<br><br><b><I>-x=float</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the horizontal scaling factor as a floating-point number.<br><br><b><I>-y=float</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the vertical scaling factor as a floating-point number.<br><br><b><I>ppmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the PPM image file to be processed. If omitted, ppmdim reads from standard input.<br><br>


title: DESCRIPTION
content:
ppmdim is a specialized utility within the Netpbm image processing suite, designed to <I>dim</I> or <I>scale</I> Portable Pixmap (PPM) images. It reads a PPM image from standard input or a specified file and outputs a scaled version to standard output. While the name <I>"dim"</I> might suggest only reducing brightness, ppmdim primarily functions as a scaling tool. It achieves the <I>"dimming"</I> effect by averaging pixels, effectively reducing the resolution or detail, thereby making the image appear <I>"dimmer"</I>. This can be useful for quickly generating thumbnails, previews, or for reducing image data size for specific applications where precise high-quality scaling isn't the primary concern. It supports independent horizontal and vertical scaling factors, allowing for non-uniform resizing.


title: CAVEATS
content:
ppmdim is specific to the <B>PPM</B> (Portable Pixmap) format. It will not work directly with other image formats like JPEG, PNG, or GIF unless they are first converted to PPM using other Netpbm tools (e.g., <I>jpegtoppm</I>, <I>pngtoppm</I>).<br>The "dimming" effect is a result of resolution reduction and pixel averaging, not a direct adjustment of brightness or color values.<br>Scaling up significantly with ppmdim may result in a pixelated or blocky appearance due to its simple averaging algorithm, unlike more sophisticated image scaling algorithms that interpolate pixels for smoother results. For higher quality scaling, consider <I>pamscale</I>.


title: USAGE WITH PIPES
content:
ppmdim is frequently used in shell pipelines due to Netpbm's design philosophy. For example, to convert a JPEG image to a scaled-down PPM, you might use: <br><I>jpegtoppm image.jpg | ppmdim 0.5 > scaled_image.ppm</I><br>This allows for complex image processing workflows by chaining multiple Netpbm utilities.


title: HISTORY
content:
ppmdim is a legacy tool from the Netpbm project, which originated from Jef Poskanzer's PBMPlus package in the late 1980s. It was one of the early specialized utilities for manipulating Portable Pixmap (PPM) images. While ppmdim specifically "dims" (scales down and averages), more general-purpose scaling tools like <I>pnmscale</I> and later <I>pamscale</I> (which handles all Netpbm formats: PBM, PGM, PPM, PAM) have largely superseded it for common scaling tasks. Its continued presence in the Netpbm suite reflects its historical significance and specific, albeit simple, scaling methodology.


title: SYNOPSIS
content:
<b>ppmdist</b> [<i>-maxval N</i>] [<i>-weight N</i>] [<i>-power N</i>] [<i>-origin X Y</i>] [<i>ppmfile ...</i>]


title: PARAMETERS
content:
<b><i>-maxval N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum pixel value for the output image. By default, this is determined from the maximum maxval of the input images. Using a higher value like 65535 (2^16-1) allows for 16-bit color depth, enabling a wider range of colors or intensities.<br><br><b><i>-weight N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a base weight (a floating-point number) to be applied to each input image's pixels before the distance calculation. The default value is 1.0. This value acts as a fundamental multiplier for the distance-derived weight.<br><br><b><i>-power N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the exponent (a floating-point number) for the distance calculation. A higher power results in a steeper decrease in pixel weight as distance from the origin increases, causing a more rapid falloff effect. The default value is 2.0, mimicking an inverse square law.<br><br><b><i>-origin X Y</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the coordinates (column <i>X</i>, row <i>Y</i>) for the origin point from which all distances are calculated. Coordinates are 0-indexed. The default origin is the geometric center of the input images, calculated based on their dimensions.<br><br><b><i>ppmfile ...</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more paths to the input Portable Pixmap (PPM) image files. If no filenames are provided, <i>ppmdist</i> reads image data from standard input. All input files must have identical dimensions and maxval, otherwise an error will occur.<br><br>


title: DESCRIPTION
content:
<i>ppmdist</i> is a Netpbm utility that processes multiple Portable Pixmap (PPM) images and outputs a single composite PPM image.<br><br>For each pixel location in the output, it calculates a weighted average of the corresponding pixels from all input images. The weighting factor for each input image's pixel is determined by its Euclidean distance from a specified "origin" point (defaulting to the image's center). This distance is then modified by a configurable power and a base weight. This technique effectively emphasizes or clarifies areas closer to the origin while fading or blurring areas further away.<br><br>It's particularly useful for creating visual effects such as simulating depth-of-field, spotlight effects, or for compositing multiple images where a central subject or region needs to be highlighted or made dominant. All input images must be of identical dimensions (width and height) and possess the same maximum pixel value (maxval).


title: CAVEATS
content:
All input PPM images must have the exact same dimensions (width and height) and the same maximum pixel value (maxval) to be processed successfully. Mismatched images will result in an error and program termination. The output is always a single PPM image.


title: WORKING PRINCIPLE
content:
For each pixel position (x, y) in the output, <i>ppmdist</i> calculates the Euclidean distance <i>d</i> from (x, y) to the specified origin (<i>origin_x</i>, <i>origin_y</i>). The weight for an input pixel at (x, y) is then derived using the formula: <i>weight_factor</i> = <i>base_weight</i> / (<i>d</i>^<i>power</i> + 1). The ' + 1' in the denominator is crucial as it prevents division by zero if the origin is exactly on a pixel, and ensures a finite, non-zero weight. The final color of the output pixel is the weighted average of all input pixels at that corresponding position, considering their respective weights.


title: COMMON USE CASES
content:
This command is widely used in artistic image processing and scientific visualization. Common applications include creating soft focus or depth-of-field effects in rendered images, simulating a light source or 'hotspot' by making areas near the origin brighter and more dominant, or combining multiple frames of an animation where the primary action is centered to produce a composite still image that highlights movement.


title: HISTORY
content:
<i>ppmdist</i> is an integral part of the Netpbm package, a comprehensive suite of graphics utilities. Netpbm evolved from Jef Poskanzer's original PBMplus toolkit, which first appeared in the early 1990s. The command exemplifies the Unix philosophy of small, specialized tools that perform a single task well, providing a fundamental capability for image manipulation through weighted averaging based on spatial distribution, serving as a reliable utility for image compositing for decades.


title: SYNOPSIS
content:
<I>ppmdither</I> [<B>-floyd</B> | <B>-fs</B> | <B>-atkinson</B> | <B>-diffusion</B> | <B>-median</B> | <B>-threshold</B> <I>num</I> | <B>-nofs</B>] [<B>-red</B> | <B>-green</B> | <B>-blue</B> | <B>-red</B> <I>mapfile</I> | <B>-green</B> <I>mapfile</I> | <B>-blue</B> <I>mapfile</I>] [<B>-gamma</B> <I>num</I>] [<B>-ncolors</B> <I>num</I>] [<B>-map</B> <I>mapfile</I>] [<B>-output</B> <I>filename</I>] [<B>--</B>] [<I>inputfile</I>]


title: PARAMETERS
content:
<b><I>inputfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <I>PPM</I> image file to be dithered. If not specified, <I>ppmdither</I> reads from standard input.<br><br><b><B>-red</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dither the red component of the image. Can optionally be followed by a <I>mapfile</I> to define the colors for red component dithering.<br><br><b><B>-green</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dither the green component of the image. Can optionally be followed by a <I>mapfile</I> to define the colors for green component dithering.<br><br><b><B>-blue</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Dither the blue component of the image. Can optionally be followed by a <I>mapfile</I> to define the colors for blue component dithering.<br><br><b><B>-floyd</B> / <B>-fs</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply <I>Floyd-Steinberg</I> error diffusion dithering. <B>-fs</B> is a synonym for <B>-floyd</B>.<br><br><b><B>-atkinson</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use <I>Atkinson</I> dithering, which preserves more detail than <I>Floyd-Steinberg</I> but with less contrast.<br><br><b><B>-diffusion</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a generic error diffusion dithering algorithm.<br><br><b><B>-median</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply <I>median-cut</I> dithering, which is good for quantizing to a few colors.<br><br><b><B>-threshold</B> <I>num</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a simple thresholding dithering algorithm. <I>num</I> is the threshold value (0-255). This is the default if no other algorithm is specified.<br><br><b><B>-nofs</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly disable error diffusion, resulting in simple thresholding. This is equivalent to using <B>-threshold</B> without a specific <I>num</I>.<br><br><b><B>-gamma</B> <I>num</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply gamma correction to the image before dithering. <I>num</I> specifies the gamma value.<br><br><b><B>-ncolors</B> <I>num</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quantize the image to <I>num</I> colors before dithering. This limits the output color palette.<br><br><b><B>-map</B> <I>mapfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the colors present in <I>mapfile</I> (another <I>PPM</I> image) as the target color map for dithering.<br><br><b><B>-output</B> <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Write the dithered output image to <I>filename</I> instead of standard output.<br><br><b><B>--</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the end of command-line options, useful if <I>inputfile</I> starts with a hyphen.<br><br>


title: DESCRIPTION
content:
ppmdither is a command-line utility from the <I>Netpbm</I> suite designed to dither <I>PPM</I> (Portable Pixmap) images. Dithering is a technique used to approximate a continuous-tone image with a limited number of colors, often just a few, to simulate greater color depth. This is particularly useful for displays or printers that have a restricted color palette, or for creating artistic effects.<br><br>The command offers a variety of dithering algorithms, allowing users to choose the method best suited for their needs. By default, it employs a simple thresholding algorithm. However, more sophisticated options like <I>Floyd-Steinberg</I>, <I>Atkinson</I>, and generic error diffusion are available, which distribute quantization errors to adjacent pixels to improve image quality. It also supports quantizing to a specified number of colors or using a custom color map from another image. Input images are read from standard input by default, and the dithered output is written to standard output, making it suitable for piping with other Netpbm tools.


title: CAVEATS
content:
Combining <B>-red</B>/<B>-green</B>/<B>-blue</B> and <B>-map</B> options, or using <B>-gamma</B> with color maps, can lead to non-obvious results, requiring experimentation. Additionally, the <B>-threshold</B> option may not function correctly when used in conjunction with certain color map-related options.


title: HISTORY
content:
ppmdither is part of the <I>Netpbm</I> project, a comprehensive suite of graphics utilities and libraries for manipulating image files, primarily in the <I>PNM</I> (Portable Anymap) formats (<I>PBM</I>, <I>PGM</I>, <I>PPM</I>). It has been a standard tool within this suite for many years, providing essential dithering capabilities for various image processing workflows.


title: SYNOPSIS
content:
<b>ppmdraw</b> [<i>-maxval</i> <I>maxval</I>] [<i>-width</i> <I>width</I>] [<i>-height</i> <I>height</I>] [<i>-color</i> <I>color</I>] [<i>-background</i> <I>color</I>] [<i>-textsize</i> <I>number</I>] [<i>-font</i> <I>font</I>] <I>drawing-commands</I> [<i>ppmfile</i>]


title: PARAMETERS
content:
<b><i>-maxval</i> <I>maxval</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum color value for the output PPM image.<br><br><b><i>-width</i> <I>width</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the width of the output image if no input PPM is provided; otherwise, it is ignored.<br><br><b><i>-height</i> <I>height</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the height of the output image if no input PPM is provided; otherwise, it is ignored.<br><br><b><i>-color</i> <I>color</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the initial or current drawing color. Colors can be specified by name, hexadecimal triplet, or RGB triplet.<br><br><b><i>-background</i> <I>color</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the background color of the image if no input PPM is given and a new image is created.<br><br><b><i>-textsize</i> <I>number</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the size of the font for the <i>text</i> drawing command.<br><br><b><i>-font</i> <I>font</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the font to be used for the <i>text</i> drawing command.<br><br>


title: DESCRIPTION
content:
The <i>ppmdraw</i> command, a part of the powerful Netpbm suite, is a versatile utility designed for drawing various geometric shapes directly onto Portable Pixmap (PPM) images. It can take an existing PPM image as input and modify it, or generate a new black PPM image if no input file is provided. Users define drawing operations through a sequence of commands, allowing for the creation of lines, circles, rectangles, ellipses, arcs, and filled shapes, alongside plotting individual pixels and rendering text. The output is always a modified PPM image. <i>ppmdraw</i> is exceptionally useful for programmatic image generation, adding overlays, or performing simple graphical modifications within scripts.


title: CAVEATS
content:
Drawing commands are executed sequentially in the order they appear on the command line.<br>The coordinate system typically starts at (0,0) in the top-left corner.<br>Color specification can be flexible (names, hex, RGB) but requires correct syntax.


title: DRAWING COMMANDS SYNTAX
content:
Beyond the command-line options, <i>ppmdraw</i> functions by interpreting a series of specific drawing commands provided as arguments. These commands define the shapes and operations to be performed on the image. They are parsed from left to right, and each command may have its own set of required arguments:<br><br><b>plot</b> <I>x</I> <I>y</I>: Draws a single pixel at the specified coordinates.<br><b>line</b> <I>x1</I> <I>y1</I> <I>x2</I> <I>y2</I>: Draws a line from (x1,y1) to (x2,y2).<br><b>rectangle</b> <I>x1</I> <I>y1</I> <I>x2</I> <I>y2</I>: Draws a rectangle defined by two corner coordinates.<br><b>circle</b> <I>x</I> <I>y</I> <I>radius</I>: Draws a circle centered at (x,y) with the given radius.<br><b>ellipse</b> <I>x</I> <I>y</I> <I>xradius</I> <I>yradius</I>: Draws an ellipse centered at (x,y) with specified horizontal and vertical radii.<br><b>arc</b> <I>x</I> <I>y</I> <I>xradius</I> <I>yradius</I> <I>angle1</I> <I>angle2</I>: Draws an elliptical arc.<br><b>fill</b> <I>x</I> <I>y</I>: Fills an enclosed area with the current drawing color, starting from (x,y) (flood fill).<br><b>color</b> <I>color_spec</I>: Changes the current drawing color for subsequent commands.<br><b>text</b> <I>x</I> <I>y</I> <I>string</I>: Draws the specified text string at (x,y) using the current font and size.<br><br>Many shape commands also have 'f' prefixes (e.g., <b>frectangle</b>) to draw filled versions of the shape.


title: HISTORY
content:
<i>ppmdraw</i> is an integral part of the Netpbm project, a comprehensive suite of utilities for converting and manipulating graphic image files. Netpbm originated from <i>pbmplus</i>, developed by Jef Poskanzer, and has been a cornerstone of command-line image processing on Unix-like systems since the early 1990s. Its development reflects the long-standing need for scriptable and robust image manipulation tools.


title: SYNOPSIS
content:
<code>ppmfade [-frames <I>N</I>] [-linear] [-maxmaxval <I>M</I>] <I>start_spec</I> <I>end_spec</I></code>


title: PARAMETERS
content:
<b>-frames <I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of output images (frames) to generate during the fade. The default is 25 frames.<br><br><b>-linear</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces a linear fade progression. By default, <code>ppmfade</code> uses a non-linear, perceptually smoother fade.<br><br><b>-maxmaxval <I>M</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum color value (maxval) for the output images. Default matches the input image's maxval.<br><br><b><I>start_spec</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The starting point for the fade. Can be a PPM image file path (or '-' for standard input) or a color specification (e.g., 'red', '#FF0000').<br><br><b><I>end_spec</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The ending point for the fade. Can be a PPM image file path or a color specification.<br><br>


title: DESCRIPTION
content:
<code>ppmfade</code> is a Netpbm utility that generates a sequence of Portable Pixmap (PPM) images, simulating a fade effect. It can fade from one PPM image to another, from an image to a specified color, or from a color to an image. The generated images are written to standard output, making <code>ppmfade</code> ideal for piping into other programs that create animations (e.g., <code>ppmtompeg</code> or display sequences of images). Users can control the number of frames in the fade and whether the fade progresses linearly or perceptually.


title: CAVEATS
content:
Output is always written to standard output; it's designed for piping, not direct file creation.<br>Input images must be in PPM format. Other Netpbm tools like <code>anytopnm</code> can convert various formats to PPM.<br>The command itself does not create video files; it generates image sequences that must be further processed.


title: INPUT AND OUTPUT
content:
Ppmfade processes its inputs (either two image files, or one image and one color specification) and writes the resulting sequence of PPM images to standard output. This streaming design is fundamental to the Netpbm philosophy, enabling powerful command-line pipelines for complex image processing tasks.


title: COLOR SPECIFICATION
content:
Colors can be specified by common color names (e.g., 'blue', 'green') or as a hexadecimal RGB triplet (e.g., '#0000FF' for blue). Netpbm uses an internal color database to resolve named colors.


title: HISTORY
content:
Ppmfade is an integral part of the Netpbm project, a comprehensive suite of graphics manipulation tools. Netpbm originated from PBMplus, developed by Jef Poskanzer, and has evolved into a widely used open-source collection for processing various image formats, particularly through command-line piping. Ppmfade's purpose has consistently been to provide a flexible and efficient way to generate intermediate frames for animation or visual transitions.


title: SYNOPSIS
content:
`ppmflash` [<i>ppmfile</i>]<br><br><i><b>Description:</b></i><br>The `ppmflash` command reads a Portable Pixmap (PPM) image, applies a flash photography effect, and writes the resulting PPM image. If <I>ppmfile</I> is not specified, `ppmflash` reads from standard input. The output is always written to standard output.


title: DESCRIPTION
content:
`ppmflash` is a <I>Netpbm</I> command-line utility designed to simulate the effect of a photographic flash on a Portable Pixmap (PPM) image. It achieves this by significantly brightening the input image, particularly the darker regions, and compressing the color range. This process mimics the high contrast, flattened appearance, and often slightly overexposed look characteristic of flash photography. The command processes one PPM image at a time, reading from standard input by default and writing the modified image to standard output. It's a simple yet effective tool for creating a stylized, high-impact visual effect, often used in conjunction with other Netpbm filters for more complex image manipulations.


title: CAVEATS
content:
<I>Fixed Effect:</I> `ppmflash` does not offer any command-line options or parameters to adjust the intensity or characteristics of the flash effect. The transformation applied is predetermined.<br><br><I>PPM Format Only:</I> This command exclusively operates on Portable Pixmap (PPM) images. Attempting to use it with other image formats will result in an error, though Netpbm tools like `anytopnm` can convert other formats to PPM beforehand.


title: NETPBM PHILOSOPHY
content:
Like many Netpbm utilities, `ppmflash` adheres to the Unix philosophy of doing one thing well. It's designed to be a simple filter that can be easily integrated into shell scripts and pipelines, allowing users to combine its specific effect with other Netpbm commands for more intricate image transformations.


title: HISTORY
content:
`ppmflash` is an integral part of the <B>Netpbm</B> project, a suite of graphics utilities for converting and manipulating images. The command was authored by <B>Greg Roelofs</B> and became part of the Netpbm distribution, which originated from the Pbmplus package developed by Jef Poskanzer in the late 1980s. `ppmflash` exemplifies Netpbm's philosophy of providing simple, specialized tools that can be chained together via pipelines to perform complex image processing tasks. Its functionality has remained consistent, focusing solely on applying a fixed flash effect to PPM images.


title: SYNOPSIS
content:
<b>ppmforge</b> [<b>-x</b> <i>width</i>] [<b>-y</b> <i>height</i>] [<b>-s</b> <i>seed</i>] [<b>-l</b> <i>lambda</i>] [<b>-a</b> <i>attenuation</i>] [<b>-p</b> <i>palette</i>] [<b>-o</b> <i>outfile</i>] [<b>-g</b>] [<b>-m</b>] [<b>-q</b>] [<b>-e</b>] [<b>-v</b>] [<b>-d</b>] [<b>-t</b>]


title: PARAMETERS
content:
<b><b>-x</b> <i>width</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the width of the output image in pixels. Defaults to 256.<br><br><b><b>-y</b> <i>height</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the height of the output image in pixels. Defaults to 256.<br><br><b><b>-s</b> <i>seed</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the random number generator seed. Useful for recreating specific landscapes.<br><br><b><b>-l</b> <i>lambda</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the 'roughness' or 'spikiness' of the terrain. A floating-point value between 0.0 and 1.0. Higher values create rougher landscapes. Defaults to 0.5.<br><br><b><b>-a</b> <i>attenuation</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls how quickly the roughness decreases with resolution. A floating-point value between 0.0 and 1.0. Lower values make terrain features smaller at higher resolution. Defaults to 0.5.<br><br><b><b>-p</b> <i>palette</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects one of 8 predefined color palettes (0-7) for the output image. Defaults to 0. Try different values to see varied color schemes.<br><br><b><b>-o</b> <i>outfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the output file. If omitted, the image is written to standard output (stdout).<br><br><b><b>-g</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a grayscale image (PGM format) instead of a color (PPM) image.<br><br><b><b>-m</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies mirror boundary conditions to the fractal generation, which can affect the edges of the generated landscape.<br><br><b><b>-q</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quiet mode; suppresses progress messages to stderr.<br><br><b><b>-e</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the image dimensions to be even, which can sometimes improve rendering for certain algorithms.<br><br><b><b>-v</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Verbose mode; prints the effective parameters used for generation to stderr.<br><br><b><b>-d</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Debug mode; prints additional diagnostic information during execution.<br><br><b><b>-t</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Test mode; used for internal testing, not generally for end-users.<br><br>


title: DESCRIPTION
content:
<i>ppmforge</i> is a command-line utility from the Netpbm suite that creates pseudo-random fractal landscapes. It uses a midpoint displacement algorithm to generate a topographical map, which is then rendered as a Portable Pixmap (PPM) image. Users can control various aspects of the generated landscape, including its dimensions, the 'roughness' or spikiness of the terrain (via the <b>-l</b> parameter), and how quickly this roughness diminishes at higher resolutions (via the <b>-a</b> parameter). The command also allows selection from several predefined color palettes, or generation of a grayscale image. The output is a raw PPM file, which can be further processed or converted using other Netpbm tools or image manipulation software. It's often used for generating background textures, heightmaps, or simply exploring fractal geometry.


title: CAVEATS
content:
Generated images are in Netpbm's raw PPM or PGM format. You may need to use other Netpbm tools like <b>ppmtogif</b>, <b>ppmtowebp</b>, or <b>pnmtopng</b>, or external image editors (e.g., ImageMagick) to convert them to more common formats like PNG or JPEG. Generating very large images can consume significant memory and processing time. Experimentation with <b>-l</b> and <b>-a</b> parameters is often necessary to achieve desired visual effects.


title: FRACTAL GENERATION
content:
<i>ppmforge</i> employs a variant of the midpoint displacement algorithm. This iterative process starts with a simple square and recursively subdivides it, offsetting the center point by a random amount. This offset is scaled down at each iteration, creating a fractal pattern. The <b>lambda</b> and <b>attenuation</b> parameters directly influence this scaling and randomness, allowing fine-grained control over the generated terrain's characteristics.


title: OUTPUT FORMAT
content:
The primary output format is PPM (Portable Pixmap) or PGM (Portable Graymap) if the <b>-g</b> option is used. These are simple, uncompressed image formats often used as an intermediate step in image processing pipelines. PPM represents each pixel as a 3-byte RGB triplet, while PGM uses a single byte per pixel for grayscale. Netpbm's philosophy is to provide many small, specialized tools that can be chained together via pipes, making its formats ideal for inter-program communication.


title: HISTORY
content:
<i>ppmforge</i> is part of the Netpbm project, a long-standing open-source package of graphics utilities for converting, manipulating, and viewing images in the Portable Pixmap (PPM), Portable Graymap (PGM), and Portable Bitmap (PBM) formats. The tool's underlying algorithm, midpoint displacement, is a classic technique for generating fractal terrains, originating in the early days of computer graphics.


title: PARAMETERS
content:
<b><b>-background=</b><I>color</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the color of the background area not covered by the globe. Default is black.<br><br><b><b>-earth=</b><I>color</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the color of the land masses. Default is green.<br><br><b><b>-sea=</b><I>color</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the color of the oceans. Default is blue.<br><br><b><b>-border=</b><I>color</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the color of the border around land masses when a map image is used. Default is white.<br><br><b><b>-grid=</b><I>color</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the color of the latitude/longitude grid lines. Default is red.<br><br><b><b>-noearth</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses drawing of the land masses.<br><br><b><b>-nosea</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses drawing of the oceans.<br><br><b><b>-nogrid</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses drawing of the latitude/longitude grid.<br><br><b><b>-noborder</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses drawing of the border.<br><br><b><b>-width=</b><I>pixels</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width of the output image in pixels. Default is 300.<br><br><b><b>-height=</b><I>pixels</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the height of the output image in pixels. Default is 300.<br><br><b><b>-x=</b><I>degrees</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the longitude of the point at the center of the image on the globe. Default is 0.<br><br><b><b>-y=</b><I>degrees</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the latitude of the point at the center of the image on the globe. Default is 0.<br><br><b><b>-z=</b><I>degrees</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the rotation about the axis formed by the central point. Default is 0.<br><br><b><b>-gamma=</b><I>gamma_value</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies gamma correction to the output image.<br><br><b><b>-truecolor</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output image to be a 24-bit truecolor PPM. By default, it's 8-bit per color component.<br><br><b><b>-azimuthal</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an azimuthal projection (the default globe view).<br><br><b><b>-azimuthaldistance=</b><I>distance</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the distance of the projection plane from the globe's center for azimuthal projections. Default is 1.0 (orthographic).<br><br><b><b>-rectangular</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a rectangular (equirectangular) projection.<br><br><b><b>-mercator</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a Mercator projection.<br><br><b><b>-mercatorwidth=</b><I>width</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width for Mercator projections; height is computed to maintain aspect ratio. Default is 300.<br><br><b><b>-rectangularwidth=</b><I>width</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width for rectangular projections; height is computed to maintain aspect ratio. Default is 300.<br><br><b><b>-gridlat=</b><I>degrees</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the spacing of latitude grid lines in degrees. Default is 15.<br><br><b><b>-gridlon=</b><I>degrees</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the spacing of longitude grid lines in degrees. Default is 15.<br><br><b><b>-resolution=</b><I>number</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the resolution of the globe, in terms of points per pixel. Higher values yield smoother curves but increase render time. Default is 1.0.<br><br><b><b>-antialias=</b><I>number</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the number of antialiasing samples per pixel. Higher values produce smoother curves but increase render time. Default is 0 (no antialiasing).<br><br><b><I>map_image</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional file name of an input image to use as the map. If not specified, a built-in map is used.<br><br>


title: DESCRIPTION
content:
The <i>ppmglobe</i> command, part of the Netpbm toolkit, generates a PPM (Portable Pixmap) image depicting a map of the world. By default, it projects a high-resolution political map onto a globe, complete with an optional grid, border, and background. Users can customize various aspects, including colors for land, sea, background, grid, and border. <br><br>The command supports different map projections: the default azimuthal (globe) projection, or flat rectangular (equirectangular) and Mercator projections. It allows specifying the output image dimensions, the central viewpoint for globe projections, and the spacing for latitude and longitude grid lines. Advanced options include gamma correction, truecolor output, resolution control, and antialiasing for smoother rendering. <br><br>Users can also provide their own map image as input, which <i>ppmglobe</i> will scale and color according to specified options, or use the original colors if preferred. This makes <i>ppmglobe</i> a versatile tool for generating custom world map visualizations.


title: CAVEATS
content:
When providing a custom <i>map_image</i>, it is expected to be a single-plane PNM image (PGM or PBM) if you wish <i>ppmglobe</i> to color it with <b>-earth</b> and <b>-sea</b>. If the input is a PPM image or you want to retain its original colors, use <b>-noearth</b> and <b>-nosea</b>. The input map is scaled to 4096x2048 and is expected to be an equirectangular projection spanning -180 to 180 degrees longitude horizontally and -90 to 90 degrees latitude vertically.


title: BUILT-IN MAP
content:
By default, <i>ppmglobe</i> uses a high-resolution political map built directly into the program. This map is used if no <i>map_image</i> argument is provided.


title: COLOR SPECIFICATION
content:
Colors for options like <b>-background</b>, <b>-earth</b>, etc., can be specified in various ways, typically by name (e.g., 'red', 'lightgreen'), RGB hexadecimal (e.g., '#FF0000'), or RGB decimal (e.g., '255,0,0'). Refer to the <i>ppm(5)</i> man page for full color specification details.


title: OUTPUT FORMAT
content:
The output is always a PPM (Portable Pixmap) image, which is a simple, uncompressed pixelmap format. It can be further processed by other Netpbm tools or converted to other image formats.


title: HISTORY
content:
<i>ppmglobe</i> is part of the Netpbm project, a long-standing open-source package of graphics programs and a programming library for handling graphical images. Netpbm began in the early 1990s as a collection of tools for manipulating PBM, PGM, and PPM image formats. <i>ppmglobe</i> specifically provides a utility for generating geographical visualizations, leveraging the core Netpbm image manipulation capabilities. Its development has focused on offering various projection types and customization options for rendering world maps.


title: PARAMETERS
content:
<b>-output=<i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output file path for the histogram. Defaults to standard output if not provided.<br><br><b>-bars</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <i>ppmhist</i> to output a visual histogram image instead of the default text list.<br><br><b>-imagetype=<i>type</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For <i>-bars</i> output, specifies the type of the output image (e.g., <i>ppm</i> for color, <i>pgm</i> for intensity/grayscale). The default is typically <i>ppm</i>.<br><br><b>-sort=<i>key</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sorts the histogram entries based on a specified <i>key</i>. Common keys include <i>count</i> (frequency), <i>intensity</i>, <i>red</i>, <i>green</i>, or <i>blue</i>.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints additional processing information and statistics to standard error.<br><br><b>-width=<i>n</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width in pixels for the output image when <i>-bars</i> is used.<br><br><b>-height=<i>n</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the height in pixels for the output image when <i>-bars</i> is used.<br><br><b>-bincolors=<i>n</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Groups colors into <i>n</i> bins or categories, effectively reducing the number of distinct colors represented in the histogram. Useful for high-color images.<br><br><b>-relative</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs color counts as percentages of the total pixels, rather than raw pixel counts.<br><br><b>-rgbonly</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Counts only distinct RGB triples. If omitted, colors are typically converted to intensity for counting, which might group different colored pixels with the same intensity value.<br><br><b>-color=<i>colorname</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For the visual histogram output, specifies the color of the bars. The <i>colorname</i> can be an X11 color name or a hexadecimal RGB value.<br><br><b>-background=<i>colorname</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For the visual histogram output, specifies the background color of the image.<br><br>


title: DESCRIPTION
content:
<i>ppmhist</i> is a utility from the Netpbm suite designed to analyze the color or intensity distribution of a Portable Pixmap (PPM) image. It reads a PPM image as input and calculates the frequency of each unique color encountered. The command can output this histogram in two primary formats: a plain text list detailing each color and its count, or a visual representation as another Netpbm image (PPM or PGM). This visual output displays the histogram as a bar graph, where bar heights correspond to color frequencies. <i>ppmhist</i> is invaluable for tasks such as understanding the dominant colors in an image, optimizing color palettes, analyzing image compression effectiveness, or preparing images for color correction by revealing their tonal range and color balance. It provides insightful data for various image processing and analysis workflows.


title: CAVEATS
content:
<i>ppmhist</i> expects its input to be in the Netpbm PPM format. If your image is in another format (like JPEG or PNG), you must first convert it using a tool like <i>anytopnm(1)</i>. For images with a very high number of distinct colors, the text output can be extremely long and resource-intensive. When using the <i>-bars</i> option for visual output, a low image width might lead to indistinguishable bars if there are too many distinct colors to represent adequately.


title: OUTPUT MODES
content:
<i>ppmhist</i> offers two distinct ways to present the image histogram:<br><br><b>Text Output</b>: By default, <i>ppmhist</i> produces a plain text list. Each line typically shows a color (often as an RGB tuple or color name) followed by the count of pixels with that color, and sometimes its intensity. This mode is highly suitable for scripting, further numerical analysis, or direct human readability of color frequencies.<br><br><b>Visual Histogram (Bars)</b>: When the <i>-bars</i> option is used, <i>ppmhist</i> generates a graphical representation of the histogram as a Netpbm image. This image typically displays vertical bars, where each bar represents a specific color or intensity range, and its height corresponds to the frequency of that color/intensity in the original image. This mode is excellent for quick visual assessment of color distribution and identifying dominant hues or tonal ranges.


title: HISTORY
content:
<i>ppmhist</i> is an integral part of the Netpbm graphics utilities package, which traces its origins back to the PBMplus toolkit developed in the early 1990s. This suite of tools has been a cornerstone of Unix-like systems for manipulating and converting various image formats, particularly the portable "anymap" formats (PPM, PGM, PBM). <i>ppmhist</i> embodies the Netpbm philosophy of simple, modular tools that can be chained together for complex image processing tasks, providing a fundamental capability for analyzing image content since its inception.


title: PARAMETERS
content:
<b><b>-font</b> <i>&lt;fontname&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the font to use for the label. This can be a Netpbm font name (e.g., <i>type1</i>) or a path to a font file. Default is <i>type1</i>.<br><br><b><b>-text</b> <i>&lt;text&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The actual text string to be added as a label. If the text begins with <i>@</i>, the rest is interpreted as a filename from which to read the text.<br><br><b><b>-size</b> <i>&lt;pixels&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the font size in pixels. This determines the height of the characters.<br><br><b><b>-color</b> <i>&lt;colorname&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the color of the text. Can be a color name (e.g., <i>red</i>, <i>blue</i>) or a hexadecimal RGB value (e.g., <i>#RRGGBB</i>). Default is <i>black</i>.<br><br><b><b>-position</b> <i>&lt;gravity&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the placement of the text label on the image. Common values include <i>northwest</i>, <i>north</i>, <i>northeast</i>, <i>west</i>, <i>center</i>, <i>east</i>, <i>southwest</i>, <i>south</i>, <i>southeast</i>, <i>top</i>, <i>bottom</i>. Default is <i>southwest</i>.<br><br><b><b>-align</b> <i>&lt;alignment&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the horizontal alignment of the text within its bounding box: <i>left</i>, <i>center</i>, or <i>right</i>. Default is <i>left</i>.<br><br><b><b>-background</b> <i>&lt;colorname&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a solid background color behind the text. If not specified, the background is transparent, blending the text with the image.<br><br><b><b>-margin</b> <i>&lt;pixels&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a margin in pixels between the text and the edge of the image, or between the text and a background box. Default is 10 pixels.<br><br><b><b>-width</b> <i>&lt;pixels&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a maximum width for the text. If the text exceeds this width, it will wrap or be truncated depending on other options.<br><br><b><b>-height</b> <i>&lt;pixels&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets a maximum height for the text. If the text exceeds this height, it will be truncated.<br><br><b><b>-wrap</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables word wrapping for the text when combined with <i>-width</i>. Text will wrap at word boundaries rather than being truncated or overflowing.<br><br><b><b>-encoding</b> <i>&lt;encoding&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character encoding of the input text (e.g., <i>iso-8859-1</i>, <i>utf8</i>). This is crucial for displaying non-ASCII characters correctly.<br><br><b><b>-dpi</b> <i>&lt;dpi&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the dots per inch for font rendering, affecting the visual size and quality of the font. Default is 72 DPI.<br><br><b><b>-shadow</b> <i>&lt;offset&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a shadow effect to the text. The <i>offset</i> specifies how many pixels the shadow is shifted from the main text.<br><br><b><b>-box</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Draws a solid box around the text label. The color of the box is determined by the <i>-background</i> option.<br><br><b><b>-vbar</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Draws a vertical bar next to the text. Typically used with <i>-align left</i> or <i>-align right</i> for visual emphasis.<br><br><b><b>-noblend</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents color blending when drawing the text, instead setting pixel values directly. This can result in sharper but less smooth text on complex backgrounds.<br><br>


title: DESCRIPTION
content:
The <i>ppmlabel</i> command is a specialized utility within the Netpbm image manipulation suite. It is designed to overlay text labels directly onto Portable Pixmap (PPM) format images. It reads an image from standard input, applies the specified text label with various customizable attributes (font, size, color, position, alignment, background, margins, etc.), and then writes the modified image to standard output. This allows for easy integration into shell scripts and pipelines for automated image processing workflows, such as adding timestamps, captions, or watermarks to image streams.


title: CAVEATS
content:
<i>ppmlabel</i> is part of the Netpbm suite, meaning it expects and outputs images in Netpbm (PPM) format. For TrueType/OpenType fonts, the <i>gttf</i> utility and the FreeType library must be installed and correctly configured within the Netpbm setup. Font availability and rendering quality can depend heavily on system configuration and the specific Netpbm build.<br>Text wrapping (<i>-wrap</i>) is only effective when combined with <i>-width</i>.


title: USAGE WITH PIPES
content:
<i>ppmlabel</i> is designed to work seamlessly with Unix pipes. It reads the input PPM image from standard input (<i>stdin</i>) and writes the labeled PPM image to standard output (<i>stdout</i>). This allows it to be easily integrated into complex image processing pipelines, for example: <br><i>cat input.ppm | ppmlabel -text 'My Label' -size 20 -color blue > output.ppm</i><br>or <br><i>jpegtopnm image.jpg | ppmlabel -text 'Watermark' -position southwest | pnmtopng > image_labeled.png</i>


title: FONT HANDLING
content:
The command primarily uses Type 1 fonts, which are typically found in Netpbm's font directories. For TrueType/OpenType font support, Netpbm relies on the <i>gttf</i> utility and the FreeType library. Users might need to configure Netpbm's <i>NETPBM_FONTDIR</i> environment variable to ensure fonts are located correctly.


title: HISTORY
content:
<i>ppmlabel</i> is a component of the venerable Netpbm project, which traces its roots back to Jef Poskanzer's PBMPlus toolkit developed in the late 1980s. Netpbm itself evolved from PBMPlus to become a comprehensive suite of utilities for manipulating graphic images in various formats. <i>ppmlabel</i> was introduced to provide a specialized, efficient way to overlay text on PPM images, fitting into the Unix philosophy of small, single-purpose tools that can be chained together via pipes.


title: SYNOPSIS
content:
<b>ppmmake</b> [<i>options</i>] [<i>width</i> <i>height</i>]<br><b>ppmmake</b> [<i>options</i>] <i>command_file</i>


title: PARAMETERS
content:
<b>-background <i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the background color of the image.<br><br><b>-line <i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the color for lines drawn.<br><br><b>-box <i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the fill color for boxes drawn.<br><br><b>-fill</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Draws filled boxes instead of outlines.<br><br><b>-r <i>value</i>, -g <i>value</i>, -b <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify individual red, green, and blue components (0-255) for the most recently set color (background, line, or box).<br><br><b>-rgb <i>r,g,b</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a color using comma-separated red, green, and blue components (0-255).<br><br><b>-color <i>name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify a color using a standard X11 color name (e.g., 'red', 'lightgray').<br><br><b>-size <i>width</i> <i>height</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the width and height of the output image in pixels.<br><br><b>-nomap</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs a truecolor image without a colormap (i.e., not indexed color).<br><br><b>-novertical</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents drawing vertical grid lines.<br><br><b>-nohorizontal</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents drawing horizontal grid lines.<br><br><b>-transparent</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Makes the background transparent. This is only effective if the output image format supports transparency (e.g., when piped to a tool like <b>pnmtopng(1)</b>).<br><br>


title: DESCRIPTION
content:
The <b>ppmmake</b> command is a versatile utility within the Netpbm image manipulation toolkit. It is designed to create basic Portable Pixmap (PPM) images from scratch by programmatically drawing filled rectangles and lines. This tool is particularly useful for generating a variety of visual elements such as test patterns, color swatches, or simple graphical components, bypassing the need for a complex image editor. Users have precise control over the output, being able to specify the image dimensions, background color, and distinct colors for both the lines and the filled boxes. Furthermore, <b>ppmmake</b> offers the flexibility to read drawing commands from a specified file, which significantly enhances its utility for creating more intricate or repeatable image designs efficiently through scripting.


title: CAVEATS
content:
<b>ppmmake</b> primarily outputs PPM format, which does not natively support transparency. For transparent output, the generated PPM must be piped to a tool like <b>pnmtopng(1)</b>. The drawing capabilities are limited to simple lines and filled rectangles; complex shapes or text are not supported directly.


title: INPUT FROM FILE
content:
Instead of specifying width and height directly, <b>ppmmake</b> can read drawing commands from a specified file. Each line in the file represents a command (e.g., 'background red', 'line 10 10 50 50'), allowing for more structured and complex image generation. This is useful for creating repeatable patterns or larger sets of drawing instructions.


title: COLOR SPECIFICATION
content:
Colors can be specified using various methods: by name (e.g., 'red'), by RGB components (e.g., '255,0,0'), or individually using <b>-r</b>, <b>-g</b>, <b>-b</b> options. The order of color options matters; subsequent <b>-r</b>, <b>-g</b>, <b>-b</b>, or <b>-rgb</b> options modify the color set by the preceding <b>-background</b>, <b>-line</b>, or <b>-box</b> option.


title: HISTORY
content:
<b>ppmmake</b> is a long-standing utility within the Netpbm project, which originated from Jef Poskanzer's PBMPlus toolkit in the late 1980s. Its core purpose has remained consistent: to provide a simple, scriptable way to generate basic graphical patterns. It embodies the Netpbm philosophy of small, focused tools that can be chained together in pipelines.


title: SYNOPSIS
content:
ppmmix [<I>options</I>] [<I>image1_file</I>] [<I>image2_file</I>]<br><br>Reads two Portable Pixmap (PPM) images from files or standard input and writes the blended PPM image to standard output.


title: PARAMETERS
content:
<b><I>image1_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the first Portable Pixmap (PPM) image to be blended. If omitted, the first image is read from standard input.<br><br><b><I>image2_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the second Portable Pixmap (PPM) image to be blended. If omitted, the second image is read from standard input after the first.<br><br><b>-weight <I>n</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a constant floating-point weight for the mix, where <I>n</I> is a value between 0.0 and 1.0. A value of 0.0 means only the first image is visible, and 1.0 means only the second. This option takes precedence over <I>-alphafile</I> and <I>-alphaval</I>.<br><br><b>-alphafile <I>alpha_file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a Portable Graymap (PGM) file to use as a per-pixel alpha mask. The grayscale values in <I>alpha_file</I> determine the blend ratio for each corresponding pixel. This file must have the same dimensions as the input images. This option takes precedence over <I>-alphaval</I>.<br><br><b>-alphaval <I>alpha_val</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a constant integer alpha value between 0 and the input images' <I>maxval</I>. This value determines the blend ratio for all pixels. 0 means <I>image1</I> is fully visible, <I>maxval</I> means <I>image2</I> is fully visible.<br><br>


title: DESCRIPTION
content:
ppmmix is a Netpbm utility designed to blend two Portable Pixmap (PPM) images together. It takes two input images of the same dimensions and maximum color value (<I>maxval</I>) and produces a single blended PPM image as output. The blending process applies a formula: <I>new_pixel</I> = (<I>pixel1</I> * (1 - <I>alpha</I>)) + (<I>pixel2</I> * <I>alpha</I>). The '<I>alpha</I>' value, which determines the blending ratio, can be specified globally via a constant weight or integer value, or on a per-pixel basis using a separate Portable Graymap (PGM) alpha mask file. If no alpha source is provided, ppmmix defaults to an even 50/50 mix. This tool is fundamental for creating effects like image fading, transparency, or combining visual elements in a compositing workflow.


title: CAVEATS
content:
<b>Input Image Requirements:</b><br>Both input PPM images must have identical dimensions (width and height) and the same maximum color value (<I>maxval</I>). Failure to meet these requirements will result in an error.<br><br><b>Alpha File Requirements:</b><br>If using the <I>-alphafile</I> option, the specified PGM file must also have the exact same dimensions as the input images.<br><br><b>Option Precedence:</b><br>Only one alpha source option (<I>-weight</I>, <I>-alphafile</I>, or <I>-alphaval</I>) can be used at a time. If multiple are provided, <I>-weight</I> takes highest precedence, followed by <I>-alphafile</I>, then <I>-alphaval</I>.


title: BLENDING FORMULA
content:
The core of ppmmix's operation is its blending formula: <I>new_pixel</I> = (<I>pixel1</I> * (1 - <I>alpha</I>)) + (<I>pixel2</I> * <I>alpha</I>).<br><br>Here:<br>&#8226;  <I>new_pixel</I> represents the resulting pixel value in the output image.<br>&#8226;  <I>pixel1</I> and <I>pixel2</I> are the corresponding pixel values from the first and second input images.<br>&#8226;  <I>alpha</I> is the blending factor, which can be a constant derived from <I>-weight</I> or <I>-alphaval</I>, or a per-pixel value from <I>-alphafile</I>.


title: DEFAULT BEHAVIOR
content:
If no alpha source option (<I>-weight</I>, <I>-alphafile</I>, or <I>-alphaval</I>) is specified, ppmmix defaults to an <I>alpha</I> value of 0.5. This results in an equal 50/50 blend between the two input images, effectively averaging their pixel values.


title: HISTORY
content:
ppmmix is a component of the Netpbm project, a comprehensive suite of graphics utilities for image manipulation. Netpbm originated from the PBMplus package, developed in the late 1980s by Jef Poskanzer. The philosophy behind Netpbm tools like ppmmix is to provide small, efficient, and specialized programs that can be chained together via pipes to perform complex image processing tasks. This modular approach emphasizes interoperability and command-line automation, a hallmark of traditional Unix tool design.


title: PARAMETERS
content:
<b><b>-b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Normalizes brightness and contrast to use the full intensity range from 0 to the maximum possible value for the image format. This is the default behavior if no option is specified.<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A historical synonym for <b>-b</b>. It performs the same brightness and contrast normalization.<br><br><b><b>-g</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies gamma correction. This stretches the intensity range non-linearly, which can be useful for correcting images taken in low light or with specific camera characteristics. It aims to make the image appear more visually balanced.<br><br><b><b>-l</b> <I>minval</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input intensity value that should be mapped to black (0) in the output. Any input values below this will also become black.<br><br><b><b>-u</b> <I>maxval</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input intensity value that should be mapped to white (the maximum possible intensity value for the image format) in the output. Any input values above this will also become white.<br><br><b><b>-S</b> <I>samples</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Calculates the normalization parameters (minimum and maximum input values) based on a random sample of <I>samples</I> pixels from the image instead of the entire image. This can speed up processing for very large images, though it might be less precise.<br><br><b><I>ppmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the input PPM image file. If omitted, ppmnorm reads the PPM image data from standard input (stdin).<br><br>


title: DESCRIPTION
content:
ppmnorm adjusts the brightness and contrast of a PPM (Portable Pixmap) image to utilize the full range of colors available in the image format. It aims to make the darkest point black and the brightest point white, distributing the intermediate colors evenly. This process can significantly improve the visual appearance of images that might otherwise look washed out, too dark, or too bright. It reads a PPM image from standard input and writes the normalized PPM image to standard output. As part of the Netpbm tools suite, ppmnorm provides a fundamental image manipulation filter for converting and enhancing various image formats by leveraging simple, pipeline-friendly operations.


title: CAVEATS
content:
ppmnorm works exclusively with PPM (Portable Pixmap) image files. It is not designed for other image formats like PNG, JPEG, or GIF directly. While effective for general brightness/contrast normalization, it may sometimes over-saturate images with very few distinct colors or extreme outlier pixel values. Repeated application without careful consideration can lead to loss of detail or unintended color shifts.


title: HISTORY
content:
ppmnorm is a component of the Netpbm project, a comprehensive suite of graphics filters for converting and manipulating images. Netpbm originated from the earlier Pbmmake, Pgmtools, and Ppmtools packages in the early days of Unix. Its development has focused on creating simple, efficient utilities that adhere to the Unix philosophy of small, specialized tools that can be chained together via pipes for complex image processing tasks. ppmnorm specifically addresses the fundamental need for adjusting image tonal range.


title: SYNOPSIS
content:
<b>ppmntsc</b> [<i>-whitelevel value</i>] [<i>-blacklevel value</i>] [<i>-brightness value</i>] [<i>-contrast value</i>] [<i>-saturation value</i>] [<i>-tint value</i>] [<i>-sharpness value</i>] [<i>-artifact value</i>] [<i>-subcarrier value</i>] [<i>-field number</i>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b><b>-whitelevel</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the NTSC white level, typically in IRE units (default is 100).<br><br><b><b>-blacklevel</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the NTSC black level, typically in IRE units (default is 7.5).<br><br><b><b>-brightness</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the image brightness, typically in IRE units (default is 0).<br><br><b><b>-contrast</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the image contrast as a percentage (default is 100).<br><br><b><b>-saturation</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the color saturation as a percentage (default is 100).<br><br><b><b>-tint</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the color tint or hue in degrees (default is 0).<br><br><b><b>-sharpness</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the simulated image sharpness (default is 0).<br><br><b><b>-artifact</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the level of simulated color artifacts (default is 1.0, where 0.0 means no artifacts and 1.0 is full). Higher values can increase artifacting.<br><br><b><b>-subcarrier</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the NTSC color subcarrier frequency in Hertz (default is 3.579545e6 Hz, or 3.579545 MHz).<br><br><b><b>-field</b> <i>number</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects which interlaced field to output. NTSC is an interlaced signal; this option allows choosing either field 0 or field 1 (default is 0).<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optional. The path to the input Portable Pixmap (PPM) image file. If omitted, <b>ppmntsc</b> reads from standard input.<br><br>


title: DESCRIPTION
content:
<b>ppmntsc</b> is a command-line utility from the Netpbm image manipulation toolkit that converts a Portable Pixmap (PPM) image into another PPM image, simulating the visual characteristics and common artifacts seen on an NTSC (National Television System Committee) television set. It reads a full-color PPM image from standard input (or a specified file) and writes the modified PPM image to standard output. The primary purpose of <b>ppmntsc</b> is to allow developers and designers to preview how their digital images might appear when displayed on an NTSC analog television, accounting for factors like limited bandwidth, YIQ color encoding, and intercarrier interference, which can lead to color bleeding, fringing, and other artifacts, especially with fine details or high-frequency color transitions. The command offers various options to control aspects like brightness, contrast, saturation, tint, sharpness, and the level of simulated color artifacts, providing granular control over the NTSC emulation. It's a valuable tool for understanding the nuances of analog video display and for optimizing digital content for NTSC compatibility.


title: CAVEATS
content:
<b>ppmntsc</b> provides a simulation of NTSC television output, but it does not perfectly model all complex analog video phenomena. It primarily focuses on color encoding and decoding artifacts. It outputs only a single field of an interlaced signal, meaning it doesn't fully simulate interlacing effects or generate interlaced output. Users should be aware that the actual display characteristics on different NTSC televisions can vary significantly, and this tool offers an approximation rather than a perfect emulation of every display scenario.


title: INPUT/OUTPUT
content:
<b>ppmntsc</b> reads a full-color Portable Pixmap (PPM) image from standard input by default, or from a specified file path. It then writes the processed PPM image to standard output. This design makes it highly suitable for piping with other Netpbm tools or other command-line utilities for complex image processing workflows.


title: NTSC COLOR SIMULATION
content:
The command simulates the conversion of the RGB color space of the input image to the YIQ color space (luminance, in-phase chrominance, quadrature-phase chrominance) used in NTSC broadcasting. It then simulates the subsequent decoding process, which introduces bandwidth limitations and phase issues. These processes lead to characteristic color artifacts, such as color bleeding or fringing, especially noticeable around sharp color transitions or fine details, typical of analog NTSC television display.


title: HISTORY
content:
<b>ppmntsc</b> is a component of the Netpbm package, a long-standing and widely used suite of graphics file format converters and image manipulation tools. Netpbm originated from Jef Poskanzer's PBMplus package, first released in 1988. Over the decades, Netpbm has been continuously developed and maintained by a community of volunteers. <b>ppmntsc</b> was specifically designed to address the need for simulating NTSC analog television characteristics on digital images, making it a valuable tool for content creators and engineers working with broadcast standards.


title: PARAMETERS
content:
<b><i>width</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired width of the output image in pixels.<br><br><b><i>height</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The desired height of the output image in pixels.<br><br><b><i>pattern</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The type of pattern to generate. Common patterns include:<br><b>solid</b>: A solid color.<br><b>hgradient</b>, <b>vgradient</b>: Horizontal/vertical gradients.<br><b>hbars</b>, <b>vbars</b>: Horizontal/vertical bars.<br><b>checkerboard</b>: A square checkerboard pattern.<br><b>hcheckerboard</b>, <b>vcheckerboard</b>: Half-checkerboard (diagonal).<br><b>circles</b>: Concentric circles.<br><b>sines</b>, <b>hsines</b>, <b>vsines</b>: Sine wave patterns.<br><b>colorbars</b>: Standard television color bars.<br><br><b><i>pattern_options</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Options specific to the chosen pattern type. These vary greatly depending on the selected pattern.<br><b>-color</b> <i><color></i>: Sets the primary color (e.g., 'red', '#FF0000').<br><b>-color2</b> <i><color></i>: Sets a secondary color for multi-color patterns.<br><b>-fade</b> <i><fraction></i>: For gradients, specifies color fade amount (0.0 to 1.0).<br><b>-barwidth</b> <i><pixels></i>: For bar patterns, sets the width of each bar.<br><b>-rows</b> <i><number></i>, <b>-cols</b> <i><number></i>: For checkerboards, number of rows/columns.<br><b>-amplitude</b> <i><value></i>, <b>-frequency</b> <i><value></i>, <b>-wavelength</b> <i><value></i>, <b>-offset</b> <i><value></i>: For sine wave patterns.<br><br>


title: DESCRIPTION
content:
<i>ppmpat</i> is a utility from the Netpbm suite that creates various types of test patterns as a Portable Pixmap (PPM) image. It's often used for display testing, calibration, or debugging graphics pipelines. Users can specify the image's dimensions (width and height) and choose from several predefined pattern types, such as solid colors, linear gradients, horizontal or vertical bars, checkerboards, concentric circles, and sine wave patterns. The output is written to standard output, making it easy to pipe to other Netpbm tools or redirect to a file. It's a foundational tool for image generation within the Netpbm ecosystem, providing simple yet powerful pattern generation capabilities.


title: CAVEATS
content:
<i>ppmpat</i> always outputs to standard output; it must be redirected to a file or piped to another Netpbm tool. <br>Pattern-specific options are only valid when their respective pattern is chosen; using an invalid option will result in an error. <br>Color names (e.g., 'red') are system-dependent and may not be universally available; hexadecimal RGB values are more portable.


title: OUTPUT FORMAT
content:
<i>ppmpat</i> exclusively generates images in the Portable Pixmap (PPM) format. The output is written to standard output (<i>stdout</i>), which necessitates redirection to a file (e.g., `ppmpat 100 100 solid > image.ppm`) or piping to another program for further processing or display (e.g., `ppmpat 100 100 checkerboard | pnmtopng > image.png`).


title: COLOR SPECIFICATION
content:
Colors can be specified either by a common English name (e.g., 'red', 'green', 'blue') or by a hexadecimal RGB value (e.g., '#FF0000' for red, '#00FF00' for green). The availability of color names depends on the system's color database (often `/etc/X11/rgb.txt`). Hexadecimal values offer more precise and portable color control.


title: HISTORY
content:
<i>ppmpat</i> is an integral part of the Netpbm package, a comprehensive suite of graphics manipulation programs for Unix-like systems. Netpbm originated from the earlier PBMplus package and has been under continuous development for decades. It adheres to the Unix philosophy of small, specialized tools that can be combined, making <i>ppmpat</i> a classic example of a single-purpose utility designed for generating basic image patterns efficiently.


title: PARAMETERS
content:
<b><i>numcolors</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The <b>required</b> integer argument specifying the maximum number of colors for the output image. This value must be between 1 and 65536, inclusive.<br><br><b><b><code>-floyd</code></b> / <b><code>-fs</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use Floyd-Steinberg error diffusion dithering. This technique helps to reduce banding artifacts and improve the perceived color depth when quantizing to a smaller palette.<br><br><b><b><code>-nofs</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable dithering. This results in a sharper image but may introduce noticeable banding or posterization effects, especially with significant color reduction.<br><br><b><b><code>-randomdither</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply random noise dithering. This is an alternative dithering method to Floyd-Steinberg.<br><br><b><b><code>-norandomdither</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disable random noise dithering.<br><br><b><b><code>-mapfile=</code></b><i><I>mapfile</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quantize colors to the specific color map defined in <i><I>mapfile</I></i> instead of generating a new palette. The number of colors in <i><I>mapfile</I></i> overrides <i><I>numcolors</I></i>.<br><br><b><b><code>-mapformat=</code></b><i><I>format</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the format of the <b><code>-mapfile</code></b>. Valid formats include <b><code>ppm</code></b>, <b><code>xpm</code></b>, <b><code>xbm</code></b>, <b><code>pgm</code></b>, and <b><code>pbm</code></b>.<br><br><b><b><code>-gamma=</code></b><i><I>value</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply gamma correction with the specified <i><I>value</I></i> to the image before quantization. This can affect how colors are perceived and grouped during the quantization process.<br><br><b><b><code>-pmfile=</code></b><i><I>file</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use a predefined palette from <i><I>file</I></i> for quantization. This implies a fixed palette and generally disables dithering.<br><br><b><b><code>-nice</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generate a 'nicer' palette. This option attempts to preserve visual quality by potentially using fewer than the requested <i><I>numcolors</I></i> if it results in a more visually appealing color set.<br><br><b><b><code>-verbose</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output progress and diagnostic information to standard error, providing insights into the quantization process.<br><br><b><b><code>-extrainfo</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print additional detailed information about the quantization process, such as color distribution statistics.<br><br><b><b><code>-meancut</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the use of the mean-cut algorithm for palette generation instead of the default median-cut algorithm. The mean-cut algorithm divides color space boxes at the mean of the color components.<br><br><b><b><code>-nopa</code></b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not generate a Netpbm format image with an embedded palette. The output will be a plain PPM image where each pixel's color is directly mapped to the closest color in the generated palette.<br><br><b><b><code>-sort=</code></b><i><I>order</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sort the colors in the output colormap according to the specified <i><I>order</I></i>. Common orders include <b><code>rgb</code></b>, <b><code>gray</code></b>, <b><code>hue</code></b>, <b><code>saturation</code></b>, <b><code>value</code></b>, and <b><code>freq</code></b> (frequency).<br><br>


title: DESCRIPTION
content:
<b><code>ppmquant</code></b> is a command-line utility from the Netpbm suite that quantizes a Portable Pixmap (PPM) image to a specified maximum number of colors. It reads a PPM image from standard input (or a specified file) and writes a new PPM image with a reduced color palette to standard output. <br><br>The primary purpose of color quantization is to reduce the file size of an image, adapt it for displays with limited color depth (e.g., 256-color monitors), or prepare it for conversion to palettized image formats like GIF or indexed PNGs. By default, <b><code>ppmquant</code></b> employs a median-cut algorithm to determine the optimal color palette. It can also apply dithering techniques, such as Floyd-Steinberg, to minimize banding artifacts that may arise from significant color reduction, thus preserving visual quality.


title: CAVEATS
content:
While <b><code>ppmquant</code></b> operates on PPM images, its `<i>numcolors</i>` argument specifies the <b>maximum</b> number of colors. The actual output image might have fewer colors if the original image contains fewer unique colors, or if the <b><code>-nice</code></b> option is used. <br><br>Dithering significantly enhances visual quality after color reduction but can slightly increase file size due to less repetitive pixel data. <br><br>For specific color requirements, providing a fixed palette via <b><code>-mapfile</code></b> or <b><code>-pmfile</code></b> offers more control than relying solely on the algorithmic quantization.


title: INPUT AND OUTPUT
content:
If no <i><I>inputfile</I></i> is specified, <b><code>ppmquant</code></b> reads the PPM image from standard input. The quantized PPM image is always written to standard output. This design facilitates piping <b><code>ppmquant</code></b> with other Netpbm utilities for complex image processing workflows.


title: COLOR DEPTH REDUCTION
content:
The <i><I>numcolors</I></i> argument effectively transforms a full-color PPM image into an indexed-color image, albeit still represented in the PPM format. The generated palette is embedded within the output PPM header, and pixels are then mapped to the closest colors in this new, smaller palette.


title: QUANTIZATION ALGORITHMS
content:
By default, <b><code>ppmquant</code></b> uses the median-cut algorithm, which recursively divides the color space into smaller rectangular boxes until the desired number of colors is met. The <b><code>-meancut</code></b> option provides an alternative, using the mean of the color components for division, which can sometimes yield different results.


title: HISTORY
content:
<b><code>ppmquant</code></b> is a long-standing component of the Netpbm project, which originated from the `pbmplus` package in the late 1980s. Its development was driven by the necessity to efficiently manage and display true-color images on hardware with limited color capabilities. The underlying median-cut color quantization algorithm, a core feature, has been a standard technique for decades. <b><code>ppmquant</code></b> has consistently served as a robust command-line utility for color reduction, adapting to evolving image processing needs within the versatile Netpbm toolkit.


title: PARAMETERS
content:
<b><b>-maxcolors=</b><i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum number of colors to use in the output common colormap. The default is usually 256. Setting a lower number reduces palette size but may impact image quality.<br><br><b><b>-floyd</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables Floyd-Steinberg dithering, which is the default behavior for spreading quantization errors to reduce banding.<br><br><b><b>-nofloyd</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables Floyd-Steinberg dithering. This can result in sharper color boundaries and potentially more noticeable color banding.<br><br><b><b>-gamma=</b><i>gamma_value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the gamma correction applied during color quantization. This influences how colors are perceived and mapped to the new palette.<br><br><b><b>-nicer</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <i>ppmquantall</i> to spend more time finding a 'nicer' or more perceptually optimal colormap. This may increase processing time but can result in better visual quality.<br><br><b><b>-noverbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppresses verbose output, showing only essential information or errors during processing.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, providing more detailed information about the processing steps and progress.<br><br>


title: DESCRIPTION
content:
<i>ppmquantall</i> reads a set of PPM (Portable Pixmap), PGM (Portable Graymap), or PBM (Portable Bitmap) image files and outputs a new set of corresponding image files. <br><br>The key function is to quantize all input images to a <b>single, common colormap</b>. This colormap is optimally derived from the combined color information of <i>all</i> input images. This command is particularly valuable when creating animations (e.g., GIFs) or collections of images that need to share a limited palette, which helps in reducing file size and maintaining visual consistency across multiple frames or images. <br><br>Internally, <i>ppmquantall</i> first analyzes all input images to build a master colormap and then applies <i>ppmquant</i> to each individual image, mapping its colors to this newly created shared palette. Output files are typically named by appending a suffix (e.g., <code>.out.ppm</code>) to the input filenames.


title: CAVEATS
content:
Processing can be <b>memory-intensive</b> and <b>time-consuming</b> for a large number of high-resolution input images. This is due to the need to load and analyze all images to construct the optimal master colormap. <br><br>Output files are created in the current directory with names derived from the input files (e.g., appending <code>.out.ppm</code>), which might overwrite existing files if not handled carefully.


title: INPUT AND OUTPUT
content:
<i>ppmquantall</i> accepts PPM, PGM, or PBM files as input. The output files will maintain the same format as the input (e.g., PPM for PPM input) and are named by adding a suffix like <code>.out.ppm</code> to the original filename. While it can process input from standard input if no files are specified, its primary utility and design are for handling multiple distinct image files provided as arguments.


title: TYPICAL USE CASE
content:
A very common application for <i>ppmquantall</i> is preparing a series of images (e.g., frames of an animation) before converting them to a format such as GIF. By ensuring all frames share the same optimal color palette, the resulting GIF file can be significantly smaller in size and maintain consistent visual quality without noticeable palette shifts between frames, which is vital for smooth animations.


title: HISTORY
content:
<i>ppmquantall</i> is a utility within the comprehensive <b>Netpbm</b> open-source graphics toolkit. Netpbm itself has a long history, evolving from the original PBMPLUS package (first released in 1988) and becoming Netpbm in 1991. The command was developed to address the specific need for consistent color palettes across multiple images, which is crucial for efficient animation and image sequence creation, especially for formats with limited palettes like GIF.


title: SYNOPSIS
content:
<b>ppmrainbow</b> [-leftcolor <i>color</i>] [-rightcolor <i>color</i>] [-xsize <i>cols</i>]<br>          [-ysize <i>rows</i>] [-xvariance <i>factor</i>] [-yvariance <i>factor</i>]<br>          [-rgb] [-maxval <i>maxval</i>]


title: PARAMETERS
content:
<b>-leftcolor <i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the RGB color for the left side (or start) of the image. Color is specified as 'R,G,B' values. Default is '255,0,0' (red).<br><br><b>-rightcolor <i>color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the RGB color for the right side (or end) of the image. Color is specified as 'R,G,B' values. Default is '128,0,255' (violet).<br><br><b>-xsize <i>cols</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the width of the image in columns (pixels). Default is 256.<br><br><b>-ysize <i>rows</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the height of the image in rows (pixels). Default is 256.<br><br><b>-xvariance <i>factor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the non-linear variation of color along the X-axis. A factor of 1 is linear. Values greater than 1 speed up variation at the start, less than 1 slow it down. Default is 1.<br><br><b>-yvariance <i>factor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the non-linear variation of color along the Y-axis. A factor of 0 means no Y-axis variation. Default is 0.<br><br><b>-rgb</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces color interpolation to occur in RGB color space instead of the default HSV (hue) space.<br><br><b>-maxval <i>maxval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the maximum color value for pixels in the output PPM image. Default is 255.<br><br>


title: DESCRIPTION
content:
The <b>ppmrainbow</b> command is a utility within the Netpbm toolkit, designed to generate a Portable Pixmap (PPM) format image depicting a smooth color spectrum, commonly referred to as a rainbow. By default, it creates an image that transitions from red on the left to violet on the right, simulating the visible light spectrum. Users have extensive control over the generated image through various options. They can specify the exact RGB colors for the left and right (and implicitly top/bottom) edges of the spectrum, define the image dimensions (width and height), and adjust the non-linear progression of the color variation along both the X and Y axes using variance factors. Additionally, it offers a choice between interpolating colors in HSV (hue) space, which is the default for a more natural rainbow effect, or a linear interpolation in RGB color space. This flexibility makes it useful for creating custom color gradients for various graphical applications.


title: CAVEATS
content:
The variance calculation might produce unexpected or less intuitive results, especially when using extreme factor values or certain complex color combinations for the start and end points.


title: OUTPUT FORMAT
content:
The command outputs a Portable Pixmap (PPM) format image to standard output. This output can be redirected to a file, for example: <br><i>ppmrainbow -xsize 512 -ysize 200 > myrainbow.ppm</i>


title: COLOR SPECIFICATION
content:
Colors for <i>-leftcolor</i> and <i>-rightcolor</i> options should be provided as comma-separated RGB integer values (e.g., '255,0,0' for red). By default, these values range from 0 to 255, but this range can be altered using the <i>-maxval</i> option.


title: HISTORY
content:
<b>ppmrainbow</b> is a component of the Netpbm project, a comprehensive toolkit for manipulating graphic images. Its development aligns with Netpbm's goal of providing modular and composable image processing utilities, with its initial release and evolution tied to the broader Netpbm codebase.


title: SYNOPSIS
content:
<b>ppmrelief</b> [<i>-azimuth A</i>] [<i>-elevation E</i>] [<i>-lightx X</i>] [<i>-lighty Y</i>] [<i>-lightz Z</i>] [<i>-ambient A</i>] [<i>-diffuse D</i>] [<i>-specular S</i>] [<i>-shininess H</i>] [<i>-gray</i>] [<i>-normal</i>] [<i>-normalize</i>] [<i>-smooth</i>] [<i>-noclamp</i>] [<i>ppmfile</i> [<i>pgmfile</i>]]


title: PARAMETERS
content:
<b><i>-azimuth A</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the azimuth of the light source in degrees (0-360). Mutually exclusive with <i>-lightx/-lighty/-lightz</i>.<br><br><b><i>-elevation E</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the elevation of the light source in degrees (0-90, 0 is horizontal). Mutually exclusive with <i>-lightx/-lighty/-lightz</i>.<br><br><b><i>-lightx X</i>, <i>-lighty Y</i>, <i>-lightz Z</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the x, y, and z coordinates of the light source relative to the image center. Mutually exclusive with <i>-azimuth/-elevation</i>.<br><br><b><i>-ambient A</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the ambient light component (0.0-1.0). Default is 0.3.<br><br><b><i>-diffuse D</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the diffuse light component (0.0-1.0). Default is 0.7.<br><br><b><i>-specular S</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the specular light component (0.0-1.0). Default is 0.5.<br><br><b><i>-shininess H</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the shininess of the surface (0.0-100.0). Default is 10.0.<br><br><b><i>-gray</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs a PGM (Portable Graymap) image instead of a PPM. This produces a grayscale relief map.<br><br><b><i>-normal</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs a normal map in PPM format, where color channels represent surface normals (x, y, z components).<br><br><b><i>-normalize</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Normalizes the light vector to unit length before calculations.<br><br><b><i>-smooth</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a smoothing filter to the input image before calculating relief, which can reduce noise and harshness.<br><br><b><i>-noclamp</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents clamping of output colors to the valid range (0-255). Can result in colors outside this range.<br><br>


title: DESCRIPTION
content:
The <b>ppmrelief</b> command creates a simulated 3D relief map from an input image, giving it a shaded, sculpted appearance. It interprets the intensity (brightness) of pixels in the input image as elevation data: darker pixels represent lower points, and brighter pixels represent higher points. <br><br>You can use <b>ppmrelief</b> in two primary ways: <br>1. With a single PPM image: The color information from this image is used as the surface texture, and its intensity determines the elevation. <br>2. With two images: The first input is a PPM image used as the texture map, and the second is a PGM (Portable Graymap) image explicitly providing the elevation data. <br><br>The command applies a lighting model (based on ambient, diffuse, and specular components) from a user-defined light source. The resulting image is a PPM (or PGM if the <i>-gray</i> option is used) that visually represents the terrain or surface defined by the input image's intensity/elevation, as if lit from a specific direction.


title: CAVEATS
content:
The primary assumption of <b>ppmrelief</b> is that brighter pixels correspond to higher elevations and darker pixels to lower elevations. Understanding this is crucial for effective use. The effect is a 'pseudo-3D' rendering, not a true 3D model, meaning it's a 2D image with shading to simulate depth. Results can vary significantly with different input image characteristics and lighting parameters. <br><br>When providing two input files (PPM texture and PGM elevation), ensure they have identical dimensions, otherwise the behavior is undefined or an error will occur.


title: INPUT AND OUTPUT
content:
By default, <b>ppmrelief</b> expects a PPM (Portable Pixmap) image as input and produces a PPM image as output. If a second PGM (Portable Graymap) image is provided, it serves exclusively as the elevation map. Output can be redirected to a file or piped to another Netpbm command.


title: LIGHTING MODEL
content:
The command employs a simplified Phong reflection model to simulate how light interacts with the surface. This model combines three components:<br><i>Ambient light</i>: Uniform light that illuminates all surfaces equally.<br><i>Diffuse light</i>: Light scattered uniformly in all directions from the surface, dependent on the angle of the light source.<br><i>Specular light</i>: Highlights that appear on shiny surfaces, dependent on the angle of the light source, surface normal, and viewer position (though the viewer is assumed to be directly above in <b>ppmrelief</b>'s model).<br>The <i>-shininess</i> option controls the size and intensity of specular highlights.


title: HISTORY
content:
<b>ppmrelief</b> is part of the Netpbm project, a widely used toolkit for manipulating graphic images. Netpbm originated from Jef Poskanzer's Pbmplus package in the late 1980s and early 1990s, becoming a standard component in Unix and Linux systems for its versatility in converting, filtering, and processing image files in various formats. <b>ppmrelief</b> was developed to add sophisticated relief shading capabilities to the suite, extending its utility for artistic and analytical image transformations.


title: SYNOPSIS
content:
<b>ppmshadow</b> [<i>-x <I>xoffset</I></i>] [<i>-y <I>yoffset</I></i>] [<i>-color <I>color</I></i>] [<i>-opacity <I>opacity</I></i>] [<i>-pm</i>] [<i>-threshold <I>threshold</I></i>] [<i>-fade <I>radius</I></i>] [<i>-background <I>color</I></i>] [<i>-fadecolor <I>color</I></i>] [<i>-nofade</i>] [<i><I>input_file</I></i>]


title: PARAMETERS
content:
<b><i>-x <I>xoffset</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the horizontal offset of the shadow in pixels. Positive values move the shadow to the right.<br><br><b><i>-y <I>yoffset</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the vertical offset of the shadow in pixels. Positive values move the shadow downwards.<br><br><b><i>-color <I>color</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the color of the shadow. Can be a color name (e.g., 'black', 'grey') or a hex triplet (e.g., '#RRGGBB'). Default is black.<br><br><b><i>-opacity <I>opacity</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the transparency of the shadow as a floating-point value from 0.0 (fully transparent) to 1.0 (fully opaque). Default is 1.0.<br><br><b><i>-pm</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables permuted shadow for better translucency, especially when the shadow's color differs significantly from the background.<br><br><b><i>-threshold <I>threshold</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An integer value (0-255) used to distinguish the object from the background. Pixels darker than this threshold are considered part of the object that casts the shadow. Default is 127.<br><br><b><i>-fade <I>radius</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a fade effect to the shadow, causing it to become more transparent at its edges over a specified radius in pixels. Default is 0 (no fade).<br><br><b><i>-background <I>color</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the background color used for areas not considered part of the object. This is important for objects extracted based on the threshold.<br><br><b><i>-fadecolor <I>color</I></i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the color the shadow fades to when the <i>-fade</i> option is used. Default is the shadow color.<br><br><b><i>-nofade</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly disables any shadow fading, even if a fade radius is implied or set by other options.<br><br>


title: DESCRIPTION
content:
<i>ppmshadow</i> is a command-line utility from the Netpbm project designed to add a simulated shadow effect to an input PPM (Portable Pixmap) image. This tool enhances visual depth, making objects within the image appear to float or stand out. It provides various options to customize the shadow's appearance, including its horizontal and vertical offset, color, opacity, and fade characteristics. The command determines which parts of the image constitute the 'object' (and thus cast a shadow) versus the 'background' based on pixel intensity relative to a threshold. Typically, <i>ppmshadow</i> reads an image from standard input or a specified file and writes the modified image to standard output, making it highly suitable for use in Unix-like pipelines for automated image processing workflows.


title: CAVEATS
content:
<i>ppmshadow</i> operates solely on Netpbm (PPM) images, which do not inherently support alpha channels for transparency. Its method of separating foreground from background relies on a simple color threshold, which may not always produce ideal results for complex images with subtle color variations or existing transparency. The shadow effect is a basic simulation and not a physically accurate rendering of light and shadow.


title: TYPICAL USAGE IN PIPELINES
content:
Like most Netpbm tools, <i>ppmshadow</i> is designed to integrate seamlessly into shell pipelines. An image can be piped from another Netpbm utility (e.g., <i>jpegtopnm</i>) into <i>ppmshadow</i>, and its output can then be piped to another utility (e.g., <i>pnmtojpeg</i>) to convert it to a different format or perform further manipulations.<br><b>Example:</b> <br><code>jpegtopnm image.jpg | ppmshadow -x 5 -y 5 -color black -opacity 0.6 -fade 3 | pnmtojpeg > shadow_image.jpg</code><br>This command converts a JPEG to PPM, adds a black, semi-transparent, fading shadow, and converts it back to JPEG.


title: HISTORY
content:
<i>ppmshadow</i> is a component of the comprehensive Netpbm package, a suite of graphics utilities that traces its origins back to the Pbmplus package, initially developed by Jef Poskanzer in the late 1980s. Its inclusion reflects the Unix philosophy of providing small, specialized tools that can be chained together for more complex tasks. The command’s development has focused on maintaining compatibility and robustness within the Netpbm ecosystem, providing a reliable command-line option for adding basic graphical effects without requiring complex graphical user interfaces.


title: SYNOPSIS
content:
<b>ppmshift</b> [<b>-redshift</b> <i>shiftval</i>] [<b>-greenshift</b> <i>shiftval</i>] [<b>-blueshift</b> <i>shiftval</i>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b>-redshift <i>shiftval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>shiftval</i> is an integer that specifies the amount by which the red component of each pixel should be shifted. Positive values increase the red intensity, while negative values decrease it.<br><br><b>-greenshift <i>shiftval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>shiftval</i> is an integer that specifies the amount by which the green component of each pixel should be shifted. Positive values increase the green intensity, while negative values decrease it.<br><br><b>-blueshift <i>shiftval</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>shiftval</i> is an integer that specifies the amount by which the blue component of each pixel should be shifted. Positive values increase the blue intensity, while negative values decrease it.<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PPM image file. If not specified, <i>ppmshift</i> reads the image data from standard input.<br><br>


title: DESCRIPTION
content:
<i>ppmshift</i> is a command-line utility from the Netpbm suite designed for basic color manipulation of Portable Pixmap (PPM) images. It allows users to adjust the red, green, and blue color components of an image by specified integer amounts. This shifting can be used for various purposes, such as correcting color casts, subtly altering the mood of an image, or creating simple special effects. The shifts are applied uniformly across all pixels in the image. If a color component value, after shifting, falls below 0 or exceeds the image's maximum color value (maxval), it is automatically clipped to 0 or maxval respectively, preventing values from going out of range. <i>ppmshift</i> operates on a single input PPM image, reading from standard input if no file is specified, and always writes the modified image to standard output.


title: CAVEATS
content:
Color component values are clipped to 0 and the image's <i>maxval</i>. This means that if a shift would push a color beyond these limits, the color will be clamped, potentially leading to loss of detail in very dark or very bright areas.<br><i>ppmshift</i> only operates on PPM (Portable Pixmap) format images. For grayscale (PGM) images, use <i>pgmshift</i>.<br>This command performs a simple linear shift. For more complex color adjustments like gamma correction or mixing, other Netpbm tools or more advanced image editors should be used.


title: HISTORY
content:
<i>ppmshift</i> is a component of the comprehensive Netpbm toolkit, which is a collection of graphics programs and a programming library for handling graphical images. Netpbm itself evolved from the PBMPlus package, originally written by Jef Poskanzer in the late 1980s. PBMPlus revolutionized command-line image manipulation by introducing a simple, pipe-friendly format (PBM, PGM, PPM) that allowed chaining multiple image processing tools together. <i>ppmshift</i>, like many other Netpbm tools, adheres to this philosophy, enabling users to perform specific, atomic operations on images, often as part of a larger script or pipeline. Its design reflects the Unix philosophy of doing one thing well.


title: SYNOPSIS
content:
<b>ppmspread</b> [<i>options</i>] [<i>spreader_file</i> [<i>base_file</i>]]<br><br><i>Note:</i> The interpretation of file arguments is flexible. If <i>spreader_file</i> is not specified, it is read from standard input. If <i>base_file</i> is not specified, it is read from standard input. If only one file argument is provided, it is treated as the <i>base_file</i>, and the <i>spreader_file</i> is read from standard input.


title: PARAMETERS
content:
<b><b>-width</b>=<i>W</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target width for the spreader image in pixels. The spreader is scaled to fit this width if provided.<br><br><b><b>-height</b>=<i>H</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the target height for the spreader image in pixels. The spreader is scaled to fit this height if provided.<br><br><b><b>-xscale</b>=<i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the spreader image horizontally by a floating-point factor of <i>N</i>. For example, 0.5 makes it half size, 2.0 makes it double size. This is applied before <b>-width</b>/<b>-height</b>.<br><br><b><b>-yscale</b>=<i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the spreader image vertically by a floating-point factor of <i>N</i>. Applied before <b>-width</b>/<b>-height</b>.<br><br><b><b>-xoffset</b>=<i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a horizontal offset of <i>N</i> pixels to the placement of each spreader instance. Useful for fine-tuning alignment of tiled patterns.<br><br><b><b>-yoffset</b>=<i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a vertical offset of <i>N</i> pixels to the placement of each spreader instance.<br><br><b><b>-random</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Places the spreader images at random locations within the base image instead of a regular grid. The number of random placements depends on the size of the spreader relative to the base image. Cannot be used with <b>-brick</b>.<br><br><b><b>-brick</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Arranges the spreader images in a brick-like pattern, where alternating rows are offset horizontally by half the spreader's width, mimicking brickwork. Cannot be used with <b>-random</b>.<br><br>


title: DESCRIPTION
content:
<b>ppmspread</b> is a utility from the Netpbm image manipulation toolkit designed to tile a smaller "spreader" image repeatedly over a larger "base" image. It allows users to create patterned backgrounds, textures, or complex visual effects by repeating a motif across a canvas. The command offers various options to control the size and scaling of the spreader image, its horizontal and vertical offsets, and the tiling pattern, including standard grid, brick-like arrangements, or random placement. The output is a PPM image, which can then be converted to other formats using other Netpbm tools.


title: CAVEATS
content:
<b>ppmspread</b> is part of the Netpbm suite, meaning it primarily operates on PPM (Portable Pixmap) format. While Netpbm tools generally handle automatic conversion from other image formats (like JPEG, PNG, GIF) via <i>anytopnm</i>, direct input/output is in PPM. The flexible handling of input file arguments (standard input vs. explicit files) requires careful attention to avoid unintended behavior.


title: INPUT/OUTPUT FORMATS
content:
The command primarily works with PPM (Portable Pixmap) images. Input images in other common graphic formats (like JPEG, PNG, GIF, TIFF) are automatically converted to PPM internally via the <i>anytopnm</i> utility provided by Netpbm. The output image produced by <b>ppmspread</b> is always in PPM format, which can then be converted to other desired formats using specific Netpbm tools like <i>pnmtojpeg</i>, <i>pnmtopng</i>, <i>pnmtopgm</i>, etc.


title: USAGE WITH STANDARD INPUT/OUTPUT
content:
The command's flexibility in reading input from files or standard input can sometimes be confusing. Here's a breakdown of common scenarios:<br><ul><li><b>Two file arguments:</b> The first file is the spreader, the second is the base. Example: <code>ppmspread spreader.ppm base.ppm > output.ppm</code></li><li><b>One file argument:</b> The file is treated as the base image, and the spreader image is read from standard input. Example: <code>cat spreader.ppm | ppmspread base.ppm > output.ppm</code></li><li><b>No file arguments:</b> The spreader image is read from standard input first, and then the base image is also read from standard input. This setup is less common for `ppmspread` and usually implies piping concatenated streams, which can be tricky.</li></ul><br>It's generally clearer to specify at least one file argument or explicitly pipe a single input.<br>Example of piping the base image and providing spreader as a file: <br><code>cat base.ppm | ppmspread spreader.ppm > output.ppm</code>


title: HISTORY
content:
<b>ppmspread</b> is a component of the Netpbm project, a comprehensive suite of graphics utilities that originated from the PBMplus package developed by Jef Poskanzer in 1988. Netpbm maintains a long history of providing robust and flexible tools for manipulating portable pixmap, graymap, and bitmap files, adhering to the Unix philosophy of small, specialized programs that can be chained together via pipes for complex operations.


title: SYNOPSIS
content:
<b>ppmtoacad</b> [<i>-color</i> <i>dxf_color_number</i>] [<i>-background</i> <i>dxf_color_number</i>] [<i>-dxftype</i> {<i>SOLID</i>|<i>TRACE</i>}] [<i>-scale</i> <i>scale_factor</i>] [<i>-blocksize</i> <i>pixels</i>] [<i>-layer</i> <i>layername</i>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input Portable Pixmap (PPM) file to convert. If omitted, <b>ppmtoacad</b> reads from standard input.<br><br><b><i>-color</i> <i>dxf_color_number</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the AutoCAD color number to use for each pixel in the output DXF. If not specified, the default DXF color (usually 0) is used.<br><br><b><i>-background</i> <i>dxf_color_number</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the AutoCAD color number for the background pixels. If this option is not provided, background pixels are simply ignored (not drawn).<br><br><b><i>-dxftype</i> {<i>SOLID</i>|<i>TRACE</i>}</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines the type of DXF entity used to represent each pixel. The default is <i>SOLID</i>, which creates filled rectangles. <i>TRACE</i> can also be used, which creates filled polygons.<br><br><b><i>-scale</i> <i>scale_factor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a scaling factor to the output DXF image. For example, <i>-scale 2.0</i> would make the output twice as large.<br><br><b><i>-blocksize</i> <i>pixels</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the size of square blocks of pixels to combine into a single DXF entity. This can reduce the output file size and complexity but may result in a loss of detail. For example, <i>-blocksize 2</i> would treat every 2x2 pixel area as one unit.<br><br><b><i>-layer</i> <i>layername</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Assigns all generated DXF entities to a specified AutoCAD layer. The default layer is '0'.<br><br>


title: DESCRIPTION
content:
The <b>ppmtoacad</b> command is a utility from the Netpbm image manipulation toolkit. It converts a Portable Pixmap (PPM) image file into an AutoCAD DXF (Drawing Exchange Format) file. Each pixel in the input PPM image is typically represented as a distinct graphical entity, specifically an AutoCAD <i>SOLID</i> entity, in the output DXF file. This makes it useful for translating simple raster graphics, such as logos, floor plans, or pixel art, into a vector format suitable for CAD applications.<br><br>The command reads the PPM image from a specified file or from standard input if no file is given. It then generates the corresponding DXF code on standard output. By default, it converts pixels into solid, filled rectangles with a default color. Options allow for specifying background colors, scaling the output, combining blocks of pixels, and choosing different DXF entity types for representation. It's important to note that while it provides a basic raster-to-vector conversion, it's not a sophisticated vectorization tool and is best suited for images where each pixel's exact representation as a geometric primitive is desired.


title: CAVEATS
content:
The output DXF file can become extremely large and complex for high-resolution PPM images, as each pixel is typically converted into a separate DXF entity. This command is best suited for images with relatively low resolution or simple graphical content, rather than photographic images. The resulting DXF is a basic pixel-level representation and lacks advanced vectorization features like curve fitting or intelligent object recognition.


title: OUTPUT STRUCTURE
content:
By default, <b>ppmtoacad</b> represents each pixel from the input PPM as an AutoCAD <i>SOLID</i> entity. A <i>SOLID</i> entity in DXF is a filled quadrilateral defined by four points. When converting, each pixel's color (or a specified <i>-color</i>) determines the color of its corresponding <i>SOLID</i> entity, and its position in the image determines the entity's coordinates within the DXF drawing space.


title: HISTORY
content:
<b>ppmtoacad</b> is part of the Netpbm project, a long-standing open-source suite of graphics programs primarily used on Unix-like operating systems. Netpbm originated from the Pbmplus package developed by Jef Poskanzer in the late 1980s. Its philosophy centers around simple, pipe-friendly tools that operate on basic image formats (PPM, PGM, PBM). <b>ppmtoacad</b> was developed to bridge the gap between simple pixel-based images and the widely used CAD environment, allowing for basic integration of raster data into DXF drawings.


title: SYNOPSIS
content:
ppmtoapplevol [-name <I>filename</I>] [-volname <I>volume_name</I>] [-notime] [-date <I>month</I> <I>day</I> <I>year</I>] [-time <I>hour</I> <I>minute</I> <I>second</I>] [<I>ppmfile</I>]


title: PARAMETERS
content:
<b>-name <I>filename</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the filename for the volume header within the ProDOS directory. The default is "PICTURE.SHR".<br><br><b>-volname <I>volume_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the volume name for the created ProDOS 8 volume. The default is "MY_VOLUME". This name can be up to 15 characters long.<br><br><b>-notime</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the embedding of time and date stamps into the volume header, which might otherwise reflect the current system time at conversion.<br><br><b>-date <I>month</I> <I>day</I> <I>year</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows manual specification of the date to be embedded in the volume header, overriding the system's current date.<br><br><b>-time <I>hour</I> <I>minute</I> <I>second</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows manual specification of the time to be embedded in the volume header, overriding the system's current time.<br><br><b><I>ppmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input Portable Pixmap (PPM) file to be converted. If omitted, <B>ppmtoapplevol</B> reads the PPM data from standard input.<br><br>


title: DESCRIPTION
content:
<B>ppmtoapplevol</B> is a specialized command within the <I>Netpbm</I> suite, designed to convert a Portable Pixmap (PPM) image into an Apple IIgs ProDOS 8 volume header. This conversion is crucial for creating custom bootable disks or disk images for the Apple IIgs, where a graphical header appears upon boot.<br><br>The command expects a specific input: a PPM file that is exactly 320 pixels wide by 200 pixels high. This resolution matches the Apple IIgs Super Hires (SHR) graphics mode. Furthermore, the input image must be a 16-color image, chosen from the extensive 4096-color palette of the Apple IIgs. <B>ppmtoapplevol</B> intelligently attempts to select the best 16-color palette from the provided image. If the image uses more than 16 colors or if a suitable palette cannot be determined, the conversion will fail.<br><br>The output is raw volume header binary data, intended to be written directly to the beginning of an Apple IIgs disk image, often using tools like <B>dd</B>. This allows for a personalized graphical splash screen to be displayed when the volume is accessed or booted on an Apple IIgs system, making it a unique tool for enthusiasts and retro-computing projects.


title: CAVEATS
content:
This command has strict requirements for the input image:<br><br><b>1. Input Dimensions:</b> The PPM file <B>must</B> be exactly 320 pixels wide by 200 pixels high.<br><br><b>2. Color Palette:</b> The image must be a 16-color image or contain colors that can be closely mapped to 16 colors from the Apple IIgs 4096-color palette. <B>ppmtoapplevol</B> does not perform complex color reduction; it expects the image to be inherently suitable for this conversion.<br><br><b>3. Output Format:</b> The output is a raw binary volume header, not a standalone graphical file. It is typically used with disk imaging tools like <B>dd</B> to be written to the beginning of an Apple IIgs disk image or physical disk.


title: PRODOS 8 VOLUME HEADER
content:
A ProDOS 8 volume header is a special data block at the beginning of an Apple IIgs disk or disk image. It contains metadata about the volume and, in this specific case, can include a Super Hires (SHR) graphical splash screen. This screen is displayed by the Apple IIgs operating system when the volume is mounted or booted, providing a visual identity to the disk.


title: USAGE WITH <B>DD</B>
content:
The binary output of <B>ppmtoapplevol</B> is designed to be written directly to the start of an Apple IIgs disk image (e.g., a .PO or .2MG file). A common usage pattern involves piping the output to the <B>dd</B> command, like: <br><br><I>ppmtoapplevol myimage.ppm &gt; header.bin</I><br><I>dd if=header.bin of=mydisk.2mg bs=512 count=1 conv=notrunc</I><br><br>This ensures the graphical header is placed at the correct offset on the disk image without overwriting existing data if only the header block needs to be updated.


title: HISTORY
content:
<B>ppmtoapplevol</B> is an integral part of the <I>Netpbm</I> graphics toolkit, which has a long and rich history in Unix-like systems, evolving from the original PBMplus package. Its specific function catering to the Apple IIgs underscores Netpbm's broad utility in converting between a vast array of niche and historical image formats. While not a mainstream command, its existence highlights the toolkit's commitment to supporting retro-computing and preserving compatibility with older systems, particularly for tasks like custom disk image creation.


title: PARAMETERS
content:
<b><b>-map</b> <i>string</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the string of characters to use for mapping pixel brightness. The first character in the string corresponds to the darkest pixels, and the last character to the brightest (unless <b>-invert</b> is used).<br><br><b><b>-invert</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inverts the brightness mapping. The first character in the <b>-map</b> string will then correspond to the brightest pixels, and the last to the darkest.<br><br><b><b>-max</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum brightness value (0-255) to map to the brightest character in the <b>-map</b> string. Values above this will also map to the brightest character.<br><br><b><b>-min</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the minimum brightness value (0-255) to map to the darkest character in the <b>-map</b> string. Values below this will also map to the darkest character.<br><br><b><b>-gamma</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies gamma correction to the pixel brightness values before mapping. A value of 1.0 (default) means no correction. Values greater than 1.0 lighten the image, while values less than 1.0 darken it.<br><br><b><b>-bold</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For HTML output (with <b>-html</b>), wraps characters corresponding to pixels brighter than a certain threshold (default 50%) in <b>&lt;b&gt;</b> tags.<br><br><b><b>-italics</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;For HTML output (with <b>-html</b>), wraps characters corresponding to pixels brighter than a certain threshold (default 50%) in <b>&lt;i&gt;</b> tags.<br><br><b><b>-threshold</b> <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Used with <b>-bold</b> or <b>-italics</b>, this specifies the brightness percentage (0-100) above which the corresponding HTML tag will be applied. Default is 50.<br><br><b><b>-html</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the result as an HTML document rather than plain text. This enables the use of <b>-bold</b> and <b>-italics</b> options.<br><br><b><b>-plain</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the result as plain text. This is the default behavior and implicitly disables HTML-specific options.<br><br><b><b>-width</b> <i>cols</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the output image to fit approximately the specified number of character columns.<br><br><b><b>-height</b> <i>rows</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the output image to fit approximately the specified number of character rows.<br><br><b><b>-fontwidth</b> <i>chars</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the pixel width of a character for scaling calculations when using <b>-width</b> or <b>-height</b>. Default is 6.<br><br><b><b>-fontheight</b> <i>lines</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the pixel height of a character for scaling calculations when using <b>-width</b> or <b>-height</b>. Default is 10.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints diagnostic information to standard error, which can be useful for debugging.<br><br>


title: DESCRIPTION
content:
The <b>ppmtoarbtxt</b> command converts a <I>Netpbm PPM (Portable Pixmap)</I> image into a text-based representation. It calculates the brightness of each pixel and maps it to a character from a user-defined string specified with the <b>-map</b> option. Darker pixels typically map to characters at the beginning of the string, and brighter pixels map to characters towards the end. This utility is versatile for creating custom ASCII art, generating text-based previews, or producing HTML-formatted text images.


title: CAVEATS
content:
The visual quality of the text output is highly dependent on the input image's resolution, the chosen character map, and the font used for display. It is primarily designed for generating character-based representations or low-resolution ASCII art, not for high-fidelity image reproduction. The output characters will generally be much coarser than the original pixels.


title: BRIGHTNESS CALCULATION AND MAPPING
content:
The command first converts each pixel's RGB color value into a single brightness (luminosity) value. This value is then normalized to a range. The normalized brightness serves as an index into the character string provided by the <b>-map</b> option. For example, if you provide <b>-map " .:-=+*#%@"</b>, the darkest pixels will be mapped to a space (' ') or a period ('.'), while the brightest pixels will be mapped to a hash ('#') or an at-sign ('@'), creating a grayscale effect using characters.


title: HISTORY
content:
<b>ppmtoarbtxt</b> is a utility within the comprehensive <I>Netpbm</I> toolkit, a long-standing collection of graphics manipulation programs for Unix-like operating systems. Netpbm, originating from the early days of Unix, focuses on small, composable tools that can be chained together. <b>ppmtoarbtxt</b> specifically addresses the need to convert pixel-based images into human-readable text forms, a common practice for low-bandwidth display or artistic ASCII art generation.


title: SYNOPSIS
content:
<b>ppmtoascii</b> [<b>-chars</b> <i>characters</i>] [<b>-invert</b>] [<b>-maxwidth</b> <i>width</i>] [<b>-maxheight</b> <i>height</i>] [<b>-monochrome</b>] [<b>-verbose</b>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b><b>-chars</b> <i>characters</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the sequence of ASCII characters to use, ordered from darkest to brightest. For example, <I>" .:-=+*#%@"</I>.<br><br><b><b>-invert</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inverts the character mapping, so dark pixels are represented by lighter characters and vice-versa.<br><br><b><b>-maxwidth</b> <i>width</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the output ASCII art to a maximum specified column <I>width</I>.<br><br><b><b>-maxheight</b> <i>height</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the output ASCII art to a maximum specified row <I>height</I>.<br><br><b><b>-monochrome</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses only two characters (space and '#') for black and white representation, ignoring other character set options.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints progress and debugging information to standard error during processing.<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input image file in PPM, PGM, or PBM format. If omitted, <I>ppmtoascii</I> reads from standard input.<br><br>


title: DESCRIPTION
content:
<i>ppmtoascii</i> is a utility from the <I>Netpbm</I> suite that transforms a raster image into text-based ASCII art. It reads images in <B>PPM</B> (Portable Pixmap) format, but can also handle <B>PGM</B> (Portable Graymap) and <B>PBM</B> (Portable Bitmap). The conversion process involves mapping the brightness level of each pixel to a corresponding ASCII character. Typically, a sequence of characters from darkest to brightest (e.g., ' ', '.', ':', '@') is used to represent the various shades, effectively rendering the image using text characters.<br><br>This command is particularly useful for viewing images in text-only environments, creating stylized text representations, or for educational purposes demonstrating image processing concepts. Users can customize the character set used for the conversion and scale the output dimensions to fit terminal constraints or specific display needs.


title: CAVEATS
content:
ASCII art inherently has significantly lower resolution and color depth compared to the original image, as it converts all color information into luminance values. The visual quality of the output depends heavily on the terminal font, line spacing, and the chosen character set. Scaling operations can sometimes distort the aspect ratio if not applied carefully, especially when only one dimension (<I>maxwidth</I> or <I>maxheight</I>) is specified.


title: INPUT AND PIPING
content:
While named <I>ppmtoascii</I>, it can directly process <B>PGM</B> and <B>PBM</B> files in addition to <B>PPM</B>. For other image formats (like JPEG, PNG, GIF), they must first be converted to a <I>Netpbm</I> format using specialized tools such as <I>jpegtopnm</I>, <I>pngtopnm</I>, or <I>anytopnm</I>, and then piped as input. For example: <I><code>jpegtopnm image.jpg | ppmtoascii</code></I>.


title: OUTPUT DESTINATION
content:
By default, <I>ppmtoascii</I> sends its ASCII art output to standard output (<B>stdout</B>). This makes it straightforward to redirect the output to a file (e.g., <I><code>ppmtoascii image.ppm > image.txt</code></I>), or to pipe it to another command for further processing or viewing (e.g., <I><code>ppmtoascii image.ppm | less</code></I> or <I><code>ppmtoascii image.ppm | lp</code></I>).


title: HISTORY
content:
<I>ppmtoascii</I> is a core utility within the <I>Netpbm</I> project, which originated from Jef Poskanzer's Portable Bitmap (PBM) tools in the late 1980s. The <I>Netpbm</I> toolkit is renowned for its modular design, allowing simple utilities to be chained together using Unix pipes. <I>ppmtoascii</I> exemplifies this philosophy, focusing on the singular task of converting images to ASCII art, making it a reliable and widely adopted tool for text-based image representation over decades.


title: PARAMETERS
content:
<b><b>-b</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs a 1-bit per pixel (monochrome) BMP image.<br><br><b><b>-1</b>, <b>-2</b>, <b>-4</b>, <b>-8</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an indexed color BMP output with 1, 2, 4, or 8 bits per pixel respectively. The color palette will be generated or specified by <b>-map</b>.<br><br><b><b>-24</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs a 24-bit per pixel (true color) BMP image without an alpha channel.<br><br><b><b>-32</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs a 32-bit per pixel BMP image. By default, this implies <b>-alpha</b> unless explicitly denied.<br><br><b><b>-alpha</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a 32-bit BMP with an alpha channel. This option is only relevant when using <b>-32</b>.<br><br><b><b>-map</b> <i>colormapfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the specified PPM file as the color map for indexed color output (e.g., with <b>-8</b>). The input PPM's maxval must match the colormap file's maxval.<br><br><b><b>-clump</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a special quantization method that clumps similar colors together before mapping to a reduced color palette.<br><br><b><b>-force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output of BMP types that might not be fully compliant with standard BMP specifications or may cause issues with some readers. Use with caution.<br><br><b><b>-noforce</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The default behavior, which prevents the output of potentially non-compliant BMP files.<br><br><b><b>-colorcount</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum number of colors to use for indexed color images. The default is 256. Valid for 1, 2, 4, and 8-bit output modes.<br><br><b><b>-rowbytes</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pads each row of the BMP image to a total of <i>N</i> bytes. This is primarily useful for debugging specific BMP reader implementations.<br><br><b><b>-compression</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the compression type for the output BMP. Supported values include:<br><i>0</i>: BI_RGB (no compression, default for non-indexed)<br><i>1</i>: BI_RLE8 (8-bit Run-Length Encoding)<br><i>2</i>: BI_RLE4 (4-bit Run-Length Encoding)<br><i>3</i>: BI_BITFIELDS (custom masks, typically used with <b>-32</b>)<br><i>4</i>: BI_JPEG (JPEG compression embedding)<br><i>5</i>: BI_PNG (PNG compression embedding)<br>Note that not all combinations of bit depth and compression are valid or fully supported.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints informative messages about the conversion process to standard error.<br><br><b><b>-debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints detailed debugging information during the conversion process.<br><br>


title: DESCRIPTION
content:
The <b>ppmtobmp</b> command is a utility from the Netpbm image processing toolkit. It reads a Portable Pixmap (PPM) image from standard input (or a specified file) and converts it into a Windows Bitmap (BMP) file, outputting to standard output. It supports various BMP bit depths (1, 2, 4, 8, 24, 32 bits per pixel) and can apply different compression methods. This tool is essential for converting between Netpbm's flexible formats and the widely used BMP format, often required for compatibility with Windows applications.


title: CAVEATS
content:
Older versions of <b>ppmtobmp</b> only supported BI_RGB (uncompressed) output. BMP images with alpha channels (created with <b>-alpha</b> and <b>-32</b>) are considered non-standard and may not be supported by all image viewers or applications. Run-Length Encoding (RLE) compression in BMP is often inefficient and has limitations on the image content it can effectively compress. Embedded JPEG or PNG compression (via <b>-compression 4</b> or <b>5</b>) is specific to certain BMP versions and may not be universally compatible.


title: INPUT/OUTPUT
content:
The command reads a PPM image from standard input if no <i>ppmfile</i> argument is provided. The resulting BMP image is written to standard output. This design allows for easy piping with other Netpbm commands.


title: BIT DEPTH AND COLOR HANDLING
content:
<b>ppmtobmp</b> automatically quantizes colors when converting to indexed color formats (1, 2, 4, or 8-bit). For 24-bit and 32-bit output, it attempts to preserve full color information. The <b>-map</b> option allows precise control over the color palette for indexed output, while <b>-colorcount</b> limits the number of colors in the palette.


title: HISTORY
content:
The <b>ppmtobmp</b> command is part of the Netpbm project, a long-standing and widely used toolkit for graphic file format conversion and manipulation. Netpbm originated from the Pbmplus package developed in the late 1980s by Jef Poskanzer. Over the decades, it has evolved into a robust collection of tools, including <b>ppmtobmp</b>, which was developed to facilitate interoperability between the flexible Netpbm formats and the prevalent Windows Bitmap standard, continually adapting to new BMP features like alpha channels and embedded compression.


title: PARAMETERS
content:
<b>-frames N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the number of frames (<I>N</I>) to convert from the input. If omitted, defaults to 1 frame. The input must be a stream of <I>N</I> <I>PPM</I> images when converting multiple frames.<br><br><b>-rate R</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the frame rate (<I>R</I>) in frames per second into the output metadata. This does not affect the actual playback speed but informs the viewing program. Defaults to 25 frames per second.<br><br><b>ppmfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input <I>PPM</I> image file. If not specified, <I>ppmtoeyuv</I> reads <I>PPM</I> data from standard input (stdin). When converting multiple frames with <I>-frames</I>, this should be a stream of <I>PPM</I> images.<br><br>


title: DESCRIPTION
content:
The <I>ppmtoeyuv</I> command is a utility from the <I>Netpbm</I> package, designed for converting <I>PPM</I> (Portable PixMap) image files into the <I>EyeYUV</I> video format. <I>PPM</I> is a simple, uncompressed image format commonly used within the <I>Netpbm</I> suite for various image manipulations. <I>EyeYUV</I> is a specific YUV color space format, particularly suited for video applications, animations, and specialized hardware like some video players (e.g., XANIM).<br><br>The YUV color model separates the luma (brightness) component (Y) from the two chrominance (color) components (U and V). This separation is beneficial for video compression and transmission. <I>ppmtoeyuv</I> specifically outputs 8-bit YUV 4:2:2 data, which means for every two horizontal luma samples, there is one corresponding U and one V chrominance sample. While it can convert a single <I>PPM</I> image, its design and primary use case often involve converting streams of <I>PPM</I> images into a multi-frame <I>EyeYUV</I> animation, providing options to control the number of frames and the embedded frame rate metadata.


title: CAVEATS
content:
The output of <I>ppmtoeyuv</I> is raw <I>EyeYUV</I> 4:2:2 data, not encapsulated in a common video container format like AVI or MP4. Therefore, it typically needs to be piped into another program or understood by specialized players that natively support the <I>EyeYUV</I> format. The <I>-rate</I> option only embeds metadata; it doesn't control the actual playback rate, which is determined by the player.


title: OUTPUT FORMAT DETAILS
content:
The <I>EyeYUV</I> output format is 8-bit YUV 4:2:2. This means that for every two horizontal luma (Y) samples, there is one chrominance U sample and one chrominance V sample. The U and V components are subsampled horizontally. This format is commonly used in digital video applications where bandwidth efficiency is important, as the human eye is less sensitive to chrominance detail than to luminance detail.


title: ANIMATION SUPPORT
content:
While <I>ppmtoeyuv</I> can convert a single <I>PPM</I> image, it is particularly useful for converting animation sequences. By specifying the <I>-frames</I> option, users can concatenate multiple <I>PPM</I> images (provided as a stream, e.g., piped from another command) into a single <I>EyeYUV</I> output file representing an animation.


title: HISTORY
content:
The <I>ppmtoeyuv</I> command is part of the extensive <I>Netpbm</I> image manipulation toolkit, which has a long history tracing back to the <I>pbmplus</I> package developed in the late 1980s. <I>ppmtoeyuv</I> itself was originally authored and copyrighted in 1990 by Ugo Paci (<I>ugop@csr.unibo.it</I>), indicating its early inclusion into the suite to address specific needs for converting image sequences into a format suitable for animation and video processing tools prevalent at that time, such as <I>XANIM</I>.


title: PARAMETERS
content:
<b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays informative messages about the conversion process, including the progress and details of the generated HDF file.<br><br><b><b>-size=columns,rows</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the dimensions (width and height) of the image within the HDF file. If this option is omitted, the HDF file will not contain a definition for the image dimensions, which might cause issues for some HDF readers expecting dimension metadata. It does not resize the input PPM image itself but adds metadata to the HDF output.<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PPM image file. If omitted, <b>ppmtoicr</b> reads the PPM image data from standard input.<br><br>


title: DESCRIPTION
content:
<b>ppmtoicr</b> is a specialized command-line utility from the Netpbm suite of graphics tools. Its primary function is to convert a Portable Pixmap (PPM) image into an NCSA Hierarchical Data Format (HDF) raster image, specifically utilizing the Image and Contour Reference (ICR) model within HDF. This tool is often used in scientific and visualization contexts where HDF is a common data storage format for complex datasets. The input is expected to be a standard PPM image, which can be provided via standard input or as a file argument. The output is an HDF file containing the 24-bit RGB image data. It facilitates interoperability between Netpbm's simple image formats and the more complex, structured HDF format used for large datasets.


title: CAVEATS
content:
<b>ppmtoicr</b> specifically creates a 24-bit RGB raster image within the HDF file. It does not support alpha channels (transparency) or other advanced image features. The NCSA HDF format itself can be complex, and the resulting file might require specific HDF libraries or viewers for proper interpretation. The <i>-size</i> option is crucial for adding dimension metadata to the HDF structure, and its omission can lead to HDF files lacking essential information about the image dimensions, making them unreadable by some applications.


title: STANDARD INPUT/OUTPUT
content:
Like most Netpbm tools, <b>ppmtoicr</b> is designed to work seamlessly with standard input and standard output. This allows it to be used effectively in shell pipelines, chaining conversions with other commands. For example, <i>cat image.ppm | ppmtoicr > image.hdf</i>.


title: HISTORY
content:
Part of the extensive Netpbm suite, <b>ppmtoicr</b> dates back to the earlier days of scientific data visualization where the NCSA HDF format was commonly used for sharing complex datasets, including raster images. Its development aligns with the Netpbm project's goal of providing a comprehensive set of tools for converting between various image formats, enabling interoperability across different systems and applications.


title: SYNOPSIS
content:
<b>ppmtoilbm</b> [<i>-24</i>] [<i>-maxcolors N</i>] [<i>-map N</i>] [<i>-ham</i>] [<i>-ehb</i>] [<i>-halfbrite</i>] [<i>-packed</i>] [<i>-s-superhires</i>] [<i>-l-interlaced</i>] [<i>-pal palette_file</i>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b>-24</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces 24-bit output. This is typically used for HAM8 images where each pixel effectively encodes a 24-bit color, though limited by HAM constraints.<br><br><b>-maxcolors N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the maximum number of colors to include in the output colormap for paletted modes. The tool will quantize the image to this number of colors if needed.<br><br><b>-map N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the exact number of bits per pixel (N) for a colormapped image. For example, -map 4 for 16 colors (AGA) or -map 5 for EHB/HAM6. Useful for precise control over color depth.<br><br><b>-ham</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Produces an Amiga Hold-And-Modify (HAM) image. HAM modes allow more colors than the palette size by modifying previous pixel colors. Typically used for HAM6 or HAM8.<br><br><b>-ehb</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Produces an Amiga Extra HalfBrite (EHB) image. In EHB mode, the first 32 colors of the palette have a 'half-bright' version automatically available, effectively providing 64 colors from a 32-entry palette.<br><br><b>-halfbrite</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Alias for -ehb. Produces an Amiga Extra HalfBrite (EHB) image.<br><br><b>-packed</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs packed bitmap data instead of standard interleaved planar data. This can sometimes result in smaller files or be required by specific Amiga software.<br><br><b>-s-superhires</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Amiga SuperHiRes display mode (768x240 or 768x480 interlaced). Modifies the display parameters in the ILBM header.<br><br><b>-l-interlaced</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Amiga interlaced display mode, effectively doubling the vertical resolution (e.g., 320x400 instead of 320x200). Modifies the ILBM header.<br><br><b>-pal palette_file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the specified palette from 'palette_file' instead of generating one. The palette file should be in a Netpbm format (e.g., PPM or PGM header followed by colors).<br><br><b>ppmfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input Portable PixMap (PPM) image file. If not specified, <i>ppmtoilbm</i> reads from standard input.<br><br>


title: DESCRIPTION
content:
The <i>ppmtoilbm</i> command converts a Portable PixMap (PPM) image, a standard Netpbm format, into an Amiga InterLeaved BitMap (ILBM) image. ILBM is a chunk-based file format, commonly used on Amiga computers for storing graphic data, including static images and animations (ANIM).<br><br>This utility is crucial for adapting modern or general-purpose images for use on Amiga systems, which have specific display hardware characteristics. <i>ppmtoilbm</i> handles various Amiga display modes, including standard paletted modes (1-8 bits per pixel), Extra HalfBrite (EHB), and Hold-And-Modify (HAM) modes. It intelligently reduces the color depth or applies HAM/EHB algorithms if the input PPM image has more colors than the target Amiga mode supports.<br><br>It can automatically generate a suitable palette or accept a pre-defined palette. The output is typically a static ILBM image. Its primary use case is for retrocomputing, game development for Amiga, or archival purposes where images need to be in a native Amiga format.


title: CAVEATS
content:
<i>ppmtoilbm</i> is designed for Amiga-specific image formats, which have inherent limitations compared to modern true-color images. Color reduction and mode selection (like HAM or EHB) can lead to color banding or dithered output, especially when converting images with a wide color gamut. The command does not handle alpha channels; if the input PPM is derived from a PAM file with transparency, the alpha information will be lost. Output dimensions are determined by the input PPM unless explicitly overridden by other Netpbm tools like <i>pamscale</i> before piping to <i>ppmtoilbm</i>.


title: AMIGA DISPLAY MODES
content:
The Amiga platform supports various display modes with different resolutions and color depths. <i>ppmtoilbm</i> generates ILBM files compatible with these modes, which typically include OCS/ECS (Original Chip Set/Enhanced Chip Set) modes like LoRes (320x200/256) and HiRes (640x200/256), often with up to 32 or 64 colors (with EHB). AGA (Advanced Graphics Architecture) Amigas support higher resolutions and more colors (up to 256 paletted, or HAM8 for 262,144 colors).


title: PALETTE HANDLING
content:
When converting an image to a paletted Amiga mode, <i>ppmtoilbm</i> attempts to find the best possible palette. If the input image has more colors than the target mode's palette size, it quantizes the colors. Users can provide a specific palette file using the <i>-pal</i> option, which is useful for ensuring color consistency across multiple images or adhering to specific game/application palette requirements.


title: HISTORY
content:
The <i>ppmtoilbm</i> command is a component of the comprehensive <i>Netpbm</i> image manipulation toolkit. Netpbm's origins trace back to the early 1990s, evolving from Jef Poskanzer's Pbmplus utilities. The suite was developed to provide a standardized set of tools for converting and manipulating various bitmap image formats across different Unix-like systems. Given the Amiga's prominence in graphics and multimedia during that era, incorporating support for its native ILBM format was a logical and necessary addition to ensure interoperability and ease of image transfer between PCs/Unix workstations and Amiga systems. Its development reflects the need for cross-platform graphics conversion in the pre-web era.


title: PARAMETERS
content:
<b>-quality <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the JPEG compression quality, where <i>N</i> is an integer from 0 (lowest quality, smallest file) to 100 (highest quality, largest file). The default is usually 75.<br><br><b>-grayscale</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Converts the input image to grayscale before JPEG encoding, even if the input is a color PPM file. The output JPEG will be grayscale.<br><br><b>-optimize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs entropy coding optimization (optimizes Huffman tables). This typically results in a slightly smaller JPEG file size but requires more processing time during compression.<br><br><b>-progressive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a progressive JPEG file. Progressive JPEGs display a low-resolution version of the image first and gradually improve quality as more data is loaded, which is useful for web display.<br><br><b>-comment "<i>text</i>"</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a comment string to the JPEG header. The comment must be enclosed in quotes.<br><br><b>-density <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the horizontal and vertical density (in DPI) to <i>N</i> in the JPEG header. This information is used by some display programs for scaling.<br><br><b>-icc <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Embeds the International Color Consortium (ICC) color profile from <i>FILE</i> into the JPEG header. This helps maintain color accuracy across different devices.<br><br><b>-strict</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treats all warnings as fatal errors. The command will exit immediately if any warning occurs during processing.<br><br><b>-smooth <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a smoothing filter to the input image before compression. <i>N</i> is a value from 1 to 100, where higher values indicate more smoothing.<br><br><b>-sample <i>HxV</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls chrominance subsampling. <i>H</i> and <i>V</i> specify the horizontal and vertical sampling factors, e.g., 2x1, 1x1. Common options are 2x2 (standard, 4:2:0) or 1x1 (no subsampling, larger file).<br><br><b>-restart <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inserts restart markers into the JPEG stream every <i>N</i> Minimum Coded Units (MCUs). This can help with error recovery in corrupted files.<br><br><b>-arithmetic</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses arithmetic coding instead of Huffman coding. While it can produce slightly smaller files, arithmetic coding is less widely supported by JPEG decoders and patents may apply.<br><br><b>-baseline</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the output JPEG is a baseline JPEG, which is the most widely compatible JPEG format.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints detailed information about the compression process to standard error.<br><br><b>-qtable <i>FILE</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses custom quantization tables defined in <i>FILE</i>. This allows for very specific control over compression.<br><br><b>-quant-table <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses one of the predefined quantization tables (e.g., 0 for default, 1 for less aggressive, 2 for more aggressive, etc.).<br><br>


title: DESCRIPTION
content:
The <b>ppmtojpeg</b> command, a utility from the Netpbm toolkit, is designed to convert images in the Netpbm formats – Portable Pixmap (PPM), Portable Graymap (PGM), or Portable Bitmap (PBM) – into the widely used JPEG image format.<br><br>It functions by reading image data from a specified input file or, by default, from standard input. The converted JPEG data is then written to standard output or a specified output file. This versatile tool offers extensive control over the JPEG compression process, allowing users to adjust parameters such as compression quality, progressive encoding, color handling, and more. It is particularly valuable for scripting image conversion tasks within Linux and Unix-like environments.


title: CAVEATS
content:
Using the <b>-arithmetic</b> option may result in smaller files but can lead to compatibility issues as not all JPEG decoders support arithmetic coding. For maximum compatibility, ensure the <b>-baseline</b> option is implicitly or explicitly used. Choosing the optimal <b>-quality</b> setting often requires experimentation to balance file size and visual fidelity.


title: INPUT/OUTPUT BEHAVIOR
content:
By default, <b>ppmtojpeg</b> reads image data from standard input (stdin). If an input <i>netpbmfile</i> is provided as an argument, it reads from that file instead. The resulting JPEG data is written to standard output (stdout) by default, which can be redirected to a file using shell redirection (e.g., <code>ppmtojpeg input.ppm &gt; output.jpg</code>).


title: JPEG COMPRESSION DETAILS
content:
The command offers fine-grained control over JPEG compression parameters. The <b>-quality</b> option is the most frequently used, allowing a straightforward trade-off between file size and visual fidelity; higher quality values retain more detail but result in larger files. Other options like <b>-optimize</b>, <b>-progressive</b>, and <b>-sample</b> allow for further optimization and the creation of specific JPEG features tailored to different use cases, such as web delivery or archival.


title: HISTORY
content:
The <b>ppmtojpeg</b> utility is an integral part of the Netpbm image manipulation toolkit, which traces its origins back to the Pbmplus package developed in the late 1980s. Netpbm serves as a foundational suite of tools for various image conversions and manipulations in Unix-like systems. Specifically, <b>ppmtojpeg</b> leverages the widely used <i>libjpeg</i> library for its JPEG encoding capabilities, providing robust and industry-standard compression. Its continuous development is intertwined with the evolution of the Netpbm project, ensuring its functionality and compatibility with modern image processing requirements and standards.


title: SYNOPSIS
content:
`<b>ppmtoleaf</b> [-width <i>width</i>] [-height <i>height</i>] [-threshold | -diffusion | -clusters | -dots] [-gamma <i>gamma</i>] [-x <i>x</i>] [-y <i>y</i>] [-yoffset <i>yoffset</i>] [-yincr <i>yincr</i>] [-reverse] [<i>ppmfile</i>]`


title: PARAMETERS
content:
<b>-width <i>width</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired output width in pixels. If omitted, the width is inherited from the input image.<br><br><b>-height <i>height</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired output height in pixels. If omitted, the height is inherited from the input image.<br><br><b>-threshold</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a simple thresholding algorithm for halftoning, converting pixels directly to black or white based on a cutoff value.<br><br><b>-diffusion</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Employs an error diffusion halftoning algorithm (e.g., Floyd-Steinberg), which spreads quantization errors to neighboring pixels, often resulting in a more uniform appearance.<br><br><b>-clusters</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a clustered-dot halftoning method, where dots are grouped together to create darker shades. This is common for traditional printing.<br><br><b>-dots</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a dispersed-dot halftoning method, distributing dots more evenly across the image to simulate shades, which can appear finer but might be more sensitive to printing errors.<br><br><b>-gamma <i>gamma</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a gamma correction factor to the image before halftoning, adjusting the tonal curve to compensate for display or printing characteristics.<br><br><b>-x <i>x</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the starting X coordinate for the output image within the Leaf file's internal coordinate system.<br><br><b>-y <i>y</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the starting Y coordinate for the output image within the Leaf file's internal coordinate system.<br><br><b>-yoffset <i>yoffset</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a vertical offset for interleaved output, useful when generating multiple strips of an image.<br><br><b>-yincr <i>yincr</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the vertical increment for interleaved output, used in conjunction with <i>-yoffset</i> for multi-strip image generation.<br><br><b>-reverse</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inverts the monochrome output image (black becomes white and vice-versa).<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input `<b>Portable Pixmap</b>` (`<b>PPM</b>`) image file. If not specified, `<b>ppmtoleaf</b>` reads `<b>PPM</b>` data from standard input (stdin).<br><br>


title: DESCRIPTION
content:
`<b>ppmtoleaf</b>` is a Netpbm program that reads a `<b>Portable Pixmap</b>` (`<b>PPM</b>`) image as input and produces a `<b>Leaf Technologies</b>` (`<b>Leaf</b>`) image as output. The `<b>Leaf</b>` format was originally developed by Leaf Technologies, which was later acquired by Mitsubishi Electric Research Labs (MERL), for use in their high-quality digital halftone printing systems. This command is particularly useful for workflows that require generating images compatible with `<b>Leaf</b>`'s proprietary imaging hardware or software. <br><br>It handles the pixel data conversion, ensuring the output is correctly structured for the `<b>Leaf</b>` format. As the `<b>Leaf</b>` format is often a 1-bit monochrome format, `<b>ppmtoleaf</b>` typically performs a halftoning or dithering process on the input `<b>PPM</b>` to simulate shades of gray or color using varying dot patterns. It provides several algorithms for this conversion, allowing users to choose the best method for their specific printing or display requirements. While `<b>Leaf</b>` is a specialized format, `<b>ppmtoleaf</b>` serves as a crucial bridge for integrating standard Netpbm image processing into such specific systems. It's part of a larger suite of Netpbm utilities designed to convert between various image formats, promoting interoperability within diverse imaging pipelines.


title: CAVEATS
content:
The `<b>Leaf</b>` format is a specialized, proprietary image format primarily associated with older high-end printing systems by Leaf Technologies and Mitsubishi Electric Research Labs (MERL). It is not a broadly supported or commonly used image format in general modern image processing workflows.<br><br>The halftoning options (<i>-threshold</i>, <i>-diffusion</i>, <i>-clusters</i>, <i>-dots</i>) are mutually exclusive; only one can be chosen per invocation.<br><br>Input must be a valid `<b>Portable Pixmap</b>` (`<b>PPM</b>`) file. `<b>ppmtoleaf</b>` does not convert other image formats directly; use other Netpbm tools to convert to `<b>PPM</b>` first if necessary.


title: HALFTONING PROCESS
content:
When converting a full-color or grayscale `<b>PPM</b>` to a 1-bit `<b>Leaf</b>` image, <i><b>ppmtoleaf</b></i> employs halftoning. This process simulates continuous tones by varying the density and pattern of binary dots. The choice of halftoning algorithm (e.g., error diffusion, clustered dots) significantly impacts the visual quality and detail preservation of the monochrome output, especially for high-resolution printing.


title: LEAF FORMAT USAGE
content:
The `<b>Leaf</b>` format is typically a raster image format often used for high-resolution monochrome output. It was designed for specific professional imaging devices, particularly digital proofing and computer-to-plate systems. Its usage is niche and specific to workflows involving Leaf Technologies or MERL hardware and software. For general image viewing or editing, conversion to more common formats like `<b>PPM</b>` or `<b>PNG</b>` is usually necessary.


title: HISTORY
content:
<i><b>ppmtoleaf</b></i> is a component of the Netpbm project, which traces its roots back to Jef Poskanzer's Pbmplus toolkit, initially developed in the late 1980s. Netpbm evolved into a comprehensive, open-source suite for graphics file format conversions and image manipulation. This command specifically extended Netpbm's capabilities to support the proprietary `<b>Leaf Technologies</b>` image format, facilitating interoperability between standard image formats and specialized printing systems prevalent at the time.


title: SYNOPSIS
content:
<b>ppmtolj</b> [<i>-resolution</i> <I>resolution</I>] [<i>-compress</i> <I>method</I>] [<i>-nodither</i>] [<i>-gamma</i> <I>gamma_factor</I>] [<i>-magnify</i> <I>magnification_factor</I>] [<i>-xoff</i> <I>x_offset</I>] [<i>-yoff</i> <I>y_offset</I>] [<i>-landscape</i> | <i>-portrait</i>] [<i>-formfeed</i> | <i>-noformfeed</i>] [<i>-monochrome</i> | <i>-color</i>] [<i>-verbose</i>] [<i>-&lt;number&gt;</i>] [<i>-&lt;number&gt;x&lt;number&gt;</i>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b><i>-resolution</i> <i>resolution</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output resolution in dots per inch (DPI), e.g., <b>75</b>, <b>150</b>, <b>300</b>, <b>600</b>. Can also be specified as <i>Width</i>x<i>Height</i>, e.g., <b>600x300</b>. The default is typically <b>300</b> DPI.<br><br><b><i>-compress</i> <i>method</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the compression method for the PCL output. <b>0</b> for no compression, <b>1</b> for run-length compression, and <b>2</b> for TIFF compression (the default and usually most efficient).<br><br><b><i>-nodither</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables dithering. When converting a color PPM to a monochrome PCL output (or for printers that don't support many colors), this option will map colors directly without using dither patterns, potentially reducing image quality but also processing time.<br><br><b><i>-gamma</i> <i>gamma_factor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a gamma correction to the image. A value greater than <b>1.0</b> lightens the image, while a value less than <b>1.0</b> darkens it.<br><br><b><i>-magnify</i> <i>magnification_factor</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image by the specified factor. For example, <b>-magnify 2</b> would double the image size.<br><br><b><i>-xoff</i> <i>x_offset</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the horizontal offset of the image on the page in pixels from the left edge.<br><br><b><i>-yoff</i> <i>y_offset</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the vertical offset of the image on the page in pixels from the top edge.<br><br><b><i>-landscape</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the page orientation to landscape mode.<br><br><b><i>-portrait</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the page orientation to portrait mode (the default).<br><br><b><i>-formfeed</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a form feed character at the end of the PCL output, useful for ensuring a new page after printing.<br><br><b><i>-noformfeed</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Omits the form feed character at the end of the PCL output.<br><br><b><i>-monochrome</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be monochrome, even if the input PPM is color. This often implies dithering unless <b>-nodither</b> is also used.<br><br><b><i>-color</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be color. This option is only effective if the target printer supports color printing.<br><br><b><i>-verbose</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints informative messages about the conversion process to standard error.<br><br><b><i>-&lt;number&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A shorthand for <b>-resolution</b> <i>&lt;number&gt;</i>, e.g., <b>-300</b> is equivalent to <b>-resolution 300</b>.<br><br><b><i>-&lt;number&gt;x&lt;number&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A shorthand for <b>-resolution</b> <i>&lt;number&gt;x&lt;number&gt;</i>, e.g., <b>-600x300</b> is equivalent to <b>-resolution 600x300</b>.<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PPM image file. If omitted, <b>ppmtolj</b> reads from standard input.<br><br>


title: DESCRIPTION
content:
The <b>ppmtolj</b> command is a utility from the <b>Netpbm</b> package designed to convert a Portable Pixmap (PPM) image into a Printer Control Language (PCL) file suitable for HP LaserJet printers.<br><br>It reads the PPM image from standard input by default, or from a specified file, and outputs the PCL data to standard output. This tool is essential for users needing to print PPM images on LaserJet devices, as it handles various aspects of the conversion process, including dithering for monochrome output, image compression, resolution control, gamma correction, and page positioning. It allows fine-tuning of the output to match specific printer capabilities and desired print quality.


title: CAVEATS
content:
Generated PCL files can be very large, potentially exceeding printer memory limits for complex images or high resolutions.<br>Forcing monochrome output with <b>-monochrome</b> on a color printer might still result in color commands being sent if the printer's default behavior overrides the PCL instructions.


title: HISTORY
content:
<b>ppmtolj</b> is part of the extensive <b>Netpbm</b> graphics toolkit, a collection of command-line utilities for manipulating graphic images. The <b>Netpbm</b> project originated in the early 1990s, with its roots in <b>Pbmplus</b>. This command, like many others in the suite, was developed to provide flexible and scriptable image conversion capabilities across various formats on Unix-like systems. Its design emphasizes interoperability and piping with other <b>Netpbm</b> tools.


title: PARAMETERS
content:
<b>-lss8</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the output image to Labs Systems LSS8 format. This option cannot be used if the input PPM image contains more than 256 colors.<br><br><b>-lss16</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Force the output image to Labs Systems LSS16 format.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Print detailed debugging information to standard error during the conversion process.<br><br><b>-map <I>mapfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the palette specified in the <I>mapfile</I> (which should be a PPM image) as the color map for LSS8 conversion. If this option is not provided, a suitable palette will be automatically generated.<br><br><b><I>ppmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input Portable Pixmap (PPM) image file. If omitted, ppmtolss16 reads the PPM image data from standard input.<br><br>


title: DESCRIPTION
content:
ppmtolss16 is a Netpbm program used for converting Portable Pixmap (PPM) image files into Labs Systems LSS16 or LSS8 format images. These LSS formats are proprietary and typically used with specific Labs Systems equipment. The command reads the PPM image from standard input (or a specified file) and writes the converted LSS image to standard output.<br><br>The program automatically determines whether to use LSS8 (8 bits per pixel) or LSS16 (16 bits per pixel) based on the number of colors in the input PPM image. If the image contains more than 256 colors, it must be converted to LSS16. If it has 256 or fewer colors, it can be LSS8 or LSS16. Users can explicitly force the output format using the <I>-lss8</I> or <I>-lss16</I> options. For LSS8 conversion, an optional palette can be specified using the <I>-map</I> option; otherwise, a palette is automatically generated.


title: CAVEATS
content:
The LSS format is specific to Labs Systems equipment and may not be widely supported by general-purpose image viewers or editors. Ensure your target system or application supports this format. The <I>-lss8</I> option will fail if the input PPM image has more than 256 colors.


title: INPUT/OUTPUT
content:
ppmtolss16 reads input from standard input by default, or from a specified PPM file. It writes the converted LSS16 or LSS8 image to standard output. This design allows for seamless integration with other Netpbm commands through piping or redirection to a file. For example, you can use <I>cat image.ppm | ppmtolss16 > image.lss16</I> or directly <I>ppmtolss16 image.ppm > image.lss16</I>.


title: HISTORY
content:
The ppmtolss16 command was contributed to the Netpbm project by Marshall Space Flight Center, NASA. Its initial public release occurred with Netpbm version 10.3 in January 2002. It has since been maintained as part of the Netpbm suite of image processing utilities, serving specific needs for conversion to the Labs Systems image formats.


title: PARAMETERS
content:
<b>-threshold</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces a simple thresholding method for conversion to monochrome instead of the default Floyd-Steinberg dithering. Pixels are converted to white (1) if their value is greater than or equal to half of the maximum possible pixel value (maxval), and to black (0) otherwise. This method is generally less visually appealing than dithering.<br><br>


title: DESCRIPTION
content:
<b>ppmtomap</b> converts a Portable Pixmap (PPM) image into an X11 bitmap (XBM) format.<br><br>XBM is a monochrome (black and white) image format commonly used in X Window System applications for icons, cursors, and simple graphics. When converting a color or grayscale PPM image, <b>ppmtomap</b> employs a dithering algorithm, specifically Floyd-Steinberg dithering by default, to simulate shades of gray using only black and white pixels. This technique helps to preserve visual detail that would otherwise be lost in a direct binary conversion.<br><br>The command reads the PPM image from standard input by default, or from a specified file, and writes the resulting XBM data to standard output. This design makes it well-suited for use within shell pipelines for image processing tasks.


title: CAVEATS
content:
The output XBM format is strictly monochrome, meaning all color and grayscale information from the original PPM image is lost. While dithering attempts to compensate for this, it cannot perfectly represent the original image's tonality. XBM files are text-based and are primarily intended for small, simple graphics like icons or cursors, not for photographic or complex images due to their inherent limitations and file size for larger resolutions.


title: INPUT/OUTPUT BEHAVIOR
content:
<b>ppmtomap</b> adheres to the standard Unix paradigm of reading from standard input and writing to standard output. This allows it to be seamlessly integrated into complex command pipelines. For instance, you can pipe the output of another Netpbm tool (like <b>jpegtoppm</b>) directly into <b>ppmtomap</b>, and then redirect its output to a file or another command.


title: DITHERING EXPLAINED
content:
By default, <b>ppmtomap</b> uses the Floyd-Steinberg dithering algorithm. Dithering is a technique used to create the illusion of color depth in images with a limited color palette (in this case, just black and white). It achieves this by scattering pixels of available colors in a pattern that fools the eye into perceiving intermediate shades. The alternative, simple thresholding (enabled by the <b>-threshold</b> option), merely converts pixels to black or white based on a midpoint, often resulting in a harsh, blocky image with significant loss of detail compared to dithering.


title: HISTORY
content:
<b>ppmtomap</b> is an integral part of the Netpbm image processing toolkit, which originated from the Pbmplus package developed by Jef Poskanzer in the late 1980s. Netpbm is known for its modular design, where many small utilities perform specific image conversions or manipulations. <b>ppmtomap</b> embodies this philosophy by providing a focused tool for converting the ubiquitous PPM format to the X11 bitmap format, enabling interoperability within the X Window System environment. Its development aligns with the broader history of Unix tools designed for composability and pipeline processing.


title: PARAMETERS
content:
<b>-color</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates 256-color output compatible with Mitsui printers. This is often the default or most common output mode for color printing.<br><br><b>-mono</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Produces 1-bit monochrome (black and white) output. Useful for simpler graphics or when color printing isn't needed or supported.<br><br><b>-rgb</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates full 24-bit RGB color output. This option provides the highest color fidelity, assuming the Mitsui printer supports it.<br><br><b>ppmfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input <I>Portable Pixmap</I> (PPM) image file. If omitted, <code>ppmtomitsu</code> reads image data from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<code>ppmtomitsu</code> is a specialized command-line utility from the <code>Netpbm</code> suite, designed for image format conversion. Its core purpose is to transform a <I>Portable Pixmap</I> (PPM) image file into a specific, proprietary data format that can be directly understood and printed by <I>Mitsui color printers</I>.<br><br>These printers, often specialized or legacy hardware, typically do not accept standard image formats and require a unique, often compressed or device-specific, data stream. <code>ppmtomitsu</code> bridges this gap, translating the generic PPM raster data into the precise byte sequence required by Mitsui devices. It reads a PPM image from standard input by default, or from a specified filename argument, and subsequently writes the Mitsui-compatible output to standard output. This functionality makes <code>ppmtomitsu</code> particularly valuable in workflows that involve automated image processing and direct printing to these niche hardware systems.


title: CAVEATS
content:
<B>Proprietary Format:</B> The output format is specific to Mitsui printers and not a general-purpose image format. It is unlikely to be readable by standard image viewers.<br><B>Legacy Hardware:</B> Mitsui color printers are typically older, specialized hardware. This command is primarily relevant for environments still utilizing such devices.<br><B>Color Depth Limitations:</B> The actual color depth and quality of the output will depend on the capabilities of the specific Mitsui printer model being targeted, even with the <code>-rgb</code> option.


title: OUTPUT DESTINATION
content:
The command writes its converted output to standard output (<B>stdout</B>). Users typically redirect this output to a file or pipe it directly to a printer driver or network connection for printing.


title: HISTORY
content:
<code>ppmtomitsu</code> is a component of the comprehensive <B>Netpbm</B> toolkit, which is a widely used and venerable collection of graphics manipulation tools for Unix-like operating systems.<br><br>The Netpbm project originated from <I>Jef Poskanzer's PBMPlus package</I>, first released in the late 1980s. Over the decades, Netpbm has been maintained and expanded by various developers, evolving into a robust suite for converting, modifying, and creating image files in various formats.<br><br><code>ppmtomitsu</code> specifically addresses a niche need by providing compatibility with Mitsui color printers, reflecting the Netpbm suite's goal of universal image format interoperability.


title: SYNOPSIS
content:
<b>ppmtompeg</b> [<i>options</i>] [<i>image_file_prefix</i> | <b>-</b>] [<i>start_frame</i>] [<i>end_frame</i>]<br>If <i>image_file_prefix</i> is provided, <b>ppmtompeg</b> expects numbered PPM files (e.g., <i>frame0001.ppm</i>, <i>frame0002.ppm</i>). Using <b>-</b> indicates reading PPM frames from standard input.


title: PARAMETERS
content:
<b><b>-f</b> <i>&lt;rate&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the output video frame rate in frames per second (e.g., 25).<br><br><b><b>-s</b> <i>&lt;width&gt;x&lt;height&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output video resolution (e.g., 352x240 for SIF NTSC).<br><br><b><b>-b</b> <i>&lt;bitrate&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the target video bitrate in kilobits per second (kbit/s).<br><br><b><b>-g</b> <i>&lt;gop_size&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Group of Pictures (GOP) size. A GOP defines the interval between I-frames.<br><br><b><b>-q</b> <i>&lt;qscale&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the average quantization scale for video quality (1-31, where 1 is best quality, 31 is lowest).<br><br><b><b>-o</b> <i>&lt;filename&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the output MPEG file name. If omitted, output goes to standard output.<br><br><b><b>-no_b_frames</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the use of B-frames (bi-directionally predicted frames), resulting in larger files but potentially faster encoding/decoding.<br><br><b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a help message with available options.<br><br>


title: DESCRIPTION
content:
The <b>ppmtompeg</b> command is a utility designed to encode a sequence of Portable Pixmap (PPM) image files into an MPEG-1 video stream.<br>It's often used in conjunction with other Netpbm tools, which can convert various image formats into PPM, allowing for flexible input sources. This command reads individual PPM frames, either from numbered files or from standard input (via piping), and combines them into a compressed MPEG video, ideal for creating simple animations, time-lapses, or early web video content.<br>While <b>ppmtompeg</b> provides control over key encoding parameters like frame rate, bitrate, and Group of Pictures (GOP) size, it produces MPEG-1, an older video standard. For modern high-definition video encoding or more advanced features, contemporary tools like FFmpeg are generally preferred. Nonetheless, <b>ppmtompeg</b> remains a classic and functional tool for specific use cases within the Unix/Linux environment, particularly when integrated with script-based image processing workflows.


title: CAVEATS
content:
<b>ppmtompeg</b> is primarily an MPEG-1 encoder, meaning it produces video in an older format not suitable for modern high-definition resolutions or advanced compression needs.<br>It expects input in the PPM (Portable Pixmap) format, which often requires pre-processing with other image conversion utilities.<br>While functional, it has been largely superseded by more comprehensive and feature-rich multimedia tools like FFmpeg for general video encoding tasks.


title: TYPICAL USAGE PATTERN
content:
<b>ppmtompeg</b> is frequently used in a pipeline where image sequences are generated or converted to PPM format and then piped directly to the encoder. For example:<br><b>convert frames*.png ppm:- | ppmtompeg -f 25 -s 352x240 > output.mpg</b><br>or from pre-numbered files:<br><b>ppmtompeg -f 25 -s 352x240 myframe 0001 0100 > output.mpg</b>


title: MPEG-1 STANDARD
content:
MPEG-1 was developed by the Moving Picture Experts Group (MPEG) and standardized in 1993. It's primarily used for video quality roughly equivalent to a VHS tape, common for Video CD (VCD) and early online video. <b>ppmtompeg</b> implements this standard, including I-frames (intra-coded), P-frames (predictive), and B-frames (bi-directional predictive).


title: HISTORY
content:
<b>ppmtompeg</b> emerged as part of early efforts to provide command-line MPEG encoding capabilities on Unix-like systems. It was often distributed as a component of various multimedia utility suites, or as a standalone tool specifically for MPEG-1 encoding from image sequences.<br>Its tight integration with the Netpbm toolkit made it a staple for scripted image-to-video workflows in the pre-FFmpeg era, leveraging Netpbm's extensive image format conversion abilities to feed PPM data into the encoder.<br>While its direct development might have slowed, its functionality is preserved in various distributions.


title: SYNOPSIS
content:
<code>ppmtoneo</code> [<i>options</i>] [<i>ppmfile</i>]<br><br>Options include:<br><b>-alpha</b><br><b>-forcealpha</b><br><b>-icon</b><br><b>-opaque</b><br><b>-color</b><br><b>-noopaque</b><br><b>-bpp</b> <i>bpp</i>


title: PARAMETERS
content:
<b><b>-alpha</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a 2-bit icon with an alpha channel, deriving alpha from the input image's alpha or treating black (0,0,0) as transparent if no alpha is present.<br><br><b><b>-forcealpha</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Similar to <b>-alpha</b>, but forces the output to be a 2-bit icon even if the input appears to be a color image.<br><br><b><b>-icon</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Creates a 2-bit icon using old-fashioned transparency (transparent index), where black (0,0,0) pixels are treated as transparent. Less recommended for modern systems.<br><br><b><b>-opaque</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Produces a 2-bit icon with an alpha channel where all pixels are fully opaque, suitable for 2-bit grayscale images without transparency.<br><br><b><b>-color</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates an 8-bit color icon. Uses the input's alpha channel if available; otherwise, black (0,0,0) is used as the transparent color. This is the default behavior if no 2-bit option is specified.<br><br><b><b>-noopaque</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When generating an 8-bit icon, this option forces the use of black (0,0,0) as the transparent color, even if the input image contains an alpha channel that would normally be used.<br><br><b><b>-bpp</b> <i>bpp</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly sets the bits per pixel for the output icon. <i>bpp</i> must be either 2 or 8. This option is mutually exclusive with other color depth and transparency options (<b>-alpha</b>, <b>-forcealpha</b>, etc.).<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input portable pixmap (PPM) file. If not specified, <b>ppmtoneo</b> reads from standard input.<br><br>


title: DESCRIPTION
content:
<code>ppmtoneo</code> is a Netpbm utility designed to transform portable pixmap (PPM) images into the NeXT icon file format. These icons are typically 48x48 pixels and can be either 2-bit (monochrome with alpha channel) or 8-bit (color). The command reads a PPM image from standard input or a specified file and outputs the NeXT icon data to standard output. While the input PPM can be of any dimension, <code>ppmtoneo</code> automatically scales it to the required 48x48 size for the output icon, though it is often advisable to pre-scale the image using tools like <code>pamscale</code> or <code>pnmscale</code> for better quality. The utility offers various options to control the output's color depth and transparency handling, allowing for creation of icons with alpha channels or traditional transparent color indices.


title: CAVEATS
content:
Input images are automatically scaled to 48x48 pixels for output. For best quality, it is recommended to pre-scale your images using tools like <code>pamscale</code> or <code>pnmscale</code> before passing them to <code>ppmtoneo</code>.<br>The behavior regarding transparency (alpha channel vs. transparent color) depends heavily on the selected options and the presence of an alpha channel in the input PPM. Carefully choose options like <b>-alpha</b>, <b>-color</b>, and <b>-noopaque</b> to achieve desired transparency effects.<br>When generating 8-bit color icons, <code>ppmtoneo</code> quantizes the input image's colors to fit the 256-color palette of the NeXT icon format, which may result in color degradation.


title: INPUT/OUTPUT
content:
<code>ppmtoneo</code> typically reads the input PPM image from standard input and writes the resulting NeXT icon file to standard output. This allows for flexible use in pipelines, such as <code>cat image.ppm | ppmtoneo -color &gt; icon.next</code>.


title: NEXT ICON FORMAT SPECIFICS
content:
NeXT icon files are fixed at 48x48 pixels. They can be 2-bit (monochrome with 2-bit alpha) or 8-bit (color with a palette). The 2-bit alpha channel provides varying levels of transparency (fully transparent to fully opaque).


title: HISTORY
content:
The <code>ppmtoneo</code> command is an integral part of the Netpbm project, a comprehensive suite of graphics file format conversion tools. Netpbm originated from the <code>pbmplus</code> package, created by Jef Poskanzer in the late 1980s. These tools were designed to handle conversions between various image formats, promoting interoperability and ease of scripting. <code>ppmtoneo</code> specifically addresses the need to generate icons for the NeXTstep operating system, which was notable for its innovative GUI and development environment. As NeXTstep evolved into macOS, the NeXT icon format became less prevalent in new development, but <code>ppmtoneo</code> remains useful for legacy conversions or specific niche applications requiring adherence to this format. The command's design reflects the Netpbm philosophy of simple, single-purpose tools that can be piped together to achieve complex tasks.


title: SYNOPSIS
content:
<br><code>ppmtopbm [<i>Netpbm_options</i>] [-floyd | -threshold] [-value <i>value</i>] [-bayer <i>ditherlevel</i>] [-gamma <i>gamma</i>] [-mix] [-not] [<i>ppmfile</i>]</code>


title: PARAMETERS
content:
<b>-floyd</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the <i>Floyd-Steinberg</i> dithering algorithm (default). This distributes quantization errors to neighboring pixels for smoother results.<br><br><b>-threshold</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a simple thresholding method. Pixels brighter than a set value become white, otherwise black. This results in a harsher, less detailed conversion.<br><br><b>-value <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the threshold value when using <b>-threshold</b>. It ranges from 0 to 255 (or MAXVAL of the input). Pixels with brightness greater than <i>value</i> become white.<br><br><b>-bayer <i>ditherlevel</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs <i>Bayer ordered dithering</i>. The <i>ditherlevel</i> can be 0, 1, or 2, controlling the pattern size and detail. This method creates a patterned dot matrix effect.<br><br><b>-gamma <i>gamma</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a gamma correction before conversion. <i>gamma</i> is a floating-point value. Values less than 1 brighten midtones, greater than 1 darken them.<br><br><b>-mix</b><br>&nbsp;&nbsp;&nbsp;&nbsp;When converting from color (PPM), mixes colors according to a perceived brightness formula rather than simply averaging the R, G, B components. This can produce more visually accurate monochrome images.<br><br><b>-not</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inverts the resulting monochrome image. Black pixels become white and vice versa.<br><br>


title: DESCRIPTION
content:
`ppmtopbm` is a fundamental utility within the <i>Netpbm</i> image toolkit. It serves to convert any Netpbm image format — <b>PPM</b> (Portable PixMap, color), <b>PGM</b> (Portable GrayMap, grayscale), or <b>PBM</b> (Portable BitMap, monochrome) — into the 1-bit, black-and-white <b>PBM</b> format. This conversion is particularly useful for applications requiring simple monochrome output, such as printing to black-and-white printers or displaying images on low-bit-depth screens.<br><br>When converting color or grayscale images, `ppmtopbm` employs sophisticated algorithms to approximate the original image with only two colors. The default and generally recommended method is <i>Floyd-Steinberg dithering</i>, which distributes quantization errors to neighboring pixels, resulting in a visually smoother monochrome representation. Alternatively, a simpler <i>thresholding</i> method can be used, where pixels are set to black or white based on whether their brightness exceeds a certain value. The command offers various options to control this conversion process, including specific dithering types, gamma correction, and output inversion, providing flexibility for diverse image processing needs.


title: CAVEATS
content:
<br>Conversion from color (PPM) or grayscale (PGM) to monochrome (PBM) is inherently a <i>lossy</i> process. Significant detail and color information will be lost. While dithering attempts to preserve perceived detail, the output is always a 1-bit image. The default <b>-floyd</b> dithering generally provides the best visual quality for most images.


title: INPUT AND OUTPUT
content:
If <i>ppmfile</i> is not specified, `ppmtopbm` reads its input from standard input. The converted PBM image is always written to standard output. This allows for easy piping with other <i>Netpbm</i> tools or redirecting output to a file, e.g., <code>cat image.ppm | ppmtopbm > image.pbm</code> or <code>ppmtopbm image.ppm > image.pbm</code>.


title: IMAGE MAXVAL
content:
For Netpbm formats, <i>MAXVAL</i> defines the maximum pixel value. For PBM, <i>MAXVAL</i> is always 1 (black or white). When `ppmtopbm` processes PPM or PGM images, it implicitly scales their pixel values (typically 255 for 8-bit images) down to this 0-1 range for the monochrome conversion.


title: HISTORY
content:
<br>`ppmtopbm` is a component of the venerable <i>Netpbm</i> suite of graphics utilities. Netpbm originated in the early days of Unix, evolving from the PBMplus package, and has been a cornerstone for image manipulation in command-line environments for decades. Its design philosophy emphasizes simple, pipeable tools that perform one job well, ensuring stability and widespread adoption across various Unix-like operating systems. `ppmtopbm` exemplifies this approach by providing a dedicated, robust tool for monochrome image conversion.


title: SYNOPSIS
content:
ppmtopcx [-24] [-padded] [-truecolor] [-transparent <<i>color</i>>] [-mono] [-color <<i>numcolors</i>>] [-map <<i>mapfile</i>>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b>-24</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Outputs a 24-bit truecolor PCX, even if not explicitly requested with -truecolor.</I><br><br><b>-padded</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Pads each scan line to an even byte boundary, which can be required by some PCX readers.</I><br><br><b>-truecolor</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Outputs a truecolor PCX image (either 16-bit or 24-bit depending on the input and other options).</I><br><br><b>-transparent <<i>color</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Specifies a transparent color for 8-bit paletted PCX files. The color must be provided as a hex string (e.g., #RRGGBB or #RRGGBBAA).</I><br><br><b>-mono</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Outputs a monochrome (1-bit) PCX image, converting the input PPM to black and white.</I><br><br><b>-color <<i>numcolors</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Reduces the number of colors in the output PCX image to 'numcolors' using quantization. 'numcolors' must be an integer between 2 and 256.</I><br><br><b>-map <<i>mapfile</i>></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>Uses the colormap from the specified 'mapfile' (which should be a PPM file) instead of computing one. This is useful when you need a specific palette for the output.</I><br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<I>The input PPM file. If this argument is omitted, ppmtopcx reads the PPM image from standard input (stdin).</I><br><br>


title: DESCRIPTION
content:
<b>ppmtopcx</b> is a command-line utility from the Netpbm image manipulation toolkit. Its primary function is to convert image files from the Portable Pixmap (PPM) format to the ZSoft PCX format. The PPM format is a simple, raw bitmap format, while PCX is a common image format used by applications like PC Paintbrush. <b>ppmtopcx</b> supports various features during conversion, including truecolor output, 24-bit output, specifying transparency, and monochrome conversion. It can also quantize colors to a specified number or use a custom color map, making it flexible for different PCX requirements. The command reads the PPM image from standard input if no file is specified, and writes the PCX output to standard output. This allows it to be easily integrated into shell pipelines with other Netpbm tools.


title: CAVEATS
content:
When using truecolor output, the resulting PCX file might not be compatible with older PCX viewers that only support paletted images. Transparency is only applicable to 8-bit paletted PCX files, not truecolor formats. The -color option utilizes standard Netpbm quantization, which may not always yield optimal results for all images.


title: INPUT/OUTPUT
content:
The command reads a PPM image from standard input by default, or from the specified <i>ppmfile</i>. The resulting PCX image is written to standard output. This design promotes piping and integration into larger shell scripts, allowing <b>ppmtopcx</b> to be part of complex image processing workflows.


title: COLOR MAPPING CONTROL
content:
For paletted output, <b>ppmtopcx</b> attempts to use an optimized color map. However, options like <i>-color</i> and <i>-map</i> provide fine-grained control over the output palette. This is crucial for achieving desired visual quality, reducing file size, or ensuring compatibility with specific PCX readers that might expect a predefined palette.


title: HISTORY
content:
<b>ppmtopcx</b> is an integral part of the extensive <b>Netpbm</b> package, a collection of graphics utilities that evolved from Jef Poskanzer's <b>Pbmplus</b> toolkit, initially developed in the late 1980s. <b>Netpbm</b> continues to be maintained and developed as a versatile tool for image manipulation. <b>ppmtopcx</b> specifically addresses the conversion to the PCX format, which was a widely used image format on personal computers, particularly in the MS-DOS era.


title: PARAMETERS
content:
<b>--red</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use only the red component of each pixel to determine the grayscale value.<br><br><b>--green</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use only the green component of each pixel to determine the grayscale value.<br><br><b>--blue</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use only the blue component of each pixel to determine the grayscale value.<br><br><b>--average</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Calculate the grayscale value as a simple arithmetic average of the red, green, and blue components (R+G+B)/3.<br><br><b>--lum or --luminance</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Convert to grayscale using a weighted average that approximates human perception of luminance: 0.299*R + 0.587*G + 0.114*B. This is often the default behavior or the most visually accurate choice.<br><br><b>--max</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the maximum value among the red, green, and blue components for each pixel.<br><br><b>--min</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Use the minimum value among the red, green, and blue components for each pixel.<br><br><b>--random</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Randomly pick one of the red, green, or blue components for each pixel.<br><br><b>--weight=<I>R,G,B</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify custom floating-point weights for red, green, and blue components (e.g., <I>--weight=0.2,0.7,0.1</I>). The weights do not need to sum to 1.<br><br><b>--gamma</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply gamma correction to the pixel values before applying the conversion formula. This is often used in conjunction with <I>--lum</I> or <I>--weight</I> for more accurate results, especially if the input image is not gamma-corrected.<br><br><b>--verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Display verbose information about the conversion process to standard error.<br><br>


title: DESCRIPTION
content:
<I>The <B>ppmtopgm</B> command is a specialized utility within the Netpbm suite of graphics tools. It is designed to convert a color Portable Pixmap (PPM) image file into a grayscale Portable Graymap (PGM) image file. This conversion is inherently lossy, as all color information from the original PPM image is discarded, and each pixel's color is transformed into a single grayscale intensity value.<br><br>By default, <B>ppmtopgm</B> reads a PPM image from standard input and writes the resulting PGM image to standard output, making it highly suitable for use in Unix-like shell pipelines. The command offers various methods for calculating the grayscale value, ranging from simply taking one of the color components (red, green, or blue), a simple average of all components, or more perceptually accurate methods like luminance calculation. This flexibility allows users to control how the color information is interpreted and mapped to shades of gray, influencing the final appearance of the grayscale image.</I>


title: CAVEATS
content:
<I>Converting a color image to grayscale is a <B>lossy</B> operation; all original color information is permanently discarded. The choice of conversion method (e.g., average, luminance, single component) significantly impacts the appearance of the resulting grayscale image. Different methods can emphasize or de-emphasize certain colors, potentially leading to different contrasts and details.<br><br>The <B>ppmtopgm</B> command is part of the Netpbm format philosophy, primarily dealing with PPM and PGM image types. It is not a general-purpose image editor and does not support other common image formats directly without prior conversion.</I>


title: DEFAULT BEHAVIOR
content:
If no conversion method option is specified, <B>ppmtopgm</B> typically defaults to the <I>--lum</I> (luminance) method, which provides a perceptually accurate grayscale conversion.


title: INPUT/OUTPUT
content:
By default, <B>ppmtopgm</B> reads the PPM image from standard input (stdin) and writes the resulting PGM image to standard output (stdout). This allows it to be easily integrated into shell pipelines, for example: <I>cat image.ppm | ppmtopgm > image.pgm</I> or <I>some_command_outputting_ppm | ppmtopgm | another_command_reading_pgm</I>. An optional <I>inputfile</I> argument can be provided to read from a specific file instead of stdin.


title: HISTORY
content:
<I>The <B>ppmtopgm</B> command is a long-standing component of the Netpbm graphics toolkit, which originated from the Pbmplus package developed by Jef Poskanzer in the late 1980s. Netpbm was designed as a modular suite of tools for converting, creating, and manipulating image files in simple, text-based formats (PBM, PGM, PPM). <B>ppmtopgm</B> specifically addresses the fundamental need to convert color images to grayscale, a common operation in image processing for various applications, including printing, accessibility, and further analysis. Its design emphasizes simplicity, efficiency, and pipeline compatibility, characteristic of the Unix philosophy.</I>


title: PARAMETERS
content:
<b><i>-gamma val</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a gamma correction to the image. <i>val</i> is a floating-point number representing the gamma value. This can be crucial for ensuring colors appear correctly on Amiga displays, which often have different gamma characteristics than modern displays.<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input Portable Pixmap (PPM) file. If <i>ppmfile</i> is omitted, <i>ppmtopi1</i> reads the PPM data from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<i>ppmtopi1</i> is a command-line utility from the Netpbm suite that converts an image in the Portable Pixmap (PPM) format into an Amiga Deluxe Paint PI1 format file.<br><br>The PI1 format is a specific Amiga graphics file type, typically used by early Amiga software, most notably Deluxe Paint. This tool is useful for preparing images for use on classic Amiga systems or emulators. It handles color quantization by attempting to match the input image's colors to the Amiga's 4096-color palette, selecting the best 32 colors, and then applying Floyd-Steinberg dithering to approximate colors not in the chosen palette. The output PI1 file is fixed at a resolution of 320x200 pixels and uses 32 colors. If the input PPM image is not 320x200, it will be scaled to fit.


title: CAVEATS
content:
The output PI1 file is always 320x200 pixels and uses a 32-color palette. Input images of different resolutions will be scaled to fit. The command performs color quantization and dithering to fit the Amiga's limited palette, which may result in some loss of color fidelity for images with a very wide color range.<br>It does not support the Amiga's hi-res (640x200) modes or extended color modes like EHB/HAM, only the standard 32-color lo-res (320x200) mode.


title: COLOR QUANTIZATION AND DITHERING
content:
<i>ppmtopi1</i> employs an algorithm to select the best 32 colors from the input PPM's palette to match the Amiga's 4096-color RGB space. It then uses Floyd-Steinberg dithering to approximate colors not in the chosen palette, minimizing visual artifacts caused by color reduction.


title: STANDARD OUTPUT
content:
By default, the converted PI1 image is written to standard output. Users typically redirect this output to a file using the '>' operator, e.g., <br><code>ppmtopi1 input.ppm > output.pi1</code>


title: HISTORY
content:
<i>ppmtopi1</i> is part of the extensive Netpbm project, a toolkit for converting and manipulating various graphics formats. The Netpbm project has a long history, evolving from the original Pbmplus tools created by Jef Poskanzer in the late 1980s. The inclusion of tools like <i>ppmtopi1</i> reflects the historical need to bridge various digital graphic formats, including those specific to platforms like the Amiga, for cross-platform compatibility and archiving purposes.


title: SYNOPSIS
content:
<b>ppmtopict</b> [<b>-monochrome</b>] [<b>-verbose</b>] [<b>-alpha</b>] [<b>-force</b>] [<b>-bpp</b> <i>bpp</i>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b><b>-monochrome</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Converts the input PPM image to a 1-bit monochrome PICT file. This is useful for black and white output.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints debugging information and progress messages to standard error during the conversion process.<br><br><b><b>-alpha</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Treats the input as a PAM (Portable Arbitrary Map) with an alpha channel and attempts to produce a PICT with alpha channel information. Note that PICT format does not natively support true alpha channels.<br><br><b><b>-force</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the creation of a PICT file even if the input PPM is too wide for the PICT format's maximum width (typically 65535 pixels). This may result in an unreadable or malformed PICT file.<br><br><b><b>-bpp</b> <i>bpp</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired bits per pixel for the output PICT file. Common values include 1, 2, 4, 8, 16, 24, or 32. The command will attempt to match or approximate this depth.<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PPM image file. If omitted, <b>ppmtopict</b> reads the PPM data from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<b>ppmtopict</b> is a utility from the Netpbm suite of graphics programs. Its primary function is to convert image files from the Portable Pixmap (PPM) format to the Apple PICT format.<br><br>The PPM format is a simple, flexible format for storing color images, widely used within the Netpbm tools. The Apple PICT format, on the other hand, is a graphics file format originally developed by Apple Inc. for its Macintosh operating system, supporting both bitmap and vector graphics.<br><br>This command is particularly useful for users who need to import Netpbm-generated images into Macintosh applications or environments that primarily support the PICT format. It handles color depth conversions and can output monochrome or full-color PICT images depending on the input and specified options. The tool reads a PPM image from standard input if no file is specified, and writes the PICT output to standard output, adhering to the standard Unix filter paradigm.


title: CAVEATS
content:
The PICT format has specific limitations, notably a maximum width of 65535 pixels; using <b>-force</b> beyond this limit can create invalid files. PICT does not natively support true alpha channels, so the <b>-alpha</b> option may produce non-standard PICT files. Due to PICT's older nature, modern systems and applications may have limited or no support for viewing these files, and palette-based PICTs are limited to 256 colors.


title: STANDARD INPUT/OUTPUT
content:
By default, <b>ppmtopict</b> reads its PPM image data from standard input (stdin) and writes the resulting PICT image to standard output (stdout). This design makes it highly suitable for use in shell pipelines, allowing it to be easily chained with other Netpbm commands or Unix utilities for complex image processing workflows.


title: PICT FORMAT SPECIFICS
content:
The PICT format is a complex, proprietary image format from Apple, supporting both bitmap and vector graphics. <b>ppmtopict</b> primarily outputs bitmapped PICTs. Users should be aware that not all PPM features translate perfectly to PICT due to differences in color models, transparency handling, and other format specifics. The command strives to create a valid PICT, but exact visual fidelity may vary.


title: HISTORY
content:
<b>ppmtopict</b> is an integral part of the Netpbm project, a comprehensive suite of graphics file conversion tools. The Netpbm collection originated from Jef Poskanzer's PBMPlus package in the late 1980s, adhering to the Unix philosophy of small, modular programs. Over decades, it has evolved through community contributions. <b>ppmtopict</b> was developed to facilitate interoperability between the versatile PPM format (native to Netpbm) and Apple's proprietary PICT format, which was prevalent in Macintosh environments, particularly in earlier computing eras. While PICT's usage has diminished, the tool remains a component of the robust Netpbm suite, reflecting its historical importance for cross-platform image handling.


title: PARAMETERS
content:
<b><I>ppmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PPM image file. If not specified, <i>ppmtopj</i> reads the PPM data from standard input.<br><br><b><B>-resolution</B> <I>res</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the desired output resolution in dots per inch (dpi). Common values include 300, 600, or 1200. This must match a resolution supported by the target printer.<br><br><b><B>-rle</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables Run-Length Encoding (RLE) compression for the PCL 5 output. This can reduce file size and transmission time to the printer.<br><br><b><B>-norle</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables Run-Length Encoding (RLE) compression for the PCL 5 output. Output will be uncompressed raster data.<br><br><b><B>-forcebw</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output to be monochrome (black and white). Also accessible via <B>-monochrome</B> or <B>-gray</B>.<br><br><b><B>-color1</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs 1-bit color (monochrome) PCL 5 data. This is equivalent to <B>-forcebw</B>.<br><br><b><B>-color4</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs 4-bit color (16 colors) PCL 5 data.<br><br><b><B>-color8</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs 8-bit color (256 colors) PCL 5 data. This is typically the highest color depth supported for PCL 5 images.<br><br><b><B>-xpos</B> <I>x</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the horizontal position of the image origin on the page in dots.<br><br><b><B>-ypos</B> <I>y</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the vertical position of the image origin on the page in dots.<br><br><b><B>-width</B> <I>w</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image to the specified width in dots. The height is scaled proportionally unless <B>-height</B> is also used.<br><br><b><B>-height</B> <I>h</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image to the specified height in dots. The width is scaled proportionally unless <B>-width</B> is also used.<br><br><b><B>-magnification</B> <I>factor</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a magnification factor to the image. For example, <B>-magnification</B> 2 would double the image size.<br><br><b><B>-center</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Centers the image horizontally and vertically on the page.<br><br><b><B>-landscape</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the page orientation to landscape. The image will be rotated appropriately.<br><br><b><B>-portrait</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the page orientation to portrait (the default). The image will be oriented for portrait printing.<br><br><b><B>-nocompress</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents any compression of the image data in the PCL 5 output. This is equivalent to <B>-norle</B>.<br><br><b><B>-nobatch</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables batch mode, which can sometimes improve compatibility with older printers.<br><br><b><B>-nodither</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables dithering for color reduction. When converting to a lower color depth, this might result in banding or loss of detail.<br><br><b><B>-gamma</B> <I>val</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies gamma correction to the image before conversion. <I>val</I> is a floating-point number (e.g., 0.5, 2.0).<br><br><b><B>-brightness</B> <I>val</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the brightness of the image before conversion. <I>val</I> is a floating-point number.<br><br><b><B>-contrast</B> <I>val</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the contrast of the image before conversion. <I>val</I> is a floating-point number.<br><br><b><B>-deviceready</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optimizes the PCL 5 output for faster processing on the printer device. This might involve using specific PCL 5 features.<br><br><b><B>-verbose</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose output, showing progress and detailed information during conversion.<br><br><b><B>-help</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><B>-version</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of <i>ppmtopj</i> and exits.<br><br>


title: DESCRIPTION
content:
<i>ppmtopj</i> is a command-line utility from the <B>Netpbm</B> toolkit designed to convert Portable Pixmap (PPM) image files into the Hewlett-Packard Printer Command Language (PCL) 5 format.<BR><BR>PCL 5 is a printer control language primarily used by HP LaserJet printers and compatible devices. This conversion allows users to directly print PPM images on these printers by sending the generated PCL 5 output to the printer.<BR><BR>The tool reads a PPM image from standard input (or a specified file) and writes the PCL 5 data to standard output. It supports various options to control the output, including resolution, color depth (monochrome, 4-bit, 8-bit color), image positioning, scaling, and compression. <i>ppmtopj</i> is particularly useful in scripting and automated workflows where images need to be prepared for direct printing without a graphical interface.


title: CAVEATS
content:
The output of <i>ppmtopj</i> is specifically PCL 5, which is understood primarily by HP LaserJet printers and compatible devices. It is not a universal image format.<BR><BR>The effective resolution and color depth depend on the capabilities of the target printer. For optimal results, ensure the chosen <B>-resolution</B> and color depth options are supported by your printer.<BR><BR>Some advanced PCL 5 features might not be fully utilized or supported by <i>ppmtopj</i>, focusing instead on core raster image printing.


title: INPUT AND OUTPUT
content:
<i>ppmtopj</i> typically reads <B>PPM</B> (Portable Pixmap) image data from standard input (<I>stdin</I>) if no input file is specified. The resulting <B>PCL 5</B> (Printer Command Language) data is written to standard output (<I>stdout</I>). This allows for flexible piping with other commands, such as <I>cat</I> or <I>lp</I>/<I>lpr</I>.


title: USAGE EXAMPLES
content:
To convert <I>image.ppm</I> to 300 DPI, 8-bit color PCL 5 and save it to a file:<BR><BR><CODE>ppmtopj -resolution 300 -color8 image.ppm &gt; printer.pcl</CODE><BR><BR>To convert <I>image.ppm</I> to 600 DPI monochrome PCL 5 and send it directly to a printer via <I>lp</I>:<BR><BR><CODE>cat image.ppm | ppmtopj -resolution 600 -forcebw | lp -d your_printer_queue</CODE>


title: HISTORY
content:
<i>ppmtopj</i> is part of the <B>Netpbm</B> project, a comprehensive toolkit for manipulating graphic images. Netpbm evolved from the original Pbmplus package, created by Jef Poskanzer in the late 1980s. The philosophy behind Netpbm tools is to provide simple, pipeable utilities for basic image transformations. <i>ppmtopj</i> was developed to address the need for direct conversion of portable pixmap format images into a format suitable for widely available HP LaserJet printers, enabling command-line driven printing workflows on Unix-like systems.


title: PARAMETERS
content:
<b>-output=<i>filename</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path and name of the output file where the JPEG XL image will be saved. If this option is omitted, the encoded image is written to standard output.<br><br><b>-quality=<i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the desired lossy compression quality for the JPEG XL output. The <i>value</i> typically ranges from 0 (lowest quality, highest compression) to 100 (highest quality, lowest compression). The default quality setting is 90.<br><br><b>-lossless</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables lossless compression mode. When this option is specified, the <b>-quality</b> option is ignored, ensuring that the decoded JPEG XL image is bit-for-bit identical to the original PPM input.<br><br><b>-effort=<i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Controls the encoding effort, balancing compression speed against file size. Higher <i>value</i>s (e.g., 9) result in slower encoding but potentially smaller file sizes, while lower <i>value</i>s (e.g., 1) offer faster encoding but less optimal compression. The default effort level is 7.<br><br><b>-epf=<i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables or disables the Edge Preserving Filter (EPF) during JPEG XL encoding. A <i>value</i> of 1 enables EPF (which is the default), and 0 disables it. EPF helps to maintain sharpness and detail at higher compression ratios.<br><br><b>-progressive</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates progressive encoding, which allows the JPEG XL image to be displayed in a gradual, improving quality as it loads, similar to progressive JPEG.<br><br><b>-num_threads=<i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines the number of parallel threads to use for the encoding process. Utilizing more threads can accelerate encoding on systems with multi-core processors. The default is usually determined by the system or library.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Activates verbose output, causing the command to print detailed information about the encoding process to standard error, which can be useful for debugging or monitoring.<br><br><b>-version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information of the underlying <i>libjxl</i> library that <b>ppmtopjxl</b> uses for JPEG XL encoding.<br><br><b>-help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints a comprehensive help message to standard output, detailing all available options and command usage.<br><br>


title: DESCRIPTION
content:
The <b>ppmtopjxl</b> command is a utility from the Netpbm suite, specifically designed to convert images from the Portable Pixmap (PPM) format into the advanced JPEG XL (JXL) format. It operates by reading a PPM image from standard input by default (or from a specified input file) and then writes the resulting JPEG XL image to standard output (or to a designated output file). JPEG XL represents a significant leap forward in image coding, offering superior compression efficiency compared to older formats like JPEG, alongside a rich set of features including robust lossless compression, efficient progressive decoding, and comprehensive support for high dynamic range (HDR) images. This makes it a powerful and versatile successor for various modern imaging applications.<br><br>Essentially, <b>ppmtopjxl</b> serves as a convenient front-end, leveraging the capabilities of the underlying <i>libjxl</i> library. This integration allows users within the Netpbm ecosystem to seamlessly incorporate JPEG XL's cutting-edge features into their existing image processing and manipulation workflows, facilitating the adoption of this efficient new image standard.


title: CAVEATS
content:
The specific options and their behavior for <b>ppmtopjxl</b> can vary slightly depending on the version of the Netpbm package and the linked <i>libjxl</i> library. For optimal performance and access to the latest features, it is recommended to use recent and stable versions of Netpbm and its dependencies. As JPEG XL is a relatively new image format, compatibility across different image viewing and editing software might still be evolving.


title: HISTORY
content:
<b>ppmtopjxl</b> was integrated into the Netpbm project to extend its capabilities with support for the cutting-edge JPEG XL image format. JPEG XL, standardized in 2021, was developed to succeed older image formats like JPEG by offering superior compression efficiency and advanced features, including lossless compression, alpha channel support, and HDR capabilities. The inclusion of <b>ppmtopjxl</b> allows Netpbm users to seamlessly transition to and work with this modern, high-performance image codec within their existing workflows.


title: SYNOPSIS
content:
<b>ppmtoppm</b> [-bayer <i>N</i>] [-colors <i>N</i>] [-gamma <i>R</i>] [-gammut] [-invert] [-maxval <i>N</i>] [-nocomments] [-normalize] [-plain] [-quant <i>N</i>] [-truecolor] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b>-bayer N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quantizes colors using Bayer dithering, where <i>N</i> specifies the brightness range to use for dithering.<br><br><b>-colors N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quantizes the image to use exactly <i>N</i> colors. This is an older, less flexible option than <i>-quant</i>.<br><br><b>-gamma R</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies gamma correction to the image using a gamma value of <i>R</i>.<br><br><b>-gammut</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Clips out-of-gamut colors to the sRGB displayable gamut. Equivalent to <i>pnmgamma -gammut</i>.<br><br><b>-invert</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Inverts the colors of the image. Equivalent to <i>ppminvert</i>.<br><br><b>-maxval N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Changes the maximum pixel value of the output image to <i>N</i>. Rescales all pixel values accordingly.<br><br><b>-nocomments</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Removes any comments present in the input PPM file from the output.<br><br><b>-normalize</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Normalizes the colors by stretching the image's contrast. This adjusts the darkest pixel to black and the brightest to white.<br><br><b>-plain</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the output PPM file in plain (ASCII) format instead of the default raw (binary) format.<br><br><b>-quant N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quantizes colors using a more advanced algorithm than <i>-colors</i>. <i>N</i> represents the number of colors to reduce to or a quality parameter.<br><br><b>-truecolor</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Ensures the output is a truecolor PPM. If the input is truecolor, this option does nothing; otherwise, it behaves like <i>-maxval 255</i> if input is non-truecolor.<br><br>


title: DESCRIPTION
content:
The <i>ppmtoppm</i> command is a utility from the Netpbm package primarily known for performing a "no operation" on a Portable Pixmap (PPM) image. It takes a PPM image as input and typically produces an identical PPM image as output. Its existence is largely historical, maintaining consistency with commands like <i>pbmtopbm</i> and <i>pgmtopgm</i>, which had significant functions (converting older formats) upon their inception. <br><br>While often a pass-through, <i>ppmtoppm</i> can optionally perform various simple transformations. These include color inversion, gamma correction, color quantization, and normalization. However, for most of these transformations, more specialized and general Netpbm programs (such as <i>ppminvert</i>, <i>pnmgamma</i>, or <i>pnmquant</i>) are available and often preferred due to their broader capabilities and flexibility. <i>ppmtoppm</i> can be useful in pipelines where a PPM file needs to be explicitly identified or for very basic, single-step modifications.


title: CAVEATS
content:
The primary function of <i>ppmtoppm</i> is to perform a no-operation, which can be confusing for new users expecting a significant transformation. For most common image manipulation tasks (color inversion, gamma correction, quantization), more powerful and flexible tools within the Netpbm suite (e.g., <i>ppminvert</i>, <i>pnmgamma</i>, <i>pnmquant</i>) are available and generally recommended over using <i>ppmtoppm</i> with its optional flags. Its continued existence is largely for historical reasons and consistency within the Netpbm family of tools.


title: COMMON USAGE SCENARIO
content:
While it mostly acts as a pass-through, <i>ppmtoppm</i> can be useful in shell scripts or pipelines where you need to explicitly process a PPM file or apply a very simple, single transformation (like <i>-invert</i>) without invoking a more complex command. For example, <code>cat image.ppm | ppmtoppm -invert > inverted.ppm</code>


title: HISTORY
content:
<i>ppmtoppm</i> is a part of the Netpbm package, a venerable suite of graphics utilities dating back to the late 1980s and early 1990s. Its initial purpose was largely to provide consistency. When <i>pbmtopbm</i> and <i>pgmtopgm</i> were introduced, they had a functional role in converting older PBM and PGM formats to newer, standardized versions. <i>ppmtoppm</i> was created to complete the trio for the PPM format, even though the PPM format didn't undergo similar significant internal changes requiring a direct conversion tool. Thus, it historically served as a placeholder rather than a primary manipulation tool.


title: SYNOPSIS
content:
<b>ppmtopuzz</b> [<b>-piecewidth=</b><I>N</I>] [<b>-pieceheight=</b><I>N</I>] [<b>-puzz-version=</b><I>N</I>] [<I>ppmfile</I>]


title: PARAMETERS
content:
<b><b>-piecewidth=</b><I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired width, in pixels, for each individual puzzle piece. The input image's width must be evenly divisible by this value.<br><br><b><b>-pieceheight=</b><I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the desired height, in pixels, for each individual puzzle piece. The input image's height must be evenly divisible by this value.<br><br><b><b>-puzz-version=</b><I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Determines the version of the <I>.puzz</I> file format to be generated. This is typically <I>1</I> or <I>2</I>, depending on the requirements of the puzzle application.<br><br><b><I>ppmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input Portable Pixmap (PPM) image file. If omitted, <I>ppmtopuzz</I> will read image data from standard input.<br><br>


title: DESCRIPTION
content:
<i>ppmtopuzz</i> is a utility from the <I>Netpbm</I> image manipulation toolkit. It converts a Portable Pixmap (PPM) image file into a <I>.puzz</I> file, a specialized format used by certain Jigsaw Puzzle programs. The <I>.puzz</I> file typically contains information about the puzzle's dimensions (number of pieces), the pixel data for each piece, and potentially other metadata necessary for a puzzle application to reconstruct and display the image as a puzzle. This command allows users to prepare their custom images for use in such puzzle software by segmenting the image into a grid of pieces based on specified dimensions. It's a niche tool within the broader <I>Netpbm</I> suite, designed to interoperate with specific puzzle applications that consume this <I>.puzz</I> format.


title: CAVEATS
content:
<ul><li>The specified <b>piecewidth</b> and <b>pieceheight</b> values must be exact divisors of the input image's width and height, respectively. If not, the command will issue an error.</li><li>Output is always written to standard output (<b>stdout</b>). To save the output to a file, redirection (e.g., <code>&gt; filename.puzz</code>) must be used.</li><li>The <I>.puzz</I> file format is highly specific and primarily intended for use with particular jigsaw puzzle software that recognizes it. It is not a widely adopted image format.</li></ul>


title: STANDARD INPUT/OUTPUT
content:
Like many <I>Netpbm</I> utilities, <I>ppmtopuzz</I> is designed to work with Unix pipes. It reads the input PPM image from <I>ppmfile</I> (or standard input if <I>ppmfile</I> is not provided) and writes the resulting <I>.puzz</I> file to standard output. This allows for chaining commands, for example, <code>anytopnm image.jpg | ppmtopuzz -piecewidth=50 -pieceheight=50 &gt; puzzle.puzz</code>.


title: PUZZLE FILE FORMAT
content:
The <I>.puzz</I> file format is a proprietary or niche format. While its exact internal structure can vary slightly by version, it generally embeds the image pixel data along with metadata about the puzzle grid (e.g., number of rows and columns of pieces). It is not directly viewable by standard image viewers but is consumed by specific jigsaw puzzle applications.


title: HISTORY
content:
<I>ppmtopuzz</I> is part of the <I>Netpbm</I> image manipulation package, a long-standing collection of graphics tools for Unix-like systems. It was specifically developed by Bryan Henderson, the maintainer of <I>Netpbm</I>, to provide an image source for a particular puzzle application that utilized the <I>.puzz</I> file format. Its development is tied to the <I>Netpbm</I> project's continuous evolution in providing versatile image format conversions.


title: SYNOPSIS
content:
<b>ppmtorgb3</b> [<I>ppmfile</I> [<I>redfile</I> [<I>greenfile</I> [<I>bluefile</I> [<I>alphafile</I>]]]]]<br><b>ppmtorgb3</b> <I>-alpha</I> [<I>ppmfile</I> [<I>redfile</I> [<I>greenfile</I> [<I>bluefile</I> [<I>alphafile</I>]]]]]


title: PARAMETERS
content:
<b>ppmfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input PPM or PAM image file. If omitted or specified as '-', it reads from standard input.<br><br><b>redfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The output PGM file for the red color component. If omitted, the red component is written to standard output, concatenated with other components.<br><br><b>greenfile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The output PGM file for the green color component. If omitted, the green component is written to standard output, concatenated with other components.<br><br><b>bluefile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The output PGM file for the blue color component. If omitted, the blue component is written to standard output, concatenated with other components.<br><br><b>-alpha</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables extraction of the alpha channel. If the input is a PAM image and this option is used, an additional PGM file for the alpha channel is created. If <I>alphafile</I> is not specified, the alpha component is concatenated to standard output after R, G, B.<br><br><b>alphafile</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The output PGM file for the alpha channel. This parameter is only relevant when the <I>-alpha</I> option is used with a PAM input image. If omitted, the alpha component is written to standard output, concatenated with others.<br><br><b>--</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Marks the end of command-line options. Use this if your <I>ppmfile</I> argument begins with a hyphen to prevent it from being interpreted as an option.<br><br>


title: DESCRIPTION
content:
<i>ppmtorgb3</i> is a utility from the Netpbm suite designed to separate a Portable Pixmap (PPM) image into its constituent red, green, and blue color channels. Each channel is output as a separate Portable Graymap (PGM) image, where pixel values represent the intensity of that specific color component.<br><br>If the input image is a Portable Arbitrary Map (PAM) and the <i>-alpha</i> option is specified, an additional PGM file representing the alpha transparency channel can also be extracted. This command is primarily used for color channel analysis, manipulating individual color planes, or preparing images for specific processing tasks. Output files can be specified as arguments; otherwise, the components are concatenated sequentially to standard output.


title: CAVEATS
content:
The command outputs PGM files, which are grayscale. Each PGM file represents the intensity of a single color or alpha channel. When output filenames are omitted, all components are concatenated to standard output; this typically requires further piping or parsing (e.g., using <i>pamstack</i> or multiple invocations with redirection) to truly separate them into individual files.


title: INPUT/OUTPUT FORMATS
content:
Input is expected to be a Netpbm PPM or PAM image. Output files are Netpbm PGM images, each representing a single color (red, green, blue) or alpha channel.


title: STANDARD USAGE EXAMPLE
content:
To separate <i>image.ppm</i> into individual red, green, and blue PGM files:<br><code>ppmtorgb3 image.ppm red.pgm green.pgm blue.pgm</code><br><br>To extract components including alpha from a PAM image into separate files:<br><code>ppmtorgb3 -alpha input.pam red.pgm green.pgm blue.pgm alpha.pgm</code><br><br>To pipe components to other Netpbm tools for further processing (e.g., converting red channel to a different format):<br><code>ppmtorgb3 image.ppm | head -n <I>header_lines_red</I> | <I>pgmtojpeg</I> > red.jpg</code> (This example is simplified; actual piping requires careful handling of concatenated PGM headers).


title: HISTORY
content:
<i>ppmtorgb3</i> is a part of the Netpbm project, a comprehensive toolkit for graphics file format conversion and manipulation. Netpbm evolved from the PBMPLUS package, originally created by Jef Poskanzer in the late 1980s. This command represents a fundamental operation of color channel separation, a core capability required for various image processing and analysis tasks within the Netpbm ecosystem.


title: SYNOPSIS
content:
ppmtosixel [<b>-8</b>] [<b>-c</b> <I>cols</I>] [<b>-e</b>] [<b>-g</b> <I>gamma</I>] [<b>-m</b> <I>mode</I>] [<b>-p</b>] [<b>-r</b> <I>rows</I>] [<b>-s</b>] [<b>-t</b> <I>threshold</I>] [<b>-u</b>] [<b>-w</b>] [<I>ppmfile</I>]


title: PARAMETERS
content:
<b><b>-8</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <i>ppmtosixel</i> not to limit the output to 8-color Sixel mode. By default, it may prefer 8-color for wider compatibility; specifying <b>-8</b> allows it to attempt full 256-color output if the terminal supports it.<br><br><b><b>-c</b> <I>cols</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the maximum number of output columns for the Sixel data. This can be used to control the width of the generated image on the terminal.<br><br><b><b>-e</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Emit escape sequences to erase the screen before displaying the Sixel graphic. Useful for ensuring the image is displayed cleanly.<br><br><b><b>-g</b> <I>gamma</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply gamma correction to the image. <I>gamma</I> is a floating-point number representing the gamma value.<br><br><b><b>-m</b> <I>mode</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specify the mapping mode for converting colors. Possible modes include <i>direct</i> (default, uses closest color), <i>dither</i> (uses dithering for better color representation), <i>monochrome</i>, and <i>gray</i>.<br><br><b><b>-p</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output the Sixel palette information as comments within the generated Sixel data stream.<br><br><b><b>-r</b> <I>rows</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the maximum number of output rows for the Sixel data. This can be used to control the height of the generated image on the terminal.<br><br><b><b>-s</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Show the raw Sixel string only, without emitting the terminal escape sequences that would normally display the image. Useful for debugging or saving the Sixel data for later use.<br><br><b><b>-t</b> <I>threshold</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Set the dithering threshold for the 'dither' mapping mode. <I>threshold</I> is an integer value affecting how colors are dithered.<br><br><b><b>-u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output a monochrome (black and white) Sixel image, discarding all color information.<br><br><b><b>-w</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Do not wrap Sixel lines. By default, Sixel output may wrap if it exceeds the terminal's column limit, which can distort the image.<br><br>


title: DESCRIPTION
content:
The <i>ppmtosixel</i> command is a utility from the Netpbm tools collection, designed to convert Portable Pixmap (PPM) image files into the DEC Sixel graphical format. Sixel is a bitmap graphics format originally developed by Digital Equipment Corporation (DEC) in the late 1970s, allowing images to be displayed directly on compatible text terminals by using specific ASCII characters to represent pixels. This command takes a PPM image as input (either from a file or standard input) and outputs the corresponding Sixel escape sequences to standard output. It's particularly useful for displaying simple graphics or plots within a terminal environment that supports Sixel, such as certain configurations of <i>xterm</i>, <i>mlterm</i>, or other modern terminal emulators. While Sixel is a legacy format with limitations in resolution and color depth compared to modern image formats, <i>ppmtosixel</i> provides a bridge for older applications or for users who appreciate the unique capability of in-terminal image display.


title: CAVEATS
content:
The Sixel format is a legacy graphics standard. To view the output of <i>ppmtosixel</i>, you need a terminal emulator that explicitly supports Sixel graphics, such as certain versions of <i>xterm</i> (with Sixel support compiled in), <i>mlterm</i>, <i>foot</i>, or some configurations of <i>Konsole</i>. It is part of the Netpbm package and relies on its underlying image processing capabilities. Output directly goes to standard output, making it suitable for piping to a terminal, but less so for saving as a standalone image file (unless the file is intended for a Sixel-compatible viewer). Sixel has inherent limitations in resolution and color depth compared to modern image formats.


title: NETPBM AND SIXEL
content:
<i>ppmtosixel</i> is one of many image format conversion utilities provided by the Netpbm project. Netpbm is a collection of graphics programs and a programming library. The 'Portable Pixmap' (PPM) format, which <i>ppmtosixel</i> takes as input, is one of the foundational 'portable anymap' formats (PBM, PGM, PPM) used internally by Netpbm tools, making it easy to chain operations. Sixel, while old, is still supported by a growing number of modern terminal emulators, often for its unique ability to display graphics directly in a text-based terminal session without needing an external image viewer.


title: VIEWING SIXEL OUTPUT
content:
To view the Sixel output generated by <i>ppmtosixel</i>, you typically pipe its standard output directly to a Sixel-compatible terminal emulator. For example:<br><code>cat image.ppm | ppmtosixel</code><br>or<br><code>ppmtosixel image.ppm</code><br>Ensure your terminal emulator is configured to support Sixel graphics. For <i>xterm</i>, this might involve enabling the Sixel graphics feature (e.g., <code>xterm -ti 340</code> or compiling with Sixel support).


title: HISTORY
content:
Sixel graphics were originally introduced by Digital Equipment Corporation (DEC) in the late 1970s, notably with their VT125 and subsequent VT2xx/VT3xx series terminals, as a way to display rudimentary bitmap graphics on text-based terminals. The <i>ppmtosixel</i> utility is part of the widely used Netpbm toolkit, which evolved from the 'pbmplus' package in the late 1980s. Netpbm's purpose is to provide a comprehensive suite of tools for converting and manipulating various graphics formats, and the inclusion of <i>ppmtosixel</i> reflects its commitment to supporting historical and specialized image formats relevant to the Unix ecosystem. Its usage continues in niche applications, particularly for in-terminal data visualization and retro-computing.


title: PARAMETERS
content:
<b><B>-gamma</B> <I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies gamma correction to the image. <I>N</I> specifies the gamma value to use (e.g., 2.2).<br><br><b><B>-aspect</B> <I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adjusts the aspect ratio of the output image to the specified value <I>N</I>.<br><br><b><B>-colors</B> <I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reduces the number of colors in the output SPU image to <I>N</I>. The default is typically 256 colors, relevant for the PlayStation's color capabilities.<br><br><b><B>-maxval</B> <I>N</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum pixel value for the output SPU image. The default is usually 255, corresponding to 8-bit color depth.<br><br><b><B>-noantialias</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables antialiasing during the conversion process, which can result in sharper but potentially jagged edges in the output.<br><br><b><B>-notexture</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the command not to generate texture data in the output SPU file, potentially reducing file size or adapting to specific SPU usage.<br><br><b><B>-printer</B></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a slightly different SPU format optimized for printing rather than on-screen display on the console.<br><br><b><B>-outfilename</B> <I>NAME</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the name of the output SPU file. If this option is not provided, the converted SPU image is written to standard output.<br><br><b><I>ppmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The input PPM image file to be converted. If omitted, <I>ppmtospu</I> reads the PPM data from standard input.<br><br>


title: DESCRIPTION
content:
<I>ppmtospu</I> is a command-line utility from the <B>Netpbm</B> suite designed to convert image files from the <B>PPM</B> (Portable Pixmap) format into the <B>SPU</B> (Sony PlayStation Unit) image format.<br><br>The <B>SPU</B> format was an internal graphics format primarily used for rendering images and textures on the original Sony PlayStation console. This command was useful for developers or enthusiasts creating graphics for PlayStation applications or games.<br><br>It reads a PPM image from standard input or a specified file and writes the resulting SPU image to standard output or a specified output file. The command offers various options to control aspects like color depth, gamma correction, and output file specifics.


title: CAVEATS
content:
This program is largely obsolete today as the Sony PlayStation is an old system and its internal graphics formats are no longer in common use. Its primary utility was strictly tied to the console's active development and usage period (mid-1990s to early 2000s).


title: HISTORY
content:
<I>ppmtospu</I> is an integral part of the <B>Netpbm</B> project, a robust and widely used suite of graphics file format converters and editors for Unix-like operating systems. The origins of the Netpbm tools trace back to the <B>pbmplus</B> package developed in the early 1990s. <I>ppmtospu</I> itself gained specific relevance and development during the active lifespan of the original Sony PlayStation console (from the mid-1990s into the early 2000s) as it addressed the need for converting standard image formats into the PlayStation's proprietary SPU graphics format for game and application development.


title: SYNOPSIS
content:
<b>ppmtoterm</b> [<b>-256colors</b> | <b>-ansi</b>] [<b>-80col</b>] [<b>-bold</b>] [<b>-width</b> <i>N</i>] [<b>-height</b> <i>N</i>] [<b>-gamma</b> <i>F</i>] [<b>-truecolors</b> | <b>-notruecolors</b>] [<b>-maxcolors</b> <i>N</i>] [<b>-char</b> <i>C</i>] [<b>-block</b>] [<b>-dither</b>] [<b>-map</b> <i>file</i>] [<b>-rows</b> <i>N</i>] [<b>-cols</b> <i>N</i>] [<b>-compress</b>] [<b>-noblank</b>] [<b>-fontwidth</b> <i>N</i>] [<b>-fontheight</b> <i>N</i>] [<b>-font</b> <i>file</i>] [<b>-output</b> <i>file</i>] [<b>-help</b>] [<b>-version</b>] [<i>PPMfile</i>]


title: PARAMETERS
content:
<b><b>-256colors</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses 256-color ANSI sequences for output.<br><br><b><b>-ansi</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses standard 8-color ANSI sequences (default mode).<br><br><b><b>-80col</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces output to an 80-column width.<br><br><b><b>-bold</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Employs bold attributes for brighter color simulation.<br><br><b><b>-width</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image to <i>N</i> characters wide.<br><br><b><b>-height</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Scales the image to <i>N</i> characters high.<br><br><b><b>-gamma</b> <i>F</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a gamma correction factor <i>F</i> to colors.<br><br><b><b>-truecolors</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Utilizes 24-bit true color ANSI sequences (terminal dependent).<br><br><b><b>-notruecolors</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables 24-bit true color output (default).<br><br><b><b>-maxcolors</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Limits the number of colors used in the output to <i>N</i>.<br><br><b><b>-char</b> <i>C</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies character <i>C</i> to use for drawing pixels.<br><br><b><b>-block</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses a block character (e.g., U+2588) for solid pixels.<br><br><b><b>-dither</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies dithering to improve color gradient representation.<br><br><b><b>-map</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the color map defined in <i>file</i>.<br><br><b><b>-rows</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An alias for <b>-height</b> <i>N</i>.<br><br><b><b>-cols</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An alias for <b>-width</b> <i>N</i>.<br><br><b><b>-compress</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Attempts to use run-length encoding for smaller output.<br><br><b><b>-noblank</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents printing blank lines to fill terminal height.<br><br><b><b>-fontwidth</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character font width in pixels.<br><br><b><b>-fontheight</b> <i>N</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the character font height in pixels.<br><br><b><b>-font</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads font metrics from a BDF font <i>file</i>.<br><br><b><b>-output</b> <i>file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Redirects output to <i>file</i> instead of standard output.<br><br><b><b>-help</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the command's help message.<br><br><b><b>-version</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows version information for <i>ppmtoterm</i>.<br><br><b><i>PPMfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Path to the input PPM image file, or reads from standard input if omitted.<br><br>


title: DESCRIPTION
content:
<i>ppmtoterm</i> is a versatile utility from the <i>Netpbm</i> package, designed to transform a Portable Pixmap (PPM) image into a series of ANSI escape sequences. These sequences, when printed to a compatible text terminal, enable the display of images using a combination of characters, foreground colors, and background colors. This effectively creates a "graphics mode" within a text-based console, allowing users to view image content without requiring a graphical display server. The command intelligently attempts to render the image by leveraging the specific character set and color capabilities supported by the active terminal. The resulting output is typically sent to standard output, making it easy to pipe to other commands like <b>less -R</b> for viewing or redirect to a file. It's an invaluable tool for displaying visual information in purely command-line or SSH environments.


title: CAVEATS
content:
Terminal compatibility: Output relies heavily on the terminal's ability to interpret ANSI escape sequences, especially 256-color and 24-bit true color. <br> Font metrics: Accurate display depends on correct font width/height being known or specified, otherwise aspect ratio might be distorted. <br> Performance: Complex images or large sizes can result in very long output sequences, potentially slow to render.


title: USAGE WITH PAGING PROGRAMS
content:
To view the output of <i>ppmtoterm</i> with a pager like <i>less</i> or <i>more</i> while preserving the ANSI colors and formatting, it's essential to use the <b>-R</b> or <b>-r</b> option (raw mode) respectively. For example: <b>ppmtoterm image.ppm | less -R</b>. Without this option, the escape sequences will be displayed as raw text.


title: HISTORY
content:
Part of the <i>Netpbm</i> package, which has a long history originating from <i>PBMplus</i> by Jef Poskanzer in 1988. <i>Netpbm</i> is a widely used toolkit for graphics manipulation in command-line environments. <i>ppmtoterm</i> specifically provides a way to render graphical content in text-based terminals, addressing the need for visual output in console environments.


title: PARAMETERS
content:
<b><i>-16</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the TGA image in 16-bit format (RGB 5:5:5 or 5:6:5, depending on the colors). If the image has an alpha channel, it is ignored.<br><br><b><i>-24</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the TGA image in 24-bit format (RGB 8:8:8). Alpha channel information, if present, is discarded.<br><br><b><i>-32</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Outputs the TGA image in 32-bit format (RGBA 8:8:8:8). This option includes an alpha channel in the output TGA if the input PPM contains transparency information (e.g., from a PAM image).<br><br><b><i>-rle</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Encodes the output TGA image using Run-Length Encoding (RLE) compression. By default, the output TGA is uncompressed.<br><br><b><i>-mono</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output TGA image to be monochrome (8-bit grayscale). If the input PPM is color, it will be dithered down to grayscale.<br><br><b><i>-rgb</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output TGA image to be 24-bit RGB, even if the input PPM is grayscale. This ensures a full-color TGA file.<br><br><b><i>ppmfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the input PPM image file. If this argument is omitted, <i>ppmtotga</i> reads the PPM image data from standard input.<br><br>


title: DESCRIPTION
content:
<i>ppmtotga</i> is a specialized utility within the Netpbm toolkit, designed for converting images from the Portable Pixmap (PPM) format to the Truevision Targa (TGA) format. PPM is a widely used, simple, and uncompressed image format favored as an intermediate format in Netpbm pipelines due to its direct representation of pixels. TGA is a popular raster graphics file format, particularly noted for its historical use in PC gaming and its support for alpha channels. <br><br>By default, <i>ppmtotga</i> reads a PPM image from standard input and outputs the resulting TGA image to standard output, making it highly suitable for shell scripting and piping operations. It offers flexibility by supporting various TGA subformats, including uncompressed or run-length encoded (RLE), and different bit depths such as 16-bit, 24-bit, and 32-bit (which includes an alpha channel). This tool is crucial for interoperability, allowing users to transform images between Netpbm's native formats and applications or systems that require TGA files.


title: CAVEATS
content:
When no bit depth option (<i>-16</i>, <i>-24</i>, <i>-32</i>) is specified, <i>ppmtotga</i> attempts to choose the smallest TGA type capable of representing the input PPM's colors. For proper alpha channel handling with <i>-32</i>, the input PPM must conform to Netpbm's internal representation for transparency, often created by tools like <i>pnmremap</i> from a PAM image.


title: DEFAULT BEHAVIOR
content:
If no specific options for bit depth or compression are provided, <i>ppmtotga</i> analyzes the input PPM to determine the most suitable TGA format (e.g., 16-bit, 24-bit, or 32-bit with alpha if present) and outputs an uncompressed TGA file. It seamlessly operates as a filter, reading from standard input and writing to standard output by default, which is characteristic of most Netpbm tools.


title: ALPHA CHANNEL SUPPORT
content:
While <i>ppmtotga -32</i> generates a 32-bit TGA file with an alpha channel, it's crucial that the input PPM carries the alpha information in a format <i>ppmtotga</i> can interpret. typically, this means the PPM was derived from a Netpbm PAM (Portable Arbitrary Map) image that explicitly included a transparency plane, processed perhaps by <i>pnmremap</i> to create the specific PPM structure <i>ppmtotga</i> expects for alpha data.


title: HISTORY
content:
<i>ppmtotga</i> is a long-standing component of the Netpbm project, a comprehensive suite of graphics manipulation utilities for Unix-like systems. Its development has paralleled the evolution of Netpbm itself, maintaining its role as a stable and reliable tool for converting between the flexible PPM format and the TGA standard.


title: PARAMETERS
content:
<b><b>-bitplaneorder</b> {<I>lsb</I>|<I>msb</I>}</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the order of bitplanes in the output image. <I>lsb</I> stands for Least Significant Bit first (default), and <I>msb</I> for Most Significant Bit first.<br><br><b><b>-transparentcolor</b> <I>#RRGGBB</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a specific <I>RGB</I> color (e.g., <I>#FF00FF</I> for magenta) in the input <I>PPM</I> to be treated as transparent in the output <I>MicroUI</I> image.<br><br><b><b>-nontransparentcolor</b> <I>#RRGGBB</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a specific <I>RGB</I> color to be rendered as opaque. This option is typically used in conjunction with <I>-transparentcolor</I> for specific transparency modes or 1-bit images.<br><br><b><I>ppmfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input <I>PPM</I> image file. If omitted, <b>ppmtouil</b> reads the <I>PPM</I> data from standard input.<br><br>


title: DESCRIPTION
content:
<b>ppmtouil</b> is a utility from the <I>Netpbm</I> project designed to convert <I>Portable Pixmap</I> (PPM) image files into the <I>MicroUI</I> image format. The <I>MicroUI</I> format is a proprietary image standard used by <I>Microchip Technology's Graphics Library</I>, primarily for embedded systems applications involving their <I>PIC microcontrollers</I> and associated <I>LCD</I> displays.<br><br>This command is crucial for developers working with Microchip's graphics solutions who need to display custom images on their embedded devices. It takes a <I>PPM</I> image as input, which can be generated from various other image formats using <I>Netpbm's</I> extensive suite of tools, and outputs a binary file in the <I>MicroUI</I> format ready for use in firmware. The tool handles aspects like color depth conversion and data arrangement specific to the <I>MicroUI</I> requirements, making it an essential bridge between standard image formats and specialized embedded display needs.


title: CAVEATS
content:
The output format is proprietary to <I>Microchip's Graphics Library</I>, limiting its direct usability outside this ecosystem.<br>Color depth and palette limitations of the target <I>MicroUI</I> format may lead to image degradation or loss of detail during conversion from a higher fidelity <I>PPM</I> image.


title: TYPICAL WORKFLOW
content:
Users typically convert their source images (e.g., <I>JPG</I>, <I>PNG</I>, <I>GIF</I>) to <I>PPM</I> format using other <I>Netpbm</I> utilities (like <I>jpegtopnm</I>, <I>pngtopnm</I>, or <I>giftoppm</I>) before piping the standard output to <b>ppmtouil</b> to generate the final <I>MicroUI</I> binary.<br><br>Example: <I>pngtopnm image.png | ppmtouil > image.ui</I>


title: HISTORY
content:
Part of the venerable <I>Netpbm</I> project, which originated from <I>Pbmplus</I> in the late 1980s. <b>ppmtouil</b> was developed to bridge the gap between standard image formats (<I>PPM</I>) and the specialized <I>MicroUI</I> image format required by <I>Microchip Technology's Graphics Library</I> for embedded systems, reflecting <I>Netpbm's</I> adaptability for niche hardware interfaces.


title: SYNOPSIS
content:
<b>ppmtowinicon</b> [<i>-transparent</i>] [<i>-hotspot x y</i>] [<i>-colors n</i>] [<i>-andmask</i>] [<i>-notandmask</i>] [<i>-orxor</i>] [<i>-file file</i>] [<i>ppmfile ...</i>]


title: PARAMETERS
content:
<b>-transparent</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the color of the bottom-left pixel of the first image as the transparent color for all images in the icon.<br><br><b>-hotspot x y</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the hotspot coordinates (x, y) for a cursor. While available, this option is primarily for <i>ppmtowincursor</i> and generally not applicable for icon files.<br><br><b>-colors n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Quantizes the input images to use at most <i>n</i> colors. The default is 256 colors if not specified.<br><br><b>-andmask</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables the AND-mask mechanism for transparency, where the transparent bits are defined by a separate mask.<br><br><b>-notandmask</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables the OR-XOR mechanism for transparency, which is the default if <i>-andmask</i> is not specified. This is equivalent to <i>-orxor</i>.<br><br><b>-orxor</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Equivalent to <i>-notandmask</i>, enabling the OR-XOR transparency mechanism.<br><br><b>-file file</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the resulting Windows icon data to the specified <i>file</i> instead of standard output.<br><br><b>ppmfile ...</b><br>&nbsp;&nbsp;&nbsp;&nbsp;One or more input PPM image files to be converted. If no files are specified, <b>ppmtowinicon</b> reads PPM data from standard input.<br><br>


title: DESCRIPTION
content:
<b>ppmtowinicon</b> is a command-line utility from the Netpbm suite that converts one or more Netpbm PPM (Portable Pixmap) images into a single Windows icon (ICO) file. It reads PPM data from standard input or specified files and writes the ICO output to standard output or a designated file.<br><br>This tool is essential for creating icons used in Windows applications, supporting multi-image ICO files where each input PPM can represent a different size or color depth of the same icon. It provides options for managing transparency and color quantization, making it versatile for generating icons that adhere to specific Windows display requirements. Users often preprocess images with tools like <b>pnmscale</b> or <b>pnmquant</b> before piping them to <b>ppmtowinicon</b> to achieve desired dimensions and color palettes.


title: CAVEATS
content:
Input images must be in PPM (Portable Pixmap) format. Other Netpbm formats (PGM, PBM) are not directly supported by this command, although they can be converted to PPM using other Netpbm tools like <b>anytoppm</b>.<br><br>The <i>-hotspot</i> option is intended for Windows cursor files (CUR) and is generally ineffective or irrelevant for standard icon files (ICO), despite being present for compatibility with <b>ppmtowincursor</b>.<br><br><b>ppmtowinicon</b> does not perform image resizing or advanced color depth conversions. Users should pre-process their PPM images using tools like <b>pnmscale</b> to achieve desired icon dimensions (e.g., 16x16, 32x32) and <b>pnmquant</b> for specific color depths before piping them into <b>ppmtowinicon</b>.


title: MULTI-IMAGE ICONS
content:
<b>ppmtowinicon</b> can create multi-image ICO files by accepting multiple PPM files as input. Each input PPM file contributes a separate image entry to the final icon, allowing for different resolutions or color depths within a single icon file, which is crucial for modern Windows icon display.


title: STANDARD INPUT/OUTPUT USAGE
content:
When no input <i>ppmfile</i> is specified, <b>ppmtowinicon</b> reads image data from standard input, making it highly suitable for piping operations from other Netpbm commands (e.g., `<i>pnmscale image.ppm | ppmtowinicon > icon.ico</i>`). Similarly, output is directed to standard output by default, facilitating further processing or redirection.


title: HISTORY
content:
<b>ppmtowinicon</b> is part of the Netpbm project, a well-established open-source package of graphics manipulation programs for Unix-like systems. Its development reflects the need to generate platform-specific image formats, such as Windows ICO files, from more generic and manipulable Netpbm formats, facilitating cross-platform image asset management and development workflows.


title: SYNOPSIS
content:
<b>ppmtoxpm</b> [<i>-maxcolors N</i>] [<i>-closecolors N</i>] [<i>-gamma N</i>] [<i>-verbose</i>] [<i>-name string</i>] [<i>-comment string</i>] [<i>-alpha</i>] [<i>-mono</i>] [<i>-noalpha</i>] [<i>-optimizetrans</i>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b>-maxcolors N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reduces the number of colors in the output XPM image to a maximum of <b>N</b>.<br><br><b>-closecolors N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the closeness factor for color reduction, influencing how similar colors are treated.<br><br><b>-gamma N</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies gamma correction with a value of <b>N</b> to the image before conversion.<br><br><b>-verbose</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints informational and debugging messages during the conversion process.<br><br><b>-name string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the name of the XPM image data structure in the output file to <b>string</b>.<br><br><b>-comment string</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds <b>string</b> as a comment line in the generated XPM file.<br><br><b>-alpha</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly includes the alpha channel in the XPM output, if present in the PPM. Typically implies XPM3.<br><br><b>-mono</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output XPM to be monochrome (black and white).<br><br><b>-noalpha</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Explicitly excludes any alpha channel from the XPM output, even if present in the PPM.<br><br><b>-optimizetrans</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optimizes the transparent pixels, potentially reducing the XPM file size.<br><br>


title: DESCRIPTION
content:
<br><i>ppmtoxpm</i> is a command-line utility from the Netpbm package used to convert image files from the Portable Pixmap (PPM) format to the X Pixmap (XPM) format. <br><br>PPM is a simple, raw pixel format, while XPM is a text-based format primarily used for icons, cursors, and small images within the X Window System. XPM supports transparency and can be embedded directly into C code, making it useful for developers. <br><br>This conversion often involves reducing the number of colors in the image, as XPM typically uses a limited color palette. <i>ppmtoxpm</i> provides options for controlling color reduction, gamma correction, and handling alpha channels, ensuring the output XPM is suitable for its intended display environment.


title: CAVEATS
content:
XPM format is inherently limited in color depth compared to true-color PPM images. Using <i>-maxcolors</i> can lead to significant color quantization and quality loss.<br><br>Alpha channel support depends on the XPM version; <i>ppmtoxpm</i> typically produces XPM3, which supports it. Older XPM viewers might not display transparency correctly.


title: INPUT FILE
content:
If no <i>ppmfile</i> is specified, <i>ppmtoxpm</i> reads the PPM image data from standard input (stdin). This allows for piping output from other Netpbm commands directly into <i>ppmtoxpm</i>.


title: OUTPUT FILE
content:
The converted XPM data is written to standard output (stdout). To save it to a file, redirect the output using `> filename.xpm`.


title: HISTORY
content:
<i>ppmtoxpm</i> is a standard utility within the Netpbm suite of graphics manipulation tools. The Netpbm project originated in the early 1990s as a collection of graphics filters, evolving from the earlier PBMplus package. As the X Window System gained prominence, the need for converting between various image formats, including to and from XPM, became crucial, leading to the development and refinement of tools like <i>ppmtoxpm</i> to support XPM3 (the most common version supporting transparency).


title: SYNOPSIS
content:
<b>ppmtoyuv</b> [<i>-p</i>|<i>-o</i>] [<i>-s</i>|<i>-q</i>|<i>-f</i>|<i>-a</i>] [<i>-v</i>] [<i>-gamma value</i>] [<i>-nopan</i>] [<i>-pad</i>] [<i>ppmfile</i>]


title: PARAMETERS
content:
<b>-p</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output YUV in <i>plain</i> (no header) format.<br><br><b>-o</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output YUV in <i>output</i> (with header) format. This is the default.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output YUV in <i>standard</i> 4:2:0 format. This is commonly used in video codecs.<br><br><b>-q</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output YUV in <i>quarter-pixel</i> 4:1:1 format.<br><br><b>-f</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output YUV in <i>half-pixel</i> 4:2:2 format.<br><br><b>-a</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Output YUV in <i>full-pixel</i> 4:4:4 format. This retains full color information.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Produce <i>verbose</i> output, showing progress and information messages.<br><br><b>-gamma <i>value</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Apply gamma correction using the specified <i>value</i>.<br><br><b>-nopan</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Suppress the 'pan' error message often generated when image dimensions are not a multiple of 16.<br><br><b>-pad</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Pad the output YUV image dimensions (width and height) to be a multiple of 16. This is often required by video encoders.<br><br>


title: DESCRIPTION
content:
<i>ppmtoyuv</i> is a specialized command-line utility from the <i>Netpbm</i> package, designed to convert Portable Pixmap (PPM) image files into various YUV (luminance-chrominance) video formats. PPM is a simple, uncompressed image format, often used as an intermediate format in image processing pipelines. YUV, on the other hand, is a color encoding system primarily used in video systems, particularly for analog and digital television, due to its efficient separation of luminance (brightness) and chrominance (color information).<br><br>This tool is crucial when preparing image sequences for video encoding, as many video codecs expect YUV input. <i>ppmtoyuv</i> allows users to select different YUV sampling formats (like 4:4:4, 4:2:2, 4:1:1, or 4:2:0), which represent varying levels of chrominance subsampling, impacting file size and perceived quality. It reads PPM data from standard input or a specified file and outputs the YUV stream to standard output, making it easily integrable into shell scripts and processing pipelines with other tools like <i>ffmpeg</i> or video encoders.


title: CAVEATS
content:
<i>ppmtoyuv</i> is part of the <i>Netpbm</i> toolkit, so it requires Netpbm to be installed. The YUV output is often raw and typically requires further processing by a video encoder (e.g., <i>ffmpeg</i>) or a specific YUV viewer. The choice of YUV subsampling format (4:4:4, 4:2:2, 4:1:1, 4:2:0) significantly impacts the final file size and perceived color fidelity. Ensure the selected YUV format matches the requirements of downstream video processing tools.


title: YUV SUBSAMPLING FORMATS
content:
YUV formats like 4:4:4, 4:2:2, 4:1:1, and 4:2:0 describe the ratio of chrominance (color) information sampled relative to luminance (brightness). 4:4:4 means full color information for every pixel. 4:2:2 samples chrominance at half the horizontal resolution. 4:1:1 samples chrominance at a quarter of the horizontal resolution. 4:2:0 samples chrominance at half the horizontal and half the vertical resolution. Lower ratios like 4:2:0 are common in video for efficiency, as the human eye is less sensitive to chrominance detail than luminance.


title: STANDARD INPUT/OUTPUT USAGE
content:
Like many <i>Netpbm</i> tools, <i>ppmtoyuv</i> can read from standard input and write to standard output. This allows it to be easily chained with other commands using pipes. For example, <b>anytopnm input.jpg | ppmtoyuv -s > output.yuv</b> would convert a JPG to PPM, then to YUV 4:2:0.


title: HISTORY
content:
<i>ppmtoyuv</i> is a long-standing component of the <i>Netpbm</i> project, which evolved from the original <i>pbmplus</i> package. The <i>Netpbm</i> suite, developed primarily by Bryan Henderson, is a collection of graphics programs and a programming library for handling many different graphic file formats. <i>ppmtoyuv</i>'s inclusion reflects the project's broad utility, enabling conversions vital for video production pipelines long before more comprehensive tools like <i>ffmpeg</i> became widespread. Its development has focused on robust and efficient conversion between the versatile PPM format and various YUV representations, catering to the specific needs of video processing workflows.


title: PARAMETERS
content:
<b><i>input_file.ppm</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the Portable Pixmap (PPM) image file to be processed. If this argument is omitted, <i>ppmtoyuvsplit</i> will read the PPM image data from standard input (stdin).<br><br>


title: DESCRIPTION
content:
<i>ppmtoyuvsplit</i> is a <I>Netpbm</I> utility designed to separate the color components of a <I>Portable Pixmap</I> (PPM) image into their respective YUV representation.<br><br>YUV is a color encoding system widely used in video systems, where 'Y' represents the luminance (brightness) component, and 'U' and 'V' represent the chrominance (color) components. The command reads a single PPM image from either a specified file or standard input. It then converts the RGB data of the PPM image into the YUV color space using a standard conversion matrix.<br><br>The output consists of three separate <I>Portable Graymap</I> (PGM) files: one for the Y component, one for the U component, and one for the V component. These PGM files represent the grayscale values of each respective YUV channel. This separation is particularly useful for tasks such as video compression, analysis, or processing where luminance and chrominance information needs to be handled independently.


title: CAVEATS
content:
The command outputs three separate PGM files for Y, U, and V, not a single interleaved YUV stream or a downsampled YUV format typically used in video (like YCbCr 4:2:0). The U and V components are output at the same resolution as the Y component, without any chrominance subsampling.<br><br>The conversion uses a fixed color space matrix, which might not be ideal for all YUV variants (e.g., BT.601 vs. BT.709).


title: OUTPUT FILE NAMING
content:
When an input filename is provided (e.g., <b>image.ppm</b>), the output files will be named <b>image_Y.pgm</b>, <b>image_U.pgm</b>, and <b>image_V.pgm</b>. If the input is read from standard input, the output files will be named <b>_Y.pgm</b>, <b>_U.pgm</b>, and <b>_V.pgm</b> by default.


title: COLOR SPACE CONVERSION
content:
The command performs a standard RGB to YUV (specifically, YCbCr) conversion. This is typically based on ITU-R BT.601 recommendations for standard definition television, which is a common choice for such utilities unless specified otherwise.


title: HISTORY
content:
<i>ppmtoyuvsplit</i> is part of the <I>Netpbm</I> project, a comprehensive suite of graphics file format converters and image processing tools. <I>Netpbm</I> originated from the <I>Pbmplus</I> package, developed by Jef Poskanzer in the late 1980s. It has been a staple in Unix-like environments for manipulating image files, particularly the "portable" formats (PBM, PGM, PPM), which are simple ASCII or raw binary formats designed for easy parsing and processing by command-line tools. <i>ppmtoyuvsplit</i> serves as a fundamental building block for advanced image and video processing workflows, leveraging the modularity characteristic of the <I>Netpbm</I> philosophy.


title: SYNOPSIS
content:
<i>ppmtv</i> [<b>-ntsc</b> | <b>-pal</b>] [<b>-overscan</b> <i>percent</i>] [<b>-square</b>] [<b>-half</b>] [<b>-gamma</b> <i>gamma</i>] [<b>-srgb</b> | <b>-notsrgb</b>] [<b>-dither</b>] [<b>-nodither</b>] [<b>-colors</b> <i>n</i>] [<b>-ncol</b> <i>n</i>] [<b>-maxcol</b> <i>n</i>] [<b>-cmap</b> <i>cmapfile</i>] [<b>-verbose</b>] [<i>inputfile</i>]


title: PARAMETERS
content:
<b><b>-ntsc</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optimize the output for NTSC television standards. This is the default if neither <b>-ntsc</b> nor <b>-pal</b> is specified.<br><br><b><b>-pal</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Optimize the output for PAL television standards.<br><br><b><b>-overscan</b> <i>percent</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the percentage of the image's width and height that is considered 'overscan' and will be cropped or scaled into the visible area. The default is 5 percent.<br><br><b><b>-square</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces the output image to have square pixels. This may result in an incorrect aspect ratio when viewed on a TV, as televisions typically have non-square pixels.<br><br><b><b>-half</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Halves the horizontal resolution of the output image. Useful for creating images suitable for older or lower-resolution TV displays.<br><br><b><b>-gamma</b> <i>gamma</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Applies a specified gamma correction to the image. This is crucial for accurate color representation, as computer monitors and TVs have different gamma curves. The default gamma is 2.2.<br><br><b><b>-srgb</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indicates that the input image is in the sRGB color space. This is the default behavior if no gamma option is specified.<br><br><b><b>-notsrgb</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Indicates that the input image is not sRGB, implying a linear light response, typically used with a custom <b>-gamma</b> value.<br><br><b><b>-dither</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces dithering when the image's color depth is reduced. Dithering helps to simulate a wider range of colors by interspersing pixels of different colors.<br><br><b><b>-nodither</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents dithering even if the image's color depth is reduced. This might lead to banding or posterization effects.<br><br><b><b>-colors</b> <i>n</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Reduces the image to a maximum of <i>n</i> colors using a color quantization algorithm, typically with dithering enabled by default.<br><br><b><b>-ncol</b> <i>n</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An alias for <b>-colors</b> <i>n</i>.<br><br><b><b>-maxcol</b> <i>n</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;An alias for <b>-colors</b> <i>n</i>.<br><br><b><b>-cmap</b> <i>cmapfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses the colors from the specified <i>cmapfile</i> (a PPM image) as the target color map for the output image. This ensures the output uses a predefined palette.<br><br><b><b>-verbose</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints informative messages about the image processing steps to standard error, including input/output dimensions, color information, and transformations applied.<br><br><b><i>inputfile</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The path to the input PPM image file. If omitted, <i>ppmtv</i> reads the PPM image from standard input.<br><br>


title: DESCRIPTION
content:
<i>ppmtv</i> is a command-line utility from the Netpbm image manipulation toolkit. Its primary function is to convert a Portable Pixmap (PPM) image file into another PPM file that is optimized for display on a standard NTSC or PAL television monitor.<br><br>Traditional computer displays and television screens have different characteristics, including pixel aspect ratios, overscan areas, and color reproduction capabilities. <i>ppmtv</i> addresses these differences by performing several transformations: it corrects the image's aspect ratio to prevent distortion on non-square TV pixels, adjusts for the TV's overscan area (the portion of the image that is typically cut off at the edges of the screen), and optionally reduces the color depth and applies dithering to simulate a wider range of colors within the television's limited palette.<br><br>This ensures that images originally designed for computer monitors appear correctly proportioned and visually appealing when viewed on a television. It reads a PPM image from standard input and writes the processed PPM image to standard output.


title: CAVEATS
content:
<i>ppmtv</i> is specifically designed for standard analog television displays (CRT-based NTSC/PAL systems). Results on modern digital displays (LCD, LED, OLED) via HDMI or other digital connections may vary, as these displays often handle aspect ratio and scaling differently. Using <b>-square</b> can lead to distorted images on televisions with non-square pixels. Color reduction and dithering, while necessary for some TV systems, can alter the artistic intent of the original image.


title: STANDARD INPUT/OUTPUT
content:
Like many Netpbm utilities, <i>ppmtv</i> is designed to operate as a filter in a pipeline. It reads a PPM image from standard input if no input file is specified and writes the processed PPM image to standard output. This allows for seamless integration with other commands, such as <i>cat</i>, <i>pnmscale</i>, or <i>convert</i>.


title: COLOR SPACE AND GAMMA CORRECTION
content:
Accurate color reproduction on a television display is critical, and <i>ppmtv</i> provides options to handle color space and gamma correction. The <b>-srgb</b> and <b>-notsrgb</b> options inform <i>ppmtv</i> about the input image's color profile, while the <b>-gamma</b> option allows for precise adjustment of the image's brightness curve to match the target display's characteristics, ensuring colors appear as intended on a TV.


title: HISTORY
content:
<i>ppmtv</i> is a component of the Netpbm image manipulation toolkit, which originated from the PBMplus package developed by Jef Poskanzer in the late 1980s. The Netpbm project evolved over time, becoming a widely used collection of command-line tools for processing various image formats, particularly the PNM (Portable Anymap) family. <i>ppmtv</i> was developed to address the specific challenges of displaying computer-generated graphics on consumer television sets during an era when such integration was common for video production, multimedia presentations, and early game development. Its design reflects the technical specifications and limitations of analog NTSC and PAL broadcast standards, making it a specialized tool for that particular conversion need.


title: DESCRIPTION
content:
ppmwheel is a utility from the <I>Netpbm</I> package designed to create a <I>PPM</I> (Portable Pixmap) image representing a standard color wheel.<br><br>The generated image displays a circular gradient. The center of the circle is white, and colors radiate outwards, representing increasing saturation. Simultaneously, colors vary circumferentially around the circle, representing a full range of hues. The circumference of the circle shows fully saturated hues.<br><br>It is commonly used for testing display devices, color printers, or simply for visual demonstration of color spaces. By default, it generates a 200x200 pixel image, but custom dimensions can be specified.


title: CAVEATS
content:
The command does not support any command-line options or flags for modifying its behavior beyond specifying image dimensions. It outputs directly to standard output, typically requiring redirection to a file. The output format is always PPM.


title: IMAGE DIMENSIONS
content:
The width and height values are optional <B>positional arguments</B> that define the output image's dimensions in pixels. If omitted, ppmwheel defaults to generating a 200x200 pixel image.<br><br>For example, to create a 400x300 color wheel image, you would use: ppmwheel 400 300 > wheel.ppm


title: OUTPUT FORMAT
content:
The output of ppmwheel is a <B>PPM</B> (Portable Pixmap) image, which is a plain text or binary format that can be viewed or converted using other <I>Netpbm</I> tools or image viewers that support the format. The output is sent to standard output (<B>stdout</B>) and typically needs to be redirected to a file.


title: HISTORY
content:
ppmwheel was originally authored by <B>Jef Poskanzer</B> and first copyrighted in <B>1989</B>. It is a foundational utility within the <I>Netpbm</I> toolkit, which has been instrumental in image processing on Unix-like systems since its inception.


title: DESCRIPTION
content:
The <b>pppconfig</b> command is a <i>curses</i>-based utility designed to simplify the configuration of Point-to-Point Protocol (PPP) connections on Linux systems. It provides a menu-driven interface that guides the user through the process of setting up dial-up modems, DSL connections, or other PPP-based network links. Rather than manually editing complex configuration files for the <b>pppd</b> daemon, <b>pppconfig</b> allows users to specify connection details such as ISP phone numbers, usernames, passwords, authentication methods (PAP/CHAP), and DNS settings. Upon completion, it generates or modifies the necessary configuration files in the <i>/etc/ppp/</i> directory, making it easier to establish and manage PPP sessions using commands like <b>pon</b> and <b>poff</b>.


title: CAVEATS
content:
<b>pppconfig</b> is largely considered a legacy tool for network configuration in modern Linux distributions. While still functional for dial-up or specific DSL setups, most contemporary systems utilize tools like <b>NetworkManager</b>, <b>systemd-networkd</b>, or simpler `ifupdown` configurations for managing network interfaces, including broadband connections. It typically requires root privileges to run, as it modifies system-wide network configuration files.


title: INTERACTIVE CONFIGURATION
content:
Unlike many command-line tools that accept parameters, <b>pppconfig</b> operates almost entirely through an interactive Text User Interface (TUI). Users navigate menus and input details using arrow keys and the Enter key, making it accessible even without deep knowledge of network configuration files.


title: GENERATED FILES
content:
After configuration, <b>pppconfig</b> creates or modifies several files in the <i>/etc/ppp/</i> directory, including: <br><i>/etc/ppp/peers/provider</i>: Defines the connection parameters for your ISP. <br><i>/etc/ppp/chap-secrets</i> or <i>/etc/ppp/pap-secrets</i>: Stores authentication credentials. <br><i>/etc/ppp/options</i>: General PPP options. <br>These files are then used by the <b>pppd</b> daemon.


title: HISTORY
content:
<b>pppconfig</b> emerged as a user-friendly front-end for the <b>pppd</b> daemon, particularly during an era when dial-up internet access was prevalent. It was a common utility in distributions like Debian and Ubuntu, aiming to abstract away the complexity of manual PPP configuration files. Its development and widespread usage peaked before the widespread adoption of graphical network management tools and ubiquitous broadband, which often use different underlying mechanisms (like DHCP over Ethernet) rather than PPP for primary internet access.


title: SYNOPSIS
content:
<b>pppd</b> [<I>tty_name</I>] [<I>speed</I>] [<I>local_IP</I>:<I>remote_IP</I>] [<I>options</I>]<br><b>pppd</b> <I>call</I> <I>profile_name</I> [<I>options</I>]


title: PARAMETERS
content:
<b><b>debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debugging mode, logging detailed information to system logs (syslog) or standard error.<br><br><b><b>nodetach</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>pppd</b> from detaching from the controlling terminal, useful for debugging.<br><br><b><b>noauth</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables peer authentication. The remote end is not required to authenticate itself.<br><br><b><b>user</b> <I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the username to be used for authenticating with the peer.<br><br><b><b>password</b> <I>secret</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the password to be used for authenticating with the peer. (Note: Using this option directly is insecure; prefer secret files).<br><br><b><b>ipcp-accept-remote</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows <b>pppd</b> to accept the remote IP address proposed by the peer during IPCP negotiation.<br><br><b><b>ipcp-accept-local</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Allows <b>pppd</b> to accept the local IP address proposed by the peer during IPCP negotiation.<br><br><b><b>defaultroute</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Adds a default route to the routing table through the PPP link upon connection establishment.<br><br><b><b>persist</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <b>pppd</b> to re-establish the connection if it is terminated unexpectedly.<br><br><b><b>connect</b> <I>script</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a shell script or command to execute to establish the physical link (e.g., dial a modem).<br><br><b><b>disconnect</b> <I>script</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a shell script or command to execute to terminate the physical link.<br><br><b><b>lock</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses UUCP-style lock files to ensure exclusive access to the serial device.<br><br><b><b>crtscts</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables hardware flow control (RTS/CTS) on the serial port.<br><br><b><b>modem</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses modem control lines (DTR, RTS, DCD, RI) for controlling the serial port.<br><br><b><b>call</b> <I>name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads configuration options from a named file in <I>/etc/ppp/peers/</I><I>name</I>.<br><br>


title: DESCRIPTION
content:
<b>pppd</b> (Point-to-Point Protocol daemon) is a widely used Linux daemon that implements the Point-to-Point Protocol (PPP). PPP is a data link layer protocol primarily used for establishing a direct connection between two networking nodes. Historically, <b>pppd</b> was crucial for dial-up internet access, allowing computers to connect to ISPs via modems.<br><br>Beyond modems, <b>pppd</b> supports various serial communication links, including ISDN, ADSL, and virtual private network (VPN) tunnels. It handles the negotiation of link control protocol (LCP) parameters, such as authentication (PAP and CHAP), data compression, and error correction.<br><br>Once the link is established, <b>pppd</b> proceeds with the network control protocol (NCP), typically IPCP (Internet Protocol Control Protocol), to negotiate IP addresses, DNS server addresses, and routing information. It can assign dynamic IP addresses to the local or remote end, add default routes, and manage network interfaces. Its flexibility and robustness have made it a cornerstone for many network configurations, even as direct Ethernet connections have become more common for broadband services.


title: CAVEATS
content:
<b>pppd</b> requires root privileges to configure network interfaces and manage system routes. Misconfiguration, especially concerning authentication (using PAP over unencrypted links) or allowing `noauth`, can pose significant security risks. It's crucial to protect secret files (<I>/etc/ppp/chap-secrets</I>, <I>/etc/ppp/pap-secrets</I>) with strict permissions. While still relevant for some specialized applications and VPNs, its direct usage for general internet access has largely been superseded by more modern broadband technologies.


title: CONFIGURATION FILES
content:
<b>pppd</b> relies heavily on a flexible configuration file system.<br><ul><li><I>/etc/ppp/options</I>: Global default options for all PPP connections.<br></li><li><I>/etc/ppp/peers/</I><I>name</I>: Specific options for named connections invoked with '<b>pppd call</b> <I>name</I>'.<br></li><li><I>/etc/ppp/chap-secrets</I>: Stores usernames and passwords for CHAP authentication.<br></li><li><I>/etc/ppp/pap-secrets</I>: Stores usernames and passwords for PAP authentication.<br></li></ul><br>It's critical to set strict permissions (e.g., 600) on secret files to prevent unauthorized access.


title: PLUGINS
content:
<b>pppd</b> supports dynamic plugins to extend its functionality, allowing for custom authentication methods, connection management, or integration with external systems. This modularity enhances its adaptability to various network environments.


title: HISTORY
content:
The development of PPP, and subsequently <b>pppd</b>, began in the early 1990s as a successor to SLIP (Serial Line Internet Protocol) to provide a standard method for encapsulating network layer protocols over a serial link. PPP's robustness, multi-protocol support, and built-in authentication mechanisms (PAP, CHAP) quickly made it the standard for dial-up internet access. <b>pppd</b> became the primary Linux implementation of this protocol, crucial for bringing internet connectivity to early Linux users via modems.<br><br>Over time, its usage expanded beyond traditional modems to ISDN, ADSL (via PPPoE), and establishing VPN tunnels. While direct dial-up usage has declined significantly, <b>pppd</b> remains a vital component in various embedded systems, specialized networking appliances, and for certain types of VPNs where its flexibility and maturity are still highly valued.


title: SEE ALSO
content:
<b>chat</b>(8), <b>pon</b>(8), <b>poff</b>(8), <b>pppoe</b>(8), <b>ifconfig</b>(8), <b>ip</b>(8), <b>route</b>(8)


title: SYNOPSIS
content:
pppd-radattr <I>interface-name</I> <I>tty-device</I> <I>speed</I> <I>local-IP</I> <I>remote-IP</I> [<I>ipparam</I>]


title: PARAMETERS
content:
<b><I>interface-name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the PPP network interface created (e.g., ppp0).<br><br><b><I>tty-device</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the TTY device or network interface used for the PPP connection (e.g., /dev/ttyS0, eth0).<br><br><b><I>speed</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The speed of the connection in bits per second.<br><br><b><I>local-IP</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The local IP address assigned to the PPP interface on the server side.<br><br><b><I>remote-IP</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The remote IP address assigned to the PPP client.<br><br><b>[<I>ipparam</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;An optional string parameter, if specified via the <I>ipparam</I> option in pppd's configuration.<br><br>


title: DESCRIPTION
content:
The <b>pppd-radattr</b> command is a specialized utility or script primarily used in conjunction with the <I>PPP Daemon</I> (pppd) to process and apply <I>RADIUS</I> attributes received during a PPP session's authentication or accounting phase.<br><br>When pppd is configured to use a RADIUS plugin (like `radius.so`), the RADIUS server can return various attributes specific to the authenticated user or service. These attributes are then exposed to pppd's various hook scripts (such as <I>ip-up</I>, <I>ip-down</I>, or <I>auth-up</I>) as environment variables.<br><br><b>pppd-radattr</b>'s role is to parse these environment variables, which typically begin with `RADIUS_` (e.g., `RADIUS_Framed_IP_Address`, `RADIUS_DNS_Server_1`, `RADIUS_Session_Timeout`), and then perform actions based on them. These actions might include assigning a dynamic IP address to the PPP interface, configuring DNS servers for the connected client, applying specific routing rules, setting session-specific timeouts, or updating system logs.<br><br>It acts as a crucial link in dynamically provisioning and managing PPP connections based on policies defined in a central RADIUS server, enabling flexible and scalable network access.


title: CAVEATS
content:
<b>pppd-radattr</b> is typically not a standalone executable invoked directly by users. It is almost always a helper script or program that is invoked by the <b>pppd</b> daemon's various callback scripts (e.g., <I>ip-up</I>, <I>ip-down</I>, <I>auth-up</I>). Its exact implementation and behavior can vary significantly between different Linux distributions or custom system configurations, as it is often a shell script or a small program specifically written or adapted for a particular environment to handle RADIUS attributes.


title: ENVIRONMENT VARIABLES
content:
The primary way <b>pppd-radattr</b> receives RADIUS attribute information is through environment variables passed to it by <b>pppd</b>. When <b>pppd</b> uses a RADIUS plugin, it typically populates the environment with variables prefixed with `RADIUS_` for each received RADIUS attribute. For example:<br><I>RADIUS_Framed_IP_Address</I>: The IP address assigned to the client.<br><I>RADIUS_DNS_Server_1</I>, <I>RADIUS_DNS_Server_2</I>: DNS server addresses.<br><I>RADIUS_Session_Timeout</I>: Maximum session duration.<br><I>RADIUS_Acct_Session_Id</I>: RADIUS accounting session identifier.<br>These environment variables allow the script to dynamically configure the system based on policies fetched from the RADIUS server.


title: TYPICAL USE CASE
content:
In a common scenario, when a user connects via PPP (e.g., dial-up, PPPoE, PPTP), <I>pppd</I> authenticates them against a <I>RADIUS</I> server. The RADIUS server responds with attributes like the IP address the client should use, DNS servers, and potentially routing information. An <I>ip-up</I> script, after successful authentication, then invokes <b>pppd-radattr</b>. This script reads the RADIUS attributes from environment variables and uses them to configure the network interface for the PPP session (e.g., by adding routes, setting DNS, or applying firewall rules), thereby automating the dynamic assignment of network parameters to clients.


title: HISTORY
content:
The concept behind <b>pppd-radattr</b> emerged with the widespread adoption of <I>RADIUS</I> as a central authentication, authorization, and accounting (AAA) protocol in large-scale network deployments, particularly for ISPs and corporate VPNs. As <I>pppd</I> gained RADIUS plugin capabilities, there was a growing need for a mechanism to automatically apply the dynamic configurations (like IP addresses, DNS servers, etc.) provided by the RADIUS server to the active PPP session. Rather than being a single, standardized command with a linear history, <b>pppd-radattr</b> represents a functional component or pattern implemented through various scripts and utilities over time to fulfill this crucial role in dynamic PPP session management.


title: SYNOPSIS
content:
<b>pppd</b> [<i>options</i>] <b>plugin</b> <i>radius.so</i> [<b>radius-config-file</b> <i>/etc/radiusclient-ng/radiusclient.conf</i>] ...


title: PARAMETERS
content:
<b><b>plugin</b> <i>&lt;path_to_plugin.so&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Loads a shared library plugin. For RADIUS support, this is commonly <i>radius.so</i> or <i>pppd-radius.so</i>, which provides the RADIUS client functionality to <i>pppd</i>.<br><br><b><b>radius-config-file</b> <i>&lt;path_to_file&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternate path to the RADIUS client configuration file. The default path is typically <i>/etc/radiusclient-ng/radiusclient.conf</i> or <i>/etc/radiusclient.conf</i>.<br><br><b><b>auth</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Requires the peer to authenticate itself. Essential when using RADIUS for authentication.<br><br><b><b>require-chap</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <i>pppd</i> to require CHAP authentication. RADIUS servers typically support CHAP.<br><br><b><b>require-pap</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <i>pppd</i> to require PAP authentication. RADIUS servers typically support PAP.<br><br><b><b>user</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the username to use for authentication. This can be overridden by the remote peer or specified by RADIUS.<br><br><b><b>name</b> <i>&lt;name&gt;</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the local system name for authentication. This name might be used as the NAS-Identifier in RADIUS requests.<br><br><b><b>debug</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debugging output, which is invaluable for troubleshooting RADIUS communication issues.<br><br>


title: DESCRIPTION
content:
<i>pppd-radius</i> refers to the integration of the <b>Point-to-Point Protocol daemon (pppd)</b> with <b>RADIUS (Remote Authentication Dial-In User Service)</b> for centralized Authentication, Authorization, and Accounting (AAA).<br><br>Instead of <i>pppd</i> relying on local files (e.g., <i>/etc/ppp/chap-secrets</i>) or PAM for user authentication, it queries a remote RADIUS server. This setup is crucial for Internet Service Providers (ISPs), VPN servers, and other network access servers that require scalable and centralized user management.<br><br><i>pppd</i> typically achieves this by loading a RADIUS client library (such as <i>libradiusclient-ng</i> or <i>radcli</i>) as a plugin. It sends authentication requests (Access-Request) to verify user credentials and accounting information (Accounting-Request) to track session details like start/stop times and data usage.


title: CAVEATS
content:
Using <i>pppd-radius</i> requires careful configuration and attention to security:<br><br><b>1. RADIUS Server Setup:</b> A functioning RADIUS server (e.g., FreeRADIUS) must be properly configured to handle authentication and accounting requests from the <i>pppd</i> client.<br><b>2. Configuration File:</b> The <i>radiusclient.conf</i> file must accurately define the RADIUS server addresses, shared secrets, and other client-specific settings.<br><b>3. Security:</b> Shared secrets between <i>pppd</i> and the RADIUS server must be strong and kept confidential. Ensure UDP ports 1812 (authentication) and 1813 (accounting) are correctly firewalled.<br><b>4. Plugin Dependency:</b> The RADIUS functionality relies on a specific <i>pppd</i> plugin (e.g., from the <i>radiusclient-ng</i> package), which might not be pre-installed or available on all systems.<br><b>5. Troubleshooting:</b> Debugging can be complex, involving analysis of <i>pppd</i> logs, RADIUS server logs, and potentially network packet captures.


title: CONFIGURATION FILE DETAILS
content:
The core configuration for the RADIUS client is typically found in <i>/etc/radiusclient-ng/radiusclient.conf</i> or <i>/etc/radiusclient.conf</i>. Key settings within this file include:<br><br><ul><li><b>servers:</b> Defines the IP addresses or hostnames of RADIUS authentication and accounting servers, along with their shared secrets.</li><li><b>auth_port, acct_port:</b> Specifies the UDP ports for authentication (default 1812) and accounting (default 1813).</li><li><b>dictionary:</b> Path to the RADIUS dictionary file, which defines the attributes and their corresponding values used in RADIUS packets.</li><li><b>login_tries, login_timeout:</b> Controls retransmission attempts and timeout values for RADIUS requests.</li></ul>


title: RADIUS ATTRIBUTES AND FUNCTIONALITY
content:
A RADIUS server can return various attributes to <i>pppd</i> upon successful authentication, which can control aspects of the PPP session. These attributes often include:<br><br><ul><li><b>IP Address Assignment:</b> e.g., <i>Framed-IP-Address</i>, <i>Framed-IP-Netmask</i>.</li><li><b>DNS Server Assignment:</b> e.g., <i>MS-DNS1</i>, <i>MS-DNS2</i>.</li><li><b>Session Control:</b> e.g., <i>Session-Timeout</i> (maximum session duration), <i>Idle-Timeout</i>.</li><li><b>Bandwidth Management:</b> e.g., using Vendor-Specific Attributes like <i>Cisco-AVPair</i> for traffic shaping.</li><li><b>Accounting:</b> <i>pppd</i> sends accounting start and stop packets, including details like <i>Acct-Status-Type</i>, <i>Acct-Session-Id</i>, <i>Acct-Input-Octets</i>, and <i>Acct-Output-Octets</i>.</li></ul>This allows centralized control over client network parameters and comprehensive session logging.


title: HISTORY
content:
The Point-to-Point Protocol daemon (<i>pppd</i>) has historically offered various authentication mechanisms. As network access servers grew in complexity and scale, the need for centralized user management became paramount. RADIUS emerged as the industry standard for Authentication, Authorization, and Accounting (AAA).<br><br>Integration with RADIUS for <i>pppd</i> became commonplace through dynamically loadable plugins. Libraries like <i>radiusclient</i> and later <i>radiusclient-ng</i> (which provides the <i>radius.so</i> plugin) were developed to enable <i>pppd</i> to communicate with RADIUS servers, allowing for a robust and scalable solution for managing remote access users, superseding simpler local authentication methods.


title: PARAMETERS
content:
<b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Raw output</i>. Dumps the raw log data without interpretation, showing what <i>pppdump</i> received.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Summarize</i>. Provides a brief summary of the connection parameters established during the PPP session.<br><br><b>-t</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Timestamp</i>. Shows absolute timestamps for each log entry, rather than relative times or no times.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Verbose</i>. Increases the verbosity of the output, showing more details about each parsed event.<br><br><b>-n</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>No interpretation</i>. Prevents interpretation of numeric values (e.g., protocol numbers), showing them as raw numbers instead of human-readable names.<br><br><b>-p <protocol></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Filter by protocol</i>. Displays only messages related to a specific PPP protocol (e.g., LCP, IPCP, CHAP). Use <i>-l</i> to list available protocols.<br><br><b>-o <option></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Filter by option</i>. Filters output to show messages related to a specific PPP option negotiated (e.g., MRU, authentication type). Use <i>-l</i> to list available options.<br><br><b>-f <field></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Filter by field</i>. Filters output to show messages related to a specific field within a protocol message. Use <i>-l</i> to list available fields.<br><br><b>-i <interface></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Filter by interface</i>. Shows messages only for a specified network interface, if multiple interfaces are active or mentioned in the logs.<br><br><b>-u <peer></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Filter by peer</i>. Shows messages only for a specific peer, which could be identified by its IP address or hostname if logged.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>List filters</i>. Lists available protocol, option, field, interface, and peer filters that <i>pppdump</i> can recognize and filter by.<br><br><b>-h</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Help</i>. Displays a brief help message showing command-line options and exits.<br><br><b>-V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Version</i>. Displays version information for <i>pppdump</i> and exits.<br><br>


title: DESCRIPTION
content:
<i>pppdump</i> is a utility designed to parse and interpret the detailed debug output generated by the <b>ppp</b> daemon (<i>pppd</i>). When <i>pppd</i> is configured to log extensive debugging information (typically by enabling the <i>debug</i> option), its logs can become very verbose and challenging to read directly. <i>pppdump</i> transforms these raw, often cryptic, log entries into a more human-readable and structured format.<br><br>It's an invaluable tool for network administrators and developers troubleshooting Point-to-Point Protocol (PPP) connections. By analyzing the output, one can gain insight into the various phases of a PPP session, including Link Control Protocol (LCP) negotiation, authentication (PAP/CHAP), and Network Control Protocol (NCP) negotiations like IP Control Protocol (IPCP) for IP address assignment. It helps in identifying why a PPP link fails to establish, why authentication might be failing, or why network parameters aren't being correctly assigned.<br><br><i>pppdump</i> can read log data from standard input or directly from specified log files, making it flexible for real-time monitoring via pipes or post-mortem analysis of archived logs. It provides options to filter by protocol, interface, or peer, allowing users to focus on specific aspects of the communication.


title: CAVEATS
content:
<i>pppdump</i> primarily relies on <i>pppd</i>'s debug logging. If <i>pppd</i> is not run with sufficient debug options (e.g., by adding the <i>debug</i> keyword to its configuration), <i>pppdump</i> will have little or no meaningful information to process.<br><br>The output can be extremely verbose for long-running connections or high traffic, potentially making it hard to pinpoint specific issues without applying filters.<br><br>Interpretation accuracy might vary slightly with different <i>pppd</i> versions or non-standard log formats, though it generally handles standard <i>pppd</i> debug output well.


title: ENABLING <I>PPPD</I> DEBUGGING
content:
For <i>pppdump</i> to be effective, <i>pppd</i> must be configured to log detailed debug information. This is typically achieved by adding the <i>debug</i> option to <i>pppd</i>'s configuration file (e.g., <i>/etc/ppp/options</i> or a peer-specific options file) or by passing it as a command-line argument when starting <i>pppd</i>. Without this, <i>pppdump</i> will not find the necessary diagnostic data in the logs.<br><br><i>Example:</i> Add <code>debug</code> to <i>/etc/ppp/options</i>.


title: TYPICAL USAGE
content:
A common workflow involves piping the output of <i>tail -f</i> (for real-time monitoring) or <i>cat</i> (for file analysis) of the <i>pppd</i> log file into <i>pppdump</i>.<br><br><i>Example for real-time monitoring:</i> <code>tail -f /var/log/syslog | pppdump</code><br><i>Example for analyzing a log file:</i> <code>pppdump /var/log/ppp.log</code>


title: HISTORY
content:
<i>pppdump</i> is an integral part of the <i>ppp</i> package, which has been a cornerstone of Unix-like operating systems for implementing PPP connections since the early 1990s. Its development closely parallels that of <i>pppd</i> itself, providing a crucial debugging layer for a protocol that was, for decades, essential for dial-up internet access. While the dominance of dial-up has waned, <i>pppdump</i> remains relevant for diagnosing issues in modern PPP applications such as PPPoE (often used with DSL/fiber connections), PPTP, and L2TP VPNs. Its purpose has consistently been to demystify the complex state machine and negotiation processes of PPP, making it easier for system administrators to identify and resolve connectivity problems.


title: PARAMETERS
content:
<b>-I <I>interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Ethernet interface to use for PPPoE (e.g., <I>eth0</I>). This option is often mandatory for establishing a connection.<br><br><b>-A</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Performs an auto-discovery of PPPoE Access Concentrators and prints their names and service names found. Useful for initial setup.<br><br><b>-S <I>service_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the PPPoE service name to request during session establishment. Often required by ISPs.<br><br><b>-C <I>AC_name</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Access Concentrator name to connect to, overriding auto-discovery.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Runs <b>pppoe</b> in stand-alone (daemon) mode, forking into the background after connection establishment.<br><br><b>-k</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Keeps <b>pppoe</b> in the foreground; do not fork into the background. Useful for debugging or when running from a script.<br><br><b>-P <I>pidfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Writes the Process ID (PID) of the <b>pppoe</b> daemon to the specified file when running in daemon mode.<br><br><b>-L <I>logfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Appends all diagnostic output to the specified log file instead of standard error.<br><br><b>-T <I>timeout</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum number of seconds to wait for a PPPoE session to be established.<br><br><b>-d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debugging output, printing discovery and session details to the console or log file.<br><br><b>-V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version number of the <b>pppoe</b> client and exits.<br><br>


title: DESCRIPTION
content:
The <b>pppoe</b> command is a user-space client program for establishing a Point-to-Point Protocol over Ethernet (PPPoE) connection. It is commonly used to connect to Internet service providers (ISPs) that deliver services, primarily broadband DSL or cable, via PPPoE.<br><br>The <b>pppoe</b> client handles the PPPoE Discovery stage, which involves finding an access concentrator (AC) and establishing a PPPoE session. Once a session is successfully established, <b>pppoe</b> typically forks and executes the <b>pppd</b> (Point-to-Point Protocol daemon) to manage the actual PPP session, including authentication (e.g., PAP, CHAP), IP address assignment, and routing. It supports various options for specifying the Ethernet interface, service name, AC name, and debugging levels, making it a flexible tool for managing PPPoE-based network connectivity.


title: CAVEATS
content:
The <b>pppoe</b> client primarily handles the PPPoE discovery and session establishment. The actual PPP session management (authentication, IP assignment, routing) is handed off to the <b>pppd</b> daemon, which must be installed and correctly configured separately. Firewall rules might block PPPoE traffic (Ethertype 0x8863, 0x8864), preventing connection. Only one <b>pppoe</b> instance typically runs per interface for a full session.


title: CONFIGURATION WITH PPPD
content:
The <b>pppoe</b> client handles the Ethernet-level PPPoE discovery and session establishment. However, the actual Point-to-Point Protocol (PPP) session, including user authentication (PAP/CHAP), IP address assignment, and routing, is managed by the <b>pppd</b> daemon. Therefore, successful PPPoE connectivity often requires proper configuration of <b>pppd</b> files such as <I>/etc/ppp/chap-secrets</I>, <I>/etc/ppp/pap-secrets</I>, and common options in <I>/etc/ppp/options</I> or <I>/etc/ppp/options.pppoe</I>.


title: TYPICAL WORKFLOW
content:
A common workflow for establishing a PPPoE connection involves:<br>1. <B>Discovery:</B> Running <I>sudo pppoe -A</I> to find available Access Concentrators and service names.<br>2. <B>Connection Initiation:</B> Executing <I>sudo pppoe -I &lt;interface&gt; -s [-S &lt;service_name&gt;] [-C &lt;AC_name&gt;]</I> to initiate the PPPoE session. This typically forks and runs <b>pppd</b>.<br>3. <B>Authentication:</B> <b>pppd</b> then handles authentication with the ISP using credentials configured in <I>/etc/ppp/*-secrets</I>.<br>4. <B>IP Assignment & Routing:</B> Once authenticated, <b>pppd</b> obtains an IP address and configures network routing.


title: HISTORY
content:
The <b>pppoe</b> command is a core component of the <I>rp-pppoe</I> (Roaring Penguin PPPoE) client package, developed by David F. Skoll. It emerged in the early 2000s as a crucial tool for Linux users to connect to DSL internet services that widely adopted the PPPoE protocol. Its robust and reliable implementation has made it a standard utility for broadband connectivity on Linux systems for decades.


title: PARAMETERS
content:
<b><I>ethernet_interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;The name of the Ethernet interface (e.g., `eth0`, `enp0s3`) connected to the PPPoE modem. If not provided, it's typically read from configuration.<br><br><b>USER</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The PPPoE username required for authentication with the service provider. Often set in `<i>/etc/ppp/pppoe.conf</i>`.<br><br><b>PASSWORD</b><br>&nbsp;&nbsp;&nbsp;&nbsp;The PPPoE password for authentication. Also typically defined in `<i>/etc/ppp/pppoe.conf</i>`.<br><br><b>AC_NAME</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Optional) Specifies the desired PPPoE Access Concentrator name. If omitted, the first discovered AC is used.<br><br><b>SERVICE_NAME</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Optional) Specifies the desired PPPoE Service-Name. If omitted, any service is accepted.<br><br><b>DEMAND</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Optional) If set to `yes`, the connection is established only when network traffic is detected, otherwise it remains active.<br><br><b>DNS[1,2]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;(Optional) Specifies static DNS server IP addresses to be used instead of those provided by the ISP.<br><br>


title: DESCRIPTION
content:
The <b>pppoe-connect</b> command is a crucial shell script, typically part of the `rp-pppoe` (Roaring Penguin PPPoE) client suite, designed to establish and manage a Point-to-Point Protocol over Ethernet (PPPoE) broadband internet connection. It is commonly used for DSL and some fiber-optic internet services that require PPPoE encapsulation.<br><br>Unlike a standalone executable, <b>pppoe-connect</b> acts as a wrapper script that orchestrates the connection process. It reads essential configuration parameters, such as the Ethernet interface, username, and password, primarily from the `<i>/etc/ppp/pppoe.conf</i>` file. Once configured, it initiates the PPPoE discovery phase to locate the Access Concentrator and then invokes the underlying <b>pppd</b> (PPP Daemon) to negotiate the PPP session, handle authentication (e.g., PAP or CHAP), obtain an IP address, and set up routing.<br><br>Users typically do not interact with <b>pppoe-connect</b> directly for initial setup, instead using higher-level configuration utilities like <b>pppoeconf</b> (Debian/Ubuntu) or <b>adsl-setup</b> (Red Hat/CentOS) which create the necessary configuration files. However, <b>pppoe-connect</b> is the script that ultimately performs the connection when activated by commands like <b>pppoe-start</b> or a system's network management service. It's vital for maintaining persistent PPPoE links on Linux systems.


title: CAVEATS
content:
<ul><li>Requires `root` privileges to establish and manage network interfaces.</li><li>Heavily relies on external configuration files, primarily `<i>/etc/ppp/pppoe.conf</i>`, for its operational parameters.</li><li>It is a shell script wrapper for <b>pppd</b>, not a standalone binary that directly implements PPPoE.</li><li>Does not provide interactive configuration; dedicated utilities like <b>pppoeconf</b> or <b>adsl-setup</b> are used for that purpose.</li></ul>


title: CONFIGURATION FILES
content:
The primary configuration for <b>pppoe-connect</b> resides in `<i>/etc/ppp/pppoe.conf</i>`. This file defines crucial variables like the `ETH` (Ethernet interface), `USER` (username), and `PASSWORD`. Additionally, <b>pppoe-connect</b> often utilizes or creates files in `<i>/etc/ppp/peers/</i>` (e.g., `<i>/etc/ppp/peers/pppoe</i>`) which contain <b>pppd</b>-specific options for the PPPoE connection.


title: OPERATION FLOW
content:
When executed, <b>pppoe-connect</b> typically performs the following sequence: it sources configuration, ensures the specified Ethernet interface is up, initiates PPPoE discovery to find an Access Concentrator, negotiates a PPPoE session, and then hands over control to the <b>pppd</b> daemon. <b>pppd</b> then handles the detailed PPP session management, including authentication (PAP, CHAP), IP address negotiation (via IPCP), and setting up routes and DNS information, ensuring the broadband connection is fully established.


title: HISTORY
content:
The <b>pppoe-connect</b> script is a core component of the `rp-pppoe` (Roaring Penguin PPPoE Client) suite, which was developed in the early 2000s to provide robust PPPoE support for Linux systems. At the time, DSL internet was becoming widespread, and <b>rp-pppoe</b>, including <b>pppoe-connect</b>, was crucial for enabling Linux users to access these services. While modern network managers often abstract away the direct use of these scripts, <b>pppoe-connect</b> remains a fundamental tool for manual PPPoE configurations and in environments where graphical interfaces are not used.


title: SEE ALSO
content:
<b>pppd</b>(8), <b>pppoe</b>(8), <b>pppoe-start</b>(8), <b>pppoe-stop</b>(8), <b>pppoe-status</b>(8), <b>pppoeconf</b>(8), <b>adsl-setup</b>(8)


title: PARAMETERS
content:
<b><b>-i</b> <I>interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Listen on this Ethernet interface for PPPoE packets. This option can be specified multiple times to listen on several interfaces, treating them as a single relay group.<br><br><b><b>-S</b> <I>interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Designates an Ethernet interface as connected to the PPPoE server side. PADI packets received on other interfaces will be forwarded out of this interface.<br><br><b><b>-C</b> <I>interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Designates an Ethernet interface as connected to the PPPoE client side. PADI packets received on this interface will be forwarded towards the server.<br><br><b><b>-D</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debugging mode. The daemon will not fork, and verbose debug messages will be printed to standard error.<br><br><b><b>-u</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the daemon from changing its UID/GID to 'nobody'. It will run with the privileges of the user who started it.<br><br><b><b>-P</b> <I>pidfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative PID file path. By default, <i>pppoe-relay</i> uses /var/run/pppoe-relay.pid.<br><br><b><b>-F</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents the daemon from forking into the background. It will run in the foreground.<br><br><b><b>-A</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables the addition of the 'Agent-Circuit-ID' and 'Agent-Remote-ID' tags to PADI/PADS packets. By default, <i>pppoe-relay</i> adds these tags.<br><br><b><b>-B</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables broadcast PADI packets. When a PADI packet is received, <i>pppoe-relay</i> will broadcast it on all other relay interfaces instead of unicasting to a known server.<br><br><b><b>-h</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays a brief help message and exits.<br><br><b><b>-V</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the version information and exits.<br><br>


title: DESCRIPTION
content:
<i>pppoe-relay</i> is a daemon that acts as a transparent bridge for PPPoE (Point-to-Point Protocol over Ethernet) discovery and session packets. Its primary function is to forward these packets between multiple Ethernet interfaces, effectively allowing PPPoE clients and servers to communicate even when they are not on the same broadcast domain or directly connected. This is particularly useful in network environments where PPPoE traffic needs to traverse non-PPPoE-aware segments, such as certain Wi-Fi networks, corporate LANs, or when bridging between different VLANs. The relay listens for PPPoE Active Discovery Initiation (PADI) packets from clients on specified interfaces, forwards them towards the server, and then relays subsequent session packets once a connection is established. It ensures that the client and server can establish and maintain a PPPoE session through an intermediary device.


title: CAVEATS
content:
<i>pppoe-relay</i> operates at a low level, forwarding discovery and session packets. While it's transparent, it's crucial to ensure proper network segmentation and security. If used on a publicly accessible network, it could potentially be exploited to relay unauthorized PPPoE connections. It does not provide any form of authentication or encryption for the relayed traffic itself, relying on the underlying PPPoE session for that. Performance can be a consideration in high-traffic environments, as all PPPoE packets must traverse the relay.


title: OPERATION MODES
content:
<i>pppoe-relay</i> can operate in several modes:<br>1. <b>General Relay</b>: By specifying multiple <I>-i interface</I> options, <I>pppoe-relay</I> will relay traffic between any of these interfaces.<br>2. <b>Client/Server Explicit</b>: By specifying <I>-C interface</I> (client-facing) and <I>-S interface</I> (server-facing), the relay explicitly defines the direction of initial discovery packets, though session packets are relayed bidirectionally. This mode provides more control over the flow of discovery traffic.


title: TAGGING AND IDENTIFICATION
content:
By default, <I>pppoe-relay</I> adds Agent-Circuit-ID and Agent-Remote-ID tags to PADI and PADS packets. These tags contain information about the interface and MAC address of the client and relay, which can be useful for PPPoE servers to identify the origin of the connection. The <I>-A</I> option disables this behavior if it's not desired or causes compatibility issues.


title: HISTORY
content:
<i>pppoe-relay</i> is part of the <I>rp-pppoe</I> (Roaring Penguin PPPoE) package, an open-source implementation of PPPoE for Linux and other Unix-like systems. Developed to provide robust PPPoE client and server capabilities, the <I>pppoe-relay</I> utility was included to address the need for bridging PPPoE traffic across disparate network segments, a common requirement in environments like DSL, cable modem, and wireless access points where PPPoE clients and servers are not directly connected.


title: PARAMETERS
content:
<b>-I <i>interface</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the Ethernet interface on which <b>pppoe-server</b> should listen for PPPoE discovery packets. This is a mandatory option.<br><br><b>-T <i>timeout</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the timeout in seconds for PADI packets. Sessions that don't transition from PADI to PADR within this time will be dropped.<br><br><b>-S <i>service_name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a service name that the AC will offer. Clients requesting this specific service name will be served. If omitted, the server will offer any service.<br><br><b>-p <i>plugin_path</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the path to a shared library plugin to be loaded by the server. This is typically used for advanced features or custom session management.<br><br><b>-L <i>local_IP</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the local IP address for the PPP interface created for each session. This is the server-side IP address.<br><br><b>-R <i>remote_IP_range</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Defines a range of remote IP addresses (e.g., '192.168.1.100-192.168.1.200') from which <i>pppd</i> will allocate addresses to clients. Alternatively, a single IP or 'dynamic' can be used.<br><br><b>-C <i>ac_name</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the Access Concentrator name to be advertised in PADO packets. Defaults to the hostname.<br><br><b>-s</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Causes <b>pppoe-server</b> to spawn the <i>pppoed</i> helper program for each session. This is generally the default and recommended behavior for proper session management.<br><br><b>-u</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <b>pppoe-server</b> to use its own built-in <i>pppoed</i> helper for session handling, rather than an external one. This is typically the default.<br><br><b>-x <i>max_sessions</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum number of concurrent PPPoE sessions the server will allow. New sessions will be rejected once this limit is reached.<br><br><b>-o <i>pppd_options_file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an additional options file to be passed to each <i>pppd</i> process spawned by the server. This allows for custom <i>pppd</i> configurations.<br><br><b>-k</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs the server to keep the <i>pppd</i> process running even if it becomes unresponsive or exits unexpectedly. Use with caution.<br><br><b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Restricts sessions to one per MAC address. If a client with an existing session attempts to connect again, the old session will be terminated.<br><br><b>-d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables debugging output. Increases verbosity, helpful for troubleshooting.<br><br><b>-V</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prints the version number of the <b>pppoe-server</b> and exits.<br><br>


title: DESCRIPTION
content:
The <b>pppoe-server</b> command acts as a PPPoE (Point-to-Point Protocol over Ethernet) Access Concentrator (AC). It listens for PPPoE discovery packets (PADI) from clients on a specified Ethernet interface. Upon receiving a discovery request, it offers a service (PADO) and, if accepted by the client (PADR), establishes a PPPoE session (PADS).<br><br>Once a session is established, <b>pppoe-server</b> spawns a <i>pppd</i> (Point-to-Point Protocol daemon) process for each client. This <i>pppd</i> instance then handles the actual PPP negotiation, authentication (typically via PAM, RADIUS, or a local `chap-secrets` file), and IP address assignment. It essentially bridges the Ethernet frames from the PPPoE session into a PPP link, allowing clients to obtain IP addresses and access network resources, commonly the internet.<br><br>It's widely used by ISPs and network administrators to provide internet access over Ethernet-based infrastructure, such as ADSL or fiber modems operating in bridge mode, allowing multiple clients to connect and authenticate centrally.


title: CAVEATS
content:
<b>pppoe-server</b> relies heavily on the <i>pppd</i> daemon for session management, authentication, and IP assignment. Proper configuration of <i>pppd</i>, including authentication methods (e.g., PAM, RADIUS, or <i>/etc/ppp/chap-secrets</i>) and IP address pools, is crucial for a functional server.<br><br>Firewall rules are essential to protect the server and correctly route traffic. Ensure that the specified Ethernet interface is not already in use by other services that might conflict with PPPoE.<br><br>Scaling to a very large number of concurrent sessions may require careful system tuning and resource allocation.


title: AUTHENTICATION AND IP ASSIGNMENT
content:
<b>pppoe-server</b> itself does not handle user authentication or IP address allocation directly. Instead, it delegates these critical functions to the <i>pppd</i> (Point-to-Point Protocol daemon) process it spawns for each session. <i>pppd</i> can then be configured to use various authentication mechanisms, such as PAM (Pluggable Authentication Modules), RADIUS (Remote Authentication Dial-In User Service), or local files like <i>/etc/ppp/chap-secrets</i> and <i>/etc/ppp/pap-secrets</i>. Similarly, IP address assignment is handled by <i>pppd</i> based on its configuration, often using the specified local and remote IP options or a RADIUS server.


title: DEPENDENCIES
content:
The primary and essential dependency for <b>pppoe-server</b> to function correctly is the <i>pppd</i> (Point-to-Point Protocol daemon). <b>pppoe-server</b> acts as a front-end to negotiate the PPPoE session, but the actual PPP link layer, authentication, and IP management are handled by a dedicated <i>pppd</i> instance for each connected client. Ensure <i>pppd</i> is installed and properly configured on your system.


title: HISTORY
content:
The <b>pppoe-server</b> command is part of the <i>rp-pppoe</i> (Roaring Penguin PPPoE) package, which was one of the earliest and most widely adopted open-source implementations of PPPoE for Linux. Developed by Roaring Penguin Software, it gained prominence in the early 2000s as ADSL internet access became widespread, providing a robust and flexible solution for both client and server-side PPPoE operations. Its design emphasizes modularity by leveraging the existing <i>pppd</i> daemon for PPP session handling.


title: DESCRIPTION
content:
<i>pppoe-setup</i> is an interactive shell script designed to simplify the configuration of a PPPoE (Point-to-Point Protocol over Ethernet) Internet connection on a Linux system. It forms a key part of the <i>rp-pppoe</i> client software suite, guiding the user through a series of prompts to gather essential connection details.<br><br>Users are asked for parameters such as the Ethernet interface connected to the DSL/cable modem (e.g., <i>eth0</i>), their PPPoE username and password, whether to use on-demand dialing, idle timeout settings, and primary/secondary DNS server addresses. It also offers options for firewall configuration, including NAT/masquerading and incoming firewall rules. Crucially, <i>pppoe-setup</i> prompts if the connection should be initiated automatically at boot time.<br><br>Upon successful completion, the script generates or updates configuration files, typically <i>/etc/ppp/pppoe.conf</i>, which are then utilized by companion commands like <i>pppoe-start</i> and <i>pppoe-stop</i>. This interactive approach significantly streamlines the initial setup, removing the need for manual editing of complex configuration files.


title: CAVEATS
content:
Running <i>pppoe-setup</i> requires <b>root</b> privileges. It modifies critical system network configuration files, such as <i>/etc/ppp/pppoe.conf</i> and potentially system-specific network scripts or boot-time initialization files. This utility is specifically designed for the <i>rp-pppoe</i> client and might not be compatible with other PPPoE implementations. Due to its interactive nature, it is generally not suitable for automated scripting or headless environments. It primarily focuses on setting up a single PPPoE connection.


title: CONFIGURATION FILES
content:
After execution, <i>pppoe-setup</i> creates or modifies <i>/etc/ppp/pppoe.conf</i>. This file centralizes key PPPoE parameters including the Ethernet interface (<b>ETH</b>), username (<b>USER</b>), demand dialing (<b>DEMAND</b>), idle timeout (<b>IDLETIMEOUT</b>), DNS server addresses (<b>DNS1</b>, <b>DNS2</b>), and firewall settings (<b>FIREWALL</b>). On distributions like RHEL/CentOS that use <i>sysconfig</i>, it might also generate <i>/etc/sysconfig/network-scripts/ifcfg-ppp0</i>. Furthermore, it can configure system services or add entries to <i>/etc/rc.d/rc.local</i> to enable automatic connection at boot.


title: POST-SETUP COMMANDS
content:
Once <i>pppoe-setup</i> completes, the newly configured PPPoE connection can be controlled using several companion commands:<br><i>pppoe-start</i>: To manually start the connection.<br><i>pppoe-stop</i>: To stop an active connection.<br><i>pppoe-status</i>: To check the current connection status.


title: HISTORY
content:
<i>pppoe-setup</i> is an integral component of the <b>rp-pppoe</b> (Roaring Penguin PPPoE) client package, which has served as a robust and widely-used solution for PPPoE connectivity on Linux systems for many years, particularly for DSL users. The command was developed with the primary goal of simplifying the initial configuration process, making PPPoE setup accessible even to users unfamiliar with manual system file editing. Its interactive, question-and-answer driven interface has remained a core feature, emphasizing user-friendliness throughout its development and usage history.


title: PARAMETERS
content:
<b><i>config_file</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative PPPoE configuration file to use instead of the default <b>/etc/ppp/pppoe.conf</b>. This allows for multiple connection profiles or non-standard configurations.<br><br>


title: DESCRIPTION
content:
<i>pppoe-start</i> is a command-line utility used to establish a Point-to-Point Protocol over Ethernet (PPPoE) connection on Linux systems. It is part of the <b>rp-pppoe</b> client suite, commonly employed for broadband internet access via DSL or fiber optic modems. When invoked, it reads configuration parameters primarily from <b>/etc/ppp/pppoe.conf</b> (or a specified alternative file).<br><br>The script then initiates the necessary processes to bring up the connection: it finds the PPPoE server, establishes a PPP session, performs authentication using credentials (typically username and password) defined in the configuration, obtains an IP address from the ISP, and sets up the required routing tables. Essentially, <b>pppoe-start</b> automates the complex steps involved in getting online through a PPPoE-enabled broadband service, making it a convenient tool for network administrators and users alike. It's often used in conjunction with <b>pppoe-stop</b> to manage the connection lifecycle.


title: CAVEATS
content:
<b>Root Privileges:</b> <i>pppoe-start</i> requires superuser (root) privileges to modify network interfaces and routing tables.<br><br><b>Configuration Dependency:</b> Its behavior is heavily dependent on the settings defined in the <b>pppoe.conf</b> file. Incorrect settings can prevent the connection from establishing.<br><br><b>Underlying Network:</b> Assumes that the physical Ethernet connection to the modem/router is active and functional. It does not diagnose physical layer issues.<br><br><b>Troubleshooting:</b> Connection issues often require examining system logs (e.g., <b>/var/log/syslog</b>, <b>dmesg</b>) and the output of the command itself for clues.


title: CONFIGURATION FILE (`/ETC/PPP/PPPOE.CONF`)
content:
The heart of <i>pppoe-start</i>'s operation lies in its configuration file, typically located at <b>/etc/ppp/pppoe.conf</b>. This plain-text file contains crucial parameters such as the Ethernet interface to use (e.g., <i>eth0</i>), the ISP-provided username and password, DNS server settings, and various other PPP-related options. Users must ensure this file is correctly configured for the connection to succeed.


title: AUTHENTICATION METHODS
content:
PPPoE connections rely on PPP for authentication. <i>pppoe-start</i>, through <i>pppd</i>, supports common authentication protocols like PAP (Password Authentication Protocol) and CHAP (Challenge-Handshake Authentication Protocol). The credentials (username and password) are typically sourced from <b>/etc/ppp/pppoe.conf</b> and passed to the PPP daemon for verification with the ISP's authentication server.


title: NETWORK INTERFACE SELECTION
content:
A critical parameter for <i>pppoe-start</i> is the specification of the correct local Ethernet interface (e.g., <i>eth0</i>, <i>enp2s0</i>) through which the PPPoE frames will be sent and received. This interface is usually configured in <b>/etc/ppp/pppoe.conf</b> under the 'ETH=' variable. Incorrect interface selection will prevent the connection from being established.


title: HISTORY
content:
The <b>pppoe-start</b> script is an integral part of the <b>rp-pppoe</b> (Roaring Penguin PPPoE) client package, which emerged to provide robust PPPoE client capabilities for Linux systems. Its development was crucial during the widespread adoption of DSL technology, where PPPoE became a dominant protocol for broadband internet access. The package, including <b>pppoe-start</b>, aimed to simplify the complex process of establishing and maintaining PPPoE connections, offering a user-friendly command-line interface. Over time, it has become a de-facto standard for managing PPPoE connections on various Linux distributions, known for its reliability and comprehensive feature set.


title: DESCRIPTION
content:
The `pppoe-status` command is a utility included in the `rp-pppoe` (Roaring Penguin PPPOe) client package, commonly used on Linux systems to establish and manage PPPoE (Point-to-Point Protocol over Ethernet) connections. Its primary function is to query and display the current status of an active PPPoE internet connection. <br><br>When executed, it attempts to determine if a PPPoE session, typically initiated by `pppoe-start` or `pppoe-connect`, is currently established. If a connection is active, `pppoe-status` provides valuable details such as the assigned public IP address, the default gateway, DNS server addresses configured through the connection, and the session's uptime. It's an essential tool for troubleshooting network connectivity issues related to PPPoE, allowing users or administrators to quickly ascertain if the PPPoE link itself is up and running, and to verify the network parameters received from the ISP. It usually doesn't take any arguments or options, simply reporting on the default or primary connection.


title: CAVEATS
content:
Requires a PPPoE connection to be initiated (e.g., by `pppoe-start`) to report status.<br>May require root privileges or be run via `sudo` to access certain connection details or configuration files, especially if the connection was established by root.<br>Relies on the `rp-pppoe` package and its daemon (`pppoe`) being installed and running.<br>Its output format can vary slightly between different `rp-pppoe` versions or Linux distributions.


title: TYPICAL OUTPUT
content:
The command's output usually provides a clear indication of whether the PPPoE connection is active or not. When connected, it typically lists details such as:<br><br><i>Status: Connected<br>Local IP: 192.168.1.100 (example)<br>Remote IP: 203.0.113.5 (example)<br>Primary DNS: 8.8.8.8 (example)<br>Secondary DNS: 8.8.4.4 (example)<br>Session Time: 0 days, 12 hours, 34 minutes, 56 seconds<br>Connected since: Mon Jan 1 12:00:00 2024</i><br><br>If the connection is down, it might simply report "Status: Disconnected" or an error message indicating that no `pppoe` process is running.


title: COMMON USE CASES
content:
This command is frequently used for:<br>- Quickly checking if the internet connection through PPPoE is active.<br>- Verifying the IP address assigned by the ISP.<br>- Confirming the DNS servers being used by the connection.<br>- Troubleshooting network connectivity issues by isolating problems to the PPPoE layer.


title: HISTORY
content:
The `pppoe-status` command is an integral part of the `rp-pppoe` client suite, developed by Roaring Penguin Software. This suite emerged in the early 2000s as a robust and widely adopted open-source solution for PPPoE connectivity on Linux, at a time when DSL internet connections requiring PPPoE authentication became prevalent. `pppoe-status` was included as a simple, quick way for users to verify the operational state of their PPPoE link, complementing the `pppoe-start` and `pppoe-stop` scripts. Its design emphasizes simplicity and directness, reflecting its utility as a diagnostic tool rather than a configuration utility.


title: DESCRIPTION
content:
<i><b>pppoeconf</b></i> is an interactive, menu-driven utility designed to simplify the setup of a Point-to-Point Protocol over Ethernet (PPPoE) internet connection on Linux systems. It is particularly useful for ADSL and some fiber-optic broadband environments that utilize PPPoE. The tool guides the user through the necessary steps, including scanning for available PPPoE concentrators, prompting for username and password credentials, and configuring DNS servers. It automates the creation and modification of essential configuration files, primarily <i>/etc/ppp/peers/dsl-provider</i>, which the <i><b>pppd</b></i> (the PPP daemon) uses to establish the connection. <i><b>pppoeconf</b></i> aims to make the often complex process of manually configuring PPPoE accessible even for new users, by abstracting away the intricacies of the underlying <i><b>pppd</b></i> and <i><b>pppoe</b></i> utilities. It also offers options to configure the system to automatically connect on boot or on demand.


title: CAVEATS
content:
This command requires root privileges to execute, typically by running it with <i><b>sudo</b></i>. It is primarily an interactive setup tool and does not provide command-line options for non-interactive configuration. While <i><b>pppoeconf</b></i> simplifies initial setup, advanced or very specific PPPoE configurations may still require manual editing of the <i>ppp</i> configuration files located in <i>/etc/ppp</i>. This tool is commonly found on Debian-based distributions (like Ubuntu) and might not be available or function identically on other Linux distributions.


title: USAGE NOTES
content:
To run <i><b>pppoeconf</b></i>, you must typically invoke it with <i><b>sudo</b></i>: <i><b>sudo pppoeconf</b></i>.<br>The utility will then guide you through a series of questions to detect your network interfaces, find PPPoE concentrators, and prompt for your connection credentials (username and password). It automatically configures DNS servers and asks if the connection should be established automatically on boot or on demand.


title: POST-CONFIGURATION ACTIONS
content:
After successfully running <i><b>pppoeconf</b></i>, you can initiate the PPPoE connection using the <i><b>pon</b></i> command: <i><b>pon dsl-provider</b></i>.<br>To disconnect, use the <i><b>poff</b></i> command: <i><b>poff dsl-provider</b></i>.<br>The <i>dsl-provider</i> is the default name given to the connection profile created by <i><b>pppoeconf</b></i> in the <i>/etc/ppp/peers/</i> directory.


title: HISTORY
content:
<i><b>pppoeconf</b></i> emerged as a crucial utility within the Debian ecosystem, specifically designed to ease the configuration of ADSL connections during the early 2000s when PPPoE was the dominant broadband technology. Its development was driven by the need for a user-friendly interactive script that could abstract the complexities of manual <i><b>pppd</b></i> and <i><b>pppoe</b></i> client configurations. While graphical network managers and more advanced network configuration tools have gained prominence, <i><b>pppoeconf</b></i> remains a reliable and straightforward method for setting up PPPoE, especially in server environments or during console-only installations where a graphical interface is not available.


title: SEE ALSO
content:
<b>pppd</b>(8), <b>pon</b>(1), <b>poff</b>(1), <b>pppconfig</b>(8), <b>pppoe</b>(8), <b>ip</b>(8), <b>ifconfig</b>(8)


title: SYNOPSIS
content:
pppstats [ <i>-r</i> ] [ <i>-v</i> ] [ <i>-z</i> ] [ <i>-c</i> ] [ <i>-d</i> ] [ <i>-p <device></i> ] [ <i>-l</i> ] [ <i><interval></i> ]


title: PARAMETERS
content:
<b>-r</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Resets statistics after printing them.<br><br><b>-v</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Enables verbose mode, displaying protocol statistics in more detail.<br><br><b>-z</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Resets statistics to zero only, without printing. This option must be used in conjunction with <i>-r</i>.<br><br><b>-c</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Displays compression statistics for the PPP link.<br><br><b>-d</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Displays packet counts in addition to the default byte counts.<br><br><b>-p <device></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Specifies the PPP device to monitor (e.g., <i>ppp0</i>). By default, <b>pppstats</b> will attempt to use the first active PPP device.<br><br><b>-l</b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>Displays raw LCP (Link Control Protocol) statistics.<br><br><b><interval></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i><br></i>An optional numerical argument specifying the interval in seconds between updates. If provided, <b>pppstats</b> will run continuously, updating the display every <i><interval></i> seconds.<br><br>


title: DESCRIPTION
content:
The <b>pppstats</b> command provides a real-time or snapshot view of the statistics for an active Point-to-Point Protocol (PPP) link. It displays comprehensive data related to the PPP connection, including total bytes transmitted and received, number of packets, error counts (such as bad packets, lost packets), and details about compression and protocol statistics.<br><br>This utility is particularly useful for monitoring the health and performance of dial-up connections, DSL, or other network links that utilize the PPP protocol. It can run continuously, updating the display at specified intervals, or provide a single summary report. Administrators and users can use <b>pppstats</b> to diagnose network issues, identify bottlenecks, or simply observe data transfer rates over a PPP interface.


title: CAVEATS
content:
<ul><li>Requires an active PPP link to report meaningful statistics.</li><li>The command typically needs root privileges or be run via <b>sudo</b> to access PPP device statistics from the kernel.</li><li>The displayed statistics reflect kernel-level PPP driver data and may not always align perfectly with application-level data transfer figures due to protocol overheads or filtering.</li><li>Availability and specific features might vary slightly depending on the Linux distribution and <b>pppd</b> version.</li></ul>


title: OUTPUT FORMAT
content:
When run without an interval, <b>pppstats</b> provides a single line of summary statistics. When an interval is specified, it runs continuously, typically clearing the screen or overwriting the previous output to provide a real-time update. The columns usually include IP bytes transmitted and received, IP packets, compression statistics (if enabled), and various error counts. The exact column layout can vary based on the options used.


title: PERMISSIONS
content:
Accessing <b>pppstats</b> typically requires elevated privileges (e.g., using <b>sudo</b>) because it needs to read kernel-level network device statistics. These statistics are often protected to prevent unauthorized access or manipulation of network interfaces and data.


title: HISTORY
content:
<b>pppstats</b> is an integral part of the <b>ppp</b> package, which provides the Point-to-Point Protocol daemon (<b>pppd</b>) and associated utilities for Linux and other Unix-like operating systems. The <b>ppp</b> project has been a cornerstone of Linux networking since its early days, facilitating dial-up and broadband connections. <b>pppstats</b> has been a consistent utility within this package, offering essential monitoring capabilities for PPP links and evolving alongside <b>pppd</b> itself to support various PPP features and extensions. Its core functionality has remained focused on providing clear, accessible statistics for diagnosing and observing PPP connection performance.


title: SYNOPSIS
content:
<b>pprof</b> [<I>options</I>] [<I>executable</I>] <I>profile_data_source</I><br>Where <I>profile_data_source</I> can be a file path to profiling data or a URL to a live profiling endpoint (e.g., from a Go <I>debug/pprof</I> server). The <I>executable</I> is often optional but recommended for better symbol resolution, especially with Go binaries.


title: PARAMETERS
content:
<b><b>-web</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Launches an interactive web interface in your browser to explore the profile data. This is often the most comprehensive and user-friendly way to analyze profiles.<br><br><b><b>-text</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the profile data as a plain text report, typically showing call stacks and their associated costs.<br><br><b><b>-list</b> <I>regexp</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Lists source code for functions matching the provided regular expression, with line-by-line annotations of profiling data.<br><br><b><b>-top</b> [<I>N</I>]</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Shows the top <I>N</I> (default 10) entries (functions, files, etc.) that consume the most resources based on the profile type.<br><br><b><b>-call_tree</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates a graphical call tree visualization, showing function calls and their hierarchical relationships.<br><br><b><b>-flame</b></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Generates an SVG flame graph, a powerful visualization for hierarchical data that quickly highlights hot paths.<br><br><b><b>-output</b> <I>path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the file path where the generated output (e.g., graph, flame graph, text report) should be saved.<br><br><b><b>-seconds</b> <I>duration</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;When profiling from a URL, specifies the duration (in seconds) for which to collect profiling samples.<br><br><b><b>-sample_index</b> <I>type</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Selects the specific type of samples to analyze within a profile. Common types include <I>cpu</I>, <I>alloc_space</I> (total bytes allocated), <I>inuse_space</I> (bytes currently in use), <I>goroutine</I>, <I>mutex</I>, and <I>block</I>.<br><br><b><b>-base</b> <I>profile_path</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Subtracts the profile data from a specified base profile, useful for comparing two profiles (e.g., before and after an optimization).<br><br><b><b>-focus</b> <I>regexp</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters the profile to focus only on data paths (functions, files) that match the given regular expression.<br><br><b><b>-ignore</b> <I>regexp</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Filters the profile to ignore data paths (functions, files) that match the given regular expression.<br><br>


title: DESCRIPTION
content:
<b>pprof</b> is a command-line tool for visualizing and analyzing profiling data. It reads various profiling formats, including those generated by Go programs (CPU, heap, goroutine, mutex, block profiles), and can also process profiles from other sources like <I>perf</I>, gperftools, and Java applications (when converted to the pprof format).<br><br><b>pprof</b> can generate a wide range of reports and visualizations, such as text-based call stacks, flame graphs, call graphs, and highly interactive web UIs. It's an indispensable tool for performance tuning, helping developers identify bottlenecks, memory leaks, and concurrency issues in their applications. By providing deep insights into where CPU time is spent, memory allocations occur, or contention arises, <b>pprof</b> enables targeted optimizations across diverse programming environments. Its versatility and powerful visualization capabilities make it a staple in performance analysis workflows.


title: CAVEATS
content:
<b>pprof</b> primarily processes profiles in the Go-specific <I>pprof</I> format (gzipped protocol buffers). While it can ingest other formats (like <I>perf</I> data) via conversion tools (e.g., <I>perf_to_pprof</I>), direct support is limited. For proper symbol resolution, especially with Go binaries, providing the original executable is crucial. Analyzing very large profiles can be resource-intensive, requiring significant memory and CPU. The <I>-web</I> option requires a web browser configured to open URLs.


title: SUPPORTED PROFILE TYPES
content:
<b>pprof</b> can interpret various types of profiling data, including CPU usage, heap allocations (both total allocated and currently in-use memory), goroutine stacks, mutex contention, blocking operations, and trace data. The type of analysis depends on the nature of the collected profile.


title: OUTPUT FORMATS
content:
Beyond the interactive web UI and text reports, <b>pprof</b> can generate static graphical outputs in formats like SVG, PNG, JPEG, GIF, and PDF. It can also produce raw profile data in protocol buffer format or convert to <I>dot</I> format for further processing with graph visualization tools.


title: HISTORY
content:
<b>pprof</b> originated at Google as an internal profiling tool for C++ applications and was later open-sourced as a core component of the Go programming language toolchain. Its development focused on providing robust and flexible profile visualization capabilities. Over time, it has evolved to support a broader range of profiling data sources beyond just Go applications, establishing itself as a widely adopted tool for performance analysis across various languages and environments.


title: DESCRIPTION
content:
The command 'ppt' is not a standard, widely recognized utility or executable found in mainstream Linux distributions. It is highly probable that this is a typo, a misunderstanding, or refers to a very specific, non-standard application, an alias, or a custom script.<br><br>Common confusions might include:<br><ul><li><b><I>ppp</I> (Point-to-Point Protocol):</b> Commands like <I>pppd</I> (PPP daemon), <I>pppoe-start</I>, <I>pppoe-stop</I>, <I>ppp-go</I>, etc., are related to establishing dial-up or broadband connections using the PPP protocol.</li><li><b>Microsoft PowerPoint files:</b> While files ending with '.ppt' are associated with Microsoft PowerPoint, there is no native Linux command named 'ppt' to handle these files directly for viewing or editing (other than opening them with compatible office suites like LibreOffice Impress).</li></ul>If you encountered 'ppt' in a specific context, please verify the exact command name or its source.


title: CAVEATS
content:
The command 'ppt' is not part of the standard GNU/Linux core utilities or widely available package sets. Attempting to execute 'ppt' will typically result in a 'command not found' error unless a custom script or alias with that name has been defined in your environment.


title: POSSIBLE LOCAL ALIASES/SCRIPTS
content:
It's possible that 'ppt' is a custom alias or a script created by a user or system administrator on a specific machine. Users can define aliases (e.g., <I>alias ppt='ls -l'</I>) or create executable scripts named 'ppt' in their PATH, which would then make the command available only in that specific environment.


title: HISTORY
content:
There is no documented history or development for a standard 'ppt' Linux command, as it does not exist in the official command landscape.


title: SYNOPSIS
content:
<b>pptp</b> <i>server_address</i> [<i>--options</i>...]<br><b>pptp</b> [<i>--options</i>...] (when invoked as a <i>pppd</i> plugin)


title: PARAMETERS
content:
<b><i>server_address</i></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Required.</i> The IP address or hostname of the PPTP VPN server to connect to.<br><br><b>--client-ip <ip></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Requests a specific local IP address for the client's end of the tunnel.<br><br><b>--server-ip <ip></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Requests a specific remote IP address for the server's end of the tunnel.<br><br><b>--nolaunchpppd</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>pptp</b> from automatically launching the <b>pppd</b> daemon after the GRE tunnel is established.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debugging output, useful for troubleshooting connection issues.<br><br><b>--loglevel <level></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the logging verbosity level (0=silent, 4=debug) for <b>pptp</b>'s internal operations.<br><br><b>--timeout <seconds></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Sets the maximum time in seconds to wait for a connection to be established before timing out.<br><br><b>--pppd-call <name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Instructs <b>pptp</b> to pass control to <b>pppd</b> using options defined in the configuration file <i>/etc/ppp/peers/<name></i>.<br><br><b>--sync</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Uses synchronous PPP framing, often necessary when <b>pptp</b> works in conjunction with <b>pppd</b> through <i>--pppd-call</i>.<br><br><b>--nobuffer</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Disables internal buffering of GRE packets, which can sometimes resolve specific performance or compatibility issues.<br><br><b>--refuse-<method></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Refuses specific PPP authentication methods, e.g., <i>--refuse-chap</i>, <i>--refuse-mschap-v2</i>.<br><br><b>--quirk-<name></b><br>&nbsp;&nbsp;&nbsp;&nbsp;A collection of various workarounds (e.g., <i>--quirk-welcome</i>, <i>--quirk-broken-asyncread</i>) for compatibility with non-standard or buggy PPTP server implementations.<br><br>


title: DESCRIPTION
content:
The <b>pptp</b> command is a client for the Point-to-Point Tunneling Protocol (PPTP), a VPN protocol developed by Microsoft. It enables Linux systems to establish tunneled connections to PPTP-compatible VPN servers, commonly found in older corporate networks or legacy ISP setups.<br><br><b>pptp</b> itself handles the establishment of the PPTP control connection and the Generic Routing Encapsulation (GRE) tunnel that encapsulates PPP packets. Once the tunnel is set up, <b>pptp</b> typically launches the <b>pppd</b> (PPP daemon) utility, which then manages the actual PPP negotiation, authentication (e.g., PAP, CHAP, MS-CHAPv1/v2), IP address assignment, and routing table configuration.<br><br>While <b>pptp</b> was once a prevalent solution for VPN connectivity, it is now largely considered outdated and insecure due to known vulnerabilities in its underlying authentication and encryption mechanisms. It is generally recommended to use more modern and secure VPN protocols like OpenVPN, WireGuard, or IKEv2/IPsec for new deployments.


title: CAVEATS
content:
PPTP is widely considered insecure by modern standards. Its underlying authentication protocols (especially MS-CHAPv1/v2) have known vulnerabilities, and its encryption (MPPE) can be weak or easily compromised. It is not recommended for new VPN deployments or for securing sensitive data. Furthermore, PPTP connections using GRE can often encounter difficulties traversing Network Address Translation (NAT) devices.


title: <I>USAGE WITH PPPD</I>
content:
The <b>pptp</b> command typically acts as a frontend to the <b>pppd</b> daemon. After <b>pptp</b> establishes the underlying GRE tunnel, it usually launches <b>pppd</b> to handle the PPP negotiation. This involves authentication, IP address assignment, and setting up routes. Configuration for the <b>pppd</b> part of the connection is often found in files under <i>/etc/ppp/</i> or in specific peer files like <i>/etc/ppp/peers/&lt;connection_name&gt;</i>, where credentials might be stored in <i>/etc/ppp/chap-secrets</i> or <i>/etc/ppp/pap-secrets</i>.


title: <I>SECURITY CONSIDERATIONS</I>
content:
It is crucial to understand that PPTP offers minimal security by modern standards. Exploits exist for breaking its authentication, and its encryption can be easily bypassed or cracked. Users should prioritize more secure VPN solutions like OpenVPN, IPsec/IKEv2, or WireGuard for any new deployments or for protecting sensitive communications. The use of <b>pptp</b> should be limited to legacy systems where no other VPN option is available, and even then, with extreme caution.


title: HISTORY
content:
The Point-to-Point Tunneling Protocol (PPTP) was initially developed by Microsoft in collaboration with Ascend Communications and others, and was released in 1996. The <b>pptp-linux</b> client, which provides the <b>pptp</b> command, was developed to allow Linux systems to interoperate with these Windows-centric VPN servers. It gained significant usage in the late 1990s and early 2000s as a primary method for remote access VPNs, particularly for connecting to Microsoft Windows NT/2000/2003 servers. However, its security shortcomings led to its gradual deprecation in favor of more robust protocols.


title: SYNOPSIS
content:
<b>pptpsetup --create <I>interface</I> --server <I>server_ip</I> --username <I>username</I> --password <I>password</I> [--encrypt] [--start] [--log <I>logfile</I>] [--debug] [--local-ip <I>local_ip</I>] [--no-default-route] [--no-dns] [--set-option <I>option</I>] [--mppe-stateful] [--force-hostname <I>hostname</I>] [--chap-secrets-file <I>file</I>] [--options-file <I>file</I>] [--peers-file <I>file</I>]<br><b>pptpsetup --delete <I>interface</I><br><b>pptpsetup --start <I>interface</I><br><b>pptpsetup --stop <I>interface</I><br><b>pptpsetup --status <I>interface</I><br><b>pptpsetup --version<br><b>pptpsetup --help


title: PARAMETERS
content:
<b>--create <I>interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Required.</i> Specifies that a new PPTP connection should be created with the given interface name (e.g., <i>vpn0</i>).<br><br><b>--delete <I>interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Required.</i> Deletes the configuration files for the specified PPTP interface.<br><br><b>--start <I>interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Starts the PPTP connection associated with the specified interface.<br><br><b>--stop <I>interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Stops the PPTP connection associated with the specified interface.<br><br><b>--status <I>interface</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the current status of the specified PPTP connection.<br><br><b>--server <I>server_ip</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Required with --create.</i> The IP address or hostname of the PPTP server.<br><br><b>--username <I>username</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Required with --create.</i> The username for authentication with the PPTP server.<br><br><b>--password <I>password</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;<i>Required with --create.</i> The password for authentication with the PPTP server.<br><br><b>--encrypt</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables MPPE (Microsoft Point-to-Point Encryption) encryption. This is highly recommended for security.<br><br><b>--mppe-stateful</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables stateful MPPE encryption. This is sometimes required for compatibility with certain PPTP servers.<br><br><b>--local-ip <I>local_ip</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies the local IP address for the PPTP interface. Normally, the PPTP server assigns one.<br><br><b>--no-default-route</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>pptpsetup</b> from adding a default route via the PPTP connection. Useful if you only want specific routes through the VPN.<br><br><b>--no-dns</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Prevents <b>pptpsetup</b> from setting DNS servers provided by the PPTP server. Useful if you want to use your existing DNS configuration.<br><br><b>--set-option <I>option</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Passes an additional option directly to <b>pppd</b>. Can be used multiple times for different options.<br><br><b>--log <I>logfile</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies a file to log <b>pppd</b> output, which can be helpful for debugging connection issues.<br><br><b>--debug</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Enables verbose debugging output for <b>pppd</b>.<br><br><b>--force-hostname <I>hostname</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Forces <b>pppd</b> to use a specific hostname during authentication, which might be required by some PPTP servers.<br><br><b>--chap-secrets-file <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative <i>chap-secrets</i> file to use instead of the default.<br><br><b>--options-file <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative options file for the PPTP connection.<br><br><b>--peers-file <I>file</I></b><br>&nbsp;&nbsp;&nbsp;&nbsp;Specifies an alternative peers file for the PPTP connection.<br><br><b>--version</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the <b>pptpsetup</b> version information.<br><br><b>--help</b><br>&nbsp;&nbsp;&nbsp;&nbsp;Displays the help message and exits.<br><br>


title: DESCRIPTION
content:
<b>pptpsetup</b> is a utility program designed to simplify the configuration of a Point-to-Point Tunneling Protocol (PPTP) client connection on Linux systems. It acts as a wrapper around the <b>pppd</b> (PPP daemon) and <b>ip</b> commands, automating the creation of necessary configuration files located primarily in <i>/etc/ppp/</i>. These files include secrets for authentication (e.g., <i>chap-secrets</i>), options for the PPTP connection, and peer configuration files. <br><br>The command allows users to specify the PPTP server address, VPN username, password, and optionally a local IP address and routing information. By automating these steps, <b>pptpsetup</b> reduces the manual effort and potential for errors when setting up a PPTP VPN, making it more accessible for users who need to connect to PPTP-based VPNs, typically in older network environments or specific corporate setups. It's important to note that while <b>pptpsetup</b> facilitates connection, PPTP itself is an outdated and generally insecure protocol.


title: CAVEATS
content:
<ul><li><b><I>Security Risk:</I></b> PPTP is an <I>outdated and insecure</I> VPN protocol with known vulnerabilities, particularly regarding its authentication (MS-CHAPv2) and encryption (MPPE). It is susceptible to various attacks, including dictionary attacks and bit-flipping attacks on encrypted data. <br><b><I>Usage is strongly discouraged</I></b> for sensitive data or over untrusted networks. Newer, more secure VPN protocols like OpenVPN or IPsec (IKEv2) should be preferred.</li><li><b><I>Root Privileges:</I></b> <b>pptpsetup</b> modifies system network configuration files and requires <b>root</b> privileges to run successfully.</li><li><b><I>Dependencies:</I></b> It relies on the <b>pppd</b> (PPP daemon) and <b>ip</b> utilities being installed and correctly configured on the system.</li><li><b><I>Configuration Overrides:</I></b> While <b>pptpsetup</b> simplifies setup, advanced <b>pppd</b> configurations might require manual editing of the generated files.</li></ul>


title: CONFIGURATION FILES GENERATED
content:
When a connection is created with <b>--create</b>, <b>pptpsetup</b> generates several configuration files, typically in <i>/etc/ppp/</i>:<br><ul><li><i>/etc/ppp/chap-secrets</i>: Contains the username and password for authentication.</li><li><i>/etc/ppp/options.pptpsetup.<I>interface</I></i>: Specific options for the <b>pppd</b> instance related to the PPTP connection.</li><li><i>/etc/ppp/peers/<I>interface</I></i>: Defines the peer (PPTP server) information and links to the options file.</li></ul>These files can be manually inspected or modified for advanced configurations.


title: DEFAULT ROUTING BEHAVIOR
content:
By default, <b>pptpsetup</b> attempts to set the newly established PPTP connection as the <I>default route</I> for all internet traffic. This means all your network traffic will flow through the VPN tunnel. If you only want specific traffic to go through the VPN, use the <b>--no-default-route</b> option and manually configure specific routes using the <b>ip route</b> command.


title: HISTORY
content:
<b>pptpsetup</b> is part of the <b>pptp-client</b> project, which aimed to provide a functional PPTP client for Linux. Its development emerged from the need for Linux users to connect to Microsoft Windows-based VPN servers that predominantly used PPTP in the late 1990s and early 2000s. <br><br>While initially useful for interoperability, the underlying PPTP protocol quickly showed its cryptographic weaknesses. Although <b>pptpsetup</b> continued to be maintained for compatibility purposes, its usage has declined significantly in favor of more robust and secure VPN solutions. Its primary historical significance lies in simplifying an otherwise complex manual configuration process for a then-common VPN standard.


