1use std::path::{Path, PathBuf};
6
7use logit_loom_diffusion::{Digest, ImageOperation};
8use serde::{Deserialize, Serialize};
9
10use crate::{
11 ControlledGenerationReceipt, Error, GenerationMeasurements, ImageRequest, ImageRequestReceipt,
12 ProfileReceipt, Result,
13};
14
15pub const MAX_REFERENCE_IMAGES: usize = 16;
17pub const MAX_REQUEST_LORAS: usize = 32;
19pub const MAX_VAE_TENSOR_RANK: usize = 8;
21
22#[derive(Clone, Copy, Debug)]
24pub struct ImagePixels<'a> {
25 bytes: &'a [u8],
26 width: u32,
27 height: u32,
28 channels: u32,
29}
30
31impl<'a> ImagePixels<'a> {
32 pub fn rgb8(bytes: &'a [u8], width: u32, height: u32) -> Result<Self> {
38 Self::new(bytes, width, height, 3)
39 }
40
41 pub fn rgba8(bytes: &'a [u8], width: u32, height: u32) -> Result<Self> {
47 Self::new(bytes, width, height, 4)
48 }
49
50 pub fn gray8(bytes: &'a [u8], width: u32, height: u32) -> Result<Self> {
56 Self::new(bytes, width, height, 1)
57 }
58
59 fn new(bytes: &'a [u8], width: u32, height: u32, channels: u32) -> Result<Self> {
60 let value = Self {
61 bytes,
62 width,
63 height,
64 channels,
65 };
66 value.validate_length()?;
67 Ok(value)
68 }
69
70 pub const fn bytes(self) -> &'a [u8] {
72 self.bytes
73 }
74
75 pub const fn width(self) -> u32 {
77 self.width
78 }
79
80 pub const fn height(self) -> u32 {
82 self.height
83 }
84
85 pub const fn channels(self) -> u32 {
87 self.channels
88 }
89
90 pub(crate) fn validate_color(self) -> Result<()> {
91 self.validate_length()?;
92 if !matches!(self.channels, 3 | 4) {
93 return Err(Error::Invalid(
94 "color image must contain three or four channels".to_owned(),
95 ));
96 }
97 Ok(())
98 }
99
100 pub(crate) fn validate_mask(self) -> Result<()> {
101 self.validate_length()?;
102 if self.channels != 1 {
103 return Err(Error::Invalid(
104 "mask image must contain exactly one channel".to_owned(),
105 ));
106 }
107 Ok(())
108 }
109
110 fn validate_length(self) -> Result<()> {
111 if self.width == 0
112 || self.height == 0
113 || self.width > crate::MAX_IMAGE_DIMENSION
114 || self.height > crate::MAX_IMAGE_DIMENSION
115 {
116 return Err(Error::Invalid(format!(
117 "image pixel dimensions must be within 1..={}",
118 crate::MAX_IMAGE_DIMENSION
119 )));
120 }
121 let expected = usize::try_from(self.width)
122 .ok()
123 .and_then(|width| {
124 usize::try_from(self.height)
125 .ok()
126 .and_then(|height| width.checked_mul(height))
127 })
128 .and_then(|pixels| {
129 usize::try_from(self.channels)
130 .ok()
131 .and_then(|channels| pixels.checked_mul(channels))
132 })
133 .ok_or_else(|| Error::Invalid("image pixel length overflowed".to_owned()))?;
134 if self.bytes.len() != expected {
135 return Err(Error::Invalid(format!(
136 "image has {} bytes; expected {expected}",
137 self.bytes.len()
138 )));
139 }
140 Ok(())
141 }
142
143 fn receipt(self, domain: &'static str) -> PixelReceipt {
144 PixelReceipt {
145 bytes: Digest::of_bytes(domain, self.bytes),
146 width: self.width,
147 height: self.height,
148 channels: self.channels,
149 }
150 }
151}
152
153#[derive(Clone, Debug)]
155pub struct LoraBinding {
156 path: PathBuf,
157 identity: Digest,
158 scale: f32,
159 high_noise: bool,
160}
161
162impl LoraBinding {
163 pub fn new(path: impl Into<PathBuf>, identity: Digest, scale: f32) -> Result<Self> {
172 let value = Self {
173 path: path.into(),
174 identity,
175 scale,
176 high_noise: false,
177 };
178 value.validate()?;
179 Ok(value)
180 }
181
182 #[must_use]
184 pub const fn with_high_noise(mut self, high_noise: bool) -> Self {
185 self.high_noise = high_noise;
186 self
187 }
188
189 pub fn path(&self) -> &Path {
191 &self.path
192 }
193
194 pub const fn identity(&self) -> &Digest {
196 &self.identity
197 }
198
199 pub const fn scale(&self) -> f32 {
201 self.scale
202 }
203
204 pub const fn is_high_noise(&self) -> bool {
206 self.high_noise
207 }
208
209 fn validate(&self) -> Result<()> {
210 if self.path.as_os_str().is_empty() {
211 return Err(Error::Invalid("LoRA path must be non-empty".to_owned()));
212 }
213 if !self.scale.is_finite() || !(-64.0..=64.0).contains(&self.scale) {
214 return Err(Error::Invalid(
215 "LoRA scale must be finite and within -64..=64".to_owned(),
216 ));
217 }
218 Ok(())
219 }
220
221 fn receipt(&self) -> LoraBindingReceipt {
222 LoraBindingReceipt {
223 identity: self.identity.clone(),
224 scale_bits: self.scale.to_bits(),
225 high_noise: self.high_noise,
226 }
227 }
228}
229
230#[derive(Clone, Debug)]
232pub struct AdvancedImageRequest<'a> {
233 base: ImageRequest,
234 operation: ImageOperation,
235 negative_prompt: String,
236 strength: f32,
237 source: Option<ImagePixels<'a>>,
238 mask: Option<ImagePixels<'a>>,
239 references: Vec<ImagePixels<'a>>,
240 loras: Vec<LoraBinding>,
241}
242
243impl<'a> AdvancedImageRequest<'a> {
244 pub fn text_to_image(base: ImageRequest) -> Result<Self> {
250 let value = Self {
251 base,
252 operation: ImageOperation::TextToImage,
253 negative_prompt: String::new(),
254 strength: 1.0,
255 source: None,
256 mask: None,
257 references: Vec::new(),
258 loras: Vec::new(),
259 };
260 value.validate()?;
261 Ok(value)
262 }
263
264 pub fn image_to_image(mut self, source: ImagePixels<'a>, strength: f32) -> Result<Self> {
270 self.operation = ImageOperation::ImageToImage;
271 self.source = Some(source);
272 self.mask = None;
273 self.strength = strength;
274 self.validate()?;
275 Ok(self)
276 }
277
278 pub fn inpaint(
284 mut self,
285 source: ImagePixels<'a>,
286 mask: ImagePixels<'a>,
287 strength: f32,
288 ) -> Result<Self> {
289 self.operation = ImageOperation::Inpaint;
290 self.source = Some(source);
291 self.mask = Some(mask);
292 self.strength = strength;
293 self.validate()?;
294 Ok(self)
295 }
296
297 pub fn outpaint(
305 mut self,
306 expanded_source: ImagePixels<'a>,
307 mask: ImagePixels<'a>,
308 strength: f32,
309 ) -> Result<Self> {
310 self.operation = ImageOperation::Outpaint;
311 self.source = Some(expanded_source);
312 self.mask = Some(mask);
313 self.strength = strength;
314 self.validate()?;
315 Ok(self)
316 }
317
318 pub fn with_negative_prompt(mut self, prompt: impl Into<String>) -> Result<Self> {
324 self.negative_prompt = prompt.into();
325 self.validate()?;
326 Ok(self)
327 }
328
329 pub fn with_reference(mut self, reference: ImagePixels<'a>) -> Result<Self> {
336 self.references.push(reference);
337 self.validate()?;
338 Ok(self)
339 }
340
341 pub fn with_loras(mut self, loras: Vec<LoraBinding>) -> Result<Self> {
351 self.loras = loras;
352 self.validate()?;
353 Ok(self)
354 }
355
356 pub const fn base(&self) -> &ImageRequest {
358 &self.base
359 }
360
361 pub const fn operation(&self) -> ImageOperation {
363 self.operation
364 }
365
366 pub fn negative_prompt(&self) -> &str {
368 &self.negative_prompt
369 }
370
371 pub const fn strength(&self) -> f32 {
373 self.strength
374 }
375
376 pub const fn source(&self) -> Option<ImagePixels<'a>> {
378 self.source
379 }
380
381 pub const fn mask(&self) -> Option<ImagePixels<'a>> {
383 self.mask
384 }
385
386 pub fn references(&self) -> &[ImagePixels<'a>] {
388 &self.references
389 }
390
391 pub fn loras(&self) -> &[LoraBinding] {
393 &self.loras
394 }
395
396 pub fn validate(&self) -> Result<()> {
402 self.base.validate_common()?;
403 if self.negative_prompt.len() > crate::MAX_PROMPT_BYTES
404 || self.negative_prompt.contains('\0')
405 {
406 return Err(Error::Invalid(format!(
407 "negative prompt must contain at most {} bytes without NUL",
408 crate::MAX_PROMPT_BYTES
409 )));
410 }
411 if !self.strength.is_finite() || !(0.0..=1.0).contains(&self.strength) {
412 return Err(Error::Invalid(
413 "image strength must be finite and within 0..=1".to_owned(),
414 ));
415 }
416 if self.references.len() > MAX_REFERENCE_IMAGES || self.loras.len() > MAX_REQUEST_LORAS {
417 return Err(Error::Invalid(
418 "image reference or LoRA collection exceeds the ABI bound".to_owned(),
419 ));
420 }
421 let dimensions_match = |pixels: ImagePixels<'_>| {
422 pixels.width == self.base.width() && pixels.height == self.base.height()
423 };
424 for reference in &self.references {
425 reference.validate_color()?;
426 }
427 for lora in &self.loras {
428 lora.validate()?;
429 }
430 match (self.operation, self.source, self.mask) {
431 (ImageOperation::TextToImage, None, None)
432 if self.strength.to_bits() == 1.0_f32.to_bits() =>
433 {
434 Ok(())
435 }
436 (ImageOperation::ImageToImage, Some(source), None)
437 if dimensions_match(source) && self.strength > 0.0 =>
438 {
439 source.validate_color()
440 }
441 (ImageOperation::Inpaint | ImageOperation::Outpaint, Some(source), Some(mask))
442 if dimensions_match(source) && dimensions_match(mask) && self.strength > 0.0 =>
443 {
444 source.validate_color()?;
445 mask.validate_mask()
446 }
447 _ => Err(Error::Invalid(
448 "operation, source, mask, strength, or canvas geometry is inconsistent".to_owned(),
449 )),
450 }
451 }
452
453 pub fn receipt(&self) -> Result<AdvancedImageRequestReceipt> {
459 self.validate()?;
460 Ok(AdvancedImageRequestReceipt {
461 base: self.base.receipt()?,
462 operation: self.operation,
463 negative_prompt: Digest::of_bytes(
464 "sdcpp-negative-prompt-bytes-v1",
465 self.negative_prompt.as_bytes(),
466 ),
467 strength_bits: self.strength.to_bits(),
468 source: self
469 .source
470 .map(|pixels| pixels.receipt("sdcpp-source-image-u8-v1")),
471 mask: self
472 .mask
473 .map(|pixels| pixels.receipt("sdcpp-mask-image-u8-v1")),
474 references: self
475 .references
476 .iter()
477 .copied()
478 .map(|pixels| pixels.receipt("sdcpp-reference-image-u8-v1"))
479 .collect(),
480 loras: self.loras.iter().map(LoraBinding::receipt).collect(),
481 })
482 }
483
484 pub(crate) fn validate_for(&self, profile: crate::Profile) -> Result<()> {
485 self.validate()?;
486 self.base.validate_for(profile)
487 }
488}
489
490#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
492#[serde(deny_unknown_fields)]
493pub struct PixelReceipt {
494 pub bytes: Digest,
496 pub width: u32,
498 pub height: u32,
500 pub channels: u32,
502}
503
504#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
506#[serde(deny_unknown_fields)]
507pub struct LoraBindingReceipt {
508 pub identity: Digest,
510 pub scale_bits: u32,
512 pub high_noise: bool,
514}
515
516#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
518#[serde(deny_unknown_fields)]
519pub struct AdvancedImageRequestReceipt {
520 pub base: ImageRequestReceipt,
522 pub operation: ImageOperation,
524 pub negative_prompt: Digest,
526 pub strength_bits: u32,
528 pub source: Option<PixelReceipt>,
530 pub mask: Option<PixelReceipt>,
532 pub references: Vec<PixelReceipt>,
534 pub loras: Vec<LoraBindingReceipt>,
536}
537
538impl AdvancedImageRequestReceipt {
539 pub fn digest(&self) -> Result<Digest> {
545 Digest::of_serializable("sdcpp-image-request-v2", self)
546 .map_err(logit_loom_diffusion::Error::from)
547 .map_err(Error::from)
548 }
549}
550
551#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
553#[serde(deny_unknown_fields)]
554pub struct AdvancedGenerationReceipt {
555 pub request: AdvancedImageRequestReceipt,
557 pub generation: ControlledGenerationReceipt,
559}
560
561#[derive(Clone, Debug)]
563pub struct AdvancedGenerationOutput {
564 pub bytes_written: usize,
566 pub receipt: AdvancedGenerationReceipt,
568 pub measurements: GenerationMeasurements,
570}
571
572#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
580#[serde(deny_unknown_fields)]
581pub struct AdvancedProgramGenerationReceipt {
582 pub request: AdvancedImageRequestReceipt,
584 pub generation: crate::GenerationReceipt,
587}
588
589#[derive(Clone, Debug)]
592pub struct AdvancedProgramGenerationOutput {
593 pub bytes_written: usize,
595 pub receipt: AdvancedProgramGenerationReceipt,
597 pub measurements: GenerationMeasurements,
599}
600
601#[derive(Clone, Debug)]
603pub struct VaeTensor {
604 values: Vec<f32>,
605 shape: Vec<i64>,
606}
607
608impl VaeTensor {
609 pub fn from_parts(values: Vec<f32>, shape: Vec<i64>) -> Result<Self> {
616 let value = Self { values, shape };
617 value.validate()?;
618 Ok(value)
619 }
620
621 pub fn values(&self) -> &[f32] {
623 &self.values
624 }
625
626 pub fn shape(&self) -> &[i64] {
628 &self.shape
629 }
630
631 pub fn to_le_bytes(&self) -> Vec<u8> {
633 let mut bytes = Vec::with_capacity(self.values.len().saturating_mul(4));
634 for value in &self.values {
635 bytes.extend_from_slice(&value.to_bits().to_le_bytes());
636 }
637 bytes
638 }
639
640 pub fn digest(&self) -> Digest {
642 let bytes = self.to_le_bytes();
643 Digest::of_bytes("sdcpp-vae-tensor-f32-le-v1", &bytes)
644 }
645
646 fn validate(&self) -> Result<()> {
647 if self.shape.is_empty()
648 || self.shape.len() > MAX_VAE_TENSOR_RANK
649 || self.shape.iter().any(|dimension| *dimension <= 0)
650 || self.values.is_empty()
651 || u64::try_from(self.values.len()).map_or(true, |elements| {
652 elements > logit_loom_diffusion::MAX_TENSOR_ELEMENTS
653 })
654 || self.values.iter().any(|value| !value.is_finite())
655 {
656 return Err(Error::Invalid(
657 "VAE tensor must have bounded positive shape, element count, and finite values"
658 .to_owned(),
659 ));
660 }
661 let expected = self.shape.iter().try_fold(1_usize, |elements, dimension| {
662 usize::try_from(*dimension)
663 .ok()
664 .and_then(|dimension| elements.checked_mul(dimension))
665 });
666 if expected != Some(self.values.len()) {
667 return Err(Error::Invalid(
668 "VAE tensor shape does not match its element count".to_owned(),
669 ));
670 }
671 Ok(())
672 }
673}
674
675#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
677#[serde(deny_unknown_fields)]
678pub struct VaeOperationReceipt {
679 pub profile: ProfileReceipt,
681 pub backend: Digest,
683 pub session_epoch: u64,
685 pub input: Digest,
687 pub output: Digest,
689 pub tensor_shape: Vec<i64>,
691 pub width: u32,
693 pub height: u32,
695 pub channels: u32,
697}
698
699#[derive(Clone, Debug)]
701pub struct VaeTensorOutput {
702 pub tensor: VaeTensor,
704 pub receipt: VaeOperationReceipt,
706}
707
708#[derive(Clone, Debug)]
710pub struct VaeImageOutput {
711 pub bytes: Vec<u8>,
713 pub receipt: VaeOperationReceipt,
715}
716
717#[cfg(test)]
718mod tests {
719 use super::*;
720 use logit_loom_diffusion::DiffusionSchedule;
721
722 fn request() -> ImageRequest {
723 ImageRequest::new(
724 "mechanical fixture",
725 64,
726 64,
727 7,
728 1.0,
729 DiffusionSchedule::new(Digest::of_bytes("test-schedule", b"v2"), vec![1.0, 0.0])
730 .unwrap(),
731 )
732 .unwrap()
733 }
734
735 #[test]
736 fn advanced_operations_require_exact_tight_canvases() {
737 let source_bytes = vec![0_u8; 64 * 64 * 3];
738 let mask_bytes = vec![255_u8; 64 * 64];
739 let source = ImagePixels::rgb8(&source_bytes, 64, 64).unwrap();
740 let mask = ImagePixels::gray8(&mask_bytes, 64, 64).unwrap();
741 let value = AdvancedImageRequest::text_to_image(request())
742 .unwrap()
743 .outpaint(source, mask, 0.75)
744 .unwrap();
745 assert_eq!(value.operation(), ImageOperation::Outpaint);
746 assert_eq!(value.receipt().unwrap().references.len(), 0);
747 }
748
749 #[test]
750 fn request_receipt_omits_lora_path() {
751 let lora = LoraBinding::new(
752 "/private/model-store/adapter.safetensors",
753 Digest::of_bytes("test-lora", b"exact"),
754 0.5,
755 )
756 .unwrap();
757 let receipt = AdvancedImageRequest::text_to_image(request())
758 .unwrap()
759 .with_loras(vec![lora])
760 .unwrap()
761 .receipt()
762 .unwrap();
763 let encoded = serde_json::to_string(&receipt).unwrap();
764 assert!(!encoded.contains("private"));
765 assert!(!encoded.contains("safetensors"));
766 }
767
768 #[test]
769 fn vae_tensor_rejects_non_finite_or_wrong_shape() {
770 assert!(VaeTensor::from_parts(vec![0.0, f32::NAN], vec![2]).is_err());
771 assert!(VaeTensor::from_parts(vec![0.0], vec![2]).is_err());
772 assert!(VaeTensor::from_parts(vec![0.0, 1.0], vec![2]).is_ok());
773 }
774}