Creating gmobile cutout files
gmobile display-panel files describe device-specific screen geometry, such as rounded corners, notches and punch-hole camera cutouts. Phosh uses this information to keep shell UI elements like the top bar, clock and status icons away from unusable parts of the display. When this data is missing, Phosh may draw content underneath a camera hole or too close to rounded corners. This page explains how to create candidate gmobile cutout files from Android/LineageOS device overlay data, test them on postmarketOS, and prepare them for upstream submission.
| The files generated by these tools are candidates. Always validate the result on the target device, for example with Phosh/Phoc cutout debugging, before upstreaming it to gmobile or relying on it in a device port. |
lineage_cutout_to_gmobile is a helper script for generating gmobile display-panel JSON files from LineageOS Android device overlay repositories.
It is useful when Phosh does not correctly avoid a notch, punch-hole camera cutout or rounded screen corners. Many Android/LineageOS device trees already contain display cutout and rounded-corner information in framework overlay resources, while gmobile only contains display-panel data for some devices.
The related autogenerated_gmobile_files repository contains generated JSON candidates, currently focused on Xiaomi devices.
Repositories
- lineage_cutout_to_gmobile - generator script
- autogenerated_gmobile_files - autogenerated candidate display-panel JSON files
What the generator extracts
The generator clones a LineageOS device repository named like:
android_device_<oem>_<codename>
It then scans the repository, and optionally related repositories, for display information such as:
- display resolution
- rounded corner radius values
- Android display cutout paths
- Android display cutout rectangular approximations
- display density, when needed for converting
dp/dipvalues to pixels
The Android cutout path is converted to the coordinate system expected by gmobile. Android's default cutout path origin is the top center of the display, while gmobile display-panel JSON paths use normal display coordinates.
Requirements
- Python 3.9 or newer
git- optional:
json-glib-validate, for validating the generated JSON
No third-party Python packages are required.
Basic usage
Clone the generator:
$ git clone https://github.com/PiotrZPL/lineage_cutout_to_gmobile.git
$ cd lineage_cutout_to_gmobile
Generate a display-panel JSON file:
$ python3 main.py <oem> <codename> --output-dir ./display-panels
For example, for the Xiaomi Redmi Note 10 Pro/Pro Max (xiaomi-sweet):
$ python3 main.py xiaomi sweet \
--branch lineage-23.2 \
--workdir ./lineage-device-work \
--output-dir ./display-panels \
--force \
--print-notes
This writes:
display-panels/xiaomi,sweet.json
If --branch is omitted, the script tries to use the newest available lineage-* branch.
Common options
| Option | Description |
|---|---|
--branch BRANCH
|
Use a specific LineageOS branch, for example lineage-23.2. If omitted, the newest available lineage-* branch is selected automatically.
|
--workdir DIR
|
Directory where LineageOS repositories are cloned. |
--output-dir DIR
|
Directory where the generated JSON file is written. |
--output-file PATH
|
Write the generated JSON to an exact path instead of using --output-dir.
|
--repo-url URL
|
Use a specific device repository instead of the default https://github.com/LineageOS/android_device_<oem>_<codename>.git.
|
--clone-dependencies
|
Also clone repositories listed in lineage.dependencies. This is useful when display overlays are inherited from a common device tree.
|
--use-wiki
|
Use LineageOS wiki device YAML metadata as a fallback for display resolution. |
--compatible STEM
|
Choose the output filename stem, for example xiaomi,sweet. This is useful when the Linux device-tree compatible differs from the LineageOS repo name.
|
--x-res PX
|
Override the detected horizontal resolution. |
--y-res PX
|
Override the detected vertical resolution. |
--density DPI
|
Override the detected Android screen density. This is needed when the Android overlay uses dp or dip values and density was not detected automatically.
|
--corner-format auto
|
Automatically choose how rounded corners are emitted. |
--corner-format border-radius
|
Emit a single border-radius value.
|
--corner-format corner-radii
|
Emit explicit per-corner values. |
--use-rect-approx
|
Use Android's rectangular cutout approximation instead of the exact cutout path. |
--include-physical-size
|
Estimate physical display width and height from the display diagonal, if available. |
--update
|
Update an existing checkout instead of reusing it as-is. |
--depth N
|
Set the Git clone depth. Use --depth 0 for a full clone.
|
--force
|
Overwrite an existing output JSON file. |
--no-validate
|
Skip json-glib-validate.
|
--print-notes
|
Print detection notes, including where values were found. |
Run the script with --help for the full CLI reference:
$ python3 main.py --help
Examples
Generate a file for a normal LineageOS device tree
$ python3 main.py xiaomi sweet \
--output-dir ./display-panels \
--force \
--print-notes
Use a specific branch
$ python3 main.py xiaomi sweet \
--branch lineage-23.2 \
--output-dir ./display-panels
Clone dependency repositories too
Some devices inherit overlays from a common tree. In that case, use:
$ python3 main.py xiaomi sweet \
--clone-dependencies \
--output-dir ./display-panels \
--print-notes
Use LineageOS wiki metadata as fallback
Some LineageOS device trees do not contain the panel resolution directly in their README or makefiles. The generator can use LineageOS wiki metadata as a fallback:
$ python3 main.py xiaomi sweet \
--use-wiki \
--output-dir ./display-panels \
--print-notes
Override missing values manually
If the display resolution or density is not detected correctly:
$ python3 main.py xiaomi sweet \
--x-res 1080 \
--y-res 2400 \
--density 440 \
--output-dir ./display-panels \
--force
Use a custom repository URL
$ python3 main.py xiaomi sweet \
--repo-url https://github.com/LineageOS/android_device_xiaomi_sweet.git \
--output-dir ./display-panels
Generate a file with a custom compatible filename
gmobile filenames should match a Linux device-tree compatible string. If the LineageOS codename does not match the compatible string, use --compatible:
$ python3 main.py xiaomi sweet \
--compatible xiaomi,sweet \
--output-dir ./display-panels
This writes:
display-panels/xiaomi,sweet.json
Autogenerated candidate files
The autogenerated_gmobile_files repository contains JSON files generated with the helper script.
The files are named like:
<vendor>,<codename>.json
Examples:
xiaomi,peridot.json
xiaomi,sweet.json
xiaomi,venus.json
These files are useful as starting points, but should not be considered guaranteed-correct device data. Before using one:
- Check that the filename matches the Linux device-tree compatible string.
- Validate the JSON.
- Test the cutout and rounded corners on the device.
- If the result is correct, consider submitting it upstream to gmobile.
Testing with Phosh/Phoc
Copy the generated file to a local gmobile overlay directory, for example:
$ mkdir -p ~/.local/share/gmobile/display-panels
$ cp display-panels/xiaomi,sweet.json ~/.local/share/gmobile/display-panels/
Then create or edit ~/.phoshdebug:
G_RESOURCE_OVERLAYS=/mobi/phosh/gmobile/devices/display-panels=$HOME/.local/share/gmobile/display-panels
export G_RESOURCE_OVERLAYS
PHOC_DEBUG=cutouts
export PHOC_DEBUG
Restart Phosh, log out and back in, or reboot. If the debug overlay matches the physical notch or punch-hole, the JSON is likely suitable for further testing and upstreaming.
To disable the debug drawing but keep the local gmobile override, remove only the PHOC_DEBUG=cutouts line.
Upstreaming to gmobile
Once tested, submit the JSON file to gmobile:
data/devices/display-panels/<vendor>,<codename>.json
Also add the file to:
data/gmobile.gresources.xml
The merge request should mention:
- the device model and codename
- the Linux device-tree compatible string
- where the values came from, for example LineageOS overlay resources
- how the result was tested on the device
Limitations
The generated files should be reviewed manually. Possible problems include:
- LineageOS repositories may omit display cutout information.
- Some devices inherit overlay values from common repositories.
- Android overlays may describe multiple regional variants.
- Display resolution may need to be taken from LineageOS wiki metadata or provided manually.
- Some generated files may describe the approximate Android cutout rectangle instead of the exact visual shape, depending on the options used.
- A generated file may be syntactically valid but still visually wrong on real hardware.