README.md

---
license: mit
pipeline_tag: image-segmentation
tags:
  - faceocc
  - face-segmentation
  - face-occlusion
  - visible-face-segmentation
  - semantic-segmentation
  - pytorch
  - segmentation-models-pytorch
---

# FaceOcc

Modernized canonical FaceOcc model for visible-face segmentation.

This model is based on **FaceOcc**, introduced by Xiangnan Yin and
Liming Chen, and the accompanying upstream FaceExtraction implementation.
The original FaceOcc work should be cited when using the underlying
method or dataset.

This release provides the canonical model weights from the modernized
FaceOcc implementation available at:

**https://github.com/mertakinstd/FaceOcc**

![FaceOcc result](show_1.png)

## Model

| Property | Value |
| --- | --- |
| Architecture | U-Net |
| Encoder | ResNet18 |
| Encoder pretraining | ImageNet |
| Input | RGB, 256 × 256 |
| Input range | `[0, 1]` before normalization |
| Normalization | ImageNet mean/std |
| Output | Single-channel logits |
| Canonical probability threshold | `0.5` |
| Training objective | Global OHEM-BCE |
| Precision | IEEE FP32 |
| Checkpoint format | SafeTensors |

### Input normalization

Images are normalized immediately before the model forward pass using:

```text
mean = [0.485, 0.456, 0.406]
std  = [0.229, 0.224, 0.225]
```

Masks are not normalized.

The released checkpoint contains the complete trained model weights.
ImageNet weights are therefore not required separately when loading the
checkpoint.

## Reference result

The canonical checkpoint was selected by maximum COFW validation face
IoU at a probability threshold of `0.5`.

| Metric | Value |
| --- | ---: |
| COFW face IoU @ p=0.5 | **0.936523** |
| Best epoch | **24 / 30** |
| Dice | **0.966749** |
| Precision | **0.948656** |
| Recall | **0.986324** |
| Boundary IoU | **0.682287** |
| IoU p10 | **0.893731** |
| IoU median | **0.945921** |
| IoU p90 | **0.971353** |

COFW was used for validation and checkpoint selection in this training
protocol and should not be interpreted as an untouched external test set.

The canonical reference run was trained on a single
**NVIDIA GeForce RTX 3060 12 GB** GPU.

## Loading the checkpoint

The model is implemented with
[`segmentation_models_pytorch`](https://github.com/qubvel-org/segmentation_models.pytorch).

A corresponding model can be instantiated and the SafeTensors
checkpoint loaded as follows:

```python
import segmentation_models_pytorch as smp
from safetensors.torch import load_file

model = smp.Unet(
    encoder_name="resnet18",
    encoder_weights=None,
    in_channels=3,
    classes=1,
)

state_dict = load_file("model.safetensors")
model.load_state_dict(state_dict, strict=True)
model.eval()
```

`encoder_weights=None` is intentional when loading the released
checkpoint because all trained encoder and decoder parameters are already
contained in `model.safetensors`.

For the complete preprocessing and inference implementation, use the
source repository linked below.

## Intended use

FaceOcc predicts a binary visible-face mask:

- `1`: visible facial surface
- `0`: background or occluding region

The model is intended for visible-face segmentation and downstream
applications that require a facial region of interest.

It is not a face-recognition, identity-verification, or landmark model.

## Limitations

Performance can vary with image alignment, capture conditions,
occlusion type, image quality, and annotation policy.

The canonical `0.5` probability threshold is retained for reproducible
comparison with the released training protocol. Application-specific
threshold tuning should be validated independently.

## Files

- `model.safetensors` — canonical FaceOcc v1.0.0 weights
- `config.json` — model and inference contract
- `training_config.json` — canonical training provenance
- `README.md` — model card
- `LICENSE` — software license

## Links

- **Source code:** https://github.com/mertakinstd/FaceOcc
- **Archived software release:** https://doi.org/10.5281/zenodo.22261117
- **Original FaceExtraction repository:** https://github.com/face3d0725/FaceExtraction
- **Original FaceOcc paper:** https://arxiv.org/abs/2201.08425

## Citation

If you use FaceOcc or the underlying face-extraction method, please cite
the original FaceOcc paper:

```bibtex
@article{yin2022faceocc,
  title   = {FaceOcc: A Diverse, High-quality Face Occlusion Dataset for Human Face Extraction},
  author  = {Yin, Xiangnan and Chen, Liming},
  journal = {arXiv preprint arXiv:2201.08425},
  year    = {2022}
}
```

If this modernized implementation or the released model weights
contribute to published work, please also consider citing the archived
software release:

**Mert Akın. FaceOcc: Modernized Implementation, v1.0.0.**  
https://doi.org/10.5281/zenodo.22261117

## License

Distributed under the MIT License. See `LICENSE`.

Attribution and provenance information for the original FaceOcc work
and subsequent modernization contributions are provided in `NOTICE.md`.

Third-party datasets, pretrained resources, and external artifacts
remain subject to their respective licenses and terms.