Eye Gaze Editor Guide

1. Getting Started

1. Open the Editor.
2. Click the image upload button and choose a portrait.
3. Wait while the face and eyes are detected.
4. Use the controls on the right side of the editor to adjust the eyes.
5. Compare your result with the original image.
6. Export the finished image as PNG or JPEG.

JPG, PNG and WebP portrait images are supported. For best results, use an image where the eyes are visible and reasonably well defined.

2. How the Editor Works

The editor uses facial landmarks to locate the upper and lower eyelids, the inner and outer eye corners and the approximate position of each iris.

These landmarks define an eye-opening mask. Think of this as the exact opening between the eyelids. The original portrait remains untouched outside this area.

Inside each eye-opening mask, the editor renders a new eye from several layers:

1. Eye white / sclera
2. Iris
3. Pupil
4. Shadow
5. Highlight / reflection

Because all synthetic eye content is clipped to the eyelid opening, the original eyelids, eyelashes, makeup, wrinkles and surrounding skin remain visible on top of the replacement eye.

3. Changing Gaze Direction

The Gaze Controller changes the direction both eyes are looking.

• Drag left to make the person look left.
• Drag right to make the person look right.
• Drag upward to make the person look up.
• Drag downward to make the person look down.
• Drag diagonally for combined horizontal and vertical movement.

You can also use the Horizontal Gaze and Vertical Gaze sliders for more precise positioning.

Gaze Strength

Gaze Strength controls how far the iris and pupil move for the selected gaze direction. Lower values create subtler eye movement, while higher values create stronger movement.

Individual Eye Position

If one eye needs a small correction, use the individual left and right eye X/Y controls. These let you fine-tune each iris and pupil independently without changing the shared gaze direction.

4. Eye Base / Eye White Controls

Clean and Red Eye Base

Choose between the available eye-base styles:

• Clean — a cleaner, brighter sclera.
• Red — an eye base with more visible veins and redness.

Eye Base Size

Eye Base Size changes the size of the synthetic eyeball image behind the eyelid opening. It does not change the size of the eye-opening mask itself.

Separate left and right eye-base size controls are available when the two eyes need slightly different scaling.

Eye Base Brightness

Use Eye Base Brightness to make the eye whites darker or brighter so that they better match the lighting in the original photograph.

There is a master brightness control as well as independent controls for the left and right eyes.

5. Iris Controls

Iris Color

The iris texture can be recolored. Use the iris color selector to choose a color manually.

If available, you can also use the color sampled from the original eye as a starting point.

Iris Darkness / Brightness

Adjust the iris brightness to make it better match the original lighting and eye color.

Iris Size

Iris Size changes the diameter of the iris while preserving its position and gaze direction.

6. Pupil Controls

The pupil is generated as a perfect circle rather than taken from the original photograph.

Pupil Size

Use Pupil Size to make the pupil smaller or larger relative to the iris.

Pupil Darkness

Use Pupil Darkness to control how dark the pupil appears.

The pupil always remains centered inside the iris and moves together with it when gaze direction changes.

7. Shadow and Highlight Controls

Shadow Opacity

The shadow layer helps reproduce the natural shadow created by the upper eyelid.

Use the master Shadow Opacity control to adjust both eyes together. Separate left and right shadow controls allow you to compensate for uneven lighting in the original photograph.

Highlight Opacity

The highlight layer adds a catchlight or reflection to the eye.

You can adjust both eyes together or control the left and right highlights independently.

Subtle values usually produce the most natural result.

8. Eye-Opening Mask Controls

The eye-opening mask determines exactly which part of the original eye is replaced.

Automatic detection usually provides a useful starting point, but every photograph is different. You can therefore move and resize the masks manually.

Shared Mask Controls

Shared controls affect both eyes together:

• Mask X
• Mask Y
• Mask Width
• Mask Height

Individual Mask Controls

Separate controls are available for the left and right eyes. Use them when one eye requires different positioning or scaling.

Width and height can be adjusted independently, which is useful when the detected eyelid opening is too wide, too narrow, too tall or too short.

9. Manually Editing Eye Landmarks

For precise corrections, enable Edit Eye Landmarks.

The editable points define the shape of the eye-opening mask. Drag individual points to better match the real edge of the upper and lower eyelids.

1. Enable Show Eye Landmarks.
2. Enable Edit Eye Landmarks.
3. Zoom into the eye if necessary.
4. Drag individual landmark points so they follow the eyelid boundary.
5. Watch the synthetic eye mask update immediately.

Use Reset Eye Landmarks if you want to restore the original automatically detected positions.

10. Soft Edge

The Soft Edge control feathers the boundary between the synthetic eye and the original photograph.

A value that is too low may create a visibly sharp cutout around the eye. A value that is too high can make the eyelid boundary look blurry.

The ideal setting depends on the image resolution, focus and lighting. Increase the value gradually until the transition looks natural.

Soft Edge affects only the compositing boundary. It does not intentionally blur the iris, pupil or interior eye detail.

11. Preview Zoom and Pan

Preview navigation lets you inspect the eyes closely without changing the exported image.

Zoom

• Use the mouse wheel to zoom in and out.
• You can also use the Preview Zoom slider.

Pan

• Drag with the left mouse button to move around the preview.
• Middle mouse button drag performs the same pan action.
• You can also use the Preview Left Offset and Preview Top Offset sliders.

The sliders update automatically when you zoom or drag the preview.

Fit to Screen and Reset View

Fit to Screen automatically positions the photograph inside the available workspace. Reset View restores the preview viewport.

Preview zoom and pan are only navigation tools. They do not change the actual image or exported result.

12. Debug and Alignment Tools

The editor includes several visualization tools that can help when automatic eye detection needs manual correction.

• Show Eye Landmarks — displays the detected/editable eyelid points.
• Show Eye Masks — displays the area being replaced.
• Show Eye Centers — displays calculated eye centers.
• Show Eye Axes — shows local eye orientation.
• Show Bounding Boxes — displays calculated eye bounds.
• Show Sampled Iris Color — helps inspect automatic color sampling.

Debug overlays are intended for editing only and should not appear in the exported image.

13. Undo and Redo

The editor keeps a history of recent editing actions.

• Ctrl + Z — Undo
• Ctrl + Y — Redo
• Ctrl + Shift + Z — Redo
• Cmd + Z — Undo on macOS
• Cmd + Shift + Z — Redo on macOS

Up to approximately 30 recent editing actions are kept in history.

Continuous actions such as moving a slider or dragging a landmark are treated as a single edit rather than hundreds of tiny undo steps.

Preview navigation such as zooming and panning is not part of the undo history.

14. Comparing With the Original

Use the Original / Edited comparison control to quickly check whether your changes still look natural.

Frequent comparison is useful because the human eye is extremely sensitive to small changes in gaze, iris size and eye alignment.

15. Reset Controls

Reset Gaze

Restores gaze direction and related positional adjustments without necessarily resetting the rest of the eye appearance.

Reset Eye Landmarks

Restores manually moved eyelid landmarks to their automatically detected positions.

Reset All

Restores the editor settings to their initial state for the currently loaded image.

16. Exporting the Finished Image

When you are satisfied with the result, use the export controls to download the edited portrait.

PNG

PNG is a good choice when you want lossless image output.

JPEG

JPEG produces smaller files and includes a quality setting so you can balance image quality and file size.

The editor renders the export separately at the original uploaded image resolution. Preview zoom, preview pan and the size of the browser window do not reduce export resolution.

17. Recommended Editing Workflow

1. Upload the portrait and wait for eye detection.
2. Turn on Show Eye Masks and check the detected eye openings.
3. Correct mask position, width and height if necessary.
4. Use landmark editing for any remaining eyelid alignment problems.
5. Adjust the eye-base size so the sclera looks natural behind the eyelids.
6. Match eye-white brightness to the photograph.
7. Set iris color, brightness and size.
8. Adjust pupil size.
9. Set the desired gaze direction.
10. Use individual left/right positioning controls for small corrections.
11. Adjust shadow and highlight opacity to match the photograph's lighting.
12. Increase Soft Edge slightly if the eye replacement boundary is visible.
13. Turn off debug overlays.
14. Compare the result with the original.
15. Export the finished image.

18. Tips for Natural Results

• Keep gaze changes believable. Very extreme iris positions may look unnatural even when technically possible.
• Match the brightness of the original eyes. Bright white sclera in a dark portrait is immediately noticeable.
• Do not make both eyes artificially identical. Real photographs often contain slightly different lighting and reflections in each eye.
• Use per-eye controls when needed. Perspective, head rotation and uneven lighting can make the two eyes require different settings.
• Check the eye-opening mask closely. A correctly positioned mask is one of the most important factors in making the replacement convincing.
• Use Soft Edge carefully. Enough feathering can hide a hard compositing boundary, but too much can make the eyelids appear blurry.
• Zoom in while editing, then zoom out. Details may look perfect at extreme magnification but unnatural when viewing the entire portrait.
• Use before/after frequently. Small changes can accumulate surprisingly quickly.

19. Images That May Need More Manual Adjustment

Automatic eye detection works best when the eye opening is clearly visible. More manual correction may be necessary with:

• very small faces
• strong side-profile views
• closed or heavily squinting eyes
• hair covering the eyes
• very dark shadows
• strong reflections on glasses
• sunglasses
• motion blur
• very low-resolution photographs
• extreme head angles

The manual mask, landmark and per-eye controls are provided specifically so that automatic detection can be corrected when necessary.

20. Image Processing

The editor is designed so that the actual eye editing and final image rendering happen in the browser. Preview rendering, eye adjustments and image export are handled client-side rather than requiring server-side image generation.