# karel_asset

A package to draw Karel in graphics projects.
For use by students who want to make art or games with Karel as a character.
* Demo [Draw Karel](https://codeinplace.stanford.edu/cip6/share/t6iMlN3l2JhVLvZW788e)
* Demo [Flash Karel](https://codeinplace.stanford.edu/cip6/share/jT6Uoy5fPrND2ZeuqLKp)
* Demo [Karel spinner](https://codeinplace.stanford.edu/cip6/share/gbgGP9tqYZyC4LwmsyaZ)
* Demo [Karel slider](https://codeinplace.stanford.edu/cip6/share/faD10zUPcOnV1ghxa1R4)

## Getting started
1. In CIP6 click on **["Code / You own"](https://codeinplace.stanford.edu/cip6/create)**, or on CIP self-guided clock on **["Code / You own"](https://codeinplace.stanford.edu/public/create)**
1. Create a new or open an existing **graphics project**
1. Go to the **Project Files** view by clicking the "**Files**" button in the ribbon on the left
1. Add the karel_asset.py file by:
    * Either clicking the CIP icon of a file with a plus sign (+) in it to add a new file and paste the content of [karel_asset.py](https://git.h0v1n8.nl/Stanford/karel_asset/raw/master/karel_asset.py)
    * Or by downloading/cloning this project and uploading the karel_asset.py file with the upload button on the CIP IDE

## Using karel_asset.py when it is added to a CIP project
In your main.py or any other project file on CIP, add: `from karel_asset import *`

### Drawing Karel
To simply draw a Karel in the top left corner use: `draw_karel(canvas)`
But surely this will not suffice for any project so there are optional arguments to pass:
* centre_x
* centre_y
* size
* orientation
* colour
* background
* transparent

#### Coordinates
To draw a Karel in the middle of X / Y coordinates 100 / 100, use the optional arguments centre_x, centre_y:
```
draw_karel(canvas, 100, 100)
```

#### Size
To draw a Karel of size 200, use the optional argument size:
```
draw_karel(canvas, size=200)
```

#### Orientation
To draw a Karel facing north, use the optional argument orientation:
```
draw_karel(canvas, orientation="north")
```
Orientation options:
* "east"
* "east-flipped"
* "north"
* "north-flipped"
* "west"
* "west-flipped"
* "south"
* "south-flipped"
Flipped makes Karel appear upside down.

#### Colour
To draw a Karel in any colour use the optional argument colour:
```
draw_karel(canvas, colour="red", background="#FF8833")
```
Colour names and hex codes are accepted, just like normal for any CIP graphical object.

#### Transparancy
To draw a transparant Karel, which only has outlines and no fill, use the optional argument transparent:
```
draw_karel(canvas, transparent=True)
```

#### Examples
Draw a Karel at 85x and 35y upside down facing east with a red outline and blue filling:
```
karel_east_mirrored = draw_karel(canvas, 85, 35, 100, "east-flipped", "red", "blue")
```
Draw a Karel at 135X and 35y, facing west with a red background:
```
karel_west = draw_karel(canvas, centre_x=135, centre_y=35, orientation="west", background="red")
```
### Changing colour
To change the colour of any asset, use recolour_asset(karel, colour, background).
For example changing a red/blue Karel to a green/yellow Karel:
```
my_karel = draw_karel(canvas, colour="red", background="blue")
my_karel = recolour_asset(my_karel, colour="green", background="yellow) 
```

### Changing position relative to current position
To change the position of an asset on the canvas relative to its current position, use relative_move_asset(karel, x, y).
Where x is the amout of pixels shifted horizontally, and y is the amount of pixels shifted vertically.
To move a Karel up 10 pixes:
```
my_karel = draw_karel(canvas, colour="red", background="blue")
my_karel = relative_move_asset(my_karel, y=-10)
```

To move a Karel down 10 and left 10 pixels:
```
my_karel = draw_karel(canvas, colour="red", background="blue")
my_karel = relative_move_asset(my_karel, 10, -10)
```

### Changing position relative to its orientation
To change the position of an asset on the canvas relative to its current orientation, use orientation_move_asset(asset, direction, amount)
Directional options:
* forward
* front
* left
* right
* backward
* back
To move an asset to its right by 10 pixels:
```
my_karel = draw_karel(canvas, colour="red", background="blue")
my_karel = orientation_move_asset(my_karel, "right", 10)
```

### Changing absolute position on the canvas
To change the position of an asset on the canvas with absolute coordinates, use absolute_move_asset(asset, x, y).
Where x is the absolute width centre and y is the absolute height centre.
To move an asset to 100 by 100:
```
my_karel = draw_karel(canvas, colour="red", background="blue")
my_karel = absolute_move_asset(my_karel, 100, 100)
```

### Rotating
To turn an asset, use rotate_asset(asset, orientation).
Orientation options:
* "right"
* "left"
* "east"
* "east-flipped"
* "north"
* "north-flipped"
* "west"
* "west-flipped"
* "south"
* "south-flipped"
To turn a Karel to the right:
```
my_karel = draw_karel(canvas, colour="red", background="blue")
my_karel = rotate_asset(my_karel, "right")
```
To turn a Akrel toward the south:
```
my_karel = draw_karel(canvas, colour="red", background="blue")
my_karel = rotate_asset(my_karel, "south")
```

### Erasing an asset
To remove a Karel from the canvas, use erase_asset(asset):
```
my_karel = draw_karel(canvas, colour="red", background="blue")
my_karel = erase_asset(my_karel)
```

### Generating a random asset
To generate a random asset, use generate_random_asset(canvas):
```
my_asset = generate_random_asset(canvas)
```

### Generating a random karel
To draw a Karel with a rondom properties, use generate_random_karel(canvas):
```
my_karel = generate_random_karel(canvas)
```

### Generating a Karel outside the canvas
To draw a Karel outside of the canvas, to perhaps be later slid into view, use generate_outofbounds_random_karel(canvas, side):
```
my_karel = generate_outofbounds_random_karel(canvas, "left")
```

### Drawing and generating a beeper
Works the same as drawing and generating a karel, available commands:
* draw_beeper(canvas, centre_x:int=25, centre_y:int=25, size:int=50, orientation:str="east", colour:str="black", background:str="cyan", transparent:bool=False)
* generate_random_beeper(canvas)
* generate_outofbounds_random_beeper(canvas, side:str)

### Generating a random asset
Works the same as drawing and generating a karel, available commands:
* generate_random_asset(canvas)
* generate_outofbounds_random_asset(canvas, side:str)

### Generating a random colour
To get a random colour value to use in your own graphical shape, use generate_random_colour().
Side options:
* top
* left
* bottom
* right
To generate a random HEX colour:
```
my_colour = generate_random_colour()
```

To generate a random RGB colour:
```
my_colour = generate_random_colour("rgb")
```
To generate a random ANSI colour:
```
print("White or default")
colour = generate_random_colour("ansi")
print(f"{colour}Some colour")

print(f"{generate_random_colour("ansi")}Some {generate_random_colour("ansi")}other {generate_random_colour("ansi")}colour {generate_random_colour("ansi")}for {generate_random_colour("ansi")}each {generate_random_colour("ansi")}word{generate_random_colour("ansi")}.")

```

### Generating a random background
To draw a random coloured square filling the whole canvas, use generate_random_background(canvas):
```
background = generate_random_background(canvas)
```

## Example
```
from graphics import Canvas
from karel_asset import *
from time import sleep

# Constants    
CANVAS_WIDTH = 200
CANVAS_HEIGHT = 200

def main():
    canvas = Canvas(CANVAS_WIDTH, CANVAS_HEIGHT)
    
    # Create a background
    background = generate_random_background(canvas)
    
    # Demo loop
    while True:    # Keep repeating the following code forever
    
        # Draw four Karels
        karel_east = draw_karel(canvas, 35, 35)
        karel_east_mirrored = draw_karel(canvas, 85, 35, orientation="east-flipped", colour="red")
        karel_west = draw_karel(canvas, 135, 35, orientation="west", background="red")
        karel_west_mirrored = draw_karel(canvas, 185, 35, orientation="west-flipped", colour="red", background="red")
        
        # Draw a beeper
        my_beeper = draw_beeper(canvas, 100, 100)
        
        # Wait five seconds
        sleep(5)
        
        # Change the colour of one Karel to random colours
        karel_east = recolour_asset(karel_east, "random", "random")
        
        # Move one Karel
        karel_east_mirrored = move_asset(karel_east_mirrored, 10, 10)
        
        # Rotate another karel eight times, and wait one second after each time
        for i in range(8):
            rotate_asset(karel_east_mirrored, "right)
            sleep(1)
        
        # Wait five seconds
        sleep(5)
        
        # Erase four Karels
        erase_asset(karel_east)
        erase_asset(karel_east_mirrored)
        erase_asset(karel_west)
        erase_asset(karel_west_mirrored)


if __name__ == '__main__':
    main()
```