# JoyAI-Image-Edit

[JoyAI-Image](https://github.com/jd-opensource/JoyAI-Image), görüntü anlama, metinden görüntüye üretim ve talimat yönlendirmeli görüntü düzenleme için birleşik çok modlu temel bir modeldir. 8B'lik Çok Modlu Büyük Dil Modeli (MLLM) ile 16B'lik Çok Modlu Difüzyon Dönüştürücüsünü (MMDiT) birleştirir. JoyAI-Image'in temel ilkesi, anlama, üretim ve düzenleme arasındaki kapalı döngülü iş birliğidir.

JoyAI-Image-Edit, nesne taşıma, nesne döndürme ve kamera kontrolü dahil olmak üzere genel görüntü düzenleme ve uzamsal düzenleme yeteneklerini destekler.

| Model | Açıklama | İndir |
|:-----:|:-----------:|:--------:|
| JoyAI-Image-Edit | Hassas ve kontrol edilebilir uzamsal manipülasyon ile talimat yönlendirmeli görüntü düzenleme | [Hugging Face](https://huggingface.co/jdopensource/JoyAI-Image-Edit-Diffusers) |

```python
import torch
from diffusers import JoyImageEditPipeline
from diffusers.utils import load_image

pipeline = JoyImageEditPipeline.from_pretrained(
    "jdopensource/JoyAI-Image-Edit-Diffusers", dtype=torch.bfloat16
)
pipeline.to("cuda")  # or "mps", "xpu", "cpu"

image = load_image("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg")
prompt = "Add wings to the astronaut."

output = pipeline(
    image=image,
    prompt=prompt,
    num_inference_steps=40,
    guidance_scale=4.0,
    generator=torch.Generator("cuda").manual_seed(0),
).images[0]
output.save("joyimage_edit_output.png")
```

## Uzamsal düzenleme

JoyAI-Image üç uzamsal düzenleme istemci kalıbını destekler: **Object Move**, **Object Rotation** ve **Camera Control**. En iyi sonuçlar için aşağıdaki istemci şablonlarına mümkün olduğunca sadık kalın. Daha fazla bilgi için [SpatialEdit](https://github.com/EasonXiao-888/SpatialEdit) belgesine başvurun.

### Nesne Taşıma

Giriş görüntüsünde kırmızı bir kutuyla işaretlenmiş belirli bir bölgeye hedef nesneyi taşıyın.

```text
Move the <object> into the red box and finally remove the red box.
```

### Nesne Dönüşümü

Bir nesneyi belirli bir kanonik görünüme döndürün. Desteklenen `<view>` değerleri: `front`, `right`, `left`, `rear`, `front right`, `front left`, `rear right`, `rear left`.

```text
Rotate the <object> to show the <view> side view.
```

### Kamera Kontrolü

3D sahneyi değiştirmeden kamera bakış açısını değiştirin.

```text
Move the camera.
- Camera rotation: Yaw {y_rotation}°, Pitch {p_rotation}°.
- Camera zoom: in/out/unchanged.
- Keep the 3D scene static; only change the viewpoint.
```

## JoyImageEditPipeline[[diffusers.JoyImageEditPipeline]]

#### diffusers.JoyImageEditPipeline[[diffusers.JoyImageEditPipeline]]

```python
diffusers.JoyImageEditPipeline(scheduler: FlowMatchEulerDiscreteScheduler, vae: AutoencoderKLWan, text_encoder: Qwen3VLForConditionalGeneration, tokenizer: Qwen2Tokenizer, transformer: JoyImageEditTransformer3DModel, processor: Qwen3VLProcessor, text_token_max_length: int = 2048)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit.py#L100)

JoyImage mimarisini kullanarak görüntü düzenleme için difüzyon hattı.

Pipeline, metin ve görüntü koşullandırmasını Qwen3-VL metin kodlayıcı ile kodlar, latensleri 3-B dönüştürücü ile gürültüden arındırır ve sonucu WAN VAE ile çözer.

Model aktarma sırası: text_encoder -> transformer -> vae.

#### __call__[[diffusers.JoyImageEditPipeline.__call__]]

```python
__call__(image: typing.Union[PIL.Image.Image, numpy.ndarray, torch.Tensor, list[PIL.Image.Image], list[numpy.ndarray], list[torch.Tensor], NoneType] = None, prompt: str | list[str] = None, height: int | None = None, width: int | None = None, num_inference_steps: int = 40, timesteps: typing.List[int] = None, sigmas: typing.List[float] = None, guidance_scale: float = 4.0, negative_prompt: typing.Union[str, typing.List[str], NoneType] = None, num_images_per_prompt: typing.Optional[int] = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds_mask: typing.Optional[torch.Tensor] = None, output_type: typing.Optional[str] = 'pil', return_dict: bool = True, callback_on_step_end: typing.Union[typing.Callable[[int, int, typing.Dict], NoneType], diffusers.callbacks.PipelineCallback, diffusers.callbacks.MultiPipelineCallbacks, NoneType] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], max_sequence_length: int = 4096, enable_denormalization: bool = True)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit.py#L600)

**Parametreler:**

prompt (*str* veya *List[str]*) : Üretimi yönlendirmek için istem veya istemler.

height (*int*) : Üretilen çıktının piksel cinsinden yüksekliği.

width (*int*) : Üretilen çıktının piksel cinsinden genişliği.

image (*PipelineImageInput*, *isteğe bağlı*) : Koşullandırma için kullanılan referans görüntü. Sağlandığında, pipeline `num_items=2` ile görüntü düzenleme modunda çalışır.

num_inference_steps (*int*, *optional*, varsayılan 40) : Gürültü azaltma adım sayısı. Daha fazla adım, genellikle daha yavaş çıkarım maliyetiyle kaliteyi artırır.

timesteps (*List[int]*, *isteğe bağlı*) : Gürültü azaltma süreci için özel zaman adımları. Sağlandığında, `num_inference_steps` listenin uzunluğundan çıkarılır.

sigmas (*List[float]*, *opsiyonel*) : Gürültü azaltma süreci için özel sigmalar. `timesteps` ile birbirini dışlar.

guidance_scale (*float*, *optional*, varsayılan 4.0) : Classifier-free guidance ölçeği.

negative_prompt (*str* veya *List[str]*, *isteğe bağlı*) : İstenmeyen içeriği bastırmak için kullanılan negatif istem(ler).

num_images_per_prompt (*int*, *optional*, varsayılan 1) : Her istem için üretilen örnek sayısı.

generator (*torch.Generator* veya *List[torch.Generator]*, *opsiyonel*) : Deterministik örneklemeler için RNG üreteçleri.

latents (*torch.Tensor*, *opsiyonel*) : Hedef slot için önceden oluşturulmuş gürültülü latensler. Sağlanmadığında, Gauss dağılımından örneklenir. Belirli bir başlangıç gürültü tensöründen üretim başlatmak için tohum olarak kullanılabilir.

prompt_embeds (*torch.Tensor*, *isteğe bağlı*) : Ön hesaplanmış prompt gömme değerleri. Sağlandığında `prompt` atlanabilir.

prompt_embeds_mask (*torch.Tensor*, *isteğe bağlı*) : `prompt_embeds` için dikkat maskesi.

negative_prompt_embeds (*torch.Tensor*, *opsiyonel*) : Ön hesaplanmış negatif prompt gömme değerleri.

negative_prompt_embeds_mask (*torch.Tensor*, *isteğe bağlı*) : `negative_prompt_embeds` için dikkat maskesi.

output_type (*str*, *isteğe bağlı*, varsayılan `"pil"`) : Çıktı biçimi. Ham latentleri döndürmek için `"latent"` geçirin.

return_dict (*bool*, *opsiyonel*, varsayılan *True*) : [JoyImageEditPipelineOutput](/docs/diffusers/main/tr/api/pipelines/joyimage_edit#diffusers.JoyImageEditPipelineOutput) mu yoksa düz bir tensör mü döndürüleceğini belirtir.

callback_on_step_end (*Callable*, *PipelineCallback*, *MultiPipelineCallbacks*, *opsiyonel*) : İmzası `(self, step: int, timestep: int, callback_kwargs: Dict)` olan, her gürültü azaltma adımının sonunda çağrılan geri bildirim.

callback_on_step_end_tensor_inputs (*List[str]*, *opsiyonel*, varsayılan `["latents"]`) : `callback_on_step_end` için `callback_kwargs` içinde yer alan Tensor anahtarları.

max_sequence_length (*int*, *optional*, varsayılan 4096) : İstem kodlaması için maksimum dizi uzunluğu.

enable_denormalization (*bool*, *opsiyonel*, varsayılan *True*) : VAE çözümleme öncesinde latentleri normalleştirmeyi iptal et.

**Dönüş:** [*~pipelines.joyimage.JoyImageEditPipelineOutput*] veya *torch.Tensor*

`return_dict` `True` ise, üretilen görüntü(ler)i içeren bir pipeline çıktı nesnesi döndürür. Aksi halde görüntü tensörünü doğrudan döndürür.

Referans bir görüntü ve metin komutuna koşullu olarak düzenlenmiş bir görüntü oluşturun.

Örnekler:
```python
>>> import torch
>>> from diffusers import JoyImageEditPipeline
>>> from diffusers.utils import load_image

>>> model_id = "jdopensource/JoyAI-Image-Edit-Diffusers"
>>> pipe = JoyImageEditPipeline.from_pretrained(model_id, torch_dtype=torch.bfloat16)
>>> pipe.to("cuda")

>>> image = load_image("https://huggingface.co/datasets/diffusers/docs-images/resolve/main/astronaut.jpg")
>>> output = pipe(
...     image=image,  # pass an image for editing; omit for text-to-image generation
...     prompt="Add wings to the astronaut.",
...     num_inference_steps=40,
...     guidance_scale=4.0,
...     generator=torch.manual_seed(0),
... )
>>> output.images[0].save("joyimage_edit.png")
```

#### check_inputs[[diffusers.JoyImageEditPipeline.check_inputs]]

```python
check_inputs(prompt, height, width, negative_prompt = None, prompt_embeds = None, negative_prompt_embeds = None, prompt_embeds_mask = None, negative_prompt_embeds_mask = None, callback_on_step_end_tensor_inputs = None)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit.py#L409)

**Yükselen:** ``ValueError``

- ``ValueError`` -- Geçersiz argüman kombinasyonlarının herhangi birinde.

İleri geçişten önce pipeline girdilerini doğrulayın.

#### denormalize_latents[[diffusers.JoyImageEditPipeline.denormalize_latents]]

```python
denormalize_latents(latent: Tensor)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit.py#L476)

**Parametreler:**

latent : Normalize edilmiş latent tensör.

**Dönüş:**

`vae.decode` tarafından beklenen ölçekteki gizli tensör.

Orijinal latent ölçeği geri getirmek için `normalize_latents` işlemini tersine çevirin.

#### encode_prompt[[diffusers.JoyImageEditPipeline.encode_prompt]]

```python
encode_prompt(prompt: typing.Union[str, typing.List[str]], device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, max_sequence_length: int = 1024, template_type: str = 'image')
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit.py#L364)

**Parametreler:**

prompt : Prompt dizgesi veya prompt dizgileri listesi.

device : Hedef cihaz.

num_images_per_prompt : Her istem için üretilecek çıktı sayısı.

prompt_embeds : Önceden hesaplanmış istek gömme değerleri.

prompt_embeds_mask : Ön hesaplanmış gömceler için dikkat maskesi.

max_sequence_length : Maksimum çıktı dizisi uzunluğu.

template_type : Prompt şablonu anahtarı (`"image"` veya `"multiple_images"`).

**Dönüş:**

(prompt_embeds, prompt_embeds_mask) tuple'ı.

Bir metin komutunu gömme değerlerine kodlayın (yalnızca metin yolu).

Önceden hesaplanmış `prompt_embeds`, kodlamayı tamamen atlar.

#### encode_prompt_multiple_images[[diffusers.JoyImageEditPipeline.encode_prompt_multiple_images]]

```python
encode_prompt_multiple_images(prompt: typing.Union[str, typing.List[str]], device: typing.Optional[torch.device] = None, num_images_per_prompt: int = 1, images: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, prompt_embeds_mask: typing.Optional[torch.Tensor] = None, template_type: typing.Optional[str] = 'multiple_images', max_sequence_length: typing.Optional[int] = None)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit.py#L286)

**Parametreler:**

prompt : İsteğe bağlı olarak `&amp;lt;image>\n` jetonları içeren istem dizgeleri.

device : Hedef cihaz.

num_images_per_prompt : Her istem için üretilecek çıktı sayısı.

images : Satır içi görsel jetonlarına karşılık gelen piksel tensörleri.

prompt_embeds : Önceden hesaplanmış istek gömme değerleri.

prompt_embeds_mask : Ön hesaplanmış gömceler için dikkat maskesi.

template_type : `"multiple_images"` olmalıdır.

max_sequence_length : Ayarlanırsa, çıktı bu uzunluğa kırpılır (son `max_sequence_length` token korunur).

**Dönüş:**

(prompt_embeds, prompt_embeds_mask) tuple'ı.

Qwen işlemcisi aracılığıyla satır içi görsel jetonları içeren istemleri kodlayın.

Her istemci dizisindeki `&amp;lt;image>\n` yer tutucuları, çok modlu kodlayıcıya verilmeden önce Qwen görme özel belirteçleriyle değiştirilir.

#### normalize_latents[[diffusers.JoyImageEditPipeline.normalize_latents]]

```python
normalize_latents(latent: Tensor)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit.py#L447)

**Parametreler:**

latent : `vae.encode`'den gelen ham latent tensör.

**Dönüş:**

Normalize edilmiş latent tensör.

VAE yapılandırmasındaki kanal başına istatistikleri kullanarak latentleri normalize edin.

Uses VAE `latents_mean` ve `latents_std` değerlerini sağladığında (latent - mean) / std; aksi halde `scaling_factor` ile ölçeklemeye geri düşer.

#### prepare_latents[[diffusers.JoyImageEditPipeline.prepare_latents]]

```python
prepare_latents(batch_size: int, num_channels_latents: int, height: int, width: int, video_length: int, dtype: dtype, device: device, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType], latents: typing.Optional[torch.Tensor] = None, image: typing.Optional[typing.List[PIL.Image.Image]] = None, enable_denormalization: bool = True)
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/joyimage/pipeline_joyimage_edit.py#L502)

**Parametreler:**

batch_size : Batch'teki örnek sayısı.

num_channels_latents : Transformer yapılandırmasından gelen gizli kanal boyutu.

height : Piksel cinsinden uzamsal yükseklik.

width : Piksel cinsinden uzamsal genişlik.

video_length : Kare sayısı (görsel çıkarımı için 1).

dtype : Gizli tensör için kayan noktalı veri türü.

device : Hedef cihaz.

generator : Yeniden üretilebilir örneklemeler için RNG üreteçleri.

latents : Hedef slot için isteğe bağlı, kullanıcı tarafından sağlanan başlangıç gürültüsü. `None` olduğunda rastgele gürültü örneklenir.

image : VAE kodlaması için koşullama yuvaları olarak kullanılacak isteğe bağlı PIL referans görselleri listesi.

enable_denormalization : Kodlanmış referans latentleri normalize edip edilmeyeceği.

**Dönüş:**

`(latents, image_latents)` biçiminde bir Tuple; burada `latents` `(B, 1, C, T, H', W')` şekline sahipken, referans görüntüler verilmediğinde `image_latents` `(B, N_ref, C, T, H', W')` şekline sahip ya da `None` değerini alır.

**Yükselen:** `ValueError`

- `ValueError` -- `generator`, `batch_size` ile farklı uzunlukta bir liste ise.

Gürültü azaltma döngüsü için başlangıç gürültülü latent tensörünü hazırlayın.

## JoyImageEditPipelineOutput[[diffusers.JoyImageEditPipelineOutput]]

#### diffusers.JoyImageEditPipelineOutput[[diffusers.JoyImageEditPipelineOutput]]

```python
diffusers.JoyImageEditPipelineOutput(images: typing.Union[typing.List[PIL.Image.Image], numpy.ndarray])
```

[Kaynak](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/joyimage/pipeline_output.py#L11)

JoyImageEdit üretim hatları için çıktı sınıfı.