improved images handling code and documentation